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

       •   David Golden <david@mongodb.com>

       •   Stefan G. <minimalist@lavabit.com>

       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

perl v5.40.1                                       2025-04-16                                   BSON::Types(3pm)

       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.

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.

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

           use BSON::Types ':all';

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

       version v1.12.2