/ 
BSON-v1.12.2
River stage one • 6 direct dependents • 7 total dependents
/ BSON::Types

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@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