BSON::Types(3pm)

🎀 BSON::Types 🎀

okay so bestie, welcome to the BSON::Types manual page — it's a Perl module, it lives in section 3pm of the user-contributed Perl docs, and it's basically your little group chat of helper functions that wrap up BSON type classes so your data stops being ✨ambiguous✨. pull up a chair. 🫶

---

✨ VERSION ✨

this is version v1.12.2 — periodt.

---

🌈 SYNOPSIS 🌈

use BSON::Types ':all';

$int32   = bson_int32(42);
$double  = bson_double(3.14159);
$decimal = bson_decimal("24.01");
$time    = bson_time(); # now
...

like, that's the whole vibe. one use line with ':all' and suddenly every helper is just there for you 💅

---

💜 DESCRIPTION 💜

so this module hands you helper functions for BSON type wrappers. the wrappers are objects that line up with BSON types, and they exist to represent data that would otherwise have an ambiguous type — or data that just doesn't have a native Perl representation at all. no cap.

here's the tea: Perl scalars can be strings, integers, or floating point numbers, and honestly? they're not gonna tell you which. so the serialization rules have to lean on a bunch of heuristics, and that's lowkey chaos. the glow-up is wrapping a Perl scalar in a class — like BSON::Int32 — so you, the main character, get to specify exactly how that scalar serializes to BSON. iconic. 🔥

---

🦋 FUNCTIONS 🦋

🌸 bson_bytes

$bytes = bson_bytes( $byte_string );
$bytes = bson_bytes( $byte_string, $subtype );

gives you back a BSON::Bytes object that wraps the string you passed in. you can pass a numeric subtype as a second argument, but ngl, that's not recommended for new applications. 🙈

🌸 bson_code

$code = bson_code( $javascript );
$code = bson_code( $javascript, $hashref );

returns a BSON::Code object wrapping the Javascript code you handed over. optionally you can also pass a hashref representing the variables in scope for the function. slay. ✨

🌸 bson_dbref

$dbref = bson_dbref( $object_id, $collection_name );

returns a BSON::DBRef object wrapping the Object ID and collection name you gave it. 🎀

🌸 bson_decimal128

$decimal = bson_decimal128( "0.12" );
$decimal = bson_decimal128( "1.23456789101112131415116E-412" );

returns a BSON::Decimal128 object wrapping that decimal string. and the way this differs from floating point values is that it preserves exact decimal precision — no rounding betrayal, we love to see it. 💖

🌸 bson_doc

$doc = bson_doc( first => "hello, second => "world" );

returns a BSON::Doc object, and the whole point is that it preserves the order of the key-value pairs you passed. order matters, bestie. 👑

🌸 bson_array

$doc = bson_array(...);

returns a BSON::Array object, which preserves the order of the list of elements you gave it. same energy as above, but for lists. ✨

🌸 bson_double

$double = bson_double( 1.0 );

returns a BSON::Double object wrapping a native double value. this locks it in so it serializes to BSON as a double, instead of getting mistaken for a string or an integer, because Perl's scalar typing is lax and honestly a little chaotic. 😭

🌸 bson_int32

$int32 = bson_int32( 42 );

returns a BSON::Int32 object wrapping a native integer value. this makes sure it serializes to BSON as an Int32, not a string, not a double — because again, Perl's lax scalar typing would absolutely let that happen. 💀

🌸 bson_int64

$int64 = bson_int64( 0 ); # 64-bit zero

returns a BSON::Int64 object wrapping a native integer value. this guarantees it serializes to BSON as an Int64 rather than a string or double — you already know why, Perl's lax typing strikes again. 🔥

🌸 bson_maxkey

$maxkey = bson_maxkey();

returns a singleton representing the "maximum key" BSON type. it's giving one-of-a-kind. 💅

🌸 bson_minkey

$minkey = bson_minkey();

returns a singleton representing the "minimum key" BSON type. the other half of the iconic duo. 🌈

🌸 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

returns a BSON::OID object wrapping a 12-byte MongoDB Object ID. call it with no arguments and instead it generates a brand new, unique Object ID for you — obsessed. and if you hand it 24 hexadecimal characters, they get packed into a 12-byte Object ID. 🦋

🌸 bson_raw

$raw = bson_raw( $bson_encoded );

returns a BSON::Raw object wrapping a document that's already BSON-encoded. it's the "I did the work myself" option. ✨

🌸 bson_regex

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

returns a BSON::Regex object wrapping a PCRE pattern, plus optional flags if you've got 'em. 🎀

🌸 bson_string

$string = bson_string( "08544" );

returns a BSON::String object wrapping a native string value. this ensures it serializes to BSON as a UTF-8 string, and not as an integer or a double, because — say it with me — Perl's lax typing for scalars. 😤

🌸 bson_time

$time = bson_time( $seconds_from_epoch );

returns a BSON::Time object representing a UTC date and time, precise down to the millisecond. the argument has to be a number of seconds relative to the Unix epoch, and yes it can be positive or negative. it can also be a floating point value if you want fractional seconds — go off. and if you pass no argument at all, it just uses the current time from Time::HiRes. 👑

🌸 bson_timestamp

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

returns a BSON::Timestamp object. ngl, it is not recommended for general use. you've been warned, bestie. 💀

🌸 bson_bool (DISCOURAGED)

# for consistency with other helpers
$bool = bson_bool( $expression );

# preferred for efficiency
use boolean;
$bool = boolean( $expression );

returns a boolean object — true or false — based on the expression you gave it (or false if you didn't give an expression at all). it's here for consistency's sake, so that literally every BSON type has a matching helper function. cute, right?

but for efficiency? use "boolean::boolean()" directly instead. that's the move. ✨

---

🫶 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

---

and that's the whole page, bestie 💅 this was BSON::Types(3pm), generated by perl v5.30.3, dated 2020-08-14 — take care of her, she's iconic. 🎀✨💜