.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "BSON::OID 3pm"
.TH BSON::OID 3pm "2020-08-14" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BSON::OID \- BSON type wrapper for Object IDs
.SH "VERSION"
.IX Header "VERSION"
version v1.12.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use BSON::Types \*(Aq:all\*(Aq;
\&
\& my $oid = bson_oid();
\& my $oid = bson_oid\->from_epoch(1467543496, 0); # for queries only
\&
\& my $bytes = $oid\->oid;
\& my $hex = $oid\->hex;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a wrapper around a \s-1BSON\s0 Object
\&\s-1ID\s0 .
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "oid"
.IX Subsection "oid"
A 12\-byte (packed) Object \s-1ID\s0 (\s-1OID\s0) string. If not provided, a new \s-1OID\s0
will be generated.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 1
\& my $oid = BSON::OID\->new;
\&
\& my $oid = BSON::OID\->new( oid => $twelve_bytes );
.Ve
.PP
This is the preferred way to generate an \s-1OID.\s0 Without arguments, a
unique \s-1OID\s0 will be generated. With a 12\-byte string, an object can
be created around an existing \s-1OID\s0 byte-string.
.SS "from_epoch"
.IX Subsection "from_epoch"
.Vb 1
\& # 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 );
.Ve
.PP
\&\fBWarning!\fR You should not rely on this method for a source of unique IDs.
Use this method for query boundaries, only.
.PP
An \s-1OID\s0 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.
.PP
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.
.PP
When called as a class method, it returns a new \s-1BSON::OID\s0 object. When
called as an object method, it mutates the existing internal \s-1OID\s0 value.
.PP
As a special case, if the second argument is \fBdefined\fR and zero (\*(L"0\*(R"),
then the remaining bytes will be zeroed.
.PP
.Vb 1
\& my $oid = BSON::OID\->from_epoch(1467545180, 0);
.Ve
.PP
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.
.PP
For backwards compatibility with Mango, if called without a second
argument, the method generates the remainder of the fields \*(L"like usual\*(R".
This is equivalent to calling \f(CW\*(C`BSON::OID\->new\*(C'\fR and replacing the first
four bytes with the packed epoch value.
.PP
.Vb 1
\& # UNSAFE: don\*(Aqt do this unless you have to
\&
\& my $oid = BSON::OID\->from_epoch(1467545180);
.Ve
.PP
If you insist on creating a unique \s-1OID\s0 with \f(CW\*(C`from_epoch\*(C'\fR, set the
remaining eight bytes in a way that guarantees thread-safe uniqueness, such
as from a reliable source of randomness (see Crypt::URandom).
.PP
.Vb 2
\& use Crypt::Random \*(Aqurandom\*(Aq;
\& my $oid = BSON::OID\->from_epoch(1467545180, urandom(8));
.Ve
.SS "hex"
.IX Subsection "hex"
Returns the \f(CW\*(C`oid\*(C'\fR attributes as 24\-byte hexadecimal value
.SS "get_time"
.IX Subsection "get_time"
Returns a number corresponding to the portion of the \f(CW\*(C`oid\*(C'\fR value that
represents seconds since the epoch.
.SS "\s-1TO_JSON\s0"
.IX Subsection "TO_JSON"
Returns a string for this \s-1OID,\s0 with the \s-1OID\s0 given as 24 hex digits.
.PP
If the \f(CW\*(C`BSON_EXTJSON\*(C'\fR option is true, it will instead be compatible with
MongoDB's extended \s-1JSON\s0
format, which represents it as a document as follows:
.PP
.Vb 1
\& {"$oid" : "012345678901234567890123"}
.Ve
.SH "OVERLOAD"
.IX Header "OVERLOAD"
The string operator is overloaded so any string operations will actually use
the 24\-character hex value of the \s-1OID.\s0 Fallback overloading is enabled.
.PP
Both numeric comparison (\f(CW\*(C`<=>\*(C'\fR) and string comparison (\f(CW\*(C`cmp\*(C'\fR) are
overloaded to do string comparison of the 24\-character hex value of the
\&\s-1OID.\s0 If used with a non\-BSON::OID object, be sure to provide a
24\-character hex string or the results are undefined.
.SH "THREADS"
.IX Header "THREADS"
This module is thread safe.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden
.IP "\(bu" 4
Stefan G.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2020 by Stefan G. and MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\& The Apache License, Version 2.0, January 2004
.Ve