Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/branches/kicklib2/src/libraries/util/SubString.h @ 8331

Last change on this file since 8331 was 7401, checked in by landauf, 14 years ago

merged doc branch back to trunk

  • Property svn:eol-style set to native
File size: 9.8 KB
Line 
1/*
2 *   ORXONOX - the hottest 3D action shooter ever to exist
3 *                    > www.orxonox.net <
4 *
5 *
6 *   License notice:
7 *
8 *   This program is free software; you can redistribute it and/or
9 *   modify it under the terms of the GNU General Public License
10 *   as published by the Free Software Foundation; either version 2
11 *   of the License, or (at your option) any later version.
12 *
13 *   This program is distributed in the hope that it will be useful,
14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 *   GNU General Public License for more details.
17 *
18 *   You should have received a copy of the GNU General Public License
19 *   along with this program; if not, write to the Free Software
20 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
21 *
22 *   Author:
23 *      Christian Meyer
24 *   Co-authors:
25 *      Benjamin Grauer
26 *      Fabian 'x3n' Landau
27 *
28
29//  splitLine
30//  STL string tokenizer
31//
32//  Created by Clemens Wacha.
33//  Version 1.0
34//  Copyright (c) 2005 Clemens Wacha. All rights reserved.
35
36 *   Extended by Fabian 'x3n' Landau by the SL_PARENTHESES mode.
37 */
38
39 /**
40    @file
41    @ingroup String
42    @brief A helper class to split a string into several tokens.
43
44    @anchor SubStringExample
45
46    The class SubString can be used to split an std::string into multiple tokens, using
47    a delimiter. SubString allows different options, for example to remove whitespaces
48    around the delimiters or different safe-mode chars, like quotation marks and braces.
49
50    You can access the tokens of the SubString using the [] operator like an array.
51    SubString also supports to join the tokens (or a subset of the tokens) again using
52    @ref orxonox::SubString::join() "join()". It's even possible to get a subset of the
53    SubString as another SubString using @ref orxonox::SubString::subSet() "subSet()".
54
55    Example:
56    @code
57    std::string text = "This is a test, \"Hello \\\" World\" and vector {1, 2, 3}";
58    SubString tokens(text, SubString::WhiteSpaces, "", false, '\\', true, '"', true, '{', '}', true, '\0');
59
60    for (unsigned int i = 0; i < tokens.size(); ++i)
61        COUT(0) << i << ": " << tokens[i] << std::endl;
62    @endcode
63
64    The output of this code is:
65     - 0: This
66     - 1: is
67     - 2: a
68     - 3: test,
69     - 4: Hello " World
70     - 5: and
71     - 6: vector
72     - 7: 1, 2, 3
73
74    The string was split using the delimiter " ". A string between quotation mark is not
75    split, the same holds for strings between '{' and '}'. Note how the quotation marks and
76    the braces were removed from the tokens, because the corresponding argument is 'true'.
77
78    Also note that the comma after "test" in token 3 is still there - it is neither part of the
79    delimiters SubString::WhiteSpaces nor part of the delimiterNeighbours parameter, so it
80    remains a part of the token.
81*/
82
83#ifndef __SubString_H__
84#define __SubString_H__
85
86#include "UtilPrereqs.h"
87
88#include <vector>
89#include <string>
90
91namespace orxonox
92{
93    /**
94        @brief A class that splits a string into multiple tokens using different options.
95
96        The string is split into multiple tokens using a delimiter. Different options like
97        escape character, quotation marks, and more can be used to satisfy your needs.
98
99        See @ref SubStringExample "this description" for an example.
100    */
101    class _UtilExport SubString
102    {
103        /// An enumerator for the internal state of the parser
104        enum SPLIT_LINE_STATE
105        {
106            SL_NORMAL,            //!< Normal state
107            SL_ESCAPE,            //!< After an escape character
108            SL_SAFEMODE,          //!< In safe mode (usually between quotation marks).
109            SL_SAFEESCAPE,        //!< In safe mode with the internal escape character, that escapes even the savemode character.
110            SL_COMMENT,           //!< In Comment mode.
111            SL_PARENTHESES,       //!< Between parentheses (usually '{' and '}')
112            SL_PARENTHESESESCAPE, //!< Between parentheses with the internal escape character, that escapes even the closing paranthesis character.
113        };
114
115    public:
116        SubString();
117        SubString(const std::string& line,
118                  const std::string& delimiters = SubString::WhiteSpaces,
119                  const std::string& delimiterNeighbours = "",
120                  bool bAllowEmptyEntries=false,
121                  char escapeChar ='\\',
122                  bool bRemoveEscapeChar = true,
123                  char safemodeChar = '"',
124                  bool bRemoveSafemodeChar = true,
125                  char openparenthesisChar = '{',
126                  char closeparenthesisChar = '}',
127                  bool bRemoveParenthesisChars = true,
128                  char commentChar = '\0');
129        SubString(unsigned int argc, const char** argv);
130        SubString(const SubString& other, unsigned int begin);
131        SubString(const SubString& other, unsigned int begin, unsigned int end);
132        ~SubString();
133
134        // operate on the SubString
135        SubString& operator=(const SubString& other);
136        bool operator==(const SubString& other) const;
137        bool compare(const SubString& other) const;
138        bool compare(const SubString& other, unsigned int length) const;
139        SubString operator+(const SubString& other) const;
140        SubString& operator+=(const SubString& other);
141        /// Appends the tokens of another SubString to this. @return This SubString.
142        inline SubString& append(const SubString& other) { return (*this += other); }
143
144        /////////////////////////////////////////
145        // Split and Join the any String. ///////
146        unsigned int split(const std::string& line,
147                           const std::string& delimiters = SubString::WhiteSpaces,
148                           const std::string& delimiterNeighbours = "",
149                           bool bAllowEmptyEntries = false,
150                           char escapeChar ='\\',
151                           bool bRemoveEscapeChar = true,
152                           char safemodeChar = '"',
153                           bool bRemoveSafemodeChar = true,
154                           char openparenthesisChar = '{',
155                           char closeparenthesisChar = '}',
156                           bool bRemoveParenthesisChars = true,
157                           char commentChar = '\0');
158
159        std::string join(const std::string& delimiter = " ") const;
160        ////////////////////////////////////////
161
162        // retrieve a SubSet from the String
163        SubString subSet(unsigned int begin) const;
164        SubString subSet(unsigned int begin, unsigned int end) const;
165
166        // retrieve Information from within
167        /// Returns true if the SubString is empty
168        inline bool empty() const { return this->tokens_.empty(); }
169        /// Returns the number of tokens stored in this SubString
170        inline unsigned int size() const { return this->tokens_.size(); }
171        /// Returns the i'th token from the subset of strings @param index The index of the requested doken
172        inline const std::string& operator[](unsigned int index) const { return this->tokens_[index]; }
173        /// Returns the i'th token from the subset of strings @param index The index of the requested token
174        inline const std::string& getString(unsigned int index) const { return (*this)[index]; }
175        /// Returns all tokens as std::vector
176        inline const std::vector<std::string>& getAllStrings() const { return this->tokens_; }
177        /// Returns true if the token is in safemode. @param index The index of the token
178        inline bool isInSafemode(unsigned int index) const { return this->bTokenInSafemode_[index]; }
179        /// Returns the front of the list of tokens.
180        inline const std::string& front() const { return this->tokens_.front(); }
181        /// Returns the back of the list of tokens.
182        inline const std::string& back() const { return this->tokens_.back(); }
183        /// Removes the back of the list of tokens.
184        inline void pop_back() { this->tokens_.pop_back(); this->bTokenInSafemode_.pop_back(); }
185
186        void debug() const;
187
188    public:
189        static const std::string WhiteSpaces;           ///< All whitespaces (usually used as delimiters or delimiterNeighbours
190        static const std::string WhiteSpacesWithComma;  ///< All whitespaces and the comma (usually used as delimiters)
191        static const SubString   NullSubString;         ///< An empty SubString
192
193    private:
194        // the almighty algorithm.
195        static SPLIT_LINE_STATE splitLine(std::vector<std::string>& tokens,
196                                          std::vector<bool>& bTokenInSafemode,
197                                          const std::string& line,
198                                          const std::string& delimiters = SubString::WhiteSpaces,
199                                          const std::string& delimiterNeighbours = "",
200                                          bool bAllowEmptyEntries = false,
201                                          char escapeChar = '\\',
202                                          bool bRemoveEscapeChar = true,
203                                          char safemodeChar = '"',
204                                          bool bRemoveSafemodeChar = true,
205                                          char openparenthesisChar = '{',
206                                          char closeparenthesisChar = '}',
207                                          bool bRemoveParenthesisChars = true,
208                                          char commentChar = '\0',
209                                          SPLIT_LINE_STATE start_state = SL_NORMAL);
210
211        std::vector<std::string>  tokens_;              ///< The tokens after spliting the input line
212        std::vector<bool>         bTokenInSafemode_;    ///< Saves for each token if it was in safe mode (between quotation marks or parenthesis)
213    };
214}
215
216#endif /* __SubString_H__ */
Note: See TracBrowser for help on using the repository browser.