man > BSON::Types

man perldoc info pydoc3 ri search

📛 NAME

BSON::Types - Helper functions to wrap BSON type classes

🚀 Quick Reference

Use Case	Command	Description
🔤 Wrapped bytes	bson_bytes($data)	Wrap byte string as BSON::Bytes
📜 JavaScript code	bson_code($js)	Wrap JavaScript as BSON::Code
🔗 DBRef	bson_dbref($oid, $coll)	Wrap OID + collection as BSON::DBRef
💯 Decimal128	bson_decimal128("0.12")	Exact decimal precision BSON::Decimal128
📄 Ordered document	bson_doc(key => val, …)	Ordered key-value pairs BSON::Doc
📋 Ordered array	bson_array(…)	Ordered list BSON::Array
🔢 Double	bson_double(3.14)	Native double → BSON::Double
3️⃣ Int32	bson_int32(42)	Native integer → BSON::Int32
6️⃣ Int64	bson_int64(0)	Native integer → BSON::Int64
🔺 MaxKey	bson_maxkey()	BSON maximum key value
🔻 MinKey	bson_minkey()	BSON minimum key value
🆔 ObjectID	bson_oid()	Generate / wrap a 12-byte ObjectID
📦 Raw BSON	bson_raw($encoded)	Already-encoded BSON::Raw
🔍 Regex	bson_regex($pattern)	Regex pattern BSON::Regex
🔤 UTF‑8 string	bson_string("08544")	Force string serialization BSON::String
⏱️ Date/time	bson_time($epoch_seconds)	Millisecond UTC BSON::Time
⏲️ Timestamp	bson_timestamp($sec, $inc)	Special BSON::Timestamp (not general)
❔ Boolean (discouraged)	bson_bool($expr)	Boolean wrapper; prefer boolean::boolean()

📌 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 3️⃣ 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 6️⃣, 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

📛 NAME 🚀 Quick Reference 📌 VERSION 📋 SYNOPSIS 📖 DESCRIPTION ⚙️ FUNCTIONS 👥 AUTHORS ⚖️ COPYRIGHT AND LICENSE