DateTime.hpp

Go to the documentation of this file.

/*
 *
 * ---
 *
 *  Copyright (C) 2021 Anselm Schmidt (ans[ät]ohai.su)
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version in addition to the terms of any
 *  licences already herein identified.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program. If not, see <https://www.gnu.org/licenses/>.
 *
 * ---
 *
 * DateTime.hpp
 *
 * Namespace for global date/time helper functions.
 *
 *  Created on: Dec 10, 2018
 *      Author: ans
 */

#ifndef HELPER_DATETIME_HPP_
#define HELPER_DATETIME_HPP_

#include "Strings.hpp"

#include "../Main/Exception.hpp"

#include "../_extern/date/include/date/date.h"

#include <algorithm>    // std::min, std::transform
#include <array>        // std::array
#include <cctype>       // std::isdigit, std::ispunct, std::isspace, std::tolower
#include <chrono>       // std::chrono::seconds, std::chrono::system_clock
#include <clocale>      // std::setlocale
#include <cmath>        // std::lround
#include <cstddef>      // std::size_t
#include <cstdint>      // std::uint8_t, std::int64_t, std::uint16_t, std::uint64_t
#include <cstdlib>      // std::strtoul
#include <ctime>        // std::tm, std::strftime, std::time_t
#include <exception>    // std::exception
#include <iomanip>      // std::get_time
#include <locale>       // std::locale
#include <sstream>      // std::istringstream
#include <stdexcept>    // std::runtime_error
#include <string>       // std::stoi, std::stol, fstd::string, std::to_string
#include <string_view>  // std::string_view, std::string_view_literals
#include <vector>       // std::vector

namespace crawlservpp::Helper::DateTime {

    /*
     * CONSTANTS
     */

    using std::string_view_literals::operator""sv;


    inline constexpr auto longDateTime{"%a, %d %b %Y %T %Z"};

    inline constexpr auto unixTimeFormat{"UNIX"sv};

    inline constexpr auto unixTimeFormatPlus{"UNIX+"sv};

    inline constexpr auto unixTimeFormatMinus{"UNIX-"sv};

    inline constexpr auto unixTimeFormatXLength{5};

    inline constexpr auto unixTimeFormatXOffset{4};

    inline constexpr std::array englishOrdinalSuffixes{
        "st"sv, "nd"sv, "rd"sv, "th"sv
    };

    inline constexpr std::array frenchOrdinalSuffixes{
        "e"sv, "er"sv
    };

    inline constexpr std::array russianOrdinalSuffixes{
        "-ый"sv, "-го"sv, "-му"sv, "-ми"sv, "-й"sv, "-я"sv, "-е"sv, "-м"sv, "-х"sv
    };

    inline constexpr std::array ukrainianOrdinalSuffixes{
        "-а"sv, "-е"sv, "-і"sv, "-я"sv, "-є"sv
    };

    inline constexpr auto sqlTimeStamp{"%F %T"};

    inline constexpr auto sqlTimeStampLength{19};

    inline constexpr auto englishLocalePrefix{"en"sv};

    inline constexpr auto frenchLocalePrefix{"fr"sv};

    inline constexpr auto russianLocalePrefix{"ru"sv};

    inline constexpr auto ukrainianLocalePrefix{"uk"sv};

    inline constexpr auto finnishLocalePrefix{"fi"sv};

    inline constexpr auto amPmLength{2};

    inline constexpr auto hourChange{12};

    inline constexpr auto hourNoonMidnight{12};

    inline constexpr auto centuryFrom{69};

    inline constexpr auto yearsPerCentury{100};

    inline constexpr auto microsecondsPerDay{86400000000};

    inline constexpr auto millisecondsPerDay{86400000};

    inline constexpr auto secondsPerDay{86400};

    inline constexpr auto microsecondsPerHour{3600000000};

    inline constexpr auto millisecondsPerHour{3600000};

    inline constexpr auto secondsPerHour{3600};

    inline constexpr auto microsecondsPerMinute{60000000};

    inline constexpr auto millisecondsPerMinute{60000};

    inline constexpr auto secondsPerMinute{60};

    inline constexpr auto microsecondsPerSecond{1000000};

    inline constexpr auto millisecondsPerSecond{1000};

    inline constexpr auto microsecondsPerMillisecond{1000};

    inline constexpr auto isoDateLength{10};

    inline constexpr auto yearLength{4};

    inline constexpr auto isoMonthPos{5};

    inline constexpr auto isoMonthLength{2};

    inline constexpr auto minTwoDigitYear{1969};

    inline constexpr auto base10{10};

    inline constexpr auto reducedToMonthLength{7};

    inline constexpr auto daysPerWeek{7};


    inline constexpr std::uint8_t dateWeeks{0};


    inline constexpr std::uint8_t dateDays{1};


    inline constexpr std::uint8_t dateMonths{2};


    inline constexpr std::uint8_t dateYears{3};


    /*
     * DECLARATION
     */


    void convertLongDateTimeToSQLTimeStamp(std::string& dateTime);
    void convertCustomDateTimeToSQLTimeStamp(
            std::string& dateTime,
            const std::string& customFormat
    );
    void convertCustomDateTimeToSQLTimeStamp(
            std::string& dateTime,
            const std::string& customFormat,
            const std::string& locale
    );
    void convertTimeStampToSQLTimeStamp(std::string& timeStamp);
    void convertSQLTimeStampToTimeStamp(std::string& timeStamp);
    void convert12hTo24h(int& hour, bool isPm);
    [[nodiscard]] std::string getYearAndWeek(const std::string& date);
    void reduceDate(std::string& date, std::uint8_t resolution);


    [[nodiscard]] std::string microsecondsToString(std::uint64_t microseconds);
    [[nodiscard]] std::string millisecondsToString(std::uint64_t milliseconds);
    [[nodiscard]] std::string secondsToString(std::uint64_t seconds);
    [[nodiscard]] std::string now();


    [[nodiscard]] bool isValidISODate(const std::string& isoDate);


    [[nodiscard]] bool isISODateInRange(std::string_view isoDate, std::string_view rangeFrom, std::string_view rangeTo);


