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