man > BSON::OID

man perldoc info pydoc3 ri search

📛 NAME

BSON::OID - BSON type wrapper for Object IDs

🚀 Quick Reference

Use Case	Command	Description
Create a new unique OID	my $oid = BSON::OID->new;	Generate a fresh Object ID
OID for date‑range queries	my $oid = BSON::OID->from_epoch(1467545180, 0);	First 4 bytes = epoch, rest zeroed
Get 24‑char hex string	my $hex = $oid->hex;	String suitable for display / JSON
Retrieve raw 12‑byte OID	my $bytes = $oid->oid;	Packed binary form of the OID
Extract timestamp	my $secs = $oid->get_time;	Seconds since Unix epoch from OID
Compare two OIDs	$oid1 cmp $oid2 / $oid1 <=> $oid2	Hex‑based string comparison
Use OID as a string	print "$oid\n";	String overload emits 24 hex digits

🔢 VERSION

version v1.12.2

📝 SYNOPSIS

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;

📘 DESCRIPTION

This module provides a wrapper around a BSON Object ID <https://docs.mongodb.com/manual/reference/method/ObjectId/>.

⚙️ ATTRIBUTES

📦 oid

A 12-byte (packed) Object ID (OID) string. If not provided, a new OID will be generated.

🔧 METHODS

🆕 new

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

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

This is the preferred way to generate an OID. Without arguments, a unique OID will be generated. With a 12-byte string, an object can be created around an existing OID byte-string.

⏱️ from_epoch

# 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! You should not rely on this method for a source of unique IDs. Use this method for query boundaries, only.

An OID is a twelve-byte string. Typically, the first four bytes represent integer seconds since the Unix epoch in big-endian format. The remaining bytes ensure uniqueness.

With this method, the first argument to this method is an epoch time (in integer seconds). The second argument is the remaining eight-bytes to append to the string.

When called as a class method, it returns a new BSON::OID object. When called as an object method, it mutates the existing internal OID value.

As a special case, if the second argument is defined and zero ("0"), then the remaining bytes will be zeroed.

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

This is particularly useful when looking for documents by their insertion date: you can simply look for OIDs which are greater or lower than the one generated with this method.

For backwards compatibility with Mango, if called without a second argument, the method generates the remainder of the fields "like usual". This is 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);

If you insist on creating a unique OID with "from_epoch", set the remaining eight bytes in a way that guarantees thread-safe uniqueness, such as from a reliable source of randomness (see Crypt::URandom).

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

🔡 hex

Returns the "oid" attributes as 24-byte hexadecimal value

🕒 get_time

Returns a number corresponding to the portion of the "oid" value that represents seconds since the epoch.

📤 TO_JSON

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

If the "BSON_EXTJSON" option is true, it will instead be compatible with MongoDB's extended JSON <https://github.com/mongodb/specifications/blob/master/source/extended-json.rst> format, which represents it as a document as follows:

{"$oid" : "012345678901234567890123"}

🔄 OVERLOAD

The string operator is overloaded so any string operations will actually use the 24-character hex value of the OID. Fallback overloading is enabled.

Both numeric comparison ("<=>") and string comparison ("cmp") are overloaded to do string comparison of the 24-character hex value of the OID. If used with a non-BSON::OID object, be sure to provide a 24-character hex string or the results are undefined.

🧵 THREADS

This module is thread safe.

👥 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 ⚙️ ATTRIBUTES 🔧 METHODS 🔄 OVERLOAD 🧵 THREADS 👥 AUTHORS ©️ COPYRIGHT AND LICENSE