Description

Simple portable wrapper for handling POSIX Time (ie Unix Time)

Package Information

Version0.1.0 (2016-Aug-09)
Homepagehttps://github.com/rfarr/UnixTime-D
Repositoryhttps://github.com/rfarr/UnixTime-D
LicenseISC
AuthorsRichard Farr
Registered byRichard Farr
Dependenciesnone

Installation

To use this package, put the following dependency into your project's dependencies section:

dub.json
dub.sdl

Readme

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 necessitate 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.

As of right now just Linux and FreeBSD are supported.

Linux
ClockTypeclockid_t
REALTIMECLOCK_REALTIME
MONOTONICCLOCK_MONOTONIC
SECOND(uses core.stdc.time)
REALTIME_PRECISECLOCK_REALTIME
REALTIME_FASTCLOCKREALTIMECOARSET
MONOTONIC_FASTCLOCKMONOTONICCOARSE
MONOTONIC_PRECISECLOCKMONOTONICRAW
UPTIMECLOCK_BOOTTIME
UPTIME_FASTCLOCK_BOOTTIME
UPTIME_PRECISECLOCK_BOOTTIME
FreeBSD
ClockTypeclockid_t
REALTIMECLOCK_REALTIME
MONOTONICCLOCK_MONOTONIC
SECONDCLOCK_SECOND
REALTIME_PRECISECLOCKREALTIMEPRECISE
REALTIME_FASTCLOCKREALTIMEFAST
MONOTONIC_FASTCLOCKMONOTONICFAST
MONOTONIC_PRECISECLOCKMONOTONICPRECISE
UPTIMECLOCK_UPTIME
UPTIME_FASTCLOCKUPTIMEFAST
UPTIME_PRECISECLOCKUPTIMEPRECISE

Author

Richard Farr, <richard@nxbit.io>

Copyright (c) 2016, 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.

Available versions

0.1.0 ~master ~v0.2.0