unixtime 0.2.3

Unix Time

Simple and portable D wrapper for POSIX Time (aka Unix Time)

Rationale

While D has good datetime support from std.datetime, the internal representation is always kept in stdtime (hecto-nanoseconds since Jan 1, 0 AD). This necessitates constant conversion to/from stdtime when all you want to deal with good ol' fashioned Unix Time.

UnixTime also allows you to more easily get at the raw clock values on your system and allows full nanosecond resolution (assuming your arch supports it).

It is also very simple (no TZ or date formatting/parsing) and basically tries to do the least amount of work while still doing the "right thing" when all you want to get at is some clock values.

Converting to/from UnixTime/SysTime is easy via the provided methods so when you need it you have all the power of std.datetime at your disposal.

Basic Usage

import unixtime : UnixTime, UnixTimeHiRes;

auto hiResNow = UnixTimeHiRes.now();

writeln(hiResNow.seconds); // 1470292916
writeln(hiResNow.nanos); // 473318461


auto lowResNow = UnixTime.now();

writeln(lowResNow.seconds); // 1470292916

Addition and Subtraction

// Basic addition of timestamps
UnixTime(500) + UnixTime(250); // UnixTime(750)
UnixTime(500) + UnixTime(-750); // UnixTime(-250)
UnixTime(time_t.max) + UnixTime(1); // overflow, throws exception

// And subtraction
UnixTime(500) - UnixTime(250); // UnixTime(250)
UnixTime(500) - UnixTime(-750); // UnixTime(1250)
UnixTime(time_t.min) - UnixTime(1); // underflow, throws exception

// Same thing with hi res, nanos will cause seconds to roll over
UnixTimeHiRes(500, 100) + UnixTimeHiRes(250, 250); // UnixTimeHiRese(750, 350)
UnixTimeHiRes(500) + UnixTimeHiRes(0, -500); // UnixTime(499, 999_999_500)
UnixTimeHiRes(time_t.max, 999_999_999) + UnixTimeHiRes(0, 1); // overflow, throws exception

// Can mix and match hi res and normal, will return hi res
UnixTime(500) - UnixTimeHiRes(250); // UnixTimeHiRes(250, 0)
UnixTimeHiRes(500, 250) - UnixTime(-750); // UnixTimeHiRes(1250, 250)
UnixTime(time_t.min) - UnixTime(1); // underflow, throws exception

Parsing / Display

UnixTime.parse("123"); // UnixTime(123)
UnixTimeHiRes.parse("123.123"); // UnixTimeHiRes(123, 123000000)

to!string(UnixTime(123)); // "123"
to!string(UnixTimeHiRes(123, 123000000)); // "123.123000000"

Conversion to/from SysTime

cast(SysTime) UnixTime(0); // SysTime(1970-Jan-1 00:00:00 UTC)
cast(SysTime) UnixTimeHiRes(123, 123000000); // SysTime(1970-Jan-1 00:02:03.123 UTC)
cast(SysTime) UnixTime(time_t.max); // throws exception, SysTime can't represent this timestamp

UnixTime(SysTime.min); // UnixTime(-984472800485)
UnixTimeHiRes(SysTime.max); // UnixTimeHiRes(860201606885, 477580700)

Multiple clock support

// Pass the clock you want as template parameter
auto realtime = UnixTime.now!(ClockType.REALTIME)();
auto monotonic = UnixTime.now!(ClockType.MONOTONIC)();
auto boot = UnixTime.now!(ClockType.UPTIME)();

// Also can just pass it in as a runtime parameter
realtime = UnixTime.now(ClockType.REALTIME);
monotonic = UnixTime.now(ClockType.MONOTONIC);
boot = UnixTime.now(ClockType.UPTIME);

NOTE: Clock support is of course architecture and kernel dependent. Not all clocks are available so in many cases you may get the same clock regardless of your ClockType.

Currently supported OSes are Linux, FreeBSD, and MacOS. MacOS uses emulation to get to Unix time. Since Sierra this should not be neccessary but I haven't updated the code to support it. PRs welcome :)

Linux

FreeBSD

Author

Richard Farr, <richard@nxbit.io>

Copyright & License

Copyright (c) 2016-2019, Richard Farr Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.