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

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