Utils.h

Go to the documentation of this file.

/*
 * MIT License
 *
 * Copyright (c) 2025 nfx
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

 
#pragma once
 
#include <cstdint>
#include <optional>
#include <string>
#include <string_view>
 
namespace nfx::string
{
    //=====================================================================
    // String utilities
    //=====================================================================
 
    //----------------------------------------------
    // String validation
    //----------------------------------------------

    [[nodiscard]] inline constexpr bool hasExactLength( std::string_view str, std::size_t expectedLength ) noexcept;

    [[nodiscard]] inline constexpr bool isEmpty( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isNullOrWhiteSpace( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isAllDigits( std::string_view str ) noexcept;
 
    //----------------------------------------------
    // Character classification
    //----------------------------------------------

    [[nodiscard]] inline constexpr bool isWhitespace( char c ) noexcept;

    [[nodiscard]] inline constexpr bool isDigit( char c ) noexcept;

    [[nodiscard]] inline constexpr bool isAlpha( char c ) noexcept;

    [[nodiscard]] inline constexpr bool isAlphaNumeric( char c ) noexcept;

    [[nodiscard]] inline constexpr bool isHexDigit( char c ) noexcept;

    [[nodiscard]] inline constexpr bool isOctal( char c ) noexcept;
 
    //----------------------------------------------
    // String operations
    //----------------------------------------------

    [[nodiscard]] inline constexpr bool startsWith( std::string_view str, std::string_view prefix ) noexcept;

    [[nodiscard]] inline constexpr bool startsWith( std::string_view str, char prefix ) noexcept;

    [[nodiscard]] inline constexpr bool startsWith( std::string_view str, const char* prefix ) noexcept;

    [[nodiscard]] inline bool istartsWith( std::string_view str, std::string_view prefix ) noexcept;

    [[nodiscard]] inline bool istartsWith( std::string_view str, char prefix ) noexcept;

    [[nodiscard]] inline bool istartsWith( std::string_view str, const char* prefix ) noexcept;

    [[nodiscard]] inline constexpr bool endsWith( std::string_view str, std::string_view suffix ) noexcept;

    [[nodiscard]] inline constexpr bool endsWith( std::string_view str, char suffix ) noexcept;

    [[nodiscard]] inline constexpr bool endsWith( std::string_view str, const char* suffix ) noexcept;

    [[nodiscard]] inline bool iendsWith( std::string_view str, std::string_view suffix ) noexcept;

    [[nodiscard]] inline bool iendsWith( std::string_view str, char suffix ) noexcept;

    [[nodiscard]] inline bool iendsWith( std::string_view str, const char* suffix ) noexcept;

    [[nodiscard]] inline constexpr bool contains( std::string_view str, std::string_view substr ) noexcept;

    [[nodiscard]] inline constexpr bool contains( std::string_view str, char ch ) noexcept;

    [[nodiscard]] inline constexpr bool contains( std::string_view str, const char* substr ) noexcept;

    [[nodiscard]] inline bool icontains( std::string_view str, std::string_view substr ) noexcept;

    [[nodiscard]] inline bool icontains( std::string_view str, char ch ) noexcept;

    [[nodiscard]] inline bool icontains( std::string_view str, const char* substr ) noexcept;

    [[nodiscard]] inline constexpr bool equals( std::string_view lhs, std::string_view rhs ) noexcept;

    [[nodiscard]] inline bool iequals( std::string_view lhs, std::string_view rhs ) noexcept;

    [[nodiscard]] inline std::size_t count( std::string_view str, std::string_view substr ) noexcept;

    [[nodiscard]] inline std::size_t countOverlapping( std::string_view str, std::string_view substr ) noexcept;

    [[nodiscard]] inline constexpr std::size_t count( std::string_view str, char ch ) noexcept;

    [[nodiscard]] inline std::string replace( std::string_view str, std::string_view oldStr, std::string_view newStr );

    [[nodiscard]] inline std::string replaceAll( std::string_view str, std::string_view oldStr, std::string_view newStr );

    template <typename Container>
    [[nodiscard]] inline std::string join( const Container& elements, std::string_view delimiter );

    template <typename Iterator>
    [[nodiscard]] inline std::string join( Iterator begin, Iterator end, std::string_view delimiter );

    [[nodiscard]] inline std::string reverse( std::string_view str );

    [[nodiscard]] inline constexpr std::size_t indexOf( std::string_view str, std::string_view substr ) noexcept;

    [[nodiscard]] inline constexpr std::size_t indexOf( std::string_view str, char ch ) noexcept;

    [[nodiscard]] inline constexpr std::size_t lastIndexOf( std::string_view str, std::string_view substr ) noexcept;

    [[nodiscard]] inline constexpr std::size_t lastIndexOf( std::string_view str, char ch ) noexcept;
 
    //----------------------------------------------
    // String formatting and padding
    //----------------------------------------------

    [[nodiscard]] inline std::string padLeft( std::string_view str, std::size_t width, char fillChar = ' ' );

    [[nodiscard]] inline std::string padRight( std::string_view str, std::size_t width, char fillChar = ' ' );

    [[nodiscard]] inline std::string center( std::string_view str, std::size_t width, char fillChar = ' ' );

    [[nodiscard]] inline std::string repeat( std::string_view str, std::size_t count );
 
    //----------------------------------------------
    // Substring extraction
    //----------------------------------------------

    [[nodiscard]] inline constexpr std::string_view substringBefore( std::string_view str, std::string_view delimiter ) noexcept;

    [[nodiscard]] inline constexpr std::string_view substringBefore( std::string_view str, char delimiter ) noexcept;

    [[nodiscard]] inline constexpr std::string_view substringAfter( std::string_view str, std::string_view delimiter ) noexcept;

    [[nodiscard]] inline constexpr std::string_view substringAfter( std::string_view str, char delimiter ) noexcept;

    [[nodiscard]] inline constexpr std::string_view substringBeforeLast( std::string_view str, std::string_view delimiter ) noexcept;

    [[nodiscard]] inline constexpr std::string_view substringBeforeLast( std::string_view str, char delimiter ) noexcept;

    [[nodiscard]] inline constexpr std::string_view substringAfterLast( std::string_view str, std::string_view delimiter ) noexcept;

    [[nodiscard]] inline constexpr std::string_view substringAfterLast( std::string_view str, char delimiter ) noexcept;

    [[nodiscard]] inline constexpr std::string_view extractBetween( std::string_view str, std::string_view start, std::string_view end ) noexcept;

    [[nodiscard]] inline constexpr std::string_view removePrefix( std::string_view str, std::string_view prefix ) noexcept;

    [[nodiscard]] inline constexpr std::string_view removeSuffix( std::string_view str, std::string_view suffix ) noexcept;
 
    //----------------------------------------------
    // Character & String Removal
    //----------------------------------------------

    [[nodiscard]] inline std::string removeAll( std::string_view str, char ch );

    [[nodiscard]] inline std::string removeAll( std::string_view str, std::string_view substr );

    template <typename Predicate>
    [[nodiscard]] inline std::string removeIf( std::string_view str, Predicate pred );

    [[nodiscard]] inline std::string removeWhitespace( std::string_view str );

    [[nodiscard]] inline std::string collapseWhitespace( std::string_view str );
 
    //----------------------------------------------
    // String trimming
    //----------------------------------------------

    [[nodiscard]] inline constexpr std::string_view trimStart( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr std::string_view trimEnd( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr std::string_view trim( std::string_view str ) noexcept;
 
    //----------------------------------------------
    // Predicate-based operations
    //----------------------------------------------

    template <typename Predicate>
    [[nodiscard]] inline constexpr std::string_view trimStartIf( std::string_view str, Predicate pred ) noexcept;

    template <typename Predicate>
    [[nodiscard]] inline constexpr std::string_view trimEndIf( std::string_view str, Predicate pred ) noexcept;

    template <typename Predicate>
    [[nodiscard]] inline constexpr std::string_view trimIf( std::string_view str, Predicate pred ) noexcept;

    template <typename Predicate>
    [[nodiscard]] inline constexpr std::size_t countIf( std::string_view str, Predicate pred ) noexcept;

    template <typename Predicate>
    [[nodiscard]] inline constexpr std::size_t findIf( std::string_view str, Predicate pred ) noexcept;

    template <typename Predicate>
    [[nodiscard]] inline constexpr std::size_t findIfNot( std::string_view str, Predicate pred ) noexcept;

    template <typename Predicate>
    [[nodiscard]] inline std::string replaceIf( std::string_view str, Predicate pred, char replacement );
 
    //----------------------------------------------
    // String case conversion
    //----------------------------------------------

    [[nodiscard]] inline std::string toLower( std::string_view str );

    [[nodiscard]] inline std::string toUpper( std::string_view str );
 
    //----------------------------------------------
    // Character case conversion
    //----------------------------------------------

    [[nodiscard]] inline constexpr char toLower( char c ) noexcept;

    [[nodiscard]] inline constexpr char toUpper( char c ) noexcept;
 
    //----------------------------------------------
    // Character conversion
    //----------------------------------------------

    [[nodiscard]] inline constexpr int hexToInt( char c ) noexcept;

    [[nodiscard]] inline constexpr int octalToInt( char c ) noexcept;

    [[nodiscard]] inline constexpr int digitToInt( char c ) noexcept;
 
    //----------------------------------------------
    // UTF-8 utilities
    //----------------------------------------------

    [[nodiscard]] inline bool decodeUtf8Codepoint( std::string_view str, std::size_t& i, uint32_t& codepoint ) noexcept;

    inline void encodeUtf8Codepoint( std::string& result, uint32_t codepoint ) noexcept;

    [[nodiscard]] inline std::size_t utf8Length( std::string_view str ) noexcept;

    [[nodiscard]] inline bool isValidUtf8( std::string_view str ) noexcept;

    [[nodiscard]] inline std::string_view utf8Substring( std::string_view str,
        std::size_t startCodepoint,
        std::size_t codepointCount = std::string_view::npos ) noexcept;
 
    //----------------------------------------------
    // String parsing
    //----------------------------------------------

    template <typename T>
        requires(
            std::is_same_v<std::decay_t<T>, bool> ||
            std::is_same_v<std::decay_t<T>, int> ||
            std::is_same_v<std::decay_t<T>, std::uint32_t> ||
            std::is_same_v<std::decay_t<T>, std::int64_t> ||
            std::is_same_v<std::decay_t<T>, std::uint64_t> ||
            std::is_same_v<std::decay_t<T>, float> ||
            std::is_same_v<std::decay_t<T>, double> )
    [[nodiscard]] inline bool fromString( std::string_view str, T& result ) noexcept;

    template <typename T>
        requires(
            std::is_same_v<std::decay_t<T>, bool> ||
            std::is_same_v<std::decay_t<T>, int> ||
            std::is_same_v<std::decay_t<T>, std::uint32_t> ||
            std::is_same_v<std::decay_t<T>, std::int64_t> ||
            std::is_same_v<std::decay_t<T>, std::uint64_t> ||
            std::is_same_v<std::decay_t<T>, float> ||
            std::is_same_v<std::decay_t<T>, double> )
    [[nodiscard]] inline std::optional<T> fromString( std::string_view str ) noexcept;
 
    //----------------------------------------------
    // Network and URI validation
    //----------------------------------------------
 
    //-----------------------------
    // URI character classification
    //-----------------------------

    [[nodiscard]] inline constexpr bool isUriReserved( char c ) noexcept;

    [[nodiscard]] inline constexpr bool isUriReserved( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isUriUnreserved( char c ) noexcept;

    [[nodiscard]] inline constexpr bool isUriUnreserved( std::string_view str ) noexcept;
 
    //-----------------------------
    // URL encoding/decoding
    //-----------------------------

    [[nodiscard]] inline std::string urlEncode( std::string_view str );

    [[nodiscard]] inline std::string urlDecode( std::string_view str ) noexcept;
 
    //-----------------------------
    // JSON escape/unescape
    //-----------------------------

    [[nodiscard]] inline std::string jsonEscape( std::string_view str, bool escapeNonAscii = false, bool escapeForHtml = false );

    [[nodiscard]] inline std::string jsonUnescape( std::string_view str ) noexcept;
 
    //-----------------------------
    // XML/HTML escape/unescape
    //-----------------------------

    [[nodiscard]] inline std::string xmlEscape( std::string_view str, bool escapeNonAscii = false );

    [[nodiscard]] inline std::string xmlUnescape( std::string_view str ) noexcept;
 
    //-----------------------------
    // C/C++ escape sequences
    //-----------------------------

    [[nodiscard]] inline std::string cppEscape( std::string_view str );

    [[nodiscard]] inline std::string cppUnescape( std::string_view str ) noexcept;
 
    //-----------------------------
    // String formatting utilities
    //-----------------------------

    [[nodiscard]] inline std::string truncate( std::string_view str, size_t maxLength );

    [[nodiscard]] inline std::string truncate( std::string_view str, size_t maxLength, std::string_view ellipsis );

    [[nodiscard]] inline std::string wordWrap( std::string_view str, size_t width );

    [[nodiscard]] inline std::string indent( std::string_view str, size_t spaces );

    [[nodiscard]] inline std::string dedent( std::string_view str );
 
    //-----------------------------
    // Advanced comparison
    //-----------------------------

    [[nodiscard]] inline constexpr int compareIgnoreCase( std::string_view lhs, std::string_view rhs ) noexcept;

    [[nodiscard]] inline constexpr int naturalCompare( std::string_view lhs, std::string_view rhs ) noexcept;

    [[nodiscard]] inline constexpr int inaturalCompare( std::string_view lhs, std::string_view rhs ) noexcept;

    [[nodiscard]] inline constexpr bool naturalSort( std::string_view a, std::string_view b ) noexcept;

    [[nodiscard]] inline constexpr bool inaturalSort( std::string_view a, std::string_view b ) noexcept;

    [[nodiscard]] inline constexpr std::string_view commonPrefix( std::string_view lhs, std::string_view rhs ) noexcept;

    [[nodiscard]] inline constexpr std::string_view commonSuffix( std::string_view lhs, std::string_view rhs ) noexcept;
 
    //-----------------------------
    // IP address validation
    //-----------------------------

    [[nodiscard]] inline constexpr bool isIpv4Address( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isIpv6Address( std::string_view str ) noexcept;
 
    //-----------------------------
    // Host validation
    //-----------------------------

    [[nodiscard]] inline constexpr bool isHostname( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isIdnHostname( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isDomainName( std::string_view str ) noexcept;
 
    //-----------------------------
    // Port validation
    //-----------------------------

    [[nodiscard]] inline constexpr bool isPortNumber( std::string_view str ) noexcept;
 
    //-----------------------------
    // Endpoint parsing
    //-----------------------------

    [[nodiscard]] inline bool tryParseEndpoint( std::string_view endpoint,
        std::string_view& host,
        uint16_t& port ) noexcept;
 
    //-----------------------------
    // Date and Time validation (RFC 3339)
    //-----------------------------

    [[nodiscard]] inline constexpr bool isDateTime( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isDate( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isTime( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isDuration( std::string_view str ) noexcept;
 
    //-----------------------------
    // Email validation (RFC 5321)
    //-----------------------------

    [[nodiscard]] inline constexpr bool isEmail( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isIdnEmail( std::string_view str ) noexcept;
 
    //-----------------------------
    // UUID validation (RFC 4122)
    //-----------------------------

    [[nodiscard]] inline constexpr bool isUuid( std::string_view str ) noexcept;
 
    //-----------------------------
    // URI validation (RFC 3986)
    //-----------------------------

    [[nodiscard]] inline constexpr bool isUri( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isUriReference( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isUriTemplate( std::string_view str ) noexcept;
 
    //-----------------------------
    // IRI validation (RFC 3987)
    //-----------------------------

    [[nodiscard]] inline constexpr bool isIri( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isIriReference( std::string_view str ) noexcept;
 
    //-----------------------------
    // JSON Pointer validation (RFC 6901)
    //-----------------------------

    [[nodiscard]] inline constexpr bool isJsonPointer( std::string_view str ) noexcept;

    [[nodiscard]] inline constexpr bool isRelativeJsonPointer( std::string_view str ) noexcept;
} // namespace nfx::string
 
#include "nfx/detail/string/Utils.inl"