# BSON::OID - BSON type wrapper for Object IDs - perldoc - [phpMan]

## NAME
    [BSON::OID](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AOID/markdown) - BSON type wrapper for Object IDs

## VERSION
    version v1.12.2

## SYNOPSIS
        use [BSON::Types](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3ATypes/markdown) ':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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AOID/markdown)->new;

        my $oid = [BSON::OID](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AOID/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AOID/markdown)->from_epoch( $epoch, 0); # other bytes zeroed
        my $oid = [BSON::OID](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AOID/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AOID/markdown) 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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AOID/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AOID/markdown)->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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AOID/markdown)->[from_epoch(1467545180)](https://www.chedong.com/phpMan.php/man/fromepoch/1467545180/markdown);

    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](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3AURandom/markdown)).

      use [Crypt::Random](https://www.chedong.com/phpMan.php/perldoc/Crypt%3A%3ARandom/markdown) 'urandom';
      my $oid = [BSON::OID](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AOID/markdown)->from_epoch(1467545180, [urandom(8)](https://www.chedong.com/phpMan.php/man/urandom/8/markdown));

  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](https://www.chedong.com/phpMan.php/perldoc/BSON%3A%3AOID/markdown) 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) 2020 by Stefan G. and MongoDB, Inc.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004