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

NAME

6       BSON::Types - Helper functions to wrap BSON type classes
7

VERSION

9       version v1.12.2
10

SYNOPSIS

12           use BSON::Types ':all';
13
14           $int32   = bson_int32(42);
15           $double  = bson_double(3.14159);
16           $decimal = bson_decimal("24.01");
17           $time    = bson_time(); # now
18           ...
19

DESCRIPTION

21       This module provides helper functions for BSON type wrappers.  Type
22       wrappers use objects corresponding to BSON types to represent data that
23       would have ambiguous type or don't have a native Perl representation
24
25       For example, because Perl scalars can represent strings, integers or
26       floating point numbers, the serialization rules depend on various
27       heuristics.  By wrapping a Perl scalar with a class, such as
28       BSON::Int32, users can specify exactly how a scalar should serialize to
29       BSON.
30

FUNCTIONS

32   bson_bytes
33           $bytes = bson_bytes( $byte_string );
34           $bytes = bson_bytes( $byte_string, $subtype );
35
36       This function returns a BSON::Bytes object wrapping the provided
37       string.  A numeric subtype may be provided as a second argument, but
38       this is not recommended for new applications.
39
40   bson_code
41           $code = bson_code( $javascript );
42           $code = bson_code( $javascript, $hashref );
43
44       This function returns a BSON::Code object wrapping the provided
45       Javascript code.  An optional hashref representing variables in scope
46       for the function may be given as well.
47
48   bson_dbref
49           $dbref = bson_dbref( $object_id, $collection_name );
50
51       This function returns a BSON::DBRef object wrapping the provided Object
52       ID and collection name.
53
54   bson_decimal128
55           $decimal = bson_decimal128( "0.12" );
56           $decimal = bson_decimal128( "1.23456789101112131415116E-412" );
57
58       This function returns a BSON::Decimal128 object wrapping the provided
59       decimal string.  Unlike floating point values, this preserves exact
60       decimal precision.
61
62   bson_doc
63           $doc = bson_doc( first => "hello, second => "world" );
64
65       This function returns a BSON::Doc object, which preserves the order of
66       the provided key-value pairs.
67
68   bson_array
69           $doc = bson_array(...);
70
71       This function returns a BSON::Array object, which preserves the order
72       of the provided list of elements.
73
74   bson_double
75           $double = bson_double( 1.0 );
76
77       This function returns a BSON::Double object wrapping a native double
78       value.  This ensures it serializes to BSON as a double rather than a
79       string or integer given Perl's lax typing for scalars.
80
81   bson_int32
82           $int32 = bson_int32( 42 );
83
84       This function returns a BSON::Int32 object wrapping a native integer
85       value.  This ensures it serializes to BSON as an Int32 rather than a
86       string or double given Perl's lax typing for scalars.
87
88   bson_int64
89           $int64 = bson_int64( 0 ); # 64-bit zero
90
91       This function returns a BSON::Int64 object, wrapping a native integer
92       value.  This ensures it serializes to BSON as an Int64 rather than a
93       string or double given Perl's lax typing for scalars.
94
95   bson_maxkey
96           $maxkey = bson_maxkey();
97
98       This function returns a singleton representing the "maximum key" BSON
99       type.
100
101   bson_minkey
102           $minkey = bson_minkey();
103
104       This function returns a singleton representing the "minimum key" BSON
105       type.
106
107   bson_oid
108           $oid = bson_oid();         # generate a new one
109           $oid = bson_oid( $bytes ); # from 12-byte packed OID
110           $oid = bson_oid( $hex   ); # from 24 hex characters
111
112       This function returns a BSON::OID object wrapping a 12-byte MongoDB
113       Object ID.  With no arguments, a new, unique Object ID is generated
114       instead.  If 24 hexadecimal characters are given, they will be packed
115       into a 12-byte Object ID.
116
117   bson_raw
118           $raw = bson_raw( $bson_encoded );
119
120       This function returns a BSON::Raw object wrapping an already BSON-
121       encoded document.
122
123   bson_regex
124           $regex = bson_regex( $pattern );
125           $regex = bson_regex( $pattern, $flags );
126
127       This function returns a BSON::Regex object wrapping a PCRE pattern and
128       optional flags.
129
130   bson_string
131           $string = bson_string( "08544" );
132
133       This function returns a BSON::String object, wrapping a native string
134       value.  This ensures it serializes to BSON as a UTF-8 string rather
135       than an integer or double given Perl's lax typing for scalars.
136
137   bson_time
138           $time = bson_time( $seconds_from_epoch );
139
140       This function returns a BSON::Time object representing a UTC date and
141       time to millisecond precision.  The argument must be given as a number
142       of seconds relative to the Unix epoch (positive or negative).  The
143       number may be a floating point value for fractional seconds.  If no
144       argument is provided, the current time from Time::HiRes is used.
145
146   bson_timestamp
147           $timestamp = bson_timestamp( $seconds_from_epoch, $increment );
148
149       This function returns a BSON::Timestamp object.  It is not recommended
150       for general use.
151
152   bson_bool (DISCOURAGED)
153           # for consistency with other helpers
154           $bool = bson_bool( $expression );
155
156           # preferred for efficiency
157           use boolean;
158           $bool = boolean( $expression );
159
160       This function returns a boolean object (true or false) based on the
161       provided expression (or false if no expression is provided).  It is
162       provided for consistency so that all BSON types have a corresponding
163       helper function.
164
165       For efficiency, use boolean::boolean() directly, instead.
166

AUTHORS

168       •   David Golden <david@mongodb.com>
169
170       •   Stefan G. <minimalist@lavabit.com>
171
173       This software is Copyright (c) 2020 by Stefan G. and MongoDB, Inc.
174
175       This is free software, licensed under:
176
177         The Apache License, Version 2.0, January 2004
178
179
180
181perl v5.36.0                      2023-01-20                    BSON::Types(3)
Impressum