• NAME
• VERSION
• SYNOPSIS
• DESCRIPTION
• FUNCTIONS
• bson_bytes
• bson_code
• bson_dbref
• bson_decimal128
• bson_doc
• bson_array
• bson_double
• bson_int32
• bson_int64
• bson_maxkey
• bson_minkey
• bson_oid
• bson_raw
• bson_regex
• bson_string
• bson_time
• bson_timestamp
• bson_bool (DISCOURAGED)
• AUTHORS
• COPYRIGHT AND LICENSE

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 the BSON::Int32 manpage, 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 the BSON::Bytes manpage 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 the BSON::Code manpage 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 the BSON::DBRef manpage 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 the BSON::Decimal128 manpage 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 the BSON::Doc manpage object, which preserves the order of the provided key-value pairs.

bson_array

    $doc = bson_array(...);

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

bson_double

    $double = bson_double( 1.0 );

This function returns a the BSON::Double manpage 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 the BSON::Int32 manpage 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 the BSON::Int64 manpage 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 the BSON::OID manpage 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 the BSON::Raw manpage object wrapping an already BSON-encoded document.

bson_regex

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

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

bson_string

    $string = bson_string( "08544" );

This function returns a the BSON::String manpage 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 the BSON::Time manpage 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 the Time::HiRes manpage is used.

bson_timestamp

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

This function returns a the BSON::Timestamp manpage 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