src/string_base.h

   1 /*
   2  * This file is part of OpenTTD.
   3  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   4  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   5  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   6  */
   7
   8 #ifndef STRING_BASE_H
   9 #define STRING_BASE_H
  10
  11 #include "string_type.h"
  12
  13 /** Class for iterating over different kind of parts of a string. */
  14 class StringIterator {
  15 public:
  16         /** Type of the iterator. */
  17         enum IterType {
  18                 ITER_CHARACTER, ///< Iterate over characters (or more exactly grapheme clusters).
  19                 ITER_WORD,      ///< Iterate over words.
  20         };
  21
  22         /** Sentinel to indicate end-of-iteration. */
  23         static const size_t END = SIZE_MAX;
  24
  25         /**
  26          * Create a new iterator instance.
  27          * @return New iterator instance.
  28          */
  29         static std::unique_ptr<StringIterator> Create();
  30
  31         virtual ~StringIterator() = default;
  32
  33         /**
  34          * Set a new iteration string. Must also be called if the string contents
  35          * changed. The cursor is reset to the start of the string.
  36          * @param s New string.
  37          */
  38         virtual void SetString(const char *s) = 0;
  39
  40         /**
  41          * Change the current string cursor.
  42          * @param pos New cursor position.
  43          * @return Actual new cursor position at the next valid character boundary.
  44          * @pre pos has to be inside the current string.
  45          */
  46         virtual size_t SetCurPosition(size_t pos) = 0;
  47
  48         /**
  49          * Advance the cursor by one iteration unit.
  50          * @return New cursor position (in bytes) or #END if the cursor is already at the end of the string.
  51          */
  52         virtual size_t Next(IterType what = ITER_CHARACTER) = 0;
  53
  54         /**
  55          * Move the cursor back by one iteration unit.
  56          * @return New cursor position (in bytes) or #END if the cursor is already at the start of the string.
  57          */
  58         virtual size_t Prev(IterType what = ITER_CHARACTER) = 0;
  59
  60 protected:
  61         StringIterator() {}
  62 };
  63
  64 #endif /* STRING_BASE_H */