--- name: "BSON::Types" section: "3pm" platform: "linux" package: "libbson-perl" version: "1.12.2-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/BSON::Types" --- # BSON::Types(3pm) Helper functions to wrap BSON type classes ## 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 \ - • Stefan G. \ ## 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 ```