epoch.net

A simple and non-intrusive library for all your epoch needs

using Epoch.net;

...
var timestamp = EpochTime.Now;
...

v3 breaking changes

with the new v3 some breaking changes have happened!

Methods were replaced by properties and the Error Types have changed.

If something is too broken please feel free to scream at me in the chat:

What is an Epoch

Epoch is shorthand for Unix epoch time or as it is also known POSIX time.

Short version: The number of seconds since 1970-01-01T00:00:00Z without leap seconds.

Long version: unix time

Motivation

With .net core working on all major operating systems and most of them using POSIX to denote time and timestamps. Not to mention the myriad of 3rd party tools, using POSIX time internally. The need for a working and tested implementation became clearer and clearer. Additionally I did not want to write this logic in an inferior form in many of my applications. So this little library was written.

Its sole purpose is to make the work with these unix timestamps as easy as possible.

For this purpose this library contains extension methods that build upon the existing DateTime, TimeSpan, int and long types.

Glossary

Term	Description
EpochTime	Represents a POSIX time instance exact to the second
EpochTimestamp	The number of seconds since 1970-01-01T00:00Z
LongEpochTime	Represents a POSIX time instance exact to the millisecond
LongEpochTimestamp	The number of milliseconds since 1970-01-01T00:00Z

Difference between EpochTime and LongEpochTime

The initial difference was precision. EpochTime will only be accurate to the nearest second on the other hand LongEpochTime is accurate to the millisecond. From this precision difference I decided to differentiate then by their underlying base type.

EpochTime is based on int32 / int

LongEpochTime is based on int64 / long

This is sadly implies that if you get a POSIX timestamp from somewhere you, the developer, have to know if it is representing milliseconds or seconds!

Ranges

Unit	Min value	Max value
EpochTimestamp	-2147483648	2147483647
LongEpochTimestamp	-922337203685477	922337203685477

Note: The range of the LongEpochTimestamp and LongEpoch is theoretically limited only by the range of int64. If left like this some timestamps could not be represented by the TimeSpan structure.

Installation

Installation is simple as installing any other nuget package

dotnet add package Epoch.net

Install-Package Epoch.net

Quick How-Tos

Before you go and start looking for answers in the wiki here a few common scenarios and their suggested solutions.

Current time to EpochTime

using Epoch.net;

var timestamp = EpochTime.Now;

or use the provided extension method on the DateTime structure

using Epoch.net;

var timestamp = DateTime.Now.ToEpochTime();

The same is true for a LongEpochTime

using Epoch.net;

var timestamp = LongEpochTime.Now;

using Epoch.net;

var timestamp = DateTime.Now.ToLongEpochTime();

Get a DateTime from a epoch timestamp

using Epoch.net;

int timestamp = 1547931356;

var date = new EpochTime(timestamp).DateTime;

or use the extension method on the integer

using Epoch.net

int timestamp = 1547931356;

var date = timestamp.ToDateTime();

The same can be done with a LongEpochTimestamp

using Epoch.net;

long timestamp = 1547931356567;

var date = new LongEpochTime(timestamp).DateTime;

using Epoch.net

long timestamp = 1547931356;

var date = timestamp.ToDateTime();

Determine the time span between two epoch timestamps

using Epoch.net;

int timestamp1 = 1540425600;
int timestamp2 = 1547931356;

var epoch1 = new EpochTime(timestamp1);
var epoch2 = new EpochTime(timestamp2);

var epochDif = epoch2 - epoch1;

var timeSpan = epochDif.ToTimeSpan();

or we again use some provided extension methods

using Epoch.net

int timestamp1 = 1540425600;
int timestamp2 = 1547931356;

var timeSpan = (timestamp1 - timestamp2).ToTimeSpan();

And much more...

More scenarios can be found in the wiki...

Next steps

Check out the chat

Or the wiki (if I have created one yet) :)

shanerogers / epoch.net