GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
BSON::OID(3) User Contributed Perl Documentation BSON::OID(3)

BSON::OID - BSON type wrapper for Object IDs

version v1.12.2

    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 provides a wrapper around a BSON Object ID <https://docs.mongodb.com/manual/reference/method/ObjectId/>.

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

    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.

    # 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));

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

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

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

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.

This module is thread safe.

  • 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
2020-08-13 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.