Time Shield Library
C++ library for working with time
Loading...
Searching...
No Matches
Time Shield Library

Version: 1.0.2

Introduction

The Time Shield Library is a comprehensive C++ library designed for time manipulation, formatting, and conversion. It was built for practical and engineering tasks, especially in constrained or performance-critical environments.

Why Time Shield?

Unlike std::chrono or more academic libraries like HowardHinnant/date, Time Shield is designed to be simple, portable, and suitable for scenarios like logging, serialization, MQL5 usage, and date/time formatting.

  • Uses simple types (int64_t, double) like ts_t, fts_t for timestamps — easy to serialize and store.
  • Supports multiple time representations: Unix, floating-point seconds, ms/us precision, OLE Automation, Julian dates.
  • Includes utilities for rounding, ISO8601 formatting/parsing, time parts, and boundary calculations.
  • Header-only and cross-platform; most modules require only STL and <cstdint>.
  • MQL5-compatible — does not use exceptions, STL containers, or dynamic memory.
  • Modules requiring platform-specific APIs (like NtpClient) are isolated and optional.

Features

  • Validation of dates and times
  • Time and date formatting (standard and custom)
  • Time zone conversion functions
  • ISO8601 string parsing
  • Utilities for time manipulation and conversion

Configuration

Compile-time macros in time_shield/config.hpp allow adapting the library to the target platform and toggling optional modules:

  • TIME_SHIELD_PLATFORM_WINDOWS / TIME_SHIELD_PLATFORM_UNIX — platform detection.
  • TIME_SHIELD_HAS_WINSOCK — WinSock availability.
  • TIME_SHIELD_ENABLE_NTP_CLIENT — builds the NTP client when set to 1.

All public symbols are declared inside the time_shield namespace.

API Invariants

  • ts_t represents Unix time in seconds as a signed 64-bit integer with microsecond precision available through conversions.
  • fts_t stores time as double precision seconds; conversions maintain microsecond accuracy.
  • ISO8601 parsing assumes the proleptic Gregorian calendar without leap seconds.
  • Functions avoid throwing exceptions and use no dynamic memory internally; utilities returning std::string rely on the caller for allocations.

Examples

Here is a simple demonstration:

#include <time_shield.hpp>
int main() {
time_shield::ts_t current_ts = time_shield::timestamp();
time_shield::ts_t future_ts = time_shield::end_of_year(current_ts);
int days = time_shield::get_days_difference(current_ts, future_ts);
std::cout << "Days until end of year: " << days << std::endl;
std::string formatted_time = time_shield::to_iso8601_str(future_ts);
time_shield::ts_ms_t ts_ms = 0;
if (!time_shield::str_to_ts_ms(formatted_time, ts_ms)) {
std::cout << "Error occurred while parsing ISO8601 string" << std::endl;
return -1;
}
formatted_time = time_shield::to_iso8601_utc_ms(ts_ms);
std::cout << "Future time: " << formatted_time << std::endl;
return 0;
}
time_shield::get_days_difference
constexpr T get_days_difference(ts_t start, ts_t stop) noexcept
Get the number of days between two timestamps.
Definition time_conversions.hpp:864
time_shield::end_of_year
TIME_SHIELD_CONSTEXPR ts_t end_of_year(ts_t ts=time_shield::ts())
Get the end-of-year timestamp.
Definition time_conversions.hpp:1202
time_shield::to_iso8601_utc_ms
const std::string to_iso8601_utc_ms(ts_ms_t ts_ms)
Converts a timestamp in milliseconds to an ISO8601 string in UTC format.
Definition time_formatting.hpp:615
time_shield::str_to_ts_ms
bool str_to_ts_ms(const std::string &str, ts_ms_t &ts)
Convert an ISO8601 string to a millisecond timestamp (ts_ms_t).
Definition time_parser.hpp:251
time_shield::ts_t
int64_t ts_t
Unix timestamp in seconds since 1970‑01‑01T00:00:00Z.
Definition types.hpp:46
time_shield::ts_ms_t
int64_t ts_ms_t
Unix timestamp in milliseconds since epoch.
Definition types.hpp:47
time_shield::timestamp
ts_t timestamp() noexcept
Get the current UTC timestamp in seconds.
Definition time_utils.hpp:136
main
int main()
Definition ntp_client_example.cpp:16
time_shield.hpp
Main header file for the Time Shield library.

Additional example files are located in the examples/ folder:

Installation

Install and find_package

After installing the library (e.g., via cmake --install), locate it with find_package:

cmake_minimum_required(VERSION 3.15)
project(app LANGUAGES CXX)
find_package(TimeShield CONFIG REQUIRED)
add_executable(app main.cpp)
target_link_libraries(app PRIVATE time_shield::time_shield)

Git submodule with add_subdirectory

Vendor the library as a submodule:

git submodule add https://github.com/NewYaroslav/time-shield-cpp external/time-shield-cpp

Then include it:

add_subdirectory(external/time-shield-cpp)
add_executable(app main.cpp)
target_link_libraries(app PRIVATE time_shield::time_shield)

vcpkg overlay

Install via a local overlay port:

vcpkg install time-shield-cpp --overlay-ports=./vcpkg-overlay/ports

Use the vcpkg toolchain when configuring CMake:

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

The port is intended to be upstreamed to microsoft/vcpkg.

For MQL5/MetaTrader, run install_mql5.bat to copy the .mqh files to your include directory.

To build the C++ examples use the helper scripts:

  • build-examples.bat for Windows
  • build_examples.sh for Linux/macOS
  • build-cb.bat to generate a Code::Blocks project

Tested Platforms

Platform Compilers C++ Standards
Windows MSVC, ClangCL 11, 14, 17
Linux GCC, Clang 11, 14, 17
macOS Apple Clang 11, 14, 17

Online Documentation

The latest generated API reference is available at newyaroslav.github.io/time-shield-cpp.

Repository

Time Shield Library GitHub repository

License

This library is licensed under the MIT License. See the LICENSE file for more details.