{
    "content": [
        {
            "type": "text",
            "text": "# MongoDB::DataTypes (perldoc)\n\n## NAME\n\nMongoDB::DataTypes - Using MongoDB data types with Perl\n\n## DESCRIPTION\n\nMongoDB stores typed data in a data format called BSON (<http://bsonspec.org/>). This document\ndescribes how to work with BSON data types in the MongoDB Perl driver.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **DESCRIPTION** (1 subsections)\n- **ESSENTIAL CONCEPTS** (3 subsections)\n- **NOTES ON SPECIFIC TYPES** (10 subsections)\n- **AUTHORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "MongoDB::DataTypes",
        "section": "",
        "mode": "perldoc",
        "summary": "MongoDB::DataTypes - Using MongoDB data types with Perl",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "VERSION",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 6,
                "subsections": [
                    {
                        "name": "Additional information",
                        "lines": 7
                    }
                ]
            },
            {
                "name": "ESSENTIAL CONCEPTS",
                "lines": 1,
                "subsections": [
                    {
                        "name": "MongoDB records are ordered documents",
                        "lines": 6
                    },
                    {
                        "name": "Type wrapper classes provide non-native and disambiguated types",
                        "lines": 27
                    },
                    {
                        "name": "Order sometimes matters a lot",
                        "lines": 39
                    }
                ]
            },
            {
                "name": "NOTES ON SPECIFIC TYPES",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Arrays",
                        "lines": 2
                    },
                    {
                        "name": "Documents",
                        "lines": 17
                    },
                    {
                        "name": "Numbers",
                        "lines": 33
                    },
                    {
                        "name": "Strings",
                        "lines": 7
                    },
                    {
                        "name": "Booleans",
                        "lines": 33
                    },
                    {
                        "name": "Object IDs",
                        "lines": 17
                    },
                    {
                        "name": "Regular Expressions",
                        "lines": 26
                    },
                    {
                        "name": "Dates",
                        "lines": 20
                    },
                    {
                        "name": "Binary Data",
                        "lines": 23
                    },
                    {
                        "name": "MinKey and MaxKey",
                        "lines": 11
                    }
                ]
            },
            {
                "name": "AUTHORS",
                "lines": 10,
                "subsections": []
            },
            {
                "name": "COPYRIGHT AND LICENSE",
                "lines": 6,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "MongoDB::DataTypes - Using MongoDB data types with Perl\n",
                "subsections": []
            },
            "VERSION": {
                "content": "version v2.2.2\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "MongoDB stores typed data in a data format called BSON (<http://bsonspec.org/>). This document\ndescribes how to work with BSON data types in the MongoDB Perl driver.\n\nAs of the MongoDB Perl driver v2.0.0, the driver relies on the external BSON library (and\noptional BSON::XS library) for converting between Perl data and the MongoDB BSON format.\n",
                "subsections": [
                    {
                        "name": "Additional information",
                        "content": "Additional information about MongoDB documents and types may be found in the following MongoDB\nmanual pages:\n\n*   Documents <https://docs.mongodb.com/manual/core/document/>\n\n*   BSON Types <https://docs.mongodb.com/manual/reference/bson-types/>\n"
                    }
                ]
            },
            "ESSENTIAL CONCEPTS": {
                "content": "",
                "subsections": [
                    {
                        "name": "MongoDB records are ordered documents",
                        "content": "A MongoDB record (i.e. \"row\") is a BSON document -- a list of key-value pairs, like a Perl hash\nexcept that the keys in a BSON document are ordered. Keys are always strings. Values can be any\nof 20+ BSON types.\n\nQueries and update specifications are also expressed as documents.\n"
                    },
                    {
                        "name": "Type wrapper classes provide non-native and disambiguated types",
                        "content": "In order to represent BSON types that don't natively exist in Perl, we use type wrapper classes\nfrom the BSON library, such as BSON::OID and BSON::Time.\n\nWrappers for native types are available when necessary to address limitations in Perl's type\nsystem. For example, one can use BSON::Doc for a ordered hash or BSON::Int64 for a 64-bit\ninteger.\n\nThe BSON class has attributes that configure how type wrappers are used during encoding and\ndecoding.\n\nThe PERL-BSON Type Mapping documentation has a detailed table of all BSON type conversions.\n\nString/number type conversion heuristics\nPerl's scalar values can have several underlying, internal representations such as double,\ninteger, or string (see perlguts). When encoding to BSON, the default behavior is as follows:\n\n*   If the value has a valid double representation, it will be encoded to BSON as a double.\n\n*   Otherwise, if the value has a valid integer interpretation, it will be encoded as either\nInt32 or Int64; the smallest type that the value fits will be used; a value that overflows\nwill error.\n\n*   Otherwise, the value will be encoded as a UTF-8 string.\n\nThe BSON library provides the \"prefernumeric\" attribute to more aggressively coerce number-like\nstrings that don't already have a numeric representation into a numeric form.\n"
                    },
                    {
                        "name": "Order sometimes matters a lot",
                        "content": "When writing a query document, the order of top level keys doesn't matter, but the order of keys\nin any embedded documents does matter.\n\n$coll->insertone({\nname => { first => \"John\", last => \"Doe\" },\nage => 42,\ncolor => \"blue\",\n});\n\n# Order doesn't matter here\n$coll->find( { age => 42, color => \"blue\" } );     # MATCH\n$coll->find( { color => \"blue\", age => 42 } );     # MATCH\n\n# Order *does* matter here\n$coll->find(\n{ name => { first => \"John\", last => \"Doe\" } } # MATCH\n);\n$coll->find(\n{ name => { last => \"Doe\", first => \"John\" } } # NO MATCH\n);\n\nWhen specifying a sort order or the order of keys for an index, order matters whenever there is\nmore than one key.\n\nBecause of Perl's hash order randomization, be very careful using native hashes with MongoDB.\nSee the \"Documents\" section below for specific guidance.\n\nTHE BSON::TYPES LIBRARY\nBSON::Types is a library with helper subroutines to easily create BSON type wrappers. Use of\nthis library is highly recommended.\n\nuse BSON::Types ':all';\n\n$int64   = bsonint64(42);         # force encoding more bits\n$decimal = bsondecimal(\"24.01\");  # Decimal128 type\n$time    = bsontime();            # now\n\nExamples in the rest of this document assume that all BSON::Types helper functions are loaded.\n"
                    }
                ]
            },
            "NOTES ON SPECIFIC TYPES": {
                "content": "",
                "subsections": [
                    {
                        "name": "Arrays",
                        "content": "BSON arrays encode and decode via Perl array references.\n"
                    },
                    {
                        "name": "Documents",
                        "content": "Because Perl's hashes guarantee key-order randomness, using hash references as documents will\nlead to BSON documents with a different key order. For top-level keys, this shouldn't cause\nproblems, but it may cause problems for embedded documents when querying, sorting or indexing on\nthe embedded document.\n\nFor sending data to the server, the BSON::Doc class provides a very lightweight wrapper around\nordered key-value pairs, but it's opaque.\n\n$doc = bsondoc( name => \"Larry\", color => \"purple\" );\n\nYou can also use Tie::IxHash for a more-interactive ordered document, but at the expense of\ntied-object overhead.\n\nThe BSON encoder has an \"ordered\" attribute that, if enabled, returns all documents as\norder-preserving tied hashes. This is slow, but is the only way to ensure that documents can\nroundtrip preserving key order.\n"
                    },
                    {
                        "name": "Numbers",
                        "content": "By default, the BSON decoder decodes doubles and integers into a Perl-native form. To maximize\nfidelity during a roundtrip, the decoder supports the wrapnumbers attribute to always decode to\na BSON type wrapper class with numeric overloading.\n\n32-bit Platforms\nOn a 32-bit platform, the BSON library treats Math::BigInt as the \"native\" type for integers\noutside the (signed) 32-bit range. Values that are encoded as 64-bit integers will be decoded as\nMath::BigInt objects.\n\n64-bit Platforms\nOn a 64-bit platform, (signed) Int64 values are supported, but, by default, numbers will be\nstored in the smallest BSON size needed. To force a 64-bit representation for numbers in the\nsigned 32-bit range, use a type wrapper:\n\n$int64 = bsonint64(0); # 64 bits of 0\n\nLong doubles\nOn a perl compiled with long-double support, floating point number precision will be lost when\nsending data to MongoDB.\n\nDecimal128\nMongoDB 3.4 adds support for the IEEE 754 Decimal128 type. The BSON::Decimal128 class is used as\na proxy for these values for both inserting and querying documents. Be sure to use strings when\nconstructing Decimal128 objects.\n\n$item = {\nname => \"widget\",\nprice => bsondecimal128(\"4.99\"), # 4.99 as a string\ncurrency => \"USD\",\n};\n\n$coll->insertone($item);\n"
                    },
                    {
                        "name": "Strings",
                        "content": "String values are expected to be character-data (not bytes). They are encoded as UTF-8 before\nbeing sent to the database and decoded from UTF-8 when received. If a string can't be decoded,\nan error will be thrown.\n\nTo save or query arbitrary, non-UTF8 bytes, use a binary type wrapper (see \"Binary Data\",\nbelow).\n"
                    },
                    {
                        "name": "Booleans",
                        "content": "Boolean values are emulated using the boolean package via the \"boolean::true\" and\n\"boolean::false\" functions. Using boolean objects in documents will ensure the documents have\nthe BSON boolean type in the database. Likewise, BSON boolean types in the database will be\nreturned as boolean objects.\n\nAn example of inserting boolean values:\n\nuse boolean;\n\n$collection->insertone({\"okay\" => true, \"name\" => \"fred\"});\n\nAn example of using boolean values for query operators (only returns documents where the name\nfield exists):\n\n$cursor = $collection->find({\"name\" => {'$exists' => true}});\n\nOften, you can just use 1 or 0 in query operations instead of \"true\" and \"false\", but some\ncommands require boolean objects and the database will return an error if integers 1 or 0 are\nused.\n\nBoolean objects from the following JSON libraries will also be encoded correctly in the\ndatabase:\n\n*   JSON::XS\n\n*   JSON::PP\n\n*   Cpanel::JSON::XS\n\n*   Mojo::JSON\n\n*   JSON::Tiny\n"
                    },
                    {
                        "name": "Object IDs",
                        "content": "The BSON object ID type (aka \"OID\") is a 12 byte identifier that ensures uniqueness by mixing a\ntimestamp and counter with host and process-specific bytes.\n\nAll MongoDB documents have an \"id\" field as a unique identifier. This field does not have to be\nan object ID, but if the field does not exist, an object ID is created automatically for it when\nthe document is inserted into the database.\n\nThe BSON::OID class is the type wrapper for object IDs.\n\nTo create a unique id:\n\n$oid = bsonoid();\n\nTo create a BSON::OID from an existing 24-character hexadecimal string:\n\n$oid = bsonoid(\"123456789012345678901234\");\n"
                    },
                    {
                        "name": "Regular Expressions",
                        "content": "Use \"qr/.../\" to use a regular expression in a query, but be sure to limit your regular\nexpression to syntax and features supported by PCRE, which are not fully compatible with Perl\n<https://en.wikipedia.org/wiki/PerlCompatibleRegularExpressions#DifferencesfromPerl>.\n\n$cursor = $collection->find({\"name\" => qr/[Jj]oh?n/});\n\nRegular expressions will match strings saved in the database.\n\nNOTE: only the following flags are supported: \"imsxlu\".\n\nYou can also save and retrieve regular expressions themselves, but regular expressions will be\nretrieved as BSON::Regex objects for safety (these will round-trip correctly).\n\nFrom that object, you can attempt to compile a reference to a \"qr{}\" using the \"trycompile\"\nmethod. However, due to PCRE differences, this could fail to compile or could have different\nmatch behavior than intended.\n\n$collection->insertone({\"regex\" => qr/foo/i});\n$obj = $collection->findone;\nif (\"FOO\" =~ $obj->{regex}->trycompile) { # matches\nprint \"hooray\\n\";\n}\n\nSECURITY NOTE: A regular expression can evaluate arbitrary code if \"use re 'eval'\" is in scope.\nYou are strongly advised never to use untrusted input as a regular expression.\n"
                    },
                    {
                        "name": "Dates",
                        "content": "BSON has a datetime type representing signed Int64 milliseconds relative to the Unix epoch. As\nof MongoDB v2.0.0, the lightweight BSON::Time wrapper is now the default wrapper for datetime\ndata.\n\nThe \"bsontime()\" helper function uses fractional epoch seconds, for better integration with the\nTime::HiRes module:\n\nuse Time::HiRes 'time';\n\n$later = bsontime( time() + 60 );\n\nFor convenience, The default value for the helper is \"Time::HiRes::time\":\n\n$now = bsontime();\n\nBSON::Time has methods for inflating into various popular Perl date classes, including DateTime,\nTime::Moment and DateTime::Tiny. The BSON encoder can also encode objects of these types, with\nlimitations on precision and timezone based on the underlying class. For example, DateTime::Tiny\nhas no time zone or sub-second precision.\n"
                    },
                    {
                        "name": "Binary Data",
                        "content": "By default, all database strings are UTF-8. To store images, binaries, and other non-UTF-8 data,\none can use the BSON binary data type via the BSON::Bytes wrapper.\n\nThe BSON binary type includes the notion of a \"subtype\" attribute, which can be any integer\nbetween 0 and 255. The meaning of subtypes from 0 to 127 are reserved for definition by MongoDB;\nvalues 128 to 255 are user-defined. Binary data values will only match in a MongoDB query if\nboth the binary bytes and the subtypes are the same. The default subtype is 0 (a.k.a. \"generic\nbinary data\") and generally should not be modified.\n\nTo roundtrip binary data, use the BSON::Bytes wrapper:\n\n# non-utf8 string\n$bytes = \"\\xFF\\xFE\\xFF\";\n\n$collection->insertone({\"photo\" => bsonbytes($bytes)});\n\nBinary data will be decoded into a BSON::Bytes object. It stringifies as the underlying bytes\nfor convenience.\n\nOne can also store binary data by using a string reference.\n\n$collection->insertone({\"photo\" => \\$bytes});\n"
                    },
                    {
                        "name": "MinKey and MaxKey",
                        "content": "BSON::MinKey is \"less than\" any other value of any type. This can be useful for always returning\ncertain documents first.\n\nBSON::MaxKey is \"greater than\" any other value of any type. This can be useful for always\nreturning certain documents last.\n\nThere is a helper function for each:\n\n$min = bsonminkey();\n$max = bsonmaxkey();\n"
                    }
                ]
            },
            "AUTHORS": {
                "content": "*   David Golden <david@mongodb.com>\n\n*   Rassi <rassi@mongodb.com>\n\n*   Mike Friedman <friedo@friedo.com>\n\n*   Kristina Chodorow <k.chodorow@gmail.com>\n\n*   Florian Ragwitz <rafl@debian.org>\n",
                "subsections": []
            },
            "COPYRIGHT AND LICENSE": {
                "content": "This software is Copyright (c) 2020 by MongoDB, Inc.\n\nThis is free software, licensed under:\n\nThe Apache License, Version 2.0, January 2004\n",
                "subsections": []
            }
        }
    }
}