time_parser.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: MIT
#pragma once
#ifndef _TIME_SHIELD_TIME_PARSER_HPP_INCLUDED
#define _TIME_SHIELD_TIME_PARSER_HPP_INCLUDED

 
#include "enums.hpp"
#include "constants.hpp"
#include "date_time_struct.hpp"
#include "time_zone_struct.hpp"
#include "validation.hpp"
#include "time_conversions.hpp"
#include "iso_week_conversions.hpp"
#include "time_format_parser.hpp"
 
#include <algorithm>
#include <locale>
#include <array>
#include <stdexcept>
#include <cctype>
#include <cstring>
#include <string>
 
#if __cplusplus >= 201703L
#   include <string_view>
#endif
 
namespace time_shield {

    
    namespace detail {

        inline std::string trim_copy_ascii(const std::string& s) {
            size_t b = 0;
            size_t e = s.size();
            while (b < e && std::isspace(static_cast<unsigned char>(s[b])) != 0) ++b;
            while (e > b && std::isspace(static_cast<unsigned char>(s[e - 1])) != 0) --e;
            return s.substr(b, e - b);
        }
 
#   if __cplusplus >= 201703L
        inline std::string_view trim_view_ascii(std::string_view v) {
            size_t b = 0;
            size_t e = v.size();
            while (b < e && std::isspace(static_cast<unsigned char>(v[b])) != 0) ++b;
            while (e > b && std::isspace(static_cast<unsigned char>(v[e - 1])) != 0) --e;
            return v.substr(b, e - b);
        }
#   endif

        inline void normalise_month_token_lower(const std::string& month, std::string& output) {
            output = trim_copy_ascii(month);
            if (output.empty()) return;
 
            const auto& facet = std::use_facet<std::ctype<char>>(std::locale());
            std::transform(output.begin(), output.end(), output.begin(),
                           [&facet](char ch) { return facet.tolower(ch); });
        }
 
#   if __cplusplus >= 201703L
        inline void normalise_month_token_lower(std::string_view month, std::string& output) {
            month = trim_view_ascii(month);
            output.assign(month.begin(), month.end());
            if (output.empty()) return;
 
            const auto& facet = std::use_facet<std::ctype<char>>(std::locale());
            std::transform(output.begin(), output.end(), output.begin(),
                           [&facet](char ch) { return facet.tolower(ch); });
        }
#   endif

        inline bool try_parse_month_index(const std::string& month, int& value) {
            if (month.empty()) return false;
 
            std::string month_copy;
            normalise_month_token_lower(month, month_copy);
            if (month_copy.empty()) return false;
 
            static const std::array<const char*, MONTHS_PER_YEAR> short_names = {
                "jan", "feb", "mar", "apr", "may", "jun",
                "jul", "aug", "sep", "oct", "nov", "dec"
            };
            static const std::array<const char*, MONTHS_PER_YEAR> full_names = {
                "january", "february", "march", "april", "may", "june",
                "july", "august", "september", "october", "november", "december"
            };
 
            for (std::size_t i = 0; i < short_names.size(); ++i) {
                if (month_copy == short_names[i] || month_copy == full_names[i]) {
                    value = static_cast<int>(i) + 1;
                    return true;
                }
            }
 
            return false;
        }
 
#   if __cplusplus >= 201703L
        inline bool try_parse_month_index(std::string_view month, int& value) {
            if (month.empty()) return false;
 
            std::string month_copy;
            normalise_month_token_lower(month, month_copy);
            if (month_copy.empty()) return false;
 
            static const std::array<const char*, MONTHS_PER_YEAR> short_names = {
                "jan", "feb", "mar", "apr", "may", "jun",
                "jul", "aug", "sep", "oct", "nov", "dec"
            };
            static const std::array<const char*, MONTHS_PER_YEAR> full_names = {
                "january", "february", "march", "april", "may", "june",
                "july", "august", "september", "october", "november", "december"
            };
 
            for (std::size_t i = 0; i < short_names.size(); ++i) {
                if (month_copy == short_names[i] || month_copy == full_names[i]) {
                    value = static_cast<int>(i) + 1;
                    return true;
                }
            }
 
            return false;
        }
#   endif