    [[nodiscard]] std::vector<std::string> getDateGap(
            const std::string& first,
            const std::string& second,
            std::uint8_t resolution
    );
    [[nodiscard]] std::vector<std::string> getWeekGap(const std::string& first, const std::string& second);
    [[nodiscard]] std::vector<std::string> getDayGap(const std::string& first, const std::string& second);
    [[nodiscard]] std::vector<std::string> getMonthGap(const std::string& first, const std::string& second);
    [[nodiscard]] std::vector<std::string> getYearGap(const std::string& first, const std::string& second);


    template<std::size_t N>
    void removeOrdinals(
            const std::array<std::string_view, N>& suffixes,
            std::string& strInOut
    );
    template<std::size_t N>
    void removeOrdinals(
            std::string_view currentLocale,
            std::string_view localePrefix,
            const std::array<std::string_view, N>& suffixes,
            std::string& strInOut
    );
    void fixFrenchMonths(std::string_view locale, std::string& strInOut);
    void fixRussianMonths(std::string_view locale, std::string& strInOut, std::string& formatInOut);
    void fixUkrainianMonths(std::string_view locale, std::string& strInOut, std::string& formatInOut);
    void fixFinnishMonths(std::string_view locale, std::string_view format, std::string& strInOut);
    void extendSingleDigits(std::string& dateTimeString);
    void fixYear(std::string& sqlTimeStamp, std::string_view format);
    void handle12hTime(
            std::string& formatString,
            const std::string& dateTimeString,
            bool& outIsAm,
            bool& outIsPm
    );


    /*
     * CLASSES FOR DATE/TIME EXCEPTIONS
     */


    MAIN_EXCEPTION_CLASS();


    MAIN_EXCEPTION_SUBCLASS(LocaleException);

    /*
     * IMPLEMENTATION
     */

    /*
     * CONVERSION
     */


    inline void convertLongDateTimeToSQLTimeStamp(std::string& dateTime) {
        convertCustomDateTimeToSQLTimeStamp(dateTime, longDateTime);
    }


    inline void convertCustomDateTimeToSQLTimeStamp(
            std::string& dateTime,
            const std::string& customFormat
    ) {
        // check arguments
        if(dateTime.empty()) {
            return;
        }

        if(customFormat.empty()) {
            throw Exception(
                    "DateTime::convertCustomDateTimeToSQLTimeStamp():"
                    " No custom format specified"
            );
        }

        // check for UNIX time format
        if(
                customFormat == unixTimeFormat
                || (
                        customFormat.length() > unixTimeFormatXLength
                        && (
                                customFormat.substr(0, unixTimeFormatXLength) == unixTimeFormatPlus
                                || customFormat.substr(0, unixTimeFormatXLength) == unixTimeFormatMinus
                        )
                    )
        ) {
            // get (optional) offset from UNIX time
            std::int64_t offset{};

            if(customFormat.length() > unixTimeFormatXLength) {
                try {
                    offset = std::stol(customFormat.substr(unixTimeFormatXOffset));
                }
                catch(const std::exception& e) {
                    throw Exception(
                            "DateTime::convertCustomDateTimeToSQLTimeStamp(): Invalid date/time format - "
                            + customFormat
                            + " [expected: UNIX, UNIX+N or UNIX-N where N is a valid number]"
                    );
                }
            }

            // get UNIX time
            std::time_t unixTime{};

            try {
                if(dateTime.find('.') != std::string::npos) {
                    // handle values with comma as floats (and round them)
                    float f{std::stof(dateTime)};

                    unixTime = static_cast<std::time_t>(std::lround(f));
                }
                else {
                    unixTime = static_cast<std::time_t>(std::stol(dateTime));
                }
            }
            catch(const std::exception& e) {
                throw Exception(
                        "Could not convert '"
                        + dateTime
                        + "' [expected format: '"
                        + customFormat
                        + "'] to date/time"
                );
            }

            // remove (optional) offset
            unixTime -= offset;

            // conversion
            dateTime = date::format(
                    sqlTimeStamp,
                    std::chrono::system_clock::from_time_t(unixTime)
            );
        }
        else {
            // remove English ordinal endings (st, nd, rd, th)
            removeOrdinals(englishOrdinalSuffixes, dateTime);

            std::istringstream in(dateTime);
            date::sys_seconds tp;

            in >> date::parse(customFormat, tp);

            if(bool(in)) {
                dateTime = date::format(sqlTimeStamp, tp);
            }
            else {
                // try good old C time
                std::string formatString{customFormat};
                bool isAm{false};
                bool isPm{false};
                std::tm cTime{};

                extendSingleDigits(dateTime);
                handle12hTime(formatString, dateTime, isAm, isPm);

                std::istringstream inStringStream(dateTime);

                inStringStream.imbue(std::locale(std::setlocale(LC_ALL, nullptr)));

                inStringStream >> std::get_time(&cTime, formatString.c_str());

                if(inStringStream.fail()) {
                    throw Exception(
                            "Could not convert '"
                            + dateTime
                            + "' [expected format: '"
                            + formatString
                            + "'] to date/time"
                    );
                }

                if(isAm || isPm) {
                    convert12hTo24h(cTime.tm_hour, isPm);
                }

                std::array<char, sqlTimeStampLength + 1> out{};

                const auto len{
                    std::strftime(out.data(), sqlTimeStampLength + 1, sqlTimeStamp, &cTime)
                };

                if(len > 0) {
                    dateTime = std::string(out.data(), len);
                }
                else {
                    throw Exception(
                            "Could not convert '"
                            + dateTime
                            + "' [expected format: '"
                            + customFormat
                            + "'] to date/time"
                    );
                }
            }
        }

        fixYear(dateTime, customFormat);
    }


