string.h

Go to the documentation of this file.

#pragma once
// SPDX-FileCopyrightText: 2025 Nessan Fitzmaurice <nzznfitz+gh@icloud.com>
// SPDX-License-Identifier: MIT

 
#include <algorithm>
#include <cctype>
#include <charconv>
#include <format>
#include <iterator>
#include <optional>
#include <ranges>
#include <regex>
#include <string>
#include <vector>
 
namespace utilities {
 
// --------------------------------------------------------------------------------------------------------------------
// We start with the convert-an-input-string-in-place versions which only work on *non-const* input strings.
// --------------------------------------------------------------------------------------------------------------------

[[nodiscard]] constexpr char32_t
to_upper(char32_t cp) noexcept
{
    return (cp >= 97 && cp <= 122) ? (cp ^ 0b100000) : cp;
}

[[nodiscard]] constexpr char32_t
to_lower(char32_t cp) noexcept
{
    return (cp >= 65 && cp <= 90) ? (cp | 0b0100000) : cp;
}

inline void
upper_case(std::string& str)
{
    std::transform(str.begin(), str.end(), str.begin(), [](char ch) {
        return static_cast<char>(to_upper(static_cast<char32_t>(static_cast<unsigned char>(ch))));
    });
}

inline void
lower_case(std::string& str)
{
    std::transform(str.begin(), str.end(), str.begin(), [](char ch) {
        return static_cast<char>(to_lower(static_cast<char32_t>(static_cast<unsigned char>(ch))));
    });
}

inline void
trim_left(std::string& str)
{
    str.erase(str.begin(), std::find_if(str.begin(), str.end(), [](int ch) { return !std::isspace(ch); }));
}

inline void
trim_right(std::string& str)
{
    str.erase(std::find_if(str.rbegin(), str.rend(), [](int ch) { return !std::isspace(ch); }).base(), str.end());
}

inline void
trim(std::string& str)
{
    trim_left(str);
    trim_right(str);
}

inline void
replace_left(std::string& str, std::string_view target, std::string_view replacement)
{
    auto p = str.find(target);
    if (p != std::string::npos) str.replace(p, target.length(), replacement);
}

inline void
replace_right(std::string& str, std::string_view target, std::string_view replacement)
{
    auto p = str.rfind(target);
    if (p != std::string::npos) str.replace(p, target.length(), replacement);
}

inline void
replace(std::string& str, std::string_view target, std::string_view replacement)
{
    std::size_t p = 0;
    while ((p = str.find(target, p)) != std::string::npos) {
        str.replace(p, target.length(), replacement);
        p += replacement.length();
    }
}

inline void
replace_space(std::string& s, const std::string& with = " ", bool also_trim = true)
{
    if (also_trim) trim(s);
    std::regex ws{R"(\s+)"};
    s = std::regex_replace(s, ws, with);
}

inline void
condense(std::string& s, bool also_trim = true)
{
    replace_space(s, " ", also_trim);
}

inline void
erase_left(std::string& str, std::string_view target)
{
    auto p = str.find(target);
    if (p != std::string::npos) str.erase(p, target.length());
}

inline void
erase_right(std::string& str, std::string_view target)
{
    auto p = str.rfind(target);
    if (p != std::string::npos) str.erase(p, target.length());
}

inline void
erase(std::string& str, std::string_view target)
{
    std::size_t p = 0;
    while ((p = str.find(target, p)) != std::string::npos) str.erase(p, target.length());
}

inline void
remove_surrounds(std::string& s)
{
    std::size_t len = s.length();
    while (len > 1) {
        // If the first character is alpha-numeric we are done.
        char first = s[0];
        if (isalnum(first)) return;
 
        // First character is not alpha-numeric.
        // Grab the last character & check for a match.
        char last = s[len - 1];
        bool match = false;
 
        // Handle cases [text], {text}, <text>, and (text) and then all others
        switch (first) {
            case '(':
                if (last == ')') match = true;
                break;
            case '[':
                if (last == ']') match = true;
                break;
            case '{':
                if (last == '}') match = true;
                break;
            case '<':
                if (last == '>') match = true;
                break;
            default:
                if (last == first) match = true;
                break;
        }
 
        if (match) {
            // Shrink the string and continue
            s = s.substr(1, len - 2);
            len -= 2;
        }
        else {
            // No match => no surround so we can exit.
            return;
        }
    }
}

inline void
standardize(std::string& s)
{
    condense(s);
    upper_case(s);
    remove_surrounds(s);
    trim(s);
}
 
// --------------------------------------------------------------------------------------------------------------------
// Next we have all the counterpart create-a-new-string that is a copy of input-string with the appropriate conversion.
// These happily work on *const* input strings as the inputs are left unaltered.
// --------------------------------------------------------------------------------------------------------------------

inline std::string
upper_cased(std::string_view input)
{
    std::string s{input};
    upper_case(s);
    return s;
}

inline std::string
lower_cased(std::string_view input)
{
    std::string s{input};
    lower_case(s);
    return s;
}

inline std::string
trimmed_left(std::string_view input)
{
    std::string s{input};
    trim_left(s);
    return s;
}

inline std::string
trimmed_right(std::string_view input)
{
    std::string s{input};
    trim_right(s);
    return s;
}

inline std::string
trimmed(std::string_view input)
{
    std::string s{input};
    trim(s);
    return s;
}

inline std::string
replaced_left(std::string_view input, std::string_view target, std::string_view replacement)
{
    std::string s{input};
    replace_left(s, target, replacement);
    return s;
}

inline std::string
replaced_right(std::string_view input, std::string_view target, std::string_view replacement)
{
    std::string s{input};
    replace_right(s, target, replacement);
    return s;
}

inline std::string
replaced(std::string_view input, std::string_view target, std::string_view replacement)
{
    std::string s{input};
    replace(s, target, replacement);
    return s;
}

inline std::string
replaced_space(std::string_view input, const std::string& with = " ", bool also_trim = true)
{
    std::string s{input};
    replace_space(s, with, also_trim);
    return s;
}

inline std::string
condensed(std::string_view input, bool also_trim = true)
{
    std::string s{input};
    condense(s, also_trim);
    return s;
}

inline std::string
erased_left(std::string_view input, std::string_view target)
{
    std::string s{input};
    erase_left(s, target);
    return s;
}

inline std::string
erased_right(std::string_view input, std::string_view target)
{
    std::string s{input};
    erase_right(s, target);
    return s;
}

inline std::string
erased(std::string_view input, std::string_view target)
{
    std::string s{input};
    erase(s, target);
    return s;
}

inline std::string
removed_surrounds(std::string_view input)
{
    std::string s{input};
    remove_surrounds(s);
    return s;
}

inline std::string
standardized(std::string_view input)
{
    std::string s{input};
    standardize(s);
    return s;
}
 
// --------------------------------------------------------------------------------------------------------------------
// Next some functions that have no 'in-place' versus 'out-of-place' versions.
// --------------------------------------------------------------------------------------------------------------------

inline bool
starts_with(std::string_view str, std::string_view prefix)
{
    return str.find(prefix) == 0;
}

inline bool
ends_with(std::string_view str, std::string_view suffix)
{
    const auto pos = str.rfind(suffix);
    return (pos != std::string::npos) && (pos == (str.length() - suffix.length()));
}

template<typename T>
constexpr std::optional<T>
possible(std::string_view in, const char** next = nullptr)
{
    in.remove_prefix(in.find_first_not_of("+ "));
    T    retval;
    auto ec = std::from_chars(in.cbegin(), in.cend(), retval);
    if (next) *next = ec.ptr;
    if (ec.ec != std::errc{}) return std::nullopt;
    return retval;
}

template<std::input_iterator InputIt, std::forward_iterator ForwardIt, typename BinaryFunc>
constexpr void
for_each_token(InputIt ib, InputIt ie, ForwardIt db, ForwardIt de, BinaryFunc function)
{
    while (ib != ie) {
        const auto x = std::find_first_of(ib, ie, db, de); // Find a token in the input text
        function(ib, x);                                   // Call the user supplied function on the token
        if (x == ie) break;                                // Stop if we hit the end of the input text
        ib = std::next(x);                                 // Otherwise go again past that token we just found
    }
}

template<typename Container_t>
constexpr void
tokenize(std::string_view input, Container_t& output, std::string_view delimiters = "\t,;: ", bool skip = true)
{
    auto ib = cbegin(input);
    auto ie = cend(input);
    auto db = cbegin(delimiters);
    auto de = cend(delimiters);
 
    for_each_token(ib, ie, db, de, [&output, &skip](auto tb, auto te) {
        if (tb != te || !skip) { output.emplace_back(tb, te); }
    });
}

inline std::vector<std::string>
split(std::string_view input, std::string_view delimiters = "\t,;: ", bool skip = true)
{
    std::vector<std::string> output;
    output.reserve(input.size() / 2);
    tokenize(input, output, delimiters, skip);
    return output;
}

template<typename Iter, typename Traits, typename CharT, typename UnaryFunction>
std::basic_string<CharT>
regex_replace(Iter ib, Iter ie, const std::basic_regex<CharT, Traits>& re, UnaryFunction f)
{
    std::basic_string<CharT> s;
 
    using diff_t = typename std::match_results<Iter>::difference_type;
    diff_t match_pos_old = 0;
    auto   end_last_match = ib;
 
    auto callback = [&](const std::match_results<Iter>& match) {
        auto match_pos = match.position(0);
        auto diff = match_pos - match_pos_old;
 
        auto start_match = end_last_match;
        std::advance(start_match, diff);
 
        s.append(end_last_match, start_match);
        s.append(f(match));
 
        auto match_len = match.length(0);
        match_pos_old = match_pos + match_len;
        end_last_match = start_match;
        std::advance(end_last_match, match_len);
    };
 
    std::regex_iterator<Iter> begin(ib, ie, re), end;
    std::for_each(begin, end, callback);
    s.append(end_last_match, ie);
    return s;
}

template<typename Traits, typename CharT, typename UnaryFunction>
std::string
regex_replace(const std::string& s, const std::basic_regex<CharT, Traits>& re, UnaryFunction f)
{
    return regex_replace(s.cbegin(), s.cend(), re, f);
}
 
} // namespace utilities