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.10.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_double
69           $double = bson_double( 1.0 );
70
71       This function returns a BSON::Double object wrapping a native double
72       value.  This ensures it serializes to BSON as a double rather than a
73       string or integer given Perl's lax typing for scalars.
74
75   bson_int32
76           $int32 = bson_int32( 42 );
77
78       This function returns a BSON::Int32 object wrapping a native integer
79       value.  This ensures it serializes to BSON as an Int32 rather than a
80       string or double given Perl's lax typing for scalars.
81
82   bson_int64
83           $int64 = bson_int64( 0 ); # 64-bit zero
84
85       This function returns a BSON::Int64 object, wrapping a native integer
86       value.  This ensures it serializes to BSON as an Int64 rather than a
87       string or double given Perl's lax typing for scalars.
88
89   bson_maxkey
90           $maxkey = bson_maxkey();
91
92       This function returns a singleton representing the "maximum key" BSON
93       type.
94
95   bson_minkey
96           $minkey = bson_minkey();
97
98       This function returns a singleton representing the "minimum key" BSON
99       type.
100
101   bson_oid
102           $oid = bson_oid();         # generate a new one
103           $oid = bson_oid( $bytes ); # from 12-byte packed OID
104           $oid = bson_oid( $hex   ); # from 24 hex characters
105
106       This function returns a BSON::OID object wrapping a 12-byte MongoDB
107       Object ID.  With no arguments, a new, unique Object ID is generated
108       instead.  If 24 hexadecimal characters are given, they will be packed
109       into a 12-byte Object ID.
110
111   bson_raw
112           $raw = bson_raw( $bson_encoded );
113
114       This function returns a BSON::Raw object wrapping an already BSON-
115       encoded document.
116
117   bson_regex
118           $regex = bson_regex( $pattern );
119           $regex = bson_regex( $pattern, $flags );
120
121       This function returns a BSON::Regex object wrapping a PCRE pattern and
122       optional flags.
123
124   bson_string
125           $string = bson_string( "08544" );
126
127       This function returns a BSON::String object, wrapping a native string
128       value.  This ensures it serializes to BSON as a UTF-8 string rather
129       than an integer or double given Perl's lax typing for scalars.
130
131   bson_time
132           $time = bson_time( $seconds_from_epoch );
133
134       This function returns a BSON::Time object representing a UTC date and
135       time to millisecond precision.  The argument must be given as a number
136       of seconds relative to the Unix epoch (positive or negative).  The
137       number may be a floating point value for fractional seconds.  If no
138       argument is provided, the current time from Time::HiRes is used.
139
140   bson_timestamp
141           $timestamp = bson_timestamp( $seconds_from_epoch, $increment );
142
143       This function returns a BSON::Timestamp object.  It is not recommended
144       for general use.
145
146   bson_bool (DISCOURAGED)
147           # for consistency with other helpers
148           $bool = bson_bool( $expression );
149
150           # preferred for efficiency
151           use boolean;
152           $bool = boolean( $expression );
153
154       This function returns a boolean object (true or false) based on the
155       provided expression (or false if no expression is provided).  It is
156       provided for consistency so that all BSON types have a corresponding
157       helper function.
158
159       For efficiency, use "boolean::boolean()" directly, instead.
160

AUTHORS

162       ·   David Golden <david@mongodb.com>
163
164       ·   Stefan G. <minimalist@lavabit.com>
165

167       This software is Copyright (c) 2018 by Stefan G. and MongoDB, Inc.
168
169       This is free software, licensed under:
170
171         The Apache License, Version 2.0, January 2004
172
173
174
175perl v5.28.1                      2018-12-07                    BSON::Types(3)
Impressum