        inline int parse_month_index(const std::string& month) {
            int value = 0;
            if (!try_parse_month_index(month, value)) {
                throw std::invalid_argument("Invalid month name");
            }
            return value;
        }
 
#   if __cplusplus >= 201703L
        inline int parse_month_index(std::string_view month) {
            int value = 0;
            if (!try_parse_month_index(month, value)) {
                throw std::invalid_argument("Invalid month name");
            }
            return value;
        }
#   endif
 
        struct ZoneNameEntry {
            const char* name;
            TimeZone zone;
        };

        inline const std::array<ZoneNameEntry, 25>& time_zone_name_entries() noexcept {
            static const std::array<ZoneNameEntry, 25> entries = {{
                {"GMT", GMT},
                {"UTC", UTC},
                {"EET", EET},
                {"CET", CET},
                {"WET", WET},
                {"EEST", EEST},
                {"CEST", CEST},
                {"WEST", WEST},
                {"ET", ET},
                {"CT", CT},
                {"IST", IST},
                {"MYT", MYT},
                {"WIB", WIB},
                {"WITA", WITA},
                {"WIT", WIT},
                {"KZT", KZT},
                {"TRT", TRT},
                {"BYT", BYT},
                {"SGT", SGT},
                {"ICT", ICT},
                {"PHT", PHT},
                {"GST", GST},
                {"HKT", HKT},
                {"JST", JST},
                {"KST", KST}
            }};
            return entries;
        }

        inline bool try_parse_time_zone_name_token(const char* data, std::size_t length, TimeZone& zone) noexcept {
            if (data == nullptr || length == 0) {
                zone = UNKNOWN;
                return false;
            }
 
            const std::array<ZoneNameEntry, 25>& entries = time_zone_name_entries();
            for (std::size_t i = 0; i < entries.size(); ++i) {
                const std::size_t name_length = std::strlen(entries[i].name);
                if (length == name_length && std::memcmp(data, entries[i].name, name_length) == 0) {
                    zone = entries[i].zone;
                    return true;
                }
            }
 
            zone = UNKNOWN;
            return false;
        }
 
//------------------------------------------------------------------------------
// Small C-style helpers (no lambdas, no detail namespace)
//------------------------------------------------------------------------------

        TIME_SHIELD_CONSTEXPR inline bool is_ascii_space(char c) noexcept {
            return c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == '\f' || c == '\v';
        }

        TIME_SHIELD_CONSTEXPR inline bool is_ascii_digit(char c) noexcept {
            return c >= '0' && c <= '9';
        }

        TIME_SHIELD_CONSTEXPR inline void skip_spaces(const char*& p, const char* end) noexcept {
            while (p < end && is_ascii_space(*p)) {
                ++p;
            }
        }

        TIME_SHIELD_CONSTEXPR inline bool parse_2digits(const char*& p, const char* end, int& out) noexcept {
            if (end - p < 2) {
                return false;
            }
            const char a = p[0];
            const char b = p[1];
            if (!is_ascii_digit(a) || !is_ascii_digit(b)) {
                return false;
            }
            out = (a - '0') * 10 + (b - '0');
            p += 2;
            return true;
        }

        TIME_SHIELD_CONSTEXPR inline bool parse_4digits_year(const char*& p, const char* end, year_t& out) noexcept {
            if (end - p < 4) {
                return false;
            }
            const char a = p[0], b = p[1], c = p[2], d = p[3];
            if (!is_ascii_digit(a) || !is_ascii_digit(b) || !is_ascii_digit(c) || !is_ascii_digit(d)) {
                return false;
            }
            const int v = (a - '0') * 1000 + (b - '0') * 100 + (c - '0') * 10 + (d - '0');
            out = static_cast<year_t>(v);
            p += 4;
            return true;
        }

        TIME_SHIELD_CONSTEXPR inline bool parse_fraction_to_ms(const char*& p, const char* end, int& ms_out) noexcept {
            if (p >= end || !is_ascii_digit(*p)) {
                return false;
            }
 
            int ms = 0;
            int digits = 0;
 
            while (p < end && is_ascii_digit(*p)) {
                if (digits >= 3) {
                    return false;
                }
                ms = ms * 10 + (*p - '0');
                ++digits;
                ++p;
            }
 
            if (digits == 1) {
                ms *= 100;
            } else if (digits == 2) {
                ms *= 10;
            }
 
            ms_out = ms;
            return true;
        }
 
    } // namespace detail
 
//------------------------------------------------------------------------------
// Month helpers (public)
//------------------------------------------------------------------------------
 
// Canonical API (recommended):
//  - parse_month(...) / try_parse_month(...): return month index as int [1..12]
//  - parse_month_enum(...) / try_parse_month_enum(...): return month as enum Month (or any integral/enum T)

