Skip to content

dejanfajfar/epoch.net

Repository files navigation


GitHub Workflow Status (with event) Nuget Nuget (with prereleases)


👋 Introduction

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

using Epoch.net;

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

🤔 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 LongEpoch is theoretically limited only by the range of int64.

✅ Features

  • EpochTime a second precise POSIX time wrapper
  • LongEpochTime a millisecond precise POSIX time wrapper
  • Extension methods for build in time handling classes:
    • DateTime
    • TimeSpan
    • DateOnly
    • TimeOnly
  • Fully tested ;)

🏃‍♂️ Quick start

Add the package to yor project

The preferred way of integrating the library is to use the nuget package. This is easily done be either:

dotnet add package Epoch.net

or

Install-Package Epoch.net

Reference

After the package is added to the project add the using directive:

...
using Epoch.net;
...

Done 🎉

🦮 Helping out

Everyone can help in their own way.

Here are just some ideas:

  • Create a ticket with a improvement suggestion
  • Create a ticket with a bug or issue you may be having
  • Create a ticket with a question that you may be having
  • Have a look at the code and suggest improvements
  • Spread the word of its existence
  • And for the hardcore among you you can help me with the documentation 😈

🔗 Links

⏭️ Next steps

  • Consult the Wiki
  • Create a ticket to help the project improve