    inline void convertCustomDateTimeToSQLTimeStamp(
            std::string& dateTime,
            const std::string& customFormat,
            const std::string& locale
    ) {
        // check arguments
        if(dateTime.empty()) {
            return;
        }

        if(customFormat.empty()) {
            throw Exception(
                    "DateTime::convertCustomDateTimeToSQLTimeStamp():"
                    " No custom format specified"
            );
        }

        if(locale.empty()) {
            convertCustomDateTimeToSQLTimeStamp(dateTime, customFormat);

            return;
        }

        // fix French months ("avr." -> "avril")
        fixFrenchMonths(locale, dateTime);

        // fix Russian and Ukrainian months
        std::string formatString{customFormat};
        fixRussianMonths(locale, dateTime, formatString);
        fixUkrainianMonths(locale, dateTime, formatString);
        fixFinnishMonths(locale, formatString, dateTime);

        // remove ordinals
        removeOrdinals(englishOrdinalSuffixes, dateTime);
        removeOrdinals(locale, frenchLocalePrefix, frenchOrdinalSuffixes, dateTime);
        removeOrdinals(locale, russianLocalePrefix, russianOrdinalSuffixes, dateTime);
        removeOrdinals(locale, ukrainianLocalePrefix, ukrainianOrdinalSuffixes, dateTime);

        std::istringstream in(dateTime);
        date::sys_seconds tp;

        try {
            in.imbue(std::locale(locale));
        }
        catch(const std::runtime_error& e) {
            throw LocaleException("Unknown locale '" + locale + "'");
        }

        in >> date::parse(formatString, tp);

        if(bool(in)) {
            dateTime = date::format(sqlTimeStamp, tp);
        }
        else {
            // try good old C time
            bool isAm{false};
            bool isPm{false};
            std::tm cTime{};

            extendSingleDigits(dateTime);
            handle12hTime(formatString, dateTime, isAm, isPm);

            std::istringstream inStringStream(dateTime);

            inStringStream.imbue(std::locale(locale));

            inStringStream >> std::get_time(&cTime, formatString.c_str());

            if(inStringStream.fail()) {
                throw Exception(
                        "Could not convert '"
                        + dateTime
                        + "' [expected format: '"
                        + formatString
                        + "'] to date/time"
                );
            }

            if(isAm || isPm) {
                convert12hTo24h(cTime.tm_hour, isPm);
            }

            std::array<char, sqlTimeStampLength + 1> out{};

            const auto len{
                std::strftime(out.data(), sqlTimeStampLength + 1, sqlTimeStamp, &cTime)
            };

            if(len > 0) {
                dateTime = std::string(out.data(), len);
            }
            else {
                throw Exception(
                        "Could not convert '"
                        + dateTime
                        + "' [expected format: '"
                        + formatString
                        + "', locale: '"
                        + locale
                        + "'] to date/time"
                );
            }
        }

        fixYear(dateTime, customFormat);
    }


    inline void convertTimeStampToSQLTimeStamp(std::string& timeStamp) {
        convertCustomDateTimeToSQLTimeStamp(timeStamp, "%Y%m%d%H%M%S");
    }


    inline void convertSQLTimeStampToTimeStamp(std::string& timeStamp) {
        // check argument
        if(timeStamp.empty()) {
            return;
        }

        std::istringstream in(timeStamp);
        date::sys_seconds tp;

        in >> date::parse(sqlTimeStamp, tp);

        if(!bool(in)) {
            throw Exception(
                    "Could not convert SQL timestamp '"
                    + timeStamp
                    + "' to date/time"
            );
        }

        timeStamp = date::format("%Y%m%d%H%M%S", tp);
    }


    inline void convert12hTo24h(
            int& hour,
            bool isPm
    ) {
        if(isPm) {
            if(hour < hourNoonMidnight) { /* not 12 PM [noon] */
                hour += hourChange;
            }
        }
        else if(hour == hourNoonMidnight) { /* at 12 AM [midnight] */
            hour = 0;
        }
    }


    inline std::string getYearAndWeek(const std::string& date) {
        std::istringstream in(date);
        date::sys_days tp;

        in >> date::parse("%F", tp);

        if(!bool(in)) {
            throw Exception(
                    "Could not convert date '"
                    + date
                    + "' to week number"
            );
        }

        return date::format("%G-#%V", tp);
    }


    inline void reduceDate(std::string& date, std::uint8_t resolution) {
        if(date.empty()) {
            return;
        }

        if(date.length() != isoDateLength) {
            throw Exception("Invalid length of date " + date);
        }

        switch(resolution) {
        case dateWeeks:
            // reduce to year and week (YYYY-#WW)
            date = getYearAndWeek(date);

            break;

        case dateDays:
            // no reduction necessary

            break;

        case dateMonths:
            // reduce to month (YYYY-MM)
            date = date.substr(0, reducedToMonthLength);

            break;

        case dateYears:
            // reduce to year (YYYY)
            date = date.substr(0, yearLength);

            break;

        default:
            throw Exception("Invalid date resolution: " + std::to_string(resolution));
        }
    }

    /*
     * FORMATTING
     */


    inline std::string microsecondsToString(std::uint64_t microseconds) {
        auto rest{microseconds};
        std::string result;

        const auto days{
            rest / microsecondsPerDay
        };

        rest -= days * microsecondsPerDay;

        // narrowing cast as hours are never more than hours per day
        const auto hours{static_cast<std::uint8_t>(rest / microsecondsPerHour)};

        rest -= hours * microsecondsPerHour;

        // narrowing cast as minutes are never more than minutes per hour
        const auto minutes{static_cast<std::uint8_t>(rest / microsecondsPerMinute)};

        rest -= minutes * microsecondsPerMinute;

        // narrowing cast as seconds are never more than seconds per minute
        const auto seconds{static_cast<std::uint8_t>(rest / microsecondsPerSecond)};

        rest -= seconds * microsecondsPerSecond;

        // narrowing cast as milliseconds are never more than milliseconds per second
        const auto milliseconds{static_cast<std::uint16_t>(rest / microsecondsPerMillisecond)};

        rest -= milliseconds * microsecondsPerMillisecond;

        if(days > 0) {
            result += std::to_string(days) + "d ";
        }

        if(hours > 0) {
            result += std::to_string(hours) + "h ";
        }

        if(minutes > 0) {
            result += std::to_string(minutes) + "min ";
        }

        if(seconds > 0) {
            result += std::to_string(seconds) + "s ";
        }

        if(milliseconds > 0) {
            result += std::to_string(milliseconds) + "ms ";
        }

        if(rest > 0) {
            result += std::to_string(rest) + "μs ";
        }

        if(result.empty()) {
            return "<1μs";
        }

        // remove last space
        result.pop_back();

        return result;
    }


