wildcardmatcher.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_strings of the \aliblong.
///
/// Copyright 2013-2026 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib {  namespace strings { namespace util  {
 
//==================================================================================================
/// This utility class implements so-called <em>wildcard string matching</em>. Wildcard characters
/// are
/// - <c>'*'</c>: Matches zero or more characters.
/// - <c>'?'</c>: Matches exactly one character.
///
/// Method #".Compile" accepts the pattern string and translates it to an internal (simple) list of
/// "matching commands". This way, the class is optimized for performance, because after
/// compilation, subsequent invocations of #".Match" do not need to parse the pattern string.
///
/// @tparam TChar    The character type. Implementations for \c nchar and \c wchar are provided
///                  with type definitions #"alib::WildcardMatcherN" and
///                  #"alib::WildcardMatcherW".
//==================================================================================================
template<typename TChar>
class TWildcardMatcher {
    /// The result list of commands created with #".Compile" and executed with #".Match".
    std::vector<std::pair<int,TString<TChar>>>  commands;
 
  public:
    /// Constructs a WildcardMatcher to work on a given string. Passes the optional parameters
    /// to method #".Compile".
    ///
    /// @param  pattern      The string pattern to match.
    ///                      Defaults to #"%NULL_STRING" to allow parameterless construction,
    ///                      with later invocation of #".Compile".
    TWildcardMatcher( const TString<TChar>& pattern= NULL_STRING )           { Compile( pattern ); }
 
  public:
    /// Resets this object to use the given pattern.
    ///
    /// @param  pattern      The string pattern to match.
    ALIB_DLL
    void Compile( const TString<TChar>& pattern );
 
    /// Tests if given \p{haystack} matches the actual pattern.
    /// If #".Compile" was not invoked or an empty pattern string was given, \c true is returned.
    ///
    /// @param haystack     The string to test.
    /// @param sensitivity  Denotes whether the matching is performed case-sensitive.
    ///                     Defaults to #"%Case::Sensitive".
    /// @return \c true if given \p{haystack} matches the actual pattern, \c false otherwise.
    ALIB_DLL
    bool Match( const TString<TChar>& haystack, lang::Case sensitivity= lang::Case::Sensitive );
 
}; // class WildcardMatcher
 
 
extern template ALIB_DLL void TWildcardMatcher<nchar>::Compile( const TString<nchar>& );
extern template ALIB_DLL bool TWildcardMatcher<nchar>::Match  ( const TString<nchar>&, lang::Case );
extern template ALIB_DLL void TWildcardMatcher<wchar>::Compile( const TString<wchar>& );
extern template ALIB_DLL bool TWildcardMatcher<wchar>::Match  ( const TString<wchar>&, lang::Case );
 
}} // namespace alib[::strings::util]
 
/// Type alias in namespace #"%alib".
using     WildcardMatcher=     strings::util::TWildcardMatcher<character>;
 
/// Type alias in namespace #"%alib".
using     WildcardMatcherN=    strings::util::TWildcardMatcher<nchar>;
 
/// Type alias in namespace #"%alib".
using     WildcardMatcherW=    strings::util::TWildcardMatcher<wchar>;
 
} // namespace [alib]