StringUtils.hh

/*
This file is part of the BIAS library (Basic ImageAlgorithmS).

Copyright (C) 2003-2009    (see file CONTACT for details)
Multimediale Systeme der Informationsverarbeitung
Institut fuer Informatik
Christian-Albrechts-Universitaet Kiel


BIAS is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

BIAS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with BIAS; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

#ifndef __STRING_UTILS_HH__
#define __STRING_UTILS_HH__

// std
#include <string>
#include <vector>
#include <algorithm>
#include <iomanip>
#include <sstream>

// BIAS
#include <BIAS_DeclSpec.hh>
#include <Base/Debug/Error.hh>

namespace BIAS {

  /**
   * @class StringUtils
   * @brief Contains some useful methods for string manipulation.
   * @ingroup g_utils
   * @author rwulff 04/2010
   */
  class BIASUtils_EXPORT StringUtils {

  public:

    /**
     * @brief Explodes the given string into tokens which are separated by the
     *        given separator string.
     *
     * Usage example:
     *
     * std::vector<std::string> retVec;
     * StringUtils.Explode("token1 token2 token3", " ", retVec);
     *
     * retVec will now contain the three elements "token1", "token2" and
     * "token3"
     *
     * @param str
     *        the string to explode
     * @param seperator
     *        the string that separates each token from the next
     * @param ret
     *        a vector that contains the single tokens
     */
    static
    void Explode(const std::string &str,
                 const std::string &seperator,
                 std::vector<std::string> &ret);

    /**
     * @brief Splits the given string into tokens which are separated by any of
     *        the given separator characters (similar to #StringUtils::Explode).
     * @param str
     *        the string to split
     * @param ret
     *        a vector that contains the single tokens
     * @param seperator
     *        the characters that separate each token from the next
     */
    static
    void SplitByChars(const std::string &str,
                      std::vector<std::string> &ret,
                      const std::string &charsToSplit = "\t\n ,;");

    /**
     * @brief Trims the given string, i.e. removes all permutations of the
     *        given charsToTrim from the front and the end of the string.
     *
     * Usage example:
     *
     * std::string retStr;
     * StringUtils::Trim("_/_string_/_", retStr, "/_");
     *
     * retStr will now be "string"
     *
     * @param str
     *        the string to trim
     * @param ret
     *        the trimmed string
     * @param charsToTrim
     *        the characters to remove from the front and the end of the string.
     *        the default is to remove all whitespace charakters (spaces, tabs
     *        and newlines). note that the order of characters is irrelevant
     */
    static
    void Trim(const std::string &str,
              std::string &ret,
              const std::string &charsToTrim = " \t\n");

    /**
     * \brief compare two strings ignoring their case
     * \param[in] str1 first string to compare
     * \param[in] str2 second string to compare
     * \return true if strings are equal, false otherwise
     */
    static inline
    bool CompareNoCase( const std::string& str1, const std::string& str2 ) {
        std::string str1Cpy( str1 );
        std::string str2Cpy( str2 );
        std::transform( str1Cpy.begin(), str1Cpy.end(), str1Cpy.begin(), ::tolower );
        std::transform( str2Cpy.begin(), str2Cpy.end(), str2Cpy.begin(), ::tolower );
        return ( str1Cpy == str2Cpy );
    }

    /**
     * @deprecated call PadUintByNumChars() instead
     */
    static inline
    std::string LeadingZeroString(int value, int num) {
      BIASWARNONCE("deprecated, call PadUintByNumChars() instead")
      return PadUintByNumChars(value, num);
    }

    /**
     * @brief Pads the given number with leading zeroes so that the string
     *        representation will use the number of characters determined by
     *        num (if it is not already bigger).
     *
     * @param value
     *        the value to pad
     * @param num
     *        value is padded to use this number of characters
     *
     * @return the padded string
     */
    static inline
    std::string PadUintByNumChars(unsigned int value, unsigned int num)
    {
      std::stringstream ss;
      ss << std::setfill('0') << std::setw(num) << value;
      return ss.str();
    }

    /**
     * @brief Pads the given value with leading zeroes so that the string
     *        representation will use the same number of characters as max.
     *
     * @param value
     *        the value to pad
     * @param max
     *        value is padded to use the same number of characters as this one
     *
     * @return the padded string
     */
    static inline
    std::string PadUintByMaxValue(unsigned int value, unsigned int max)
    {
      std::stringstream ss;

      ss << max;
      const unsigned int lengthMax = ss.str().size();

      ss.str("");
      ss << std::setw(lengthMax) << std::setfill('0') << value;
      return ss.str();
    }

  private:

    /**
     * @brief Hidden default constructor.
     */
    StringUtils()
    { }

  }; // end of class
} // end of namespace

#endif // __STRING_UTILS_HH__