Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 3, 2010, 12:19:53 AM (15 years ago)
Author:
landauf
Message:

added documentation

File:
1 edited

Legend:

Unmodified
Added
Removed

  • code/branches/doc/src/libraries/util/SubString.h

    r7297 r7327  
    3737 */
    3838
    39  /*!
    40  * @file
    41  * @brief a small class to get the parts of a string separated by commas
    42  *
    43  * This class is also identified as a Tokenizer. It splits up one long
    44  * String into multiple small ones by a designated Delimiter.
    45  *
    46  * Substring is Advanced, and it is possible, to split a string by ','
    47  * but also removing leading and trailing spaces around the comma.
    48  *
    49  * Example:
    50  * Split the String std::string st = "1345, The new empire   , is , orxonox"
    51  * is splitted with:
    52  * @code SubString(st, ',', " \n\t") @endcode
    53  * into
    54  * "1345", "The new empire", "is", "orxonox"
    55  * As you can see, the useless spaces around ',' were removed.
    56  */
     39 /**
     40    @file
     41    @ingroup Util String
     42    @brief a small class to get the parts of a string separated by commas
     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*/
    5782
    5883#ifndef __SubString_H__
    … …  
    6691namespace orxonox
    6792{
    68     //! A class that can load one string and split it in multipe ones
    6993    /**
    70      * SubString is a very Powerfull way to create a SubSet from a String
    71      * It can be used, to Split strings append them and join them again.
    72      */
     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    */
    73101    class _UtilExport SubString
    74102    {
    75     public:
    76         //! An enumerator for the State the Parser is in
    77         typedef enum {
     103        /// An enumerator for the internal state of the parser
     104        enum SPLIT_LINE_STATE
     105        {
    78106            SL_NORMAL,            //!< Normal state
    79107            SL_ESCAPE,            //!< After an escape character
    80             SL_SAFEMODE,          //!< In safe mode (between "" mostly).
     108            SL_SAFEMODE,          //!< In safe mode (usually between quotation marks).
    81109            SL_SAFEESCAPE,        //!< In safe mode with the internal escape character, that escapes even the savemode character.
    82110            SL_COMMENT,           //!< In Comment mode.
    83111            SL_PARENTHESES,       //!< Between parentheses (usually '{' and '}')
    84112            SL_PARENTHESESESCAPE, //!< Between parentheses with the internal escape character, that escapes even the closing paranthesis character.
    85         } SPLIT_LINE_STATE;
    86 
     113        };
    87114
    88115    public:
    89116        SubString();
    90         SubString(const std::string& string, char delimiter = ',');
    91         SubString(const std::string& string,
    92                   const std::string& delimiters, const std::string& delimiterNeighbours = "", bool emptyEntries=false,
    93                   char escapeChar ='\\', bool removeEscapeChar = true, char safemode_char = '"', bool removeSafemodeChar = true,
    94                   char openparenthesis_char = '{', char closeparenthesis_char = '}',  bool removeParenthesisChars = true, char comment_char = '\0');
     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');
    95129        SubString(unsigned int argc, const char** argv);
    96         /** @brief create a Substring as a copy of another one. @param subString the SubString to copy. */
    97         SubString(const SubString& subString) { *this = subString; };
    98         SubString(const SubString& subString, unsigned int subSetBegin);
    99         SubString(const SubString& subString, unsigned int subSetBegin, unsigned int subSetEnd);
     130        SubString(const SubString& other, unsigned int begin);
     131        SubString(const SubString& other, unsigned int begin, unsigned int end);
    100132        ~SubString();
    101133
    102134        // operate on the SubString
    103         SubString& operator=(const SubString& subString);
    104         bool operator==(const SubString& subString) const;
    105         bool compare(const SubString& subString) const;
    106         bool compare(const SubString& subString, unsigned int length) const;
    107         SubString operator+(const SubString& subString) const;
    108         SubString& operator+=(const SubString& subString);
    109         /** @param subString the String to append @returns appended String. @brief added for convenience */
    110         SubString& append(const SubString subString) { return (*this += 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); }
    111143
    112144        /////////////////////////////////////////
    113145        // Split and Join the any String. ///////
    114         unsigned int split(const std::string& string = "", char delimiter = ',');
    115         unsigned int split(const std::string& string,
    116                            const std::string& delimiters, const std::string& delimiterNeighbours = "", bool emptyEntries = false,
    117                            char escapeChar ='\\', bool removeEscapeChar = true, char safemode_char = '"', bool removeSafemodeChar = true,
    118                            char openparenthesis_char = '{', char closeparenthesis_char = '}',  bool removeParenthesisChars = true, char comment_char = '\0');
     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
    119159        std::string join(const std::string& delimiter = " ") const;
    120160        ////////////////////////////////////////
    121161
    122162        // retrieve a SubSet from the String
    123         SubString subSet(unsigned int subSetBegin) const;
    124         SubString subSet(unsigned int subSetBegin, unsigned int subSetEnd) const;
     163        SubString subSet(unsigned int begin) const;
     164        SubString subSet(unsigned int begin, unsigned int end) const;
    125165
    126166        // retrieve Information from within
    127         /** @brief Returns true if the SubString is empty */
    128         inline bool empty() const { return this->strings.empty(); };
    129         /** @brief Returns the count of Strings stored in this substring */
    130         inline unsigned int size() const { return this->strings.size(); };
    131         /** @brief Returns the i'th string from the subset of Strings @param i the i'th String */
    132         inline const std::string& operator[](unsigned int i) const { return this->strings[i]; };
    133         /** @brief Returns the i'th string from the subset of Strings @param i the i'th String */
    134         inline const std::string& getString(unsigned int i) const { return (*this)[i]; };
    135         /** @brief Returns all Strings as std::vector */
    136         inline const std::vector<std::string>& getAllStrings() const { return this->strings; }
    137         /** @brief Returns true if the token is in safemode. @param i the i'th token */
    138         inline bool isInSafemode(unsigned int i) const { return this->bInSafemode[i]; }
    139         /** @brief Returns the front of the StringList. */
    140         inline const std::string& front() const { return this->strings.front(); };
    141         /** @brief Returns the back of the StringList. */
    142         inline const std::string& back() const { return this->strings.back(); };
    143         /** @brief removes the back of the strings list. */
    144         inline void pop_back() { this->strings.pop_back(); this->bInSafemode.pop_back(); };
    145 
     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:
    146194        // the almighty algorithm.
    147         static SPLIT_LINE_STATE splitLine(std::vector<std::string>& ret,
    148                                           std::vector<bool>& bInSafemode,
     195        static SPLIT_LINE_STATE splitLine(std::vector<std::string>& tokens,
     196                                          std::vector<bool>& bTokenInSafemode,
    149197                                          const std::string& line,
    150198                                          const std::string& delimiters = SubString::WhiteSpaces,
    151199                                          const std::string& delimiterNeighbours = "",
    152                                           bool emptyEntries = false,
    153                                           char escape_char = '\\',
    154                                           bool removeEscapeChar = true,
    155                                           char safemode_char = '"',
    156                                           bool removeSafemodeChar = true,
    157                                           char openparenthesis_char = '{',
    158                                           char closeparenthesis_char = '}',
    159                                           bool removeParenthesisChars = true,
    160                                           char comment_char = '\0',
     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',
    161209                                          SPLIT_LINE_STATE start_state = SL_NORMAL);
    162         // debugging.
    163         void debug() const;
    164 
    165     public:
    166         static const std::string WhiteSpaces;
    167         static const std::string WhiteSpacesWithComma;
    168         static const SubString   NullSubString;
    169 
    170     private:
    171         std::vector<std::string>  strings;                      //!< strings produced from a single string splitted in multiple strings
    172         std::vector<bool>         bInSafemode;
     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)
    173213    };
    174214}
Note: See TracChangeset for help on using the changeset viewer.