    inline std::string millisecondsToString(std::uint64_t milliseconds) {
        auto rest{milliseconds};
        std::string result;

        const auto days{rest / millisecondsPerDay};

        rest -= days * millisecondsPerDay;

        // narrowing cast as hours will never be more than hours per day
        const auto hours{static_cast<std::uint8_t>(rest / millisecondsPerHour)};

        rest -= hours * millisecondsPerHour;

        // narrowing cast as minutes will never be more than minutes per hour
        const auto minutes{static_cast<std::uint8_t>(rest / millisecondsPerMinute)};

        rest -= minutes * millisecondsPerMinute;

        // narrowing cast as seconds will never be more than seconds per minute
        const auto seconds{static_cast<std::uint8_t>(rest / millisecondsPerSecond)};

        rest -= seconds * millisecondsPerSecond;

        if(days > 0) {
            result += std::to_string(days) + "d ";
        }

        if(hours > 0) {
            result += std::to_string(hours) + "h ";
        }

        if(minutes > 0) {
            result += std::to_string(minutes) + "min ";
        }

        if(seconds > 0) {
            result += std::to_string(seconds) + "s ";
        }

        if(rest > 0) {
            result += std::to_string(rest) + "ms ";
        }

        if(result.empty()) {
            return "<1ms";
        }

        // remove last space
        result.pop_back();

        return result;
    }


    inline std::string secondsToString(std::uint64_t seconds) {
        auto rest{seconds};
        std::string result;

        const auto days{rest / secondsPerDay};

        rest -= days * secondsPerDay;

        // narrowing cast as hours are never more than hours per day
        const auto hours{static_cast<std::uint8_t>(rest / secondsPerHour)};

        rest -= hours * secondsPerHour;

        // narrowing cast as minutes are never more than minutes per hour
        const auto minutes{static_cast<std::uint8_t>(rest / secondsPerMinute)};

        rest -= minutes * secondsPerMinute;

        if(days > 0) {
            result += std::to_string(days) + "d ";
        }

        if(hours > 0) {
            result += std::to_string(hours) + "h ";
        }

        if(minutes > 0) {
            result += std::to_string(minutes) + "min ";
        }

        if(rest > 0) {
            result += std::to_string(rest) + "s ";
        }

        if(result.empty()) {
            return "<1s";
        }

        // remove last space
        result.pop_back();

        return result;
    }


    inline std::string now() {
        return date::format(
                sqlTimeStamp,
                date::floor<std::chrono::seconds>(
                        std::chrono::system_clock::now()
                )
        );
    }

    /*
     * VERIFICATION
     */


    inline bool isValidISODate(const std::string& isoDate) {
        std::istringstream in(isoDate);
        date::sys_days tp;

        in >> date::parse("%F", tp);

        return bool(in);
    }

    /*
     * COMPARISON
     */


    inline bool isISODateInRange(
            std::string_view isoDate,
            std::string_view rangeFrom,
            std::string_view rangeTo
    ) {
        if(isoDate.length() < isoDateLength) {
            return false;
        }

        if(rangeFrom.length() < isoDateLength && rangeTo.length() < isoDateLength) {
            return true;
        }

        if(rangeTo.length() < isoDateLength) {
            return isoDate.substr(0, isoDateLength) >= rangeFrom.substr(0, isoDateLength);
        }

        if(rangeFrom.length() < isoDateLength) {
            return isoDate.substr(0, isoDateLength) <= rangeTo.substr(0, isoDateLength);
        }

        return isoDate.substr(0, isoDateLength) >= rangeFrom.substr(0, isoDateLength)
                && isoDate <= rangeTo.substr(0, isoDateLength);
    }

    /*
     * GAPS INBETWEEN DATES
     */


    inline std::vector<std::string> getDateGap(
            const std::string& first,
            const std::string& second,
            std::uint8_t resolution
    ) {
        // make sure that first date lies before second date
        switch(resolution) {
        case dateWeeks:
            // dates given as weeks (YYYY-#WW)
            return getWeekGap(first, second);

        case dateDays:
            // dates given as days, i.e. in ISO format (YYYY-MM-DD)
            return getDayGap(first, second);

        case dateMonths:
            // dates given as month (YYYY-MM)
            return getMonthGap(first, second);

        case dateYears:
            // dates given as year (YYYY)
            return getYearGap(first, second);

        default:
            throw Exception("Invalid date resolution: " + std::to_string(resolution));
        }
    }


    inline std::vector<std::string> getWeekGap(const std::string& first, const std::string& second) {
        // make sure the first month lies before the second week
        if(first > second) {
            return getWeekGap(second, first);
        }

        // convert strings to time points
        std::istringstream inFirst(first + "-1"); /* use Monday */
        date::sys_days tpFirst;

        inFirst >> date::parse("%G-#%V-%u", tpFirst);

        if(!bool(inFirst)) {
            throw Exception("Invalid week: '" + first + "' (expected: YYYY-#WW)");
        }

        std::istringstream inSecond(second + "-1"); /* use Monday */
        date::sys_days tpSecond;

        inSecond >> date::parse("%G-#%V-%u", tpSecond);

        if(!bool(inSecond)) {
            throw Exception("Invalid week: '" + second + "' (expected: YYYY-#WW)");
        }

        // get distance between time points and reserve memory
        std::vector<std::string> result;
        const auto distance{static_cast<std::size_t>((tpSecond - tpFirst).count()) / 7};

        if(distance > 1) {
            result.reserve(distance - 1);
        }

        // get and return result
        for(std::size_t week{1}; week < distance; ++week) {
            tpFirst += date::days{daysPerWeek};

            result.emplace_back(getYearAndWeek(date::format("%F", tpFirst)));
        }

        return result;
    }


    inline std::vector<std::string> getDayGap(const std::string& first, const std::string& second) {
        // make sure the first date lies before the second date
        if(first > second) {
            return getDayGap(second, first);
        }

        // convert strings to time points
        std::istringstream inFirst(first);
        date::sys_days tpFirst;

        inFirst >> date::parse("%F", tpFirst);

        if(!bool(inFirst)) {
            throw Exception("Invalid date: '" + first + "' (expected: YYYY-MM-DD)");
        }

        std::istringstream inSecond(second);
        date::sys_days tpSecond;

        inSecond >> date::parse("%F", tpSecond);

        if(!bool(inSecond)) {
            throw Exception("Invalid date: '" + second + "' (expected: YYYY-MM-DD)");
        }

        // get distance between time points and reserve memory
        std::vector<std::string> result;
        const auto distance{static_cast<std::size_t>((tpSecond - tpFirst).count())};

        if(distance > 1) {
            result.reserve(distance - 1);
        }

        // get and return result
        for(std::size_t day{1}; day < distance; ++day) {
            tpFirst += date::days{1};

            result.emplace_back(date::format("%F", tpFirst));
        }

        return result;
    }


