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

Version: 1.0.3

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 (including weekend and workday predicates)
  • 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() {
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);
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;
}
constexpr T get_days_difference(ts_t start, ts_t stop) noexcept
Get the number of days between two timestamps.
TIME_SHIELD_CONSTEXPR ts_t end_of_year(ts_t ts=time_shield::ts())
Get the end-of-year timestamp.
const std::string to_iso8601_utc_ms(ts_ms_t ts_ms)
Converts a timestamp in milliseconds to an ISO8601 string in UTC format.
bool str_to_ts_ms(const std::string &str, ts_ms_t &ts)
Convert an ISO8601 string to a millisecond timestamp (ts_ms_t).
int64_t ts_t
Unix timestamp in seconds since 1970‑01‑01T00:00:00Z.
Definition types.hpp:46
int64_t ts_ms_t
Unix timestamp in milliseconds since epoch.
Definition types.hpp:47
ts_t timestamp() noexcept
Get the current UTC timestamp in seconds.
int main()
Main header file for the Time Shield library.

Additional example files are located in the examples/ folder:

Workday helpers

Check whether a moment falls on a business day using timestamps, calendar components, or ISO8601 strings:

using namespace time_shield;
bool monday = is_workday(1710720000); // Unix seconds (2024-03-18)
bool monday_ms = is_workday_ms("2024-03-18T09:00:00.250Z"); // ISO8601 with milliseconds
bool from_date = is_workday(2024, 3, 18); // year, month, day components
// Parsing failure or a weekend evaluates to false
bool saturday = is_workday("2024-03-16T10:00:00Z");
bool invalid = is_workday("not-a-date");
bool is_workday(const std::string &str)
Parse an ISO8601 string and check if it falls on a workday using second precision.
bool is_workday_ms(const std::string &str)
Parse an ISO8601 string and check if it falls on a workday using millisecond precision.
Main namespace for the Time Shield library.
Header file with functions for parsing dates and times in ISO8601 format and converting them to vario...
Header file with time-related validation functions.

Locate the first and last trading days for a month and constrain schedules to the opening or closing workdays:

using namespace time_shield;
ts_t june28 = to_timestamp(2024, 6, 28);
bool is_last = is_last_workday_of_month(june28); // true (Friday before a weekend)
bool in_last_two = is_within_last_workdays_of_month(june28, 2); // true for the final two workdays
bool in_first_two = is_within_first_workdays_of_month(june28, 2);// false, trailing end of month
bool first_from_str = is_first_workday_of_month("2024-09-02T09:00:00Z");
bool window_from_str = is_within_first_workdays_of_month_ms(
"2024-09-03T09:00:00.250Z", 2);
TIME_SHIELD_CONSTEXPR bool is_within_first_workdays_of_month(year_t year, int month, int day, int count) noexcept
Check whether a date is within the first N workdays of its month.
TIME_SHIELD_CONSTEXPR bool is_within_first_workdays_of_month_ms(ts_ms_t ts_ms, int count) noexcept
Check whether a timestamp in milliseconds falls within the first N workdays of its month.
TIME_SHIELD_CONSTEXPR bool is_last_workday_of_month(year_t year, int month, int day) noexcept
Check whether a date is the last workday of its month.
TIME_SHIELD_CONSTEXPR bool is_first_workday_of_month(year_t year, int month, int day) noexcept
Check whether a date is the first workday of its month.
TIME_SHIELD_CONSTEXPR bool is_within_last_workdays_of_month(year_t year, int month, int day, int count) noexcept
Check whether a date is within the last N workdays of its month.
TIME_SHIELD_CONSTEXPR ts_t to_timestamp(const T &date_time)
Alias for dt_to_timestamp function.

The string overloads recognise the same ISO8601 formats handled by str_to_ts and str_to_ts_ms.

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.