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:
std::cout << "Days until end of year: " << days << std::endl;
std::string formatted_time = time_shield::to_iso8601_str(future_ts);
std::cout << "Error occurred while parsing ISO8601 string" << std::endl;
return -1;
}
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.
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.
int64_t ts_ms_t
Unix timestamp in milliseconds since epoch.
ts_t timestamp() noexcept
Get the current UTC timestamp in seconds.
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:
bool saturday =
is_workday(
"2024-03-16T10:00:00Z");
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:
"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.