NAME

       BSON::Types - Helper functions to wrap BSON type classes

VERSION

       version v1.12.2

SYNOPSIS

           use BSON::Types ':all';

           $int32   = bson_int32(42);
           $double  = bson_double(3.14159);
           $decimal = bson_decimal("24.01");
           $time    = bson_time(); # now
           ...

DESCRIPTION

       This module provides helper functions for BSON type wrappers.  Type wrappers use objects
       corresponding to BSON types to represent data that would have ambiguous type or don't have
       a native Perl representation

       For example, because Perl scalars can represent strings, integers or floating point
       numbers, the serialization rules depend on various heuristics.  By wrapping a Perl scalar
       with a class, such as BSON::Int32, users can specify exactly how a scalar should serialize
       to BSON.

FUNCTIONS

   bson_bytes
           $bytes = bson_bytes( $byte_string );
           $bytes = bson_bytes( $byte_string, $subtype );

       This function returns a BSON::Bytes object wrapping the provided string.  A numeric
       subtype may be provided as a second argument, but this is not recommended for new
       applications.

   bson_code
           $code = bson_code( $javascript );
           $code = bson_code( $javascript, $hashref );

       This function returns a BSON::Code object wrapping the provided Javascript code.  An
       optional hashref representing variables in scope for the function may be given as well.

   bson_dbref
           $dbref = bson_dbref( $object_id, $collection_name );

       This function returns a BSON::DBRef object wrapping the provided Object ID and collection
       name.

   bson_decimal128
           $decimal = bson_decimal128( "0.12" );
           $decimal = bson_decimal128( "1.23456789101112131415116E-412" );

       This function returns a BSON::Decimal128 object wrapping the provided decimal string.
       Unlike floating point values, this preserves exact decimal precision.

   bson_doc
           $doc = bson_doc( first => "hello, second => "world" );

       This function returns a BSON::Doc object, which preserves the order of the provided key-
       value pairs.

   bson_array
           $doc = bson_array(...);

       This function returns a BSON::Array object, which preserves the order of the provided list
       of elements.

   bson_double
           $double = bson_double( 1.0 );

       This function returns a BSON::Double object wrapping a native double value.  This ensures
       it serializes to BSON as a double rather than a string or integer given Perl's lax typing
       for scalars.

   bson_int32
           $int32 = bson_int32( 42 );

       This function returns a BSON::Int32 object wrapping a native integer value.  This ensures
       it serializes to BSON as an Int32 rather than a string or double given Perl's lax typing
       for scalars.

   bson_int64
           $int64 = bson_int64( 0 ); # 64-bit zero

       This function returns a BSON::Int64 object, wrapping a native integer value.  This ensures
       it serializes to BSON as an Int64 rather than a string or double given Perl's lax typing
       for scalars.

   bson_maxkey
           $maxkey = bson_maxkey();

       This function returns a singleton representing the "maximum key" BSON type.

   bson_minkey
           $minkey = bson_minkey();

       This function returns a singleton representing the "minimum key" BSON type.

   bson_oid
           $oid = bson_oid();         # generate a new one
           $oid = bson_oid( $bytes ); # from 12-byte packed OID
           $oid = bson_oid( $hex   ); # from 24 hex characters

       This function returns a BSON::OID object wrapping a 12-byte MongoDB Object ID.  With no
       arguments, a new, unique Object ID is generated instead.  If 24 hexadecimal characters are
       given, they will be packed into a 12-byte Object ID.

   bson_raw
           $raw = bson_raw( $bson_encoded );

       This function returns a BSON::Raw object wrapping an already BSON-encoded document.

   bson_regex
           $regex = bson_regex( $pattern );
           $regex = bson_regex( $pattern, $flags );

       This function returns a BSON::Regex object wrapping a PCRE pattern and optional flags.

   bson_string
           $string = bson_string( "08544" );

       This function returns a BSON::String object, wrapping a native string value.  This ensures
       it serializes to BSON as a UTF-8 string rather than an integer or double given Perl's lax
       typing for scalars.

   bson_time
           $time = bson_time( $seconds_from_epoch );

       This function returns a BSON::Time object representing a UTC date and time to millisecond
       precision.  The argument must be given as a number of seconds relative to the Unix epoch
       (positive or negative).  The number may be a floating point value for fractional seconds.
       If no argument is provided, the current time from Time::HiRes is used.

   bson_timestamp
           $timestamp = bson_timestamp( $seconds_from_epoch, $increment );

       This function returns a BSON::Timestamp object.  It is not recommended for general use.

   bson_bool (DISCOURAGED)
           # for consistency with other helpers
           $bool = bson_bool( $expression );

           # preferred for efficiency
           use boolean;
           $bool = boolean( $expression );

       This function returns a boolean object (true or false) based on the provided expression
       (or false if no expression is provided).  It is provided for consistency so that all BSON
       types have a corresponding helper function.

       For efficiency, use "boolean::boolean()" directly, instead.

AUTHORS

       •   David Golden <david@mongodb.com>

       •   Stefan G. <minimalist@lavabit.com>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2020 by Stefan G. and MongoDB, Inc.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004