phpman > perldoc > BSON::Types(3pm)

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