    inline std::vector<std::string> getMonthGap(const std::string& first, const std::string& second) {
        // make sure the first month lies before the second month
        if(first > second) {
            return getMonthGap(second, first);
        }

        // convert strings to time points
        std::istringstream inFirst(first);
        date::year_month tpFirst;

        inFirst >> date::parse("%Y-%m", tpFirst);

        if(!bool(inFirst)) {
            throw Exception("Invalid month: '" + first + "' (expected: YYYY-MM)");
        }

        std::istringstream inSecond(second);
        date::year_month tpSecond;

        inSecond >> date::parse("%Y-%m", tpSecond);

        if(!bool(inSecond)) {
            throw Exception("Invalid month: '" + second + "' (expected: YYYY-MM)");
        }

        // get distance between time points and reserve memory
        std::vector<std::string> result;
        const auto distance{static_cast<std::size_t>((tpSecond - tpFirst).count())};

        if(distance > 1) {
            result.reserve(distance - 1);
        }

        // get and return result
        for(std::size_t month{1}; month < distance; ++month) {
            tpFirst += date::months{1};

            result.emplace_back(date::format("%Y-%m", tpFirst));
        }

        return result;
    }


    inline std::vector<std::string> getYearGap(const std::string& first, const std::string& second) {
        // make sure the first year lies before the second month
        if(first > second) {
            return getYearGap(second, first);
        }

        // convert strings to time points
        std::istringstream inFirst(first);
        date::year tpFirst;

        inFirst >> date::parse("%Y", tpFirst);

        if(!bool(inFirst)) {
            throw Exception("Invalid year: '" + first + "' (expected: YYYY)");
        }

        std::istringstream inSecond(second);
        date::year tpSecond;

        inSecond >> date::parse("%Y", tpSecond);

        if(!bool(inSecond)) {
            throw Exception("Invalid year: '" + second + "' (expected: YYYY)");
        }

        // get distance between time points and reserve memory
        std::vector<std::string> result;
        const auto distance{static_cast<std::size_t>((tpSecond - tpFirst).count())};

        if(distance > 1) {
            result.reserve(distance - 1);
        }

        // get and return result
        for(std::size_t year{1}; year < distance; ++year) {
            tpFirst += date::years{1};

            result.emplace_back(date::format("%Y", tpFirst));
        }

        return result;
    }

    /*
     * HELPERS
     */


    template<std::size_t N> void removeOrdinals(
            const std::array<std::string_view, N>& suffixes,
            std::string& strInOut
    ) {
        std::size_t pos{};

        while(pos < strInOut.length()) {
            auto next{std::string::npos};
            std::size_t len{};

            for(const auto& suffix : suffixes) {
                const auto search{strInOut.find(suffix, pos)};

                if(search < next) {
                    next = search;
                    len = suffix.length();
                }
            }

            pos = next;

            if(pos == std::string::npos) {
                break;
            }

            if(pos > 0) {
                if(std::isdigit(strInOut.at(pos - 1)) != 0) {
                    const auto end{pos + len};

                    if(
                            end == strInOut.length()
                            || std::isspace(strInOut.at(end)) != 0
                            || std::ispunct(strInOut.at(end)) != 0
                    ) {
                        // remove st, nd, rd or th
                        strInOut.erase(pos, len);

                        // skip whitespace/punctuation afterwards
                        ++pos;
                    }
                    else {
                        pos += len + 1;
                    }
                }
                else {
                    pos += len + 1;
                }
            }
            else {
                pos += len + 1;
            }
        }
    }


    template<std::size_t N> void removeOrdinals(
            std::string_view currentLocale,
            std::string_view localePrefix,
            const std::array<std::string_view, N>& suffixes,
            std::string& strInOut
    ) {
        if(currentLocale.length() >= localePrefix.length()) {
            std::string prefix(currentLocale, 0, localePrefix.length());

            std::transform(
                    prefix.begin(),
                    prefix.end(),
                    prefix.begin(),
                    [](const auto c) {
                        return std::tolower(c);
                    }
            );

            if(prefix == localePrefix) {
                removeOrdinals<N>(suffixes, strInOut);
            }
        }
    }


    inline void fixFrenchMonths(std::string_view locale, std::string& strInOut) {
        if(locale.length() >= frenchLocalePrefix.length()) {
            std::string prefix(locale, 0, frenchLocalePrefix.length());

            std::transform(
                    prefix.begin(),
                    prefix.end(),
                    prefix.begin(),
                    [](const auto c) {
                        return std::tolower(c);
                    }
            );

            if(prefix == frenchLocalePrefix) {
                Helper::Strings::replaceAll(strInOut, "avr.", "avril");
            }
        }
    }


    inline void fixRussianMonths(std::string_view locale, std::string& strInOut, std::string& formatInOut) {
        if(locale.length() >= russianLocalePrefix.length()) {
            std::string prefix(locale, 0, russianLocalePrefix.length());

            std::transform(
                    prefix.begin(),
                    prefix.end(),
                    prefix.begin(),
                    [](const auto c) {
                        return std::tolower(c);
                    }
            );

            if(prefix == russianLocalePrefix) {
                std::string oldString;

                const bool bigB{
                    formatInOut.find("%B") != std::string::npos
                };

                if(bigB) {
                    oldString = strInOut;
                }

                Helper::Strings::replaceAll(strInOut, "январь", "янв");
                Helper::Strings::replaceAll(strInOut, "Январь", "янв");
                Helper::Strings::replaceAll(strInOut, "ЯНВАРЬ", "янв");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Янв", "янв");
                    Helper::Strings::replaceAll(strInOut, "ЯНВ", "янв");
                }

                Helper::Strings::replaceAll(strInOut, "февраль", "фев");
                Helper::Strings::replaceAll(strInOut, "Февраль", "фев");
                Helper::Strings::replaceAll(strInOut, "ФЕВРАЛЬ", "фев");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Фев", "фев");
                    Helper::Strings::replaceAll(strInOut, "ФЕВ", "фев");
                }

                Helper::Strings::replaceAll(strInOut, "марта", "мар");
                Helper::Strings::replaceAll(strInOut, "Марта", "мар");
                Helper::Strings::replaceAll(strInOut, "МАРТА", "мар");
                Helper::Strings::replaceAll(strInOut, "март", "мар");
                Helper::Strings::replaceAll(strInOut, "Март", "мар");
                Helper::Strings::replaceAll(strInOut, "МАРТ", "мар");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Мар", "мар");
                    Helper::Strings::replaceAll(strInOut, "МАР", "мар");
                }