    inline bool try_parse_month(const std::string& month, int& value) {
        return detail::try_parse_month_index(month, value);
    }

    inline int parse_month(const std::string& month) {
        return detail::parse_month_index(month);
    }
 
#if __cplusplus >= 201703L
    inline bool try_parse_month(std::string_view month, int& value) {
        return detail::try_parse_month_index(month, value);
    }

    inline int parse_month(std::string_view month) {
        return detail::parse_month_index(month);
    }
#endif
 
// Canonical: parse month -> enum Month (or any T)

    template<class T = Month>
    inline T parse_month_enum(const std::string& month) {
        return static_cast<T>(detail::parse_month_index(month));
    }

    template<class T = Month>
    inline bool try_parse_month_enum(const std::string& month, T& value) {
        int idx = 0;
        if (!detail::try_parse_month_index(month, idx)) return false;
        value = static_cast<T>(idx);
        return true;
    }
 
#if __cplusplus >= 201703L
    template<class T = Month>
    inline T parse_month_enum(std::string_view month) {
        return static_cast<T>(detail::parse_month_index(month));
    }

    template<class T = Month>
    inline bool try_parse_month_enum(std::string_view month, T& value) {
        int idx = 0;
        if (!detail::try_parse_month_index(month, idx)) return false;
        value = static_cast<T>(idx);
        return true;
    }
#endif
 
// Index aliases (int)

    inline bool try_get_month_index(const std::string& month, int& value) {
        return try_parse_month(month, value);
    }

    inline int get_month_index(const std::string& month) {
        return parse_month(month);
    }

    inline Month get_month_index_enum(const std::string& month) {
        return static_cast<Month>(detail::parse_month_index(month));
    }
 
#if __cplusplus >= 201703L
    inline bool try_get_month_index(std::string_view month, int& value) {
        return try_parse_month(month, value);
    }

    inline int get_month_index(std::string_view month) {
        return parse_month(month);
    }

    inline Month get_month_index_enum(std::string_view month) {
        return static_cast<Month>(detail::parse_month_index(month));
    }
#endif
 
// Month number aliases (T)

    template<class T = Month>
    inline T get_month_number(const std::string& month) {
        return parse_month_enum<T>(month);
    }

    template<class T = Month>
    inline T month_of_year(const std::string& month) {
        return get_month_number<T>(month);
    }

    template<class T = Month>
    inline bool try_get_month_number(const std::string& month, T& value) {
        return try_parse_month_enum<T>(month, value);
    }

    template<class T = Month>
    inline bool get_month_number(const std::string& month, T& value) {
        return try_get_month_number<T>(month, value);
    }

    template<class T = Month>
    inline bool month_of_year(const std::string& month, T& value) {
        return try_get_month_number<T>(month, value);
    }
 
#if __cplusplus >= 201703L
    template<class T = Month>
    inline T get_month_number(std::string_view month) {
        return parse_month_enum<T>(month);
    }

    template<class T = Month>
    inline T month_of_year(std::string_view month) {
        return get_month_number<T>(month);
    }

    template<class T = Month>
    inline bool try_get_month_number(std::string_view month, T& value) {
        return try_parse_month_enum<T>(month, value);
    }

    template<class T = Month>
    inline bool get_month_number(std::string_view month, T& value) {
        return try_get_month_number<T>(month, value);
    }

    template<class T = Month>
    inline bool month_of_year(std::string_view month, T& value) {
        return try_get_month_number<T>(month, value);
    }
#endif
 
// const char* overloads to avoid ambiguity with string vs string_view for literals

    template<class T = Month>
    inline T get_month_number(const char* month) {
#if __cplusplus >= 201703L
        return get_month_number<T>(std::string_view(month));
#else
        return get_month_number<T>(std::string(month));
#endif
    }

    template<class T = Month>
    inline bool try_get_month_number(const char* month, T& value) {
#if __cplusplus >= 201703L
        return try_get_month_number<T>(std::string_view(month), value);
#else
        return try_get_month_number<T>(std::string(month), value);
#endif
    }

    template<class T = Month>
    inline T month_of_year(const char* month) {
        return get_month_number<T>(month);
    }

