1BSON::OID(3)          User Contributed Perl Documentation         BSON::OID(3)
2
3
4

NAME

6       BSON::OID - BSON type wrapper for Object IDs
7

VERSION

9       version v1.12.2
10

SYNOPSIS

12           use BSON::Types ':all';
13
14           my $oid  = bson_oid();
15           my $oid  = bson_oid->from_epoch(1467543496, 0); # for queries only
16
17           my $bytes = $oid->oid;
18           my $hex   = $oid->hex;
19

DESCRIPTION

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

ATTRIBUTES

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

METHODS

30   new
31           my $oid = BSON::OID->new;
32
33           my $oid = BSON::OID->new( oid => $twelve_bytes );
34
35       This is the preferred way to generate an OID.  Without arguments, a
36       unique OID will be generated.  With a 12-byte string, an object can be
37       created around an existing OID byte-string.
38
39   from_epoch
40           # generate a new OID
41
42           my $oid = BSON::OID->from_epoch( $epoch, 0); # other bytes zeroed
43           my $oid = BSON::OID->from_epoch( $epoch, $eight_more_bytes );
44
45           # reset an existing OID
46
47           $oid->from_epoch( $new_epoch, 0 );
48           $oid->from_epoch( $new_epoch, $eight_more_bytes );
49
50       Warning! You should not rely on this method for a source of unique IDs.
51       Use this method for query boundaries, only.
52
53       An OID is a twelve-byte string.  Typically, the first four bytes
54       represent integer seconds since the Unix epoch in big-endian format.
55       The remaining bytes ensure uniqueness.
56
57       With this method, the first argument to this method is an epoch time
58       (in integer seconds).  The second argument is the remaining eight-bytes
59       to append to the string.
60
61       When called as a class method, it returns a new BSON::OID object.  When
62       called as an object method, it mutates the existing internal OID value.
63
64       As a special case, if the second argument is defined and zero ("0"),
65       then the remaining bytes will be zeroed.
66
67           my $oid = BSON::OID->from_epoch(1467545180, 0);
68
69       This is particularly useful when looking for documents by their
70       insertion date: you can simply look for OIDs which are greater or lower
71       than the one generated with this method.
72
73       For backwards compatibility with Mango, if called without a second
74       argument, the method generates the remainder of the fields "like
75       usual".  This is equivalent to calling "BSON::OID->new" and replacing
76       the first four bytes with the packed epoch value.
77
78           # UNSAFE: don't do this unless you have to
79
80           my $oid = BSON::OID->from_epoch(1467545180);
81
82       If you insist on creating a unique OID with "from_epoch", set the
83       remaining eight bytes in a way that guarantees thread-safe uniqueness,
84       such as from a reliable source of randomness (see Crypt::URandom).
85
86         use Crypt::Random 'urandom';
87         my $oid = BSON::OID->from_epoch(1467545180, urandom(8));
88
89   hex
90       Returns the "oid" attributes as 24-byte hexadecimal value
91
92   get_time
93       Returns a number corresponding to the portion of the "oid" value that
94       represents seconds since the epoch.
95
96   TO_JSON
97       Returns a string for this OID, with the OID given as 24 hex digits.
98
99       If the "BSON_EXTJSON" option is true, it will instead be compatible
100       with MongoDB's extended JSON
101       <https://github.com/mongodb/specifications/blob/master/source/extended-
102       json.rst> format, which represents it as a document as follows:
103
104           {"$oid" : "012345678901234567890123"}
105

OVERLOAD

107       The string operator is overloaded so any string operations will
108       actually use the 24-character hex value of the OID.  Fallback
109       overloading is enabled.
110
111       Both numeric comparison ("<=>") and string comparison ("cmp") are
112       overloaded to do string comparison of the 24-character hex value of the
113       OID.  If used with a non-BSON::OID object, be sure to provide a
114       24-character hex string or the results are undefined.
115

THREADS

117       This module is thread safe.
118

AUTHORS

120       •   David Golden <david@mongodb.com>
121
122       •   Stefan G. <minimalist@lavabit.com>
123

125       This software is Copyright (c) 2020 by Stefan G. and MongoDB, Inc.
126
127       This is free software, licensed under:
128
129         The Apache License, Version 2.0, January 2004
130
131
132
133perl v5.36.0                      2023-01-20                      BSON::OID(3)
Impressum