1BSON::Types(3) User Contributed Perl Documentation BSON::Types(3)
2
6 BSON::Types - Helper functions to wrap BSON type classes
7
9 version v1.12.2
10
12 use BSON::Types ':all';
13 $int32 = bson_int32(42);
15 $double = bson_double(3.14159);
16 $decimal = bson_decimal("24.01");
17 $time = bson_time(); # now
18 ...
19
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 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
32 bson_bytes
33 $bytes = bson_bytes( $byte_string );
34 $bytes = bson_bytes( $byte_string, $subtype );
35 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 bson_code
41 $code = bson_code( $javascript );
42 $code = bson_code( $javascript, $hashref );
43 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 bson_dbref
49 $dbref = bson_dbref( $object_id, $collection_name );
50 This function returns a BSON::DBRef object wrapping the provided Object
52 ID and collection name.
53 bson_decimal128
55 $decimal = bson_decimal128( "0.12" );
56 $decimal = bson_decimal128( "1.23456789101112131415116E-412" );
57 This function returns a BSON::Decimal128 object wrapping the provided
59 decimal string. Unlike floating point values, this preserves exact
60 decimal precision.
61 bson_doc
63 $doc = bson_doc( first => "hello, second => "world" );
64 This function returns a BSON::Doc object, which preserves the order of
66 the provided key-value pairs.
67 bson_array
69 $doc = bson_array(...);
70 This function returns a BSON::Array object, which preserves the order
72 of the provided list of elements.
73 bson_double
75 $double = bson_double( 1.0 );
76 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 bson_int32
82 $int32 = bson_int32( 42 );
83 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 bson_int64
89 $int64 = bson_int64( 0 ); # 64-bit zero
90 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 bson_maxkey
96 $maxkey = bson_maxkey();
97 This function returns a singleton representing the "maximum key" BSON
99 type.
100 bson_minkey
102 $minkey = bson_minkey();
103 This function returns a singleton representing the "minimum key" BSON
105 type.
106 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 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 bson_raw
118 $raw = bson_raw( $bson_encoded );
119 This function returns a BSON::Raw object wrapping an already BSON-
121 encoded document.
122 bson_regex
124 $regex = bson_regex( $pattern );
125 $regex = bson_regex( $pattern, $flags );
126 This function returns a BSON::Regex object wrapping a PCRE pattern and
128 optional flags.
129 bson_string
131 $string = bson_string( "08544" );
132 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 bson_time
138 $time = bson_time( $seconds_from_epoch );
139 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 bson_timestamp
147 $timestamp = bson_timestamp( $seconds_from_epoch, $increment );
148 This function returns a BSON::Timestamp object. It is not recommended
150 for general use.
151 bson_bool (DISCOURAGED)
153 # for consistency with other helpers
154 $bool = bson_bool( $expression );
155 # preferred for efficiency
157 use boolean;
158 $bool = boolean( $expression );
159 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 For efficiency, use boolean::boolean() directly, instead.
166
168 • David Golden <david@mongodb.com>
169 • Stefan G. <minimalist@lavabit.com>
171
173 This software is Copyright (c) 2020 by Stefan G. and MongoDB, Inc.
174 This is free software, licensed under:
176 The Apache License, Version 2.0, January 2004
178perl v5.38.0 2023-07-20 BSON::Types(3)