Dogcows Code - chaz/yoink/blob - src/moof/string.hh

   1
   2 /*]  Copyright (c) 2009-2011, Charles McGarvey  [*****************************
   3 **]  All rights reserved.
   4 *
   5 * Distributable under the terms and conditions of the 2-clause BSD license;
   6 * see the file COPYING for a complete text of the license.
   7 *
   8 *****************************************************************************/
   9
  10 #ifndef _MOOF_STRING_HH_
  11 #define _MOOF_STRING_HH_
  12
  13 #include <string>
  14
  15 #include <boost/noncopyable.hpp>
  16
  17
  18 /**
  19  * \file string.hh
  20  * Functions and classes related to string manipulation.
  21  */
  22
  23 namespace moof {
  24
  25
  26 using std::string;
  27 using std::wstring;
  28
  29 /**
  30  * Convert a multi-byte (UTF-8) string to a wide string.
  31  * \param multi The multi-byte string to convert.
  32  * \return The equivalent wide string.
  33  */
  34 wstring multi_to_wide(const string& multi);
  35
  36 /**
  37  * Convert a wide string to a multi-byte (UTF-8) string.
  38  * \param wide The wide string to convert.
  39  * \return The equivalent multi-byte string.
  40  */
  41 string wide_to_multi(const wstring& wide);
  42
  43
  44 /**
  45  * Class exposing the pattern-matching and substitution methods used in
  46  * Lua.
  47  */
  48 class pattern : public boost::noncopyable
  49 {
  50 public:
  51
  52         /**
  53          * Construct a pattern object.
  54          */
  55         pattern() {}
  56
  57         /**
  58          * Construct a pattern object with a pattern.
  59          * \param pattern The pattern.
  60          */
  61         pattern(const std::string& pattern);
  62
  63         /**
  64          * Construct a pattern object with a pattern and source to match.
  65          * \param pattern The pattern.
  66          * \param source The source string.
  67          */
  68         pattern(const std::string& pattern, const std::string& source);
  69
  70         /**
  71          * Deconstruct the pattern.
  72          */
  73         ~pattern();
  74
  75         /**
  76          * Get the pattern pattern.
  77          */
  78         std::string string() const;
  79
  80         /**
  81          * Set the pattern string.
  82          */
  83         void string(const std::string& pattern);
  84
  85         /**
  86          * Match a string against the pattern iteratively.
  87          * \param source The source string.
  88          */
  89         void match(const std::string& source);
  90
  91         /**
  92          * Get the next match.  If the pattern contains captures, this version
  93          * will only get the first capture.
  94          * \param match Reference to a string to be assigned the match.
  95          * \return True if there was a match to get, false otherwise.
  96          */
  97         bool get(std::string& match);
  98
  99         /**
 100          * Get the next match.  Use this version if the pattern contains more
 101          * than one capture to get all of the captures.
 102          * \param captures Reference to a vector of strings to hold the result.
 103          * \return True if there was a match to get, false otherwise.
 104          */
 105         bool get(std::vector<std::string>& captures);
 106
 107         /**
 108          * Match a string against a pattern all at one time.
 109          * \param pattern The pattern.
 110          * \param source The source string.
 111          * \param position The index of the first character of source to match.
 112          * \return The match.
 113          */
 114         static std::string
 115         match(const std::string& pattern, const std::string& source,
 116                         int position = 0)
 117         {
 118                 std::string match;
 119                 pattern::match(match, pattern, source, position);
 120                 return match;
 121         }
 122
 123         /**
 124          * Match a string against a pattern all at one time.
 125          * \param match A reference to a string to be assigned the match.
 126          * \param pattern The pattern.
 127          * \param source The source string.
 128          * \param position The index of the first character of source to match.
 129          * \return True if a match was made, false otherwise.
 130          */
 131         static bool match(std::string& match, const std::string& pattern,
 132                         const std::string& source, int position = 0);
 133
 134         /**
 135          * Match a string against a pattern all at one time.  If the pattern
 136          * contains captures, the resulting vector will contain all of the
 137          * captures.
 138          * \param captures A reference to a vector of strings to contain the
 139          * result.
 140          * \param pattern The pattern.
 141          * \param source The source string.
 142          * \param position The index of the first character of source to match.
 143          * \return True if a match was made, false otherwise.
 144          */
 145         static bool match(std::vector<std::string>& captures, const std::string& pattern,
 146                         const std::string& source, int position = 0);
 147
 148         /**
 149          * Substitute a string using a pattern and replacement string.
 150          * \param pattern The pattern.
 151          * \param source The source string.
 152          * \param replacement The replacement string; may also contain
 153          * references to captures.
 154          * \return The string with any substitutions made.
 155          */
 156         static std::string sub(const std::string& pattern,
 157                         const std::string& source, const std::string& replacement)
 158         {
 159                 std::string substitution;
 160                 pattern::sub(substitution, pattern, source, replacement);
 161                 return substitution;
 162         }
 163
 164         /**
 165          * Substitute a string using a pattern and replacement string.
 166          * \param substitution A reference to a string to contain the result.
 167          * \param pattern The pattern.
 168          * \param source The source string.
 169          * \param replacement The replacement string; may also contain
 170          * references to captures.
 171          * \return The number of substitutions made.
 172          */
 173         static int sub(std::string& substitution, const std::string& pattern,
 174                         const std::string& source, const std::string& replacement);
 175 };
 176
 177
 178 } // namespace moof
 179
 180 #endif // _MOOF_STRING_HH_
 181