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

# BSON::Time(3pm)

BSON type wrapper for date and time

## NAME

BSON::Time - BSON type wrapper for date and time

## VERSION

version v1.12.2

## SYNOPSIS

```
    use BSON::Types ':all';
    bson_time();        # now
    bson_time( $secs ); # floating point seconds since epoch
```

## DESCRIPTION

This module provides a BSON type wrapper for a 64-bit date-time value in the form of milliseconds since the Unix epoch (UTC only).

On a Perl without 64-bit integer support, the value must be a Math::BigInt object.

## ATTRIBUTES

### value

A integer representing milliseconds since the Unix epoch.  The default is 0.

## METHODS

### epoch

Returns the number of seconds since the epoch (i.e. a floating-point value).

### as\_iso8601

Returns the `"value"` as an ISO-8601 formatted string of the form `"YYYY-MM-DDThh:mm:ss.sssZ"`.  The fractional seconds will be omitted if they are zero.

### as\_datetime

Loads DateTime and returns the `"value"` as a DateTime object.

### as\_datetime\_tiny

Loads DateTime::Tiny and returns the `"value"` as a DateTime::Tiny object.

### as\_mango\_time

Loads Mango::BSON::Time and returns the `"value"` as a Mango::BSON::Time object.

### as\_time\_moment

Loads Time::Moment and returns the `"value"` as a Time::Moment object.

### TO\_JSON

Returns a string formatted by "as\_iso8601".

If the `"BSON_EXTJSON"` option is true, it will instead be compatible with MongoDB's extended JSON \<https://github.com/mongodb/specifications/blob/master/source/extended-json.rst\> format, which represents it as a document as follows:

If the `"BSON_EXTJSON"` environment variable is true and the `"BSON_EXTJSON_RELAXED"` environment variable is false, returns a hashref compatible with MongoDB's extended JSON \<https://github.com/mongodb/specifications/blob/master/source/extended-json.rst\> format, which represents it as a document as follows:

```
    {"$date" : { "$numberLong": "22337203685477580" } }
```

If the `"BSON_EXTJSON"` and `"BSON_EXTJSON_RELAXED"` environment variables are both true, then it will return a hashref with an ISO-8601 string for dates after the Unix epoch and before the year 10,000 and a `$numberLong` style value otherwise.

```
    {"$date" : "2012-12-24T12:15:30.500Z"}
    {"$date" : { "$numberLong": "-10000000" } }
```

## OVERLOADING

Both numification (`"0+"`) and stringification (`""`) are overloaded to return the result of "epoch".  Numeric comparison and string comparison are overloaded based on those and fallback overloading is enabled.

## AUTHORS

- •

  David Golden \<david@mongodb.com\>

- •

  Stefan G. \<minimalist@lavabit.com\>

## COPYRIGHT AND LICENSE

This software is Copyright (c) 2020 by Stefan G. and MongoDB, Inc.

This is free software, licensed under:

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