---
name: "BSON::OID"
section: "3pm"
platform: "linux"
package: "libbson-perl"
version: "1.12.2-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/BSON::OID"
---

# BSON::OID(3pm)

BSON type wrapper for Object IDs

## NAME

BSON::OID - BSON type wrapper for Object IDs

## VERSION

version v1.12.2

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

- •

  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
```