BSON::OID(3pm)

💖 BSON::OID — the perl wrapper for Object IDs, bestie edition 💖

okay so real talk: this is BSON::OID, a User Contributed Perl Documentation page, and it's literally the BSON type wrapper for Object IDs. yes. that's the whole vibe. it's giving "tiny module, big responsibility." 🫶

---

✨ VERSION ✨

version v1.12.2 — she's a specific girl and she knows it 💅

---

🌸 SYNOPSIS 🌸

here's the whole thing in action, no cap:

use BSON::Types ':all';

my $oid  = bson_oid();
my $oid  = bson_oid->from_epoch(1467543496, 0); # for queries only

my $bytes = $oid->oid;
my $hex   = $oid->hex;

see how she pulls the raw bytes AND the hex? versatility. main character energy fr. 👑

---

🦋 DESCRIPTION 🦋

this module is a wrapper around a BSON Object ID — here's the link so you can go read the MongoDB docs yourself:

https://docs.mongodb.com/manual/reference/method/ObjectId/

and that's it. that's the description. short and iconic, as she should be. ✨

---

🎀 ATTRIBUTES 🎀

oid

a 12-byte (packed) Object ID (OID) string. and if you don't hand her one? she just generates a brand new OID for you. no thoughts, just creation. 🌈

---

💅 METHODS 💅

new

my $oid = BSON::OID->new;

my $oid = BSON::OID->new( oid => $twelve_bytes );

okay bestie, this is the preferred way to generate an OID. like, if you're only gonna remember one thing from this page, it's this one. 💖

• call it with no arguments → you get a unique OID, freshly generated, just for you 🎀
• call it with a 12-byte string → you get an object wrapped around an OID byte-string that already exists

---

from_epoch

here come the examples, they're doing the most and honestly? respect:

# generate a new OID

my $oid = BSON::OID->from_epoch( $epoch, 0); # other bytes zeroed
my $oid = BSON::OID->from_epoch( $epoch, $eight_more_bytes );

# reset an existing OID

$oid->from_epoch( $new_epoch, 0 );
$oid->from_epoch( $new_epoch, $eight_more_bytes );

⚠️ Warning! do NOT rely on this method as a source of unique IDs. use it for query boundaries only. that's the whole assignment. periodt.

so here's the lore. an OID is a twelve-byte string. typically, the first four bytes are an integer count of seconds since the Unix epoch, in big-endian format. the remaining bytes are there to keep things unique.

with this method:

• the first argument is an epoch time (in integer seconds)
• the second argument is the remaining eight bytes to append to the string

when you call it as a class method, it returns a brand new BSON::OID object. when you call it as an object method, it mutates the existing internal OID value. same method, two moods. 💅

and here's the special case: if the second argument is defined and zero ("0"), then the remaining bytes get zeroed. like this:

my $oid = BSON::OID->from_epoch(1467545180, 0);

this is particularly useful when you're looking for documents by their insertion date — you can just look for OIDs that are greater or lower than the one this method generated. chef's kiss. 😭✨

now for the backwards-compat tea ☕: for compatibility with Mango, if you call it without a second argument, it generates the remainder of the fields "like usual". that's equivalent to calling BSON::OID->new and replacing the first four bytes with the packed epoch value.

# UNSAFE: don't do this unless you have to

my $oid = BSON::OID->from_epoch(1467545180);

like, it literally says # UNSAFE in the original. i'm just the messenger. 🙈

but if you insist on creating a unique OID with from_epoch, then set the remaining eight bytes in a way that guarantees thread-safe uniqueness — like from a reliable source of randomness. the docs point at Crypt::URandom:

use Crypt::Random 'urandom';
my $oid = BSON::OID->from_epoch(1467545180, urandom(8));

there you go. safe, random, gorgeous. 🌸

---

hex

returns the "oid" attribute as a 24-byte hexadecimal value. short method, big flex. 💖

---

get_time

returns a number corresponding to the portion of the "oid" value that represents seconds since the epoch. time travel but make it bytes. ⏰✨

---

TO_JSON

returns a string for this OID, with the OID given as 24 hex digits.

BUT — if the "BSON_EXTJSON" option is true, it will instead be compatible with MongoDB's extended JSON format:

https://github.com/mongodb/specifications/blob/master/source/extended-json.rst

which represents it as a document like this:

{"$oid" : "012345678901234567890123"}

two formats, one method. she contains multitudes. 🦋

---

🌈 OVERLOAD 🌈

the string operator is overloaded, so any string operations will actually use the 24-character hex value of the OID. and fallback overloading is enabled. slay. ✨

both numeric comparison (<=>) and string comparison (cmp) are overloaded to do string comparison of the 24-character hex value of the OID.

⚠️ but listen: if you use them with a non-BSON::OID object, you'd better provide a 24-character hex string, or the results are undefined. no cap, that's a real warning. 💀

---

🧚 THREADS 🧚

this module is thread safe. that's it. that's the section. go off, queen. 👑

---

💜 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.

and it's free software, licensed under:

The Apache License, Version 2.0, January 2004

---

okay that's the whole page bestie, you're officially an OID expert 🎓✨ this was BSON::OID(3pm), perl v5.30.3, dated 2020-08-14 — and yes i read all of it so you didn't have to. mwah. 💋💖🫶