    template<class T = Month>
    inline bool get_month_number(const char* month, T& value) {
        return try_get_month_number<T>(month, value);
    }

    template<class T = Month>
    inline bool month_of_year(const char* month, T& value) {
        return try_get_month_number<T>(month, value);
    }
 
//------------------------------------------------------------------------------
// Time zone parsing (C-style, high performance)
//------------------------------------------------------------------------------

    inline bool parse_time_zone(const char* data, std::size_t length, TimeZoneStruct& tz) noexcept {
        if (!data) {
            return false;
        }
 
        if (length == 0) {
            tz.hour = 0;
            tz.min = 0;
            tz.is_positive = true;
            return true;
        }
 
        if (length == 1 && (data[0] == 'Z' || data[0] == 'z')) {
            tz.hour = 0;
            tz.min = 0;
            tz.is_positive = true;
            return true;
        }
 
        if (length != 6) {
            return false;
        }
 
        const char sign = data[0];
        if (sign != '+' && sign != '-') {
            return false;
        }
        if (data[3] != ':') {
            return false;
        }
        if (!detail::is_ascii_digit(data[1]) || !detail::is_ascii_digit(data[2]) ||
            !detail::is_ascii_digit(data[4]) || !detail::is_ascii_digit(data[5])) {
            return false;
        }
 
        tz.is_positive = (sign == '+');
        tz.hour = (data[1] - '0') * 10 + (data[2] - '0');
        tz.min  = (data[4] - '0') * 10 + (data[5] - '0');
 
        return is_valid_time_zone(tz);
    }

    inline bool parse_time_zone(const std::string& tz_str, TimeZoneStruct& tz) noexcept {
        return parse_time_zone(tz_str.c_str(), tz_str.size(), tz);
    }

    inline bool parse_tz(const std::string& tz_str, TimeZoneStruct& tz) noexcept {
        return parse_time_zone(tz_str, tz);
    }

    inline bool parse_tz(const char* data, std::size_t length, TimeZoneStruct& tz) noexcept {
        return parse_time_zone(data, length, tz);
    }

    inline bool parse_time_zone_name(const char* data, std::size_t length, TimeZone& zone) noexcept {
        if (!data) {
            zone = UNKNOWN;
            return false;
        }
 
        std::size_t begin = 0;
        std::size_t end = length;
        while (begin < end && std::isspace(static_cast<unsigned char>(data[begin])) != 0) {
            ++begin;
        }
        while (end > begin && std::isspace(static_cast<unsigned char>(data[end - 1])) != 0) {
            --end;
        }
        return detail::try_parse_time_zone_name_token(data + begin, end - begin, zone);
    }

    inline bool parse_time_zone_name(const std::string& value, TimeZone& zone) noexcept {
        return parse_time_zone_name(value.c_str(), value.size(), zone);
    }
 
#if __cplusplus >= 201703L
    inline bool parse_time_zone_name(std::string_view value, TimeZone& zone) noexcept {
        return parse_time_zone_name(value.data(), value.size(), zone);
    }
#endif

    inline bool parse_time_zone_name(const char* value, TimeZone& zone) noexcept {
        if (value == nullptr) {
            zone = UNKNOWN;
            return false;
        }
        return parse_time_zone_name(value, std::strlen(value), zone);
    }

    inline bool parse_tz_name(const char* data, std::size_t length, TimeZone& zone) noexcept {
        return parse_time_zone_name(data, length, zone);
    }

    inline bool parse_tz_name(const std::string& value, TimeZone& zone) noexcept {
        return parse_time_zone_name(value, zone);
    }
 
#if __cplusplus >= 201703L
    inline bool parse_tz_name(std::string_view value, TimeZone& zone) noexcept {
        return parse_time_zone_name(value, zone);
    }
#endif

    inline bool parse_tz_name(const char* value, TimeZone& zone) noexcept {
        return parse_time_zone_name(value, zone);
    }
 
//------------------------------------------------------------------------------
// ISO8601 parsing (C-style, no regex, no allocations)
//------------------------------------------------------------------------------

