---
name: "Mango::BSON"
section: "3pm"
platform: "linux"
package: "libmango-perl"
version: "1.30-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Mango::BSON"
---

# Mango::BSON(3pm)

BSON

## NAME

Mango::BSON - BSON

## SYNOPSIS

```
  use Mango::BSON ':bson';
  my $bson = bson_encode {
    foo       => 'bar',
    baz       => 0.42,
    unordered => {one => [1, 2, 3], two => bson_time},
    ordered   => bson_doc(one => qr/test/i, two => bson_true)
  };
  my $doc = bson_decode $bson;
```

## DESCRIPTION

Mango::BSON is a minimalistic implementation of \<http://bsonspec.org\>.

In addition to a bunch of custom BSON data types it supports normal Perl data types like scalar, regular expression, `"undef"`, array reference, hash reference and will try to call the `"TO_BSON"` and `"TO_JSON"` methods on blessed references, or stringify them if it doesn't exist. Scalar references will be used to generate booleans, based on if their values are true or false.

## FUNCTIONS

Mango::BSON implements the following functions, which can be imported individually or at once with the `":bson"` flag.

### bson\_bin

```
  my $bin = bson_bin $bytes;
```

Create new BSON element of the binary type with Mango::BSON::Binary, defaults to the `"generic"` binary subtype.

```
  # Function
  bson_bin($bytes)->type('function');
  # MD5
  bson_bin($bytes)->type('md5');
  # UUID
  bson_bin($bytes)->type('uuid');
  # User defined
  bson_bin($bytes)->type('user_defined');
```

### bson\_code

```
  my $code = bson_code 'function () {}';
```

Create new BSON element of the code type with Mango::BSON::Code.

```
  # With scope
  bson_code('function () {}')->scope({foo => 'bar'});
```

### bson\_dbref

```
  my $dbref = bson_dbref 'test', $oid;
```

Create a new database reference.

```
  # Longer version
  my $dbref = {'$ref' => 'test', '$id' => $oid};
```

### bson\_decode

```
  my $doc = bson_decode $bson;
```

Decode BSON into Perl data structures.

### bson\_doc

```
  my $doc = bson_doc;
  my $doc = bson_doc foo => 'bar', baz => 0.42, yada => {yada => [1, 2, 3]};
```

Create new BSON document with Mango::BSON::Document, which can also be used as a generic ordered hash.

```
  # Order is preserved
  my $hash = bson_doc one => 1, two => 2, three => 3;
  $hash->{four} = 4;
  delete $hash->{two};
  say for keys %$hash;
```

### bson\_double

```
  my $doc = { foo => bson_double(13.0) };
```

Force a scalar value to be encoded as a double in MongoDB. Croaks if the value is incompatible with the double type.

### bson\_encode

```
  my $bson = bson_encode $doc;
  my $bson = bson_encode {};
```

Encode Perl data structures into BSON.

### bson\_false

```
  my $false = bson_false;
```

Create new BSON element of the boolean type false.

### bson\_int32

```
  my $doc = { foo => bson_int32(13) };
  # This will die (integer is too big)
  my $doc = { foo => bson_int32(2147483648) };
```

Force a scalar value to be encoded as a 32 bit integer in MongoDB. Croaks if the value is incompatible with the int32 type.

### bson\_int64

```
  my $doc = { foo => bson_int64(666) };
```

Force a scalar value to be encoded as a 64 bit integer in MongoDB. Croaks if the value is incompatible with the int64 type.

### bson\_length

```
  my $len = bson_length $bson;
```

Check BSON length prefix.

### bson\_max

```
  my $max_key = bson_max;
```

Create new BSON element of the max key type.

### bson\_min

```
  my $min_key = bson_min;
```

Create new BSON element of the min key type.

### bson\_oid

```
  my $oid = bson_oid;
  my $oid = bson_oid '1a2b3c4e5f60718293a4b5c6';
```

Create new BSON element of the object id type with Mango::BSON::ObjectID, defaults to generating a new unique object id.

```
  # Generate object id with specific epoch time
  my $oid = bson_oid->from_epoch(1359840145);
```

### bson\_raw

```
  my $raw = bson_raw $bson;
```

Pre-encoded BSON document.

```
  # Longer version
  my $raw = {'$bson' => $bson};
  # Embed pre-encoded BSON document
  my $first  = bson_encode {foo => 'bar'};
  my $second = bson_encode {test => bson_raw $first};
```

### bson\_time

```
  my $now  = bson_time;
  my $time = bson_time time * 1000;
```

Create new BSON element of the UTC datetime type with Mango::BSON::Time, defaults to milliseconds since the UNIX epoch.

```
  # "1360626536.748"
  bson_time(1360626536748)->to_epoch;
  # "2013-02-11T23:48:56.748Z"
  bson_time(1360626536748)->to_datetime;
```

### bson\_true

```
  my $true = bson_true;
```

Create new BSON element of the boolean type true.

### bson\_ts

```
  my $timestamp = bson_ts 23, 24;
```

Create new BSON element of the timestamp type with Mango::BSON::Timestamp.

### encode\_cstring

```
  my $bytes = encode_cstring $cstring;
```

Encode cstring.

## SEE ALSO

Mango, Mojolicious::Guides, \<http://mojolicio.us\>.