{"id":19534855,"url":"https://github.com/newyaroslav/time-shield-cpp","last_synced_at":"2026-03-14T22:36:38.552Z","repository":{"id":242907232,"uuid":"809180100","full_name":"NewYaroslav/time-shield-cpp","owner":"NewYaroslav","description":"Header-only comprehensive C++ library designed for time manipulation, formatting, and conversion.","archived":false,"fork":false,"pushed_at":"2025-12-16T06:20:43.000Z","size":4561,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-18T02:15:00.266Z","etag":null,"topics":["date-time-formatting","datetime","iso-week","iso8601","jdn","moon-phase","mql5","ntp","time","time-formatting","time-utility","time-utils","time-zone","timer","timestamp","ts","utc"],"latest_commit_sha":null,"homepage":"https://newyaroslav.github.io/time-shield-cpp/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NewYaroslav.png","metadata":{"files":{"readme":"README-RU.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-06-01T23:47:43.000Z","updated_at":"2025-12-16T06:20:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"34fa771e-46da-4bd8-9c66-d28adc9371f3","html_url":"https://github.com/NewYaroslav/time-shield-cpp","commit_stats":null,"previous_names":["newyaroslav/time-shield-cpp"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/NewYaroslav/time-shield-cpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NewYaroslav%2Ftime-shield-cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NewYaroslav%2Ftime-shield-cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NewYaroslav%2Ftime-shield-cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NewYaroslav%2Ftime-shield-cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NewYaroslav","download_url":"https://codeload.github.com/NewYaroslav/time-shield-cpp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NewYaroslav%2Ftime-shield-cpp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30520627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-14T19:51:21.629Z","status":"ssl_error","status_checked_at":"2026-03-14T19:51:12.959Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["date-time-formatting","datetime","iso-week","iso8601","jdn","moon-phase","mql5","ntp","time","time-formatting","time-utility","time-utils","time-zone","timer","timestamp","ts","utc"],"created_at":"2024-11-11T02:16:20.603Z","updated_at":"2026-03-14T22:36:38.536Z","avatar_url":"https://github.com/NewYaroslav.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Time Shield\n\n\u003cimg src=\"docs/logo-1280x640.png\" alt=\"Логотип\" width=\"600\"/\u003e\n\n![MIT License](https://img.shields.io/badge/license-MIT-green.svg)\n![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20MQL5-blue)\n![C++ Standard](https://img.shields.io/badge/C++-11--17-orange)\n![CI Windows](https://img.shields.io/github/actions/workflow/status/newyaroslav/time-shield-cpp/ci.yml?branch=main\u0026label=Windows\u0026logo=windows)\n![CI Linux](https://img.shields.io/github/actions/workflow/status/newyaroslav/time-shield-cpp/ci.yml?branch=main\u0026label=Linux\u0026logo=linux)\n![CI macOS](https://img.shields.io/github/actions/workflow/status/newyaroslav/time-shield-cpp/ci.yml?branch=main\u0026label=macOS\u0026logo=apple)\n\n**Time Shield** — это header-only C++-библиотека для работы со временем. Она включает функции для конвертации временных значений, форматирования дат и множество утилит для задач с таймстампами.\n\u003e Названа в честь «временного щита» Хомуры Акэми.\n\n## Быстрый старт\n\n```cpp\n#include \u003ctime_shield.hpp\u003e\n\nusing namespace time_shield;\n\nts_t now = ts();\nstd::string iso = to_iso8601(now);\nts_t gmt = cet_to_gmt(now);\nbool monday = is_workday(now);\n```\n\nИспользуйте `#include \u003ctime_shield.hpp\u003e` для полного API или подключайте\nотдельные заголовки для минимальной сборки.\n\n## Зачем Time Shield?\n\n**Time Shield** создавался как практичный инструмент для работы с временем в C++, ориентированный на прикладные и инженерные задачи. В отличие от стандартной `std::chrono` или более академичных решений вроде `HowardHinnant/date`, библиотека:\n\n- использует простые типы (`int64_t`, `double`) для представления времени (`ts_t`, `fts_t`) — их легко логировать, сериализовать и передавать через JSON, RPC и базы данных; без перегруженных классов `std::chrono`;\n- поддерживает **разные временные представления** — Unix‑время, дробные секунды, милли- и микросекунды, OLE Automation (Excel), джулианские даты;\n- включает **утилиты для округления, форматирования, парсинга ISO 8601**, работы с частями времени и вычисления границ периодов;\n- имеет **расширяемую архитектуру** — новые форматы (Julian, OLE, UTC-offset) добавляются как отдельные типы и модули;\n- есть адаптированные заголовки для MQL5/MetaTrader в каталоге `MQL5`, покрывающие ключевые части API;\n- поставляется как **header-only** — подключается одной строкой, без сборки и внешних зависимостей;\n- использует только **стандартные заголовки STL и системные API**; платформенные модули (например, сокетный `NtpClient`) изолированы и не мешают кроссплатформенной сборке.\n\n## Возможности\n\n- **Календарные и датовые хелперы** — валидация, будни/выходные/рабочие дни (включая строки ISO 8601).\n- **Форматирование времени** — преобразование таймстампов в строки по стандартным и пользовательским шаблонам.\n- **Конвертации** — перевод между секундными, миллисекундными и плавающими представлениями времени, структуры `DateTimeStruct`, OLE Automation (Excel) и временные зоны.\n- **Быстрые конвертации дат** — часть функций `timestamp -\u003e календарь` использует ускоренный алгоритм, вдохновлённый https://www.benjoffe.com/fast-date-64 и реализованный с нуля.\n- **Тип `DateTime`** — обёртка, хранящая UTC миллисекунды и фиксированное смещение, поддерживает ISO 8601, локальные/UTC компоненты и арифметику.\n- **ISO week date** — конвертация, форматирование и парсинг ISO 8601 для недельного счёта.\n- **Астрономические утилиты** — расчёт Julian Date/MJD/JDN и оценка лунной фазы/возраста по Unix‑времени.\n- **Утилиты** — получение текущих меток времени, вычисления начала/конца периодов, работа с частями секунды.\n- **Преобразование часовых поясов** — функции для CET/EET/ET/CT в GMT.\n- **NTP‑клиент и пул** — одиночные запросы и конфигурируемый пул/раннер/сервис с возможностью офлайн‑тестов (Windows и Unix).\n- **Поддержка MQL5** — адаптированные заголовки в каталоге `MQL5` позволяют использовать библиотеку в MetaTrader.\n- Совместимость с `C++11` – `C++17`.\n\n## Конфигурация\n\nКомпиляционные флаги в `time_shield/config.hpp` позволяют адаптировать библиотеку под платформу и отключать необязательные модули:\n\n- `TIME_SHIELD_PLATFORM_WINDOWS` / `TIME_SHIELD_PLATFORM_UNIX` — определение целевой платформы.\n- `TIME_SHIELD_HAS_WINSOCK` — наличие WinSock API.\n- `TIME_SHIELD_ENABLE_NTP_CLIENT` — включает модуль `NtpClient` (по умолчанию `1` на поддерживаемых платформах).\n\nВсе заголовки библиотеки используют пространство имён `time_shield`. Для доступа к API можно писать `time_shield::` или подключать `using namespace time_shield;`.\n\n\u003e Часть функций зависит от системных API и может быть ограничена платформой (например, получение realtime через `QueryPerformanceCounter` под Windows).\n\n## Инварианты API\n\n- `ts_t` — Unix-время в секундах (signed 64-bit). Представляет целые секунды.\n- `ts_ms_t` / `ts_us_t` — Unix-время в милли/микросекундах (signed 64-bit).\n- `fts_t` — Unix-время в секундах как `double`. Точность дробной части зависит от\n  величины значения; около современной эпохи обычно сохраняет микросекунды, на\n  очень больших |ts| младшие разряды могут теряться.\n- `year_t` — signed 64-bit год.\n- `dse_t` / `unix_day_t` / `unixday_t` — число суток с 1970-01-01 (signed 64-bit),\n  подходит для дат до эпохи.\n- ISO 8601 утилиты используют пролептический григорианский календарь и не учитывают\n  високосные секунды.\n- Базовые конверсии и “горячие” функции ориентированы на `noexcept` и отсутствие\n  динамических аллокаций; строковые/парсинговые и часть высокоуровневых хелперов\n  могут выделять память и/или бросать исключения (это указано в документации\n  конкретных функций).\n\n## Установка и настройка\n\nБиблиотека поставляется в виде заголовков. Для подключения достаточно добавить путь `include/time_shield` в проект и подключить основной файл:\n\n```cpp\n#include \u003ctime_shield.hpp\u003e\n```\n\nПримеры можно собрать скриптом `build-examples.bat`. Для установки файлов MQL5 предусмотрен `install_mql5.bat`.\n\n## Примеры использования\n\nНиже приведены небольшие примеры из разделов библиотеки.\n\n### Получение и конвертация времени\n\n```cpp\n#include \u003ctime_shield.hpp\u003e\n\nusing namespace time_shield;\n\nts_t now = ts();                 // секунды с эпохи\nfts_t now_f = fts();             // время в секундах с дробной частью\nint ms_part = ms_of_sec(now_f);  // миллисекундная часть\n```\n\n### Форматирование дат\n\n```cpp\n#include \u003ctime_shield.hpp\u003e\n\nstd::string iso = to_iso8601(now);          // 2024-06-21T12:00:00\nstd::string custom = to_string(\"%Y-%m-%d %H:%M:%S\", now);\nstd::string mql5 = to_mql5_date_time(now);  // 2024.06.21 12:00:00\nstd::string filename = to_windows_filename(now);\n```\n\n### Парсинг ISO 8601\n\n```cpp\n#include \u003ctime_shield.hpp\u003e\n\nDateTimeStruct dt;\nTimeZoneStruct tz;\nif (parse_iso8601(\"2024-11-25T14:30:00-05:30\", dt, tz)) {\n    ts_t ts_val = to_timestamp(dt) + to_offset(tz);\n}\n```\n\n### Класс DateTime\n\n`DateTime` хранит UTC миллисекунды и фиксированный offset, что позволяет\nсохранять смещение при форматировании и получать локальные компоненты.\n\n```cpp\n#include \u003ctime_shield.hpp\u003e\n\nusing namespace time_shield;\n\nDateTime dt = DateTime::parse_iso8601(\"2025-12-16T10:20:30.123+02:30\");\nstd::string local = dt.to_iso8601();        // сохраняет +02:30\nstd::string utc = dt.to_iso8601_utc();      // выводит Z\nDateTime tomorrow = dt.add_days(1).start_of_day();\nint hour_local = dt.hour();                 // локальный час с учётом offset\nint hour_utc = dt.utc_hour();               // час в UTC\n```\n\n### Преобразование дат OLE Automation (OA)\n\nПреобразования OA совместимы с Excel/COM (базовая дата 1899-12-30), выполняются в UTC и сохраняют округление к нулю, характерное для серийных OA дат.\n\n```cpp\n#include \u003ctime_shield/ole_automation_conversions.hpp\u003e\n\nusing namespace time_shield;\n\noadate_t oa = ts_to_oadate(1714608000);                     // 2024-05-02 00:00:00Z\nts_t ts_from_oa = oadate_to_ts(oa);                         // преобразование обратно в Unix-время\noadate_t from_parts = to_oadate(2024, Month::MAY, 2, 12, 0); // 2024-05-02 12:00:00Z\n```\n\n### Джулианские даты и лунные вычисления\n\nАстрономические хелперы ориентированы на аналитические оценки (JD, MJD, JDN, фазу и возраст Луны), а не на высокоточные эфемериды.\n\n```cpp\n#include \u003ctime_shield/astronomy_conversions.hpp\u003e\n\nusing namespace time_shield;\n\njd_t jd = ts_to_jd(1714608000);               // Julian Date для переданного таймстампа\nmjd_t mjd = ts_to_mjd(1714608000);             // Modified Julian Date\njdn_t jdn = gregorian_to_jdn(2, 5, 2024);      // Julian Day Number (целое значение)\ndouble phase = moon_phase(fts());              // фаза Луны [0..1)\ndouble age_days = moon_age_days(fts());        // примерный возраст Луны в днях\nMoonPhaseSineCosine signal = moon_phase_sincos(fts()); // sin/cos фазового угла без скачка в 0/1\nMoonQuarterInstants quarters = moon_quarters(fts());   // ближайшие четверти (Unix секунды в double)\nbool is_near_new = is_new_moon_window(fts());  // попадание в окно новолуния +/-12ч\n```\n\n### Геоцентрический калькулятор фаз Луны\n\n`MoonPhaseCalculator` (`time_shield::astronomy::MoonPhase`) выдаёт расширенный набор показателей (освещённость, угловые диаметры, расстояние, фазовый угол), sin/cos для непрерывного фазового сигнала, моменты четвертей и проверки «окон» вокруг фаз. Текущая математика геоцентрическая: положения Солнца/Луны рассчитываются без топоцентрических поправок. Поэтому освещённость и фазовый угол — «глобальные» в данный момент времени, а локально отличается:\n\n- дата/время из-за часового пояса,\n- ориентация освещённой части (в южном полушарии картинка отражена),\n- наблюдаемость (первый серп, высота над горизонтом, атмосфера).\n\n\u003e Текущая математика — геоцентрическая (относительно центра Земли), без топоцентрических поправок/параллакса. Освещённость/фазовый угол глобальны для Земли как целого. По месту реально меняются:\n\u003e - локальная дата/время (часовой пояс),\n\u003e - ориентация освещённой части (в северном/южном полушарии «картинка» перевёрнута),\n\u003e - видимость (первый серп/наблюдаемость) — уже про атмосферу/высоту над горизонтом и т.п.\n\n```cpp\n#include \u003ctime_shield/MoonPhase.hpp\u003e\n\nusing namespace time_shield;\n\nMoonPhaseCalculator calculator{};\nconst double ts = 1704067200.0; // 2024-01-01T00:00:00Z\nMoonPhaseResult res = calculator.compute(ts);\nMoonPhase::quarters_unix_s_t quarters = calculator.quarter_times_unix(ts); // Unix секунды (double)\nMoonQuarterInstants around = moon_quarters(ts);\nMoonPhaseSineCosine signal = moon_phase_sincos(ts);\nbool is_new = calculator.is_new_moon_window(ts); // по умолчанию окно +/-12ч\n```\n\n### Конвертация часовых поясов\n\n```cpp\n#include \u003ctime_shield.hpp\u003e\n\nts_t cet = to_ts(2024, Month::JUN, 21, 12, 0, 0);\nts_t gmt = cet_to_gmt(cet);\n```\n\n### NTP‑клиент, пул и сервис времени\n\n```cpp\n#include \u003ctime_shield/ntp_client_pool.hpp\u003e\n#include \u003ctime_shield/ntp_time_service.hpp\u003e\n\nusing namespace time_shield;\n\nNtpClientPool pool;\npool.set_default_servers();\npool.measure();\nint64_t pool_offset = pool.offset_us();\n\n// Фоновый runner + ленивый сервис через функции-обёртки:\nntp::init(std::chrono::seconds(30));\nint64_t utc_ms = ntp::utc_time_ms();\nint64_t offset_us = ntp::offset_us();\nint64_t utc_sec = ntp::utc_time_sec();\nbool ok = ntp::last_measure_ok();\nuint64_t attempts = ntp::measure_count();\nntp::shutdown();\n```\n\n## Документация\n\nПолное описание API и дополнительные примеры доступны по адресу: \u003chttps://newyaroslav.github.io/time-shield-cpp/\u003e\n\nHTML-документация Doxygen публикуется через GitHub Pages.\n\n## Лицензия\n\nПроект распространяется по лицензии [MIT](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnewyaroslav%2Ftime-shield-cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnewyaroslav%2Ftime-shield-cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnewyaroslav%2Ftime-shield-cpp/lists"}