    inline bool parse_iso8601(const char* input, std::size_t length,
                              DateTimeStruct& dt, TimeZoneStruct& tz) noexcept {
        if (!input) {
            return false;
        }
 
        const char* p = input;
        const char* end = input + length;
 
        detail::skip_spaces(p, end);
 
        dt = create_date_time_struct(0);
        tz = create_time_zone_struct(0, 0);
        tz.is_positive = true;
 
        const char* const date_start = p;
        const char* date_end = p;
        while (date_end < end && *date_end != 'T' && *date_end != 't' && !detail::is_ascii_space(*date_end)) {
            ++date_end;
        }
 
        bool parsed_iso_week_date = false;
        if (date_end > date_start) {
            IsoWeekDateStruct iso_date{};
            if (parse_iso_week_date(date_start, static_cast<std::size_t>(date_end - date_start), iso_date)) {
                const DateStruct calendar_date = iso_week_date_to_date(iso_date);
                dt.year = calendar_date.year;
                dt.mon = calendar_date.mon;
                dt.day = calendar_date.day;
                p = date_end;
                parsed_iso_week_date = true;
            }
        }
 
        if (!parsed_iso_week_date) {
            // ---- Date: YYYY<sep>MM<sep>DD
            if (!detail::parse_4digits_year(p, end, dt.year)) {
                return false;
            }
            if (p >= end) {
                return false;
            }
            const char sep1 = *p;
            if (sep1 != '-' && sep1 != '/' && sep1 != '.') {
                return false;
            }
            ++p;
 
            if (!detail::parse_2digits(p, end, dt.mon)) {
                return false;
            }
            if (p >= end) {
                return false;
            }
            const char sep2 = *p;
            if (sep2 != '-' && sep2 != '/' && sep2 != '.') {
                return false;
            }
            ++p;
 
            if (!detail::parse_2digits(p, end, dt.day)) {
                return false;
            }
        }
 
        if (!is_valid_date(dt.year, dt.mon, dt.day)) {
            return false;
        }
 
        // Date-only?
        {
            const char* q = p;
            detail::skip_spaces(q, end);
            if (q == end) {
                // dt already has time=0 ms=0
                return is_valid_date_time(dt);
            }
        }
 
        // ---- Date/time separator: 'T' or whitespace
        if (p >= end) {
            return false;
        }
 
        if (*p == 'T' || *p == 't') {
            ++p;
        } else 
        if (detail::is_ascii_space(*p)) {
            // allow one or more spaces
            detail::skip_spaces(p, end);
        } else {
            return false;
        }
 
        // ---- Time: hh:mm[:ss][.frac]
        if (!detail::parse_2digits(p, end, dt.hour)) {
            return false;
        }
        if (p >= end || *p != ':') {
            return false;
        }
        ++p;
 
        if (!detail::parse_2digits(p, end, dt.min)) {
            return false;
        }
 
        dt.sec = 0;
        dt.ms = 0;
        bool has_seconds = false;
 
        // Optional :ss
        if (p < end && *p == ':') {
            ++p;
            if (!detail::parse_2digits(p, end, dt.sec)) {
                return false;
            }
            has_seconds = true;
        }
 
        // Optional .fraction (allowed only if we had seconds in original regex,
        // but we accept it when seconds are present; for hh:mm (no seconds) we keep it strict).
        if (p < end && *p == '.') {
            // require seconds field to exist (avoid accepting YYYY-MM-DDThh:mm.xxx)
            if (!has_seconds) {
                // Ambiguous: could be "hh:mm.fff" which is not in your original formats.
                // Keep strict to preserve behavior.
                return false;
            }
 
            ++p;
            int ms = 0;
            if (!detail::parse_fraction_to_ms(p, end, ms)) {
                return false;
            }
            dt.ms = ms;
        }
 
        // ---- Optional timezone: [spaces] (Z | ±HH:MM)
        detail::skip_spaces(p, end);
 
        if (p < end) {
            if (*p == 'Z' || *p == 'z') {
                tz.hour = 0;
                tz.min = 0;
                tz.is_positive = true;
                ++p;
            } else if (*p == '+' || *p == '-') {
                // need 6 chars
                if (static_cast<std::size_t>(end - p) < 6) {
                    return false;
                }
                if (!parse_time_zone(p, 6, tz)) {
                    return false;
                }
                p += 6;
            }
        }
 
        detail::skip_spaces(p, end);
        if (p != end) {
            return false;
        }
 
        return is_valid_date_time(dt);
    }

    inline bool parse_iso8601(const std::string& input, DateTimeStruct& dt, TimeZoneStruct& tz) noexcept {
        return parse_iso8601(input.c_str(), input.size(), dt, tz);
    }

