MAIN

# Date & Time C++ Note

This posts illustrate my note upon studying on date & time features in C++ categorized in related topics.

Most of date & time features are directly from C language standard. Anyway there’s equivalent one presented in C++20 namely std::chrono ref.

Most of STL functions here defined in <ctime> header.

## Structures

STL Names Note
std::tm Structure holding a calendar date and time broken down into its components.
std::time_t Arithmetic type capable of representing time. It’s almost always an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC, corresonding to POSIX time. Mostly use this to represent wall-clock time in precision of seconds.
std::clock_t Arithmetic type capable of representing the process running time of implementation-defined range and precision. Suitable for measure running time used by a process in (mostly) precision of nanosecond.

## Creating Time

STL Names Note
std::mktime Convert a calender time std::tm to epoch time std::time_t.
std::localtime Convert an epoch time std::time_t to calendar time std::tm expressed in local time.
std::gmtime Convert an epoch time std::time_t to calendar time std::tm in Coordinated Universal Time (UTC).

## Getting Time

STL Names Note
std::time Get the current calendar time encoded as epoch time std::time_t. It will store the result in input std::time_t if input is not NULL. Be ware of 32-bit implementation of std::time will fail in the year 2038.
std::clock Get approximate processor time used by the process since the beginning of an implementation-defined related to the program’s execution. Divide the result with CLOCKS_PER_SEC to get value expressed in seconds. Only difference between two values are meaningful. Note that time expressed in std::clock may advance faster than wall-clock if such process is multithreaded and more than one execution core is available, but it may advance slower if CPU is shared by other processes. In short, to measure execution time used by a process, use std::clock to precisely measure rather than use wall-clock like std::time.
std::chrono::high_resolution_clock Get precise current wall-clock time (usually down to nanosecond at most). It’s type alias from std::chrono::system_clock to represent the clock “with the shortest tick period” until higher-than-nanosecond definitions become feasible.
std::chrono::system_clock Get precise current wall-clock time. It is the clock “with the shortest tick period”. It’s the only time which relates and is convertible to C-style time. It’s not a monotonic clock thus can be adjusted by system if system time changes at any moment. So for mission critical in measuring intervals, better use std::chrono::steady_clock.
std::chrono::steady_clock It’s a monotonic clock which is the most suitable one to be used for measuring intervals i.e. benchmarking. It is not affected / adjusted by system as the system time progresses, only move forward.

## Utility

STL Names Note
std::difftime Compute difference between twos epoch time std::time_t then return result in seconds. The first parameter is end-time, if not then the result is in negative.
std::strftime Format the input calendar time std::tm. See std::strftime for detail on format string.

## Representation

STL Names Note
std::ctime Convert an epoch time std::time_t to calendar local time std::tm internally then return result in textual representation. It is the same as calling std::asctime(std::localtime(time)).
std::asctime Convert a calendar time std::tm to texture representation.

## Code Examples

I’ve done demonstration code covering almost all above, see it at DateTime.cpp.

Also note the top code comment on how to compile the program.

## Update

Oct, 13, 2019

• Added clear note that std::chrono::system_clock is not the best option to use in measuring intervals for mission critical like benchmarking.
• Added std::chrono::steady_clock which is the right tool for measuring intervals; a monotonic clock.

Dec, 01, 2019

• Fixed several grammar errors.

First published on Oct, 8, 2019

Written by Wasin Thonkaew
In case of reprinting, comments, suggestions
or to do anything with the article in which you are unsure of, please
write e-mail to wasin[add]wasin[dot]io