BSON::Types - phpMan

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 AT mongodb.com>

    *   Stefan G. <minimalist AT 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