BSON::OID - BSON type wrapper for Object IDs

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

       •   David Golden <david@mongodb.com>

       •   Stefan G. <minimalist@lavabit.com>

       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

perl v5.40.1                                       2025-04-16                                     BSON::OID(3pm)

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

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"}

       BSON::OID - BSON type wrapper for Object IDs

       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.

           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;

       This module is thread safe.

       version v1.12.2