stringUtils.hpp

Go to the documentation of this file.

/** \file stringUtils.hpp
 * \brief Utilities for working with strings
 *
 * \author Jared R. Males (jaredmales@gmail.com)
 *
 * \ingroup stringutils
 *
 */
 
//***********************************************************************//
// Copyright 2015, 2016, 2017 Jared R. Males (jaredmales@gmail.com)
//
// This file is part of mxlib.
//
// mxlib is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// mxlib 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 General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with mxlib.  If not, see <http://www.gnu.org/licenses/>.
//***********************************************************************//
 
#ifndef ioutils_stringUtils_hpp
#define ioutils_stringUtils_hpp
 
#include <string>
#include <sstream>
#include <vector>
#include <limits>
#include <algorithm>
 
#include "../mxlib.hpp"
 
namespace mx
{
namespace ioutils
{
 
/** \addtogroup stringutils
 * @{
 */
 
/// Convert a numerical value to a string
/** The default version uses the stream library to convert.  A specialization is provided to prevent conversion of
  std::string.
  *
  * The precision parameter is only used for floating point types.  If the default precision==0 is passed, then the
  maximum useful precision is
  * used, from the value of std::numeric_limits<typeT>::max_digits10.
  *
  * The width and pad template parameters can be used to set a fixed maximum width and a pad character.
  *
  * Examples:
  *
  * To convert a double precision number to string:
  * \code
    double d = 2.898434;
    std::string str;
    str = convertToString(d);  //note that you will not normally need to specify <typeT>
  * \endcode
  *
  * To produce a fixed width 0 padded string from an integer:
  * \code
    int i = 23;
    std::string str;
    str = convertToString<int, 5, '0'>(i);  //result is "00023".
  * \endcode
  *
  * \tparam typeT is the type of value to convert
  * \tparam width specifies the maximum width, not including the '\0'
  * \tparam pad specifies the pad character
  *
  * \returns a string representation of value
  *
  */
template <typename typeT, unsigned width = 0, char pad = ' '>
std::string convertToString(
    const typeT &value, ///< [in] the value of type typeT to be converted
    int precision = 0   ///< [in] [optional] the precision (see
                      ///< http://www.cplusplus.com/reference/ios/ios_base/precision/) to use for floating point types.
)
{
 
    std::ostringstream convert;
 
    if( std::is_floating_point<typeT>::value )
    {
        if( precision == 0 )
        {
            convert.precision( std::numeric_limits<typeT>::max_digits10 );
        }
        else
        {
            convert.precision( precision );
        }
    }
 
    convert << value;
 
    if( width == 0 )
    {
        return convert.str();
    }
    else
    {
        std::string c = convert.str();
 
        if( c.length() > width )
        {
            c.erase( width, c.length() - width );
            return c;
        }
 
        return std::string( width - c.length(), pad ) + c;
    }
}
std::string convertToString( {…}
 
// Specialization of convertToString to avoid converting a string to a string
template <>
std::string convertToString<std::string>( const std::string &value, int precision );
 
/// Convert a string to a numerical value.
/** The default version attempts to do the conversion with a simple c style cast.  Template specializations
 * handle conversions to the basic types.
 *
 * Example:
 * \code
 * std::string str = "2.34567";
 * double d;
 * d = convertFromString<double>(str);
 * \endcode
 *
 * \tparam typeT is the type of the numerical value desired
 *
 * \returns the converted numerical value.
 */
template <typename typeT>
typeT convertFromString( const std::string &str /**< [in] is the string to convert*/ )
{
    // If no specialization exists, we try to cast
    return (typeT)str;
}
typeT convertFromString( const std::string &str /**< [in] is the string to convert*/ ) {…}
 
template <>
char convertFromString<char>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
char16_t convertFromString<char16_t>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
char32_t convertFromString<char32_t>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
wchar_t convertFromString<wchar_t>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
signed char convertFromString<signed char>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
unsigned char convertFromString<unsigned char>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
short convertFromString<short>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
unsigned short convertFromString<unsigned short>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
int convertFromString<int>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
unsigned int convertFromString<unsigned int>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
long convertFromString<long>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
unsigned long convertFromString<unsigned long>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
long long convertFromString<long long>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
unsigned long long convertFromString<unsigned long long>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
float convertFromString<float>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
double convertFromString<double>( const std::string &str /* [in] is the string to convert*/ );
 
template <>
long double convertFromString<long double>( const std::string &str /* [in] is the string to convert*/ );
 
/// Template specialization of convertFromString for bool
/** First looks for 0/1, f/t, or F/T in the first non-space character of str.
 * Otherwise, we use convertFromString<int>.
 *
 * \returns the converted numerical value.
 */
template <>
bool convertFromString<bool>( const std::string &str /**< [in] is the string to convert*/ );
 
/// Convert a string to all lower case.
/** Calls the c tolower function for each character in instr.
 *
 */
void toLower( std::string &outstr,     ///< [out]  will be resized and populated with the lower case characters
              const std::string &instr ///< [in] is the string to convert
);
 
/// Convert a string to all lower case.
/** Calls the c tolower function for each character in instr.
 *
 *
 * \return the all lower case string
 */
std::string toLower( const std::string &instr /**< [in] is the string to convert*/ );
 
/// Convert a string to all upper case.
/** Calls the c toupper function for each character in instr.
 *
 */
void toUpper( std::string &outstr,     ///< [out]  will be resized and populated with the lower case characters
              const std::string &instr ///< [in] is the string to convert
);
 
/// Convert a string to all upper case.
/** Calls the c toupper function for each character in instr.
 *
 *
 * \return the all lower case string
 */
std::string toUpper( const std::string &instr /**< [in] is the string to convert*/ );
 
/// Remove all white space from a string.
/**
 * Uses std::remove_if.
 */
void removeWhiteSpace( std::string &outstr,     ///< [out] will contain the new string with no whitespace.
                       const std::string &instr ///< [in] is the string to remove whitespace from
);
 
/// Remove all white space from a string.
/**
 * Uses std::remove_if.
 *
 * \returns the modified string.
 */
std::string removeWhiteSpace( const std::string &instr /**< [in] is the string to remove whitespace from*/ );
 
/// Wrap a string by breaking it into smaller sized portions of a desired width
/** Whenever possible breaks at spaces.  A single space is discarded at the break.
 */
int stringWrap( std::vector<std::string> &lines, /**< [out] each new entry contains a wrapped portion of the string.
                                                            Not cleared, so can accumulate. */
                const std::string &str,          ///< [in] the string to wrap
                int width                        ///< [in] the maximum width of the output strings
);
 
/// Parses a string into a vector of tokens delimited by a character
/** E.g., the string
  * \code
    std::string s={"0,1,2,3,4"};
    std::vector<int> v;
    parseStringVector(v,s);
    \endcode
  * is parsed to a vector as if it was initialized with
    \code
    std::vector<int> v = {0,1,2,3,4};
    \endcode
  *
  * \tparam typeT the type to convert the tokens too.
  */
template <typename typeT>
void parseStringVector(
    std::vector<typeT> &v, ///< [out] the vector holding the parsed and converted tokens.  Is cleared.
    const std::string &s,  ///< [in] the string to parse
    char delim = ','       ///< [in] [optional] the delimiter.  Default is comma \p ','.
)
{
    size_t st;
    size_t com;
 
    st = 0;
    com = s.find( delim, st );
 
    v.clear();
 
    while( com != std::string::npos )
    {
        v.push_back( convertFromString<typeT>( s.substr( st, com - st ) ) );
        st = com + 1;
        com = s.find( delim, st );
    }
    v.push_back( convertFromString<typeT>( s.substr( st, s.size() - st ) ) );
}
void parseStringVector( {…}
 
/// Parses a string into a vector of tokens delimited by a set of characters
/** E.g., the string
  * \code
    std::string s={"0,1:2 3,4"};
    std::vector<int> v;
    parseStringVector(v, s, ",: ");
    \endcode
  * is parsed to a vector as if it was initialized with
    \code
    std::vector<int> v = {0,1,2,3,4};
    \endcode
  *
  * \tparam typeT the type to convert the tokens too.
  */
template <typename typeT>
void parseStringVector(
    std::vector<typeT> &v,    ///< [out] the vector holding the parsed and converted tokens.  Is cleared.
    const std::string &s,     ///< [in] the string to parse
    const std::string &delims ///< [in] the delimiters.
)
{
    size_t st;
    size_t com;
 
    st = 0;
    com = s.find_first_of( delims, st );
 
    v.clear();
 
    while( com != std::string::npos )
    {
        v.push_back( convertFromString<typeT>( s.substr( st, com - st ) ) );
        st = com + 1;
        com = s.find_first_of( delims, st );
    }
    v.push_back( convertFromString<typeT>( s.substr( st, s.size() - st ) ) );
}
void parseStringVector( {…}
/// @}
 
} // namespace ioutils
} // namespace mx
 
#endif // ioutils_stringUtils_hpp