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