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

hex

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 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@mongodb.com>

Stefan G. <minimalist@lavabit.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 by Stefan G. and MongoDB, Inc.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

Module Install Instructions

To install BSON::OID, simply copy and paste either of the commands in to your terminal

As a valued partner and proud supporter of MetaCPAN, StickerYou is
happy to offer a 10% discount on all Custom Stickers,
Business Labels, Roll Labels,
Vinyl Lettering or Custom Decals. StickerYou.com
is your one-stop shop to make your business stick.
Use code METACPAN10 at checkout to apply your discount.