    inline bool parse_iso8601(const char* input, DateTimeStruct& dt, TimeZoneStruct& tz) noexcept {
        if (input == nullptr) {
            return false;
        }
        return parse_iso8601(input, std::strlen(input), dt, tz);
    }
 
#   if __cplusplus >= 201703L
    inline bool parse_iso8601(std::string_view input, DateTimeStruct& dt, TimeZoneStruct& tz) noexcept {
        return parse_iso8601(input.data(), input.size(), dt, tz);
    }
#   endif
    
//------------------------------------------------------------------------------
// ISO8601 -> timestamps
//------------------------------------------------------------------------------

    inline bool str_to_ts(const std::string& str, ts_t& ts) {
        DateTimeStruct dt;
        TimeZoneStruct tz;
        if (!parse_iso8601(str, dt, tz)) return false;
        try {
            ts = dt_to_timestamp(dt) - to_offset(tz);
            return true;
        } catch (...) {}
        return false;
    }
    
    inline bool str_to_ts(const char* data, std::size_t length, ts_t& ts) {
        if (!data || length == 0) {
            ts = 0;
            return false;
        }
        DateTimeStruct dt;
        TimeZoneStruct tz;
        if (!parse_iso8601(data, length, dt, tz)) return false;
        try {
            ts = dt_to_timestamp(dt) - to_offset(tz);
            return true;
        } catch (...) {}
        return false;
    }

    inline bool str_to_ts_ms(const std::string& str, ts_ms_t& ts) {
        DateTimeStruct dt;
        TimeZoneStruct tz;
        if (!parse_iso8601(str, dt, tz)) return false;
        try {
            ts = static_cast<ts_ms_t>(dt_to_timestamp_ms(dt)) - sec_to_ms(to_offset(tz));
            return true;
        } catch (...) {}
        return false;
    }
    
    inline bool str_to_ts_ms(const char* data, std::size_t length, ts_ms_t& ts) {
        if (!data || length == 0) {
            ts = 0;
            return false;
        }
        DateTimeStruct dt;
        TimeZoneStruct tz;
        if (!parse_iso8601(data, length, dt, tz)) return false;
        try {
            ts = static_cast<ts_ms_t>(dt_to_timestamp_ms(dt)) - sec_to_ms(to_offset(tz));
            return true;
        } catch (...) {}
        return false;
    }

    inline bool str_to_fts(const std::string& str, fts_t& ts) {
        DateTimeStruct dt;
        TimeZoneStruct tz;
        if (!parse_iso8601(str, dt, tz)) return false;
        try {
            ts = dt_to_ftimestamp(dt) - static_cast<fts_t>(to_offset(tz));
            return true;
        } catch (...) {}
        return false;
    }
    
    inline bool str_to_fts(const char* data, std::size_t length, fts_t& ts) {
        if (!data || length == 0) {
            ts = 0;
            return false;
        }
        DateTimeStruct dt;
        TimeZoneStruct tz;
        if (!parse_iso8601(data, length, dt, tz)) return false;
        try {
            ts = dt_to_ftimestamp(dt) - static_cast<fts_t>(to_offset(tz));
            return true;
        } catch (...) {}
        return false;
    }
 
//------------------------------------------------------------------------------
// Convenience string -> predicates (workdays)
//------------------------------------------------------------------------------

    inline bool is_workday(const std::string& str) {
        ts_t ts = 0;
        if (!str_to_ts(str, ts)) return false;
        return is_workday(ts);
    }

    inline bool is_workday_ms(const std::string& str) {
        ts_ms_t ts = 0;
        if (!str_to_ts_ms(str, ts)) return false;
        return is_workday_ms(ts);
    }
    
    inline bool workday(const std::string& str) {
        return is_workday(str);
    }

    inline bool workday_ms(const std::string& str) {
        return is_workday_ms(str);
    }

    inline bool is_first_workday_of_month(const std::string& str) {
        ts_t ts = 0;
        if (!str_to_ts(str, ts)) return false;
        return is_first_workday_of_month(ts);
    }

    inline bool is_first_workday_of_month_ms(const std::string& str) {
        ts_ms_t ts = 0;
        if (!str_to_ts_ms(str, ts)) return false;
        return is_first_workday_of_month_ms(ts);
    }

