On Apache
Under GNU General Public License
2024-05-18 17:15 @3.137.170.14 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
BSON::OID(3pm) User Contributed Perl Documentation BSON::OID(3pm)
NAME
BSON::OID - BSON type wrapper for Object IDs
VERSION
version v1.12.1
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
o David Golden <david AT mongodb.com>
o Stefan G. <minimalist AT lavabit.com>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2019 by Stefan G. and MongoDB, Inc.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
perl v5.28.1 2019-08-17 BSON::OID(3pm)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-05-18 17:15 @3.137.170.14 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)