                Helper::Strings::replaceAll(strInOut, "апрель", "апр");
                Helper::Strings::replaceAll(strInOut, "Апрель", "апр");
                Helper::Strings::replaceAll(strInOut, "АПРЕЛЬ", "апр");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Апр", "апр");
                    Helper::Strings::replaceAll(strInOut, "АПР", "апр");
                }

                Helper::Strings::replaceAll(strInOut, "май", "мая");
                Helper::Strings::replaceAll(strInOut, "Май", "мая");
                Helper::Strings::replaceAll(strInOut, "МАЙ", "мая");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Мая", "мая");
                    Helper::Strings::replaceAll(strInOut, "МАЯ", "мая");
                }

                Helper::Strings::replaceAll(strInOut, "июнь", "июн");
                Helper::Strings::replaceAll(strInOut, "Июнь", "июн");
                Helper::Strings::replaceAll(strInOut, "ИЮНь", "июн");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Июн", "июн");
                    Helper::Strings::replaceAll(strInOut, "ИЮН", "июн");
                }

                Helper::Strings::replaceAll(strInOut, "июль", "июл");
                Helper::Strings::replaceAll(strInOut, "Июль", "июл");
                Helper::Strings::replaceAll(strInOut, "ИЮЛь", "июл");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Июл", "июл");
                    Helper::Strings::replaceAll(strInOut, "ИЮЛ", "июл");
                }

                Helper::Strings::replaceAll(strInOut, "августа", "авг");
                Helper::Strings::replaceAll(strInOut, "Августа", "авг");
                Helper::Strings::replaceAll(strInOut, "АВГУСТА", "авг");
                Helper::Strings::replaceAll(strInOut, "август", "авг");
                Helper::Strings::replaceAll(strInOut, "Август", "авг");
                Helper::Strings::replaceAll(strInOut, "АВГУСТ", "авг");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Авг", "авг");
                    Helper::Strings::replaceAll(strInOut, "АВГ", "авг");
                }

                Helper::Strings::replaceAll(strInOut, "сентябрь", "сен");
                Helper::Strings::replaceAll(strInOut, "Сентябрь", "сен");
                Helper::Strings::replaceAll(strInOut, "СЕНТЯБРЬ", "сен");
                Helper::Strings::replaceAll(strInOut, "сентября", "сен");
                Helper::Strings::replaceAll(strInOut, "Сентября", "сен");
                Helper::Strings::replaceAll(strInOut, "СЕНТЯБРя", "сен");
                Helper::Strings::replaceAll(strInOut, "Сен", "сен");
                Helper::Strings::replaceAll(strInOut, "СЕН", "сен");
                Helper::Strings::replaceAll(strInOut, "сент", "сен");
                Helper::Strings::replaceAll(strInOut, "сенТ", "сен");

                Helper::Strings::replaceAll(strInOut, "октябрь", "окт");
                Helper::Strings::replaceAll(strInOut, "Октябрь", "окт");
                Helper::Strings::replaceAll(strInOut, "ОКТЯБРЬ", "окт");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Окт", "окт");
                    Helper::Strings::replaceAll(strInOut, "ОКТ", "окт");
                }

                Helper::Strings::replaceAll(strInOut, "ноябрь", "ноя");
                Helper::Strings::replaceAll(strInOut, "Ноябрь", "ноя");
                Helper::Strings::replaceAll(strInOut, "НОЯБРЬ", "ноя");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Ноя", "ноя");
                    Helper::Strings::replaceAll(strInOut, "НОЯ", "ноя");
                }

                Helper::Strings::replaceAll(strInOut, "декабрь", "дек");
                Helper::Strings::replaceAll(strInOut, "Декабрь", "дек");
                Helper::Strings::replaceAll(strInOut, "ДЕКАБРЬ", "дек");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Дек", "дек");
                    Helper::Strings::replaceAll(strInOut, "ДЕК", "дек");
                }

                if(bigB && strInOut != oldString) {
                    Helper::Strings::replaceAll(formatInOut, "%B", "%b");
                }

                return;
            }
        }

        // if the locale is English, replace the Russified "maj"/"Maj"/"MAJ" with English "May"
        if(
                formatInOut.find("%b") != std::string::npos
                || formatInOut.find("%B") != std::string::npos
        ) {
            if(locale.length() >= englishLocalePrefix.length()) {
                std::string prefix(locale, 0, russianLocalePrefix.length());

                std::transform(
                        prefix.begin(),
                        prefix.end(),
                        prefix.begin(),
                        [](const auto c) {
                            return std::tolower(c);
                        }
                );

                if(prefix == englishLocalePrefix) {
                    Helper::Strings::replaceAll(strInOut, "maj", "May");
                    Helper::Strings::replaceAll(strInOut, "Maj", "May");
                    Helper::Strings::replaceAll(strInOut, "MAJ", "May");
                }
            }
        }
    }


    inline void fixUkrainianMonths(std::string_view locale, std::string& strInOut, std::string& formatInOut) {
        if(locale.length() >= ukrainianLocalePrefix.length()) {
            std::string prefix(locale, 0, ukrainianLocalePrefix.length());

            std::transform(
                    prefix.begin(),
                    prefix.end(),
                    prefix.begin(),
                    [](const auto c) {
                        return std::tolower(c);
                    }
            );

            if(prefix == ukrainianLocalePrefix) {
                const bool bigB{
                    formatInOut.find("%B") != std::string::npos
                };
                std::string oldString;

                if(bigB) {
                    oldString = strInOut;
                }

                Helper::Strings::replaceAll(strInOut, "січень", "січ");
                Helper::Strings::replaceAll(strInOut, "Січень", "січ");
                Helper::Strings::replaceAll(strInOut, "СІЧЕНЬ", "січ");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Січ", "січ");
                    Helper::Strings::replaceAll(strInOut, "СІЧ", "січ");
                    Helper::Strings::replaceAll(strInOut, "стд", "січ");
                    Helper::Strings::replaceAll(strInOut, "Стд", "січ");
                    Helper::Strings::replaceAll(strInOut, "СТД", "січ");
                }

                Helper::Strings::replaceAll(strInOut, "лютий", "лют");
                Helper::Strings::replaceAll(strInOut, "Лютий", "лют");
                Helper::Strings::replaceAll(strInOut, "ЛЮТИЙ", "лют");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Лют", "лют");
                    Helper::Strings::replaceAll(strInOut, "ЛЮТ", "лют");
                }

                Helper::Strings::replaceAll(strInOut, "березень", "бер");
                Helper::Strings::replaceAll(strInOut, "Березень", "бер");
                Helper::Strings::replaceAll(strInOut, "БЕРЕЗЕНЬ", "бер");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Бер", "бер");
                    Helper::Strings::replaceAll(strInOut, "БЕР", "бер");
                }

                Helper::Strings::replaceAll(strInOut, "квітень", "кві");
                Helper::Strings::replaceAll(strInOut, "Квітень", "кві");
                Helper::Strings::replaceAll(strInOut, "КВІТЕНЬ", "кві");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "крс", "кві");
                    Helper::Strings::replaceAll(strInOut, "Крс", "кві");
                    Helper::Strings::replaceAll(strInOut, "КРС", "кві");
                }

                Helper::Strings::replaceAll(strInOut, "травень", "тра");
                Helper::Strings::replaceAll(strInOut, "Травень", "тра");
                Helper::Strings::replaceAll(strInOut, "ТРАВЕНЬ", "тра");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Тра", "тра");
                    Helper::Strings::replaceAll(strInOut, "ТРА", "тра");
                }

                Helper::Strings::replaceAll(strInOut, "червень", "чер");
                Helper::Strings::replaceAll(strInOut, "Червень", "чер");
                Helper::Strings::replaceAll(strInOut, "ЧЕРВЕНЬ", "чер");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Чер", "чер");
                    Helper::Strings::replaceAll(strInOut, "ЧЕР", "чер");
                }

                Helper::Strings::replaceAll(strInOut, "липень", "лип");
                Helper::Strings::replaceAll(strInOut, "Липень", "лип");
                Helper::Strings::replaceAll(strInOut, "ЛИПЕНЬ", "лип");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Лип", "лип");
                    Helper::Strings::replaceAll(strInOut, "ЛИП", "лип");
                }

                Helper::Strings::replaceAll(strInOut, "серпень", "сер");
                Helper::Strings::replaceAll(strInOut, "Серпень", "сер");
                Helper::Strings::replaceAll(strInOut, "СЕРПЕНЬ", "сер");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Сер", "сер");
                    Helper::Strings::replaceAll(strInOut, "СЕР", "сер");
                }

                Helper::Strings::replaceAll(strInOut, "вересень", "вер");
                Helper::Strings::replaceAll(strInOut, "Вересень", "вер");
                Helper::Strings::replaceAll(strInOut, "ВЕРЕСЕНЬ", "вер");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Вер", "вер");
                    Helper::Strings::replaceAll(strInOut, "ВЕР", "вер");
                    Helper::Strings::replaceAll(strInOut, "врс", "вер");
                    Helper::Strings::replaceAll(strInOut, "Врс", "вер");
                    Helper::Strings::replaceAll(strInOut, "ВРС", "вер");
                }

                Helper::Strings::replaceAll(strInOut, "жовтень", "жов");
                Helper::Strings::replaceAll(strInOut, "Жовтень", "жов");
                Helper::Strings::replaceAll(strInOut, "ЖОВТЕНЬ", "жов");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Жов", "жов");
                    Helper::Strings::replaceAll(strInOut, "ЖОВ", "жов");
                    Helper::Strings::replaceAll(strInOut, "жнв", "жов");
                    Helper::Strings::replaceAll(strInOut, "Жнв", "жов");
                    Helper::Strings::replaceAll(strInOut, "ЖНВ", "жов");
                }

                Helper::Strings::replaceAll(strInOut, "листопада", "лис");
                Helper::Strings::replaceAll(strInOut, "Листопада", "лис");
                Helper::Strings::replaceAll(strInOut, "ЛИСТОПАДА", "лис");
                Helper::Strings::replaceAll(strInOut, "листопад", "лис");
                Helper::Strings::replaceAll(strInOut, "Листопад", "лис");
                Helper::Strings::replaceAll(strInOut, "ЛИСТОПАД", "лис");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Лис", "лис");
                    Helper::Strings::replaceAll(strInOut, "ЛИС", "лис");
                }

                Helper::Strings::replaceAll(strInOut, "грудень", "гру");
                Helper::Strings::replaceAll(strInOut, "Грудень", "гру");
                Helper::Strings::replaceAll(strInOut, "ГРУДЕНЬ", "гру");

                if(!bigB) {
                    Helper::Strings::replaceAll(strInOut, "Гру", "гру");
                    Helper::Strings::replaceAll(strInOut, "ГРУ", "гру");
                }

                if(bigB && strInOut != oldString) {
                    Helper::Strings::replaceAll(formatInOut, "%B", "%b");
                }
            }
        }
    }


    inline void fixFinnishMonths(std::string_view locale, std::string_view format, std::string& strInOut) {
        if(
                format.find("%b") != std::string::npos
                && locale.length() >= finnishLocalePrefix.length()
        ) {
            std::string prefix(locale, 0, finnishLocalePrefix.length());

            std::transform(
                    prefix.begin(),
                    prefix.end(),
                    prefix.begin(),
                    [](const auto c) {
                        return std::tolower(c);
                    }
            );

            if(prefix == finnishLocalePrefix) {
                Helper::Strings::replaceAll(strInOut, "tammik", "tammi");
                Helper::Strings::replaceAll(strInOut, "Tammik", "tammi");
                Helper::Strings::replaceAll(strInOut, "TAMMIK", "tammi");

                Helper::Strings::replaceAll(strInOut, "helmik", "helmi");
                Helper::Strings::replaceAll(strInOut, "Helmik", "helmi");
                Helper::Strings::replaceAll(strInOut, "HELMIK", "helmi");

                Helper::Strings::replaceAll(strInOut, "maalisk", "maalis");
                Helper::Strings::replaceAll(strInOut, "Maalisk", "maalis");
                Helper::Strings::replaceAll(strInOut, "MAALISK", "maalis");

                Helper::Strings::replaceAll(strInOut, "huhtik", "huhti");
                Helper::Strings::replaceAll(strInOut, "Huhtik", "huhti");
                Helper::Strings::replaceAll(strInOut, "HUHTIK", "huhti");

                Helper::Strings::replaceAll(strInOut, "toukok", "touko");
                Helper::Strings::replaceAll(strInOut, "Toukok", "touko");
                Helper::Strings::replaceAll(strInOut, "TOUKOK", "touko");

                Helper::Strings::replaceAll(strInOut, "kesäk", "kesä");
                Helper::Strings::replaceAll(strInOut, "Kesäk", "kesä");
                Helper::Strings::replaceAll(strInOut, "KESÄK", "kesä");

                Helper::Strings::replaceAll(strInOut, "heinäk", "heinä");
                Helper::Strings::replaceAll(strInOut, "Heinäk", "heinä");
                Helper::Strings::replaceAll(strInOut, "HEINÄK", "heinä");

                Helper::Strings::replaceAll(strInOut, "elok", "elo");
                Helper::Strings::replaceAll(strInOut, "Elok", "elo");
                Helper::Strings::replaceAll(strInOut, "ELOK", "elo");

                Helper::Strings::replaceAll(strInOut, "syysk", "syys");
                Helper::Strings::replaceAll(strInOut, "Syysk", "syys");
                Helper::Strings::replaceAll(strInOut, "SYYSK", "syys");

                Helper::Strings::replaceAll(strInOut, "marrask", "marras");
                Helper::Strings::replaceAll(strInOut, "Marrask", "marras");
                Helper::Strings::replaceAll(strInOut, "MARRASK", "marras");

                Helper::Strings::replaceAll(strInOut, "jouluk", "joulu");
                Helper::Strings::replaceAll(strInOut, "Jouluk", "joulu");
                Helper::Strings::replaceAll(strInOut, "JOULUK", "joulu");
            }
        }
    }


    inline void extendSingleDigits(std::string& dateTimeString) {
        std::size_t pos{};

        while(pos < dateTimeString.length()) {
            pos = dateTimeString.find_first_of("123456789", pos);

            if(pos == std::string::npos) {
                break;
            }

            if(
                    (
                            pos == 0
                            || std::isdigit(dateTimeString[pos - 1]) == 0
                    ) &&
                    (
                            pos == dateTimeString.length() - 1
                            || std::isdigit(dateTimeString[pos + 1]) == 0
                    )
            ) {
                // extend digit by adding leading zero
                dateTimeString.insert(pos, 1, '0');

                ++pos;
            }

            ++pos;
        }
    }


    inline void fixYear(std::string& sqlTimeStamp, std::string_view format) {
        if(
                format.find("%y") != std::string_view::npos
                && sqlTimeStamp.length() > yearLength
                && std::strtoul(
                        sqlTimeStamp.substr(0, yearLength).c_str(),
                        nullptr,
                        base10
                ) < minTwoDigitYear
        ) {
            sqlTimeStamp[0] = '2';
            sqlTimeStamp[1] = '0';
        }
    }


    inline void handle12hTime(
            std::string& formatString,
            const std::string& dateTimeString,
            bool& outIsAm,
            bool& outIsPm
    ) {
        const auto formatPos{formatString.find("%p")};

        if(formatPos == std::string::npos) {
            return;
        }

        std::size_t pos{};

        while(pos < dateTimeString.length()) {
            auto newPos{pos};
            auto amPos1{dateTimeString.find("am", pos)};
            auto amPos2{dateTimeString.find("AM", pos)};
            auto amPos{std::min(amPos1, amPos2)};

            if(amPos != std::string::npos) {
                newPos = amPos;

                if(
                        (
                                amPos == 0
                                || std::isspace(dateTimeString[amPos - 1]) != 0
                                || std::ispunct(dateTimeString[amPos - 1]) != 0
                                || std::isdigit(dateTimeString[amPos - 1]) != 0
                        ) && (
                                amPos == dateTimeString.length() - amPmLength
                                || std::isspace(dateTimeString[amPos + amPmLength]) != 0
                                || std::ispunct(dateTimeString[amPos + amPmLength]) != 0
                                || std::isdigit(dateTimeString[amPos + amPmLength]) != 0
                        )
                ) {
                    // found am/AM -> replace it in format string
                    Helper::Strings::replaceAll(
                            formatString,
                            "%p",
                            dateTimeString.substr(amPos, amPmLength)
                    );

                    outIsAm = true;

                    return;
                }
            }

            auto pmPos1{dateTimeString.find("pm", pos)};
            auto pmPos2{dateTimeString.find("PM", pos)};
            auto pmPos{std::min(pmPos1, pmPos2)};

            if(pmPos != std::string::npos) {
                if(pmPos > newPos) {
                    newPos = pmPos;
                }

                if(
                        (
                                pmPos == 0
                                || std::isspace(dateTimeString[pmPos - 1]) != 0
                                || std::ispunct(dateTimeString[pmPos - 1]) != 0
                                || std::isdigit(dateTimeString[pmPos - 1]) != 0
                        ) && (
                                pmPos == dateTimeString.length() - amPmLength
                                || std::isspace(dateTimeString[pmPos + amPmLength]) != 0
                                || std::ispunct(dateTimeString[pmPos + amPmLength]) != 0
                                || std::isdigit(dateTimeString[pmPos + amPmLength]) != 0
                        )
                ) {
                    // found pm/PM -> replace it in format string
                    Helper::Strings::replaceAll(
                            formatString,
                            "%p",
                            dateTimeString.substr(pmPos, amPmLength)
                    );

                    outIsPm = true;

                    return;
                }
            }

            if(newPos == pos) {
                break;
            }

            pos = newPos;
        }
    }

} /* namespace crawlservpp::Helper::DateTime */

#endif /* HELPER_DATETIME_HPP_ */