-
-
13 Aug 2020 14:58:11 UTC
- Distribution: BSON
- Module version: v1.12.2
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues
- Testers
- Kwalitee
Bus factor: 1- 79.73% Coverage
- License: apache_2_0
- Perl: v5.10.1
- Activity
24 month- Tools
- Download (113.14KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 13 contributors-
David Golden
-
Stefan G.
-
Eric Daniels
-
Finn
-
Olivier Duclos
-
Pat Gunn
-
Petr Písař
-
Robert Sedlacek
-
Thomas Bloor
-
Tobias Leich
-
Wallace Reis
-
Yury Zavarin
-
Oleg Kostyuk
- Dependencies
- B
- Carp
- Crypt::URandom
- Exporter
- List::Util
- MIME::Base64
- Math::BigFloat
- Math::BigInt
- Moo
- Scalar::Util
- Sys::Hostname
- Tie::IxHash
- Time::HiRes
- Time::Local
- base
- boolean
- constant
- if
- mro
- namespace::clean
- overload
- re
- strict
- threads::shared
- version
- warnings
- Reverse dependencies
- CPAN Testers List
- Dependency graph
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.
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 valueget_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 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
Module Install Instructions
To install BSON, copy and paste the appropriate command in to your terminal.
cpanm BSON
perl -MCPAN -e shell install BSON
For more information on module installation, please visit the detailed CPAN module installation guide.