# BSON::Types - Helper functions to wrap BSON type classes - perldoc - [phpMan]

## NAME
    [BSON::Types](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ATypes/markdown) - Helper functions to wrap BSON type classes

## VERSION
    version v1.12.2

## SYNOPSIS
        use [BSON::Types](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ATypes/markdown) ':all';

        $int32   = [bson_int32(42)](https://www.chedong.com/phpMan.php/man/bsonint32/42/markdown);
        $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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AInt32/markdown), 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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ABytes/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ACode/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ADBRef/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ADecimal128/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ADoc/markdown) object, which preserves the order of the provided key-value
    pairs.

  bson_array
        $doc = bson_array(...);

    This function returns a [BSON::Array](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AArray/markdown) object, which preserves the order of the provided list of
    elements.

  bson_double
        $double = bson_double( 1.0 );

    This function returns a [BSON::Double](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ADouble/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AInt32/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AInt64/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AOID/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ARaw/markdown) object wrapping an already BSON-encoded document.

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

    This function returns a [BSON::Regex](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ARegex/markdown) object wrapping a PCRE pattern and optional flags.

  bson_string
        $string = bson_string( "08544" );

    This function returns a [BSON::String](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AString/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ATime/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/Time%3A%3AHiRes/markdown) is used.

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

    This function returns a [BSON::Timestamp](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ATimestamp/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/boolean%3A%3Aboolean/markdown)() 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