---
name: "MongoDB::BSON"
section: "3pm"
platform: "linux"
package: "libmongodb-perl"
version: "1.4.5-1+b1"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/MongoDB::BSON"
---

# MongoDB::BSON(3pm)

Tools for serializing and deserializing data in BSON form

## NAME

MongoDB::BSON - Tools for serializing and deserializing data in BSON form

## VERSION

version v1.4.5

## SYNOPSIS

```
    my $codec = MongoDB::BSON->new;
    my $bson = $codec->encode_one( $document );
    my $doc  = $codec->decode_one( $bson     );
```

## DESCRIPTION

This class implements a BSON encoder/decoder ("codec").  It consumes documents and emits BSON strings and vice versa.

## ATTRIBUTES

### dbref\_callback

A document with keys `$ref` and `$id` is a special MongoDB convention representing a DBRef \<http://docs.mongodb.org/manual/applications/database-references/#dbref\>.

This attribute specifies a function reference that will be called with a hash reference argument representing a DBRef.

The hash reference will have keys `$ref` and `$id` and may have `$db` and other keys.  The callback must return a scalar value representing the dbref (e.g. a document, an object, etc.)

The default `"dbref_callback"` returns the DBRef hash reference without modification.

Note: in MongoDB::MongoClient, when no MongoDB::BSON object is provided as the `"bson_codec"` attribute, \<MongoDB:MongoClient\> creates a **custom** MongoDB::BSON object that inflates DBRefs into MongoDB::DBRef objects using a custom `"dbref_callback"`:

```
    dbref_callback => sub { return MongoDB::DBRef->new(shift) },
```

Object-database mappers may wish to implement alternative `"dbref_callback"` attributes to provide whatever semantics they require.

### dt\_type

Sets the type of object which is returned for BSON DateTime fields. The default is DateTime. Other acceptable values are Time::Moment, DateTime::Tiny and `"undef"`. The latter will give you the raw epoch value (possibly as a floating point value) rather than an object.

### error\_callback

This attribute specifies a function reference that will be called with three positional arguments:

- •

  an error string argument describing the error condition

- •

  a reference to the problematic document or byte-string

- •

  the method in which the error occurred (e.g. `"encode_one"` or `"decode_one"`)

Note: for decoding errors, the byte-string is passed as a reference to avoid copying possibly large strings.

If not provided, errors messages will be thrown with `"Carp::croak"`.

### invalid\_chars

A string containing ASCII characters that must not appear in keys.  The default is the empty string, meaning there are no invalid characters.

### max\_length

This attribute defines the maximum document size. The default is 0, which disables any maximum.

If set to a positive number, it applies to both encoding **and** decoding (the latter is necessary for prevention of resource consumption attacks).

### op\_char

This is a single character to use for special operators.  If a key starts with `"op_char"`, the `"op_char"` character will be replaced with "$".

The default is "$".

### prefer\_numeric

If set to true, scalar values that look like a numeric value will be encoded as a BSON numeric type.  When false, if the scalar value was ever used as a string, it will be encoded as a BSON UTF-8 string.

The default is false.

## METHODS

### encode\_one

```
    $byte_string = $codec->encode_one( $doc );
    $byte_string = $codec->encode_one( $doc, \%options );
```

Takes a "document", typically a hash reference, an array reference, or a Tie::IxHash object and returns a byte string with the BSON representation of the document.

An optional hash reference of options may be provided.  Valid options include:

- •

  first\_key – if `"first_key"` is defined, it and `"first_value"` will be encoded first in the output BSON; any matching key found in the document will be ignored.

- •

  first\_value - value to assign to `"first_key"`; will encode as Null if omitted

- •

  error\_callback – overrides codec default

- •

  invalid\_chars – overrides codec default

- •

  max\_length – overrides codec default

- •

  op\_char – overrides codec default

- •

  prefer\_numeric – overrides codec default

### decode\_one

```
    $doc = $codec->decode_one( $byte_string );
    $doc = $codec->decode_one( $byte_string, \%options );
```

Takes a byte string with a BSON-encoded document and returns a hash reference representin the decoded document.

An optional hash reference of options may be provided.  Valid options include:

- •

  dbref\_callback – overrides codec default

- •

  dt\_type – overrides codec default

- •

  error\_callback – overrides codec default

- •

  max\_length – overrides codec default

### clone

```
    $codec->clone( dt_type => 'Time::Moment' );
```

Constructs a copy of the original codec, but allows changing attributes in the copy.

## AUTHORS

- •

  David Golden \<david@mongodb.com\>

- •

  Mike Friedman \<friedo@friedo.com\>

- •

  Kristina Chodorow \<k.chodorow@gmail.com\>

- •

  Florian Ragwitz \<rafl@debian.org\>

## COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by MongoDB, Inc.

This is free software, licensed under:

```
  The Apache License, Version 2.0, January 2004
```