DateTimeLib

Gas-Efficient Solidity DateTime Library

Conventions

All dates, times and Unix timestamps are UTC.

All functions operate on the uint256 timestamp data type.

Functions

daysFromDate

Calculate the number of days days from 1970/01/01 to year/month/day.

function daysFromDate(uint256 y, uint256 m, uint d) public pure returns (uint256 day)

NOTE This function does not validate the year/month/day input. Use isValidDate(...) to validate the input if necessary.

daysToDate

Calculate year/month/day from the number of days days since 1970/01/01 .

function daysToDate(uint256 _days) public pure returns (uint256 year, uint256 month, uint256 day)

timestampFromDate

Calculate the timestamp to year/month/day.

function timestampFromDate(uint256 year, uint256 month, uint256 day) public pure returns (uint timestamp)

NOTE This function does not validate the year/month/day input. Use isValidDate(...) to validate the input if necessary.

timestampToDate

Calculate year/month/day from timestamp.

function timestampToDate(uint256 t) public pure returns (uint256 y, uint256 m, uint256 d)

isValidDate

Is the date specified by year/month/day a valid date?

function isValidDate(uint256 year, uint256 month, uint256 day) internal pure returns (bool valid)

getDaysInMonth

Return number of day in the month daysInMonth for the month specified by year/month.

function getDaysInMonth(uint256 y, uint256 m) internal pure returns (uint256 d)

getDayOfWeek

Return the day of the week weekday (0 = Monday,1 = Tuesday ..., 6 = Sunday) for the date specified by timestamp.

function getWeekDay(uint256 t) internal pure returns (uint256 weekday) 

getNthDayOfWeekInMonthOfYear

Return timestamp of the Nth dayOfWeek from the year/month.

function getNthDayOfWeekInMonthOfYear(uint256 y, uint256 m, uint256 n, uint256 wd) internal pure returns (uint256 t)

NOTE This function does not validate the year/month and wd input. Use isValidDate(...) to validate for year/month and wd must be in range of [0,6].

Example :

// get 3th Friday of November 2022
getNthDayOfWeekInMonthOfYear(2022,11,3,4) -> 1668729600  //18th November 2022 00:00:00 UTC

getNextWeekDay

Return timestamp of next week day from timestamp and wd.

function getNextWeekDay(uint256 t, uint256 wd) internal pure returns (uint256 _timestamp)

Example :

// get next friday (current date is 6th November 2022)
getNextWeekDay(1667724375,4) -> 1668124800  //11th November 2022 00:00:00 UTC

Safety

This is experimental software and is provided on an "as is" and "as available" basis.

We do not give any warranties and will not be liable for any loss incurred through any use of this codebase.

Installation

To install with Foundry:

forge install Atarpara/DateTimeLib

To install with Hardhat or Truffle:

npm install

Acknowledgements

This repository is inspired by or directly modified from many sources, primarily:

• solady
• BokkyPooBahsDateTimeLibrary

References

A copy of the webpage with the algorithm Date Time Algorithm.