    inline bool is_last_workday_of_month(const std::string& str) {
        ts_t ts = 0;
        if (!str_to_ts(str, ts)) return false;
        return is_last_workday_of_month(ts);
    }

    inline bool is_last_workday_of_month_ms(const std::string& str) {
        ts_ms_t ts = 0;
        if (!str_to_ts_ms(str, ts)) return false;
        return is_last_workday_of_month_ms(ts);
    }

    inline bool is_within_first_workdays_of_month(const std::string& str, int count) {
        ts_t ts = 0;
        if (!str_to_ts(str, ts)) return false;
        return is_within_first_workdays_of_month(ts, count);
    }

    inline bool is_within_first_workdays_of_month_ms(const std::string& str, int count) {
        ts_ms_t ts = 0;
        if (!str_to_ts_ms(str, ts)) return false;
        return is_within_first_workdays_of_month_ms(ts, count);
    }

    inline bool is_within_last_workdays_of_month(const std::string& str, int count) {
        ts_t ts = 0;
        if (!str_to_ts(str, ts)) return false;
        return is_within_last_workdays_of_month(ts, count);
    }

    inline bool is_within_last_workdays_of_month_ms(const std::string& str, int count) {
        ts_ms_t ts = 0;
        if (!str_to_ts_ms(str, ts)) return false;
        return is_within_last_workdays_of_month_ms(ts, count);
    }
    
//------------------------------------------------------------------------------
// Convenience: C-string wrappers (non-throwing, ambiguous on failure)
//------------------------------------------------------------------------------

    inline ts_t ts(const char* str) {
        ts_t out = 0;
        str_to_ts(str ? std::string(str) : std::string(), out);
        return out;
    }

    inline ts_t ts(const char* data, std::size_t length) {
        ts_t out = 0;
        if (!str_to_ts(data, length, out)) {
            return 0;
        }
        return out;
    }

    inline ts_ms_t ts_ms(const char* str) {
        ts_ms_t out = 0;
        str_to_ts_ms(str ? std::string(str) : std::string(), out);
        return out;
    }

    inline ts_ms_t ts_ms(const char* data, std::size_t length) {
        ts_ms_t out = 0;
        if (!str_to_ts_ms(data, length, out)) {
            return 0;
        }
        return out;
    }

    inline fts_t fts(const char* str) {
        fts_t out = 0;
        str_to_fts(str ? std::string(str) : std::string(), out);
        return out;
    }

    inline fts_t fts(const char* data, std::size_t length) {
        fts_t out = 0;
        if (!str_to_fts(data, length, out)) {
            return 0.0;
        }
        return out;
    }
 
//------------------------------------------------------------------------------

    inline ts_t ts(const std::string& str) {
        ts_t ts = 0;
        str_to_ts(str, ts);
        return ts;
    }

    inline ts_ms_t ts_ms(const std::string& str) {
        ts_ms_t ts = 0;
        str_to_ts_ms(str, ts);
        return ts;
    }

    inline fts_t fts(const std::string& str) {
        fts_t ts = 0;
        str_to_fts(str, ts);
        return ts;
    }
 
//------------------------------------------------------------------------------

    template<class T = int>
    inline bool sec_of_day(const std::string& str, T& sec) {
        if (str.empty()) return false;
 
        const char* p = str.c_str();
        int parts[3] = {0, 0, 0}; // hour, minute, second
        int idx = 0;
 
        while (*p && idx < 3) {
            // Parse integer
            int value = 0;
            bool has_digit = false;
 
            while (*p >= '0' && *p <= '9') {
                has_digit = true;
                value = value * 10 + (*p - '0');
                ++p;
            }
 
            if (!has_digit) return false;
            parts[idx++] = value;
 
            // Expect colon or end
            if (*p == ':') {
                ++p;
            } else if (*p == '\0') {
                break;
            } else {
                return false; // unexpected character
            }
        }
 
        if (idx == 0) return false;
        if (!is_valid_time(parts[0], parts[1], parts[2])) return false;
 
        sec = static_cast<T>(sec_of_day(parts[0], parts[1], parts[2]));
        return true;
    }

    template<class T = int>
    inline T sec_of_day(const std::string& str) {
        T value{};
        if (sec_of_day(str, value))
            return value;
        return static_cast<T>(SEC_PER_DAY);
    }

 
};
 
#endif // _TIME_SHIELD_TIME_PARSER_HPP_INCLUDED