BSON::Time(3pm)

💖 BSON::Time 💖

okay bestie, welcome to BSON::Time — that's BSON::Time(3pm), from the User Contributed Perl Documentation collection. It's the BSON type wrapper for date and time, and yes it's exactly as iconic as it sounds. 🕰️✨

VERSION — this is version v1.12.2. 💅

---

✨ SYNOPSIS ✨

use BSON::Types ':all';

bson_time();        # now
bson_time( $secs ); # floating point seconds since epoch

that's it. that's the whole vibe. one function, two moods. 🫶

---

🌸 DESCRIPTION 🌸

This module is a BSON type wrapper for a 64-bit date-time value, and it holds that value in the form of milliseconds since the Unix epoch — UTC only, no local-time nonsense here, we stay consistent. ⭐

🚨 heads up bestie: on a Perl that doesn't have 64-bit integer support, the value must be a Math::BigInt object. no cap, it's required.

---

🎀 ATTRIBUTES 🎀

💫 value

An integer representing milliseconds since the Unix epoch. The default is 0. (yes, literally zero, the epoch itself, time zero, the beginning of everything 🦋)

---

👑 METHODS 👑

💅 epoch

Returns the number of seconds since the epoch — as in, a floating-point value. she converts for you, periodt.

💅 as_iso8601

Returns the value as an ISO-8601 formatted string, and the form is exactly:

"YYYY-MM-DDThh:mm:ss.sssZ"

The fractional seconds will be omitted if they are zero. tiny detail, big energy. ✨

💅 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. smol but mighty. 🐣

💅 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. the moment? captured. 📸

💅 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 format — the spec lives at:

https://github.com/mongodb/specifications/blob/master/source/extended-json.rst

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 format (same spec link, same energy):

https://github.com/mongodb/specifications/blob/master/source/extended-json.rst

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. so she behaves in math and in strings, no extra steps required. 🔥

---

🌈 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

---

okay and for the cute sign-off: this whole thing came to you courtesy of perl v5.30.3, dated 2020-08-14, and it's BSON::Time(3pm) bestie — go timestamp something gorgeous. 🎀💖✨