include/wx/tokenzr.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/tokenzr.h
   3 // Purpose:     String tokenizer - a C++ replacement for strtok(3)
   4 // Author:      Guilhem Lavaux
   5 // Modified by: (or rather rewritten by) Vadim Zeitlin
   6 // Created:     04/22/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Guilhem Lavaux
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_TOKENZRH
  13 #define _WX_TOKENZRH
  14
  15 #include "wx/object.h"
  16 #include "wx/string.h"
  17 #include "wx/arrstr.h"
  18
  19 // ----------------------------------------------------------------------------
  20 // constants
  21 // ----------------------------------------------------------------------------
  22
  23 // default: delimiters are usual white space characters
  24 #define wxDEFAULT_DELIMITERS (_T(" \t\r\n"))
  25
  26 // wxStringTokenizer mode flags which determine its behaviour
  27 enum wxStringTokenizerMode
  28 {
  29     wxTOKEN_INVALID = -1,   // set by def ctor until SetString() is called
  30     wxTOKEN_DEFAULT,        // strtok() for whitespace delims, RET_EMPTY else
  31     wxTOKEN_RET_EMPTY,      // return empty token in the middle of the string
  32     wxTOKEN_RET_EMPTY_ALL,  // return trailing empty tokens too
  33     wxTOKEN_RET_DELIMS,     // return the delim with token (implies RET_EMPTY)
  34     wxTOKEN_STRTOK          // behave exactly like strtok(3)
  35 };
  36
  37 // ----------------------------------------------------------------------------
  38 // wxStringTokenizer: replaces infamous strtok() and has some other features
  39 // ----------------------------------------------------------------------------
  40
  41 class WXDLLIMPEXP_BASE wxStringTokenizer : public wxObject
  42 {
  43 public:
  44     // ctors and initializers
  45         // default ctor, call SetString() later
  46     wxStringTokenizer() { m_mode = wxTOKEN_INVALID; }
  47         // ctor which gives us the string
  48     wxStringTokenizer(const wxString& str,
  49                       const wxString& delims = wxDEFAULT_DELIMITERS,
  50                       wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
  51
  52         // args are same as for the non default ctor above
  53     void SetString(const wxString& str,
  54                    const wxString& delims = wxDEFAULT_DELIMITERS,
  55                    wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
  56
  57         // reinitialize the tokenizer with the same delimiters/mode
  58     void Reinit(const wxString& str);
  59
  60     // tokens access
  61         // count them
  62     size_t CountTokens() const;
  63         // did we reach the end of the string?
  64     bool HasMoreTokens() const;
  65         // get the next token, will return empty string if !HasMoreTokens()
  66     wxString GetNextToken();
  67
  68     // get current tokenizer state
  69         // returns the part of the string which remains to tokenize (*not* the
  70         // initial string)
  71     wxString GetString() const { return m_string; }
  72
  73         // returns the current position (i.e. one index after the last
  74         // returned token or 0 if GetNextToken() has never been called) in the
  75         // original string
  76     size_t GetPosition() const { return m_pos; }
  77
  78     // misc
  79         // get the current mode - can be different from the one passed to the
  80         // ctor if it was wxTOKEN_DEFAULT
  81     wxStringTokenizerMode GetMode() const { return m_mode; }
  82
  83     // backwards compatibility section from now on
  84     // -------------------------------------------
  85
  86     // for compatibility only, use GetNextToken() instead
  87     wxString NextToken() { return GetNextToken(); }
  88
  89     // compatibility only, don't use
  90     void SetString(const wxString& to_tokenize,
  91                    const wxString& delims,
  92                    bool WXUNUSED(ret_delim))
  93     {
  94         SetString(to_tokenize, delims, wxTOKEN_RET_DELIMS);
  95     }
  96
  97     wxStringTokenizer(const wxString& to_tokenize,
  98                       const wxString& delims,
  99                       bool ret_delim)
 100     {
 101         SetString(to_tokenize, delims, ret_delim);
 102     }
 103
 104 protected:
 105     bool IsOk() const { return m_mode != wxTOKEN_INVALID; }
 106
 107     wxString m_string,              // the (rest of) string to tokenize
 108              m_delims;              // all delimiters
 109
 110     size_t   m_pos;                 // the position in the original string
 111
 112     wxStringTokenizerMode m_mode;   // see wxTOKEN_XXX values
 113
 114     bool     m_hasMore;             // do we have more (possible empty) tokens?
 115 };
 116
 117 // ----------------------------------------------------------------------------
 118 // convenience function which returns all tokens at once
 119 // ----------------------------------------------------------------------------
 120
 121 // the function takes the same parameters as wxStringTokenizer ctor and returns
 122 // the array containing all tokens
 123 wxArrayString WXDLLIMPEXP_BASE
 124 wxStringTokenize(const wxString& str,
 125                  const wxString& delims = wxDEFAULT_DELIMITERS,
 126                  wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
 127
 128 #endif // _WX_TOKENZRH