Improved method signature, constification of parameter and type

[libi2ncommon] / src / stringfunc.hxx

/** @file
 * @brief collection of string tools (/ functions).
 *
 * contains a collection of miscellaneous functions for dealing with strings.
 *
 * some functions (like trim, lower case, upper case ...) are available in two versions:
 * - a modifying one (suffix "Mod") which modifies the given string argument in place.
 * - a non modifying one which take a constant string reference and returns a new string.
 * .
 *
 *
 * (c) Copyright 2007-2008 by Intra2net AG
 *
 * info@intra2net.com
 */

#ifndef __STRINGFUNC_HXX
#define __STRINGFUNC_HXX

#include <list>
#include <string>
#include <sstream>
#include <stdexcept>
#include <sys/types.h>

namespace I2n
{

/*
** some useful constants:
*/

extern const std::string Whitespaces;
extern const std::string LineEndings;


/*
** predicates:
*/


bool has_prefix(const std::string& str, const std::string& prefix);

bool has_suffix(const std::string& str, const std::string& suffix);


/*
** tool functions(modifying):
*/

std::string trim_mod(std::string& str, const std::string& charlist = Whitespaces);

std::string chomp_mod(std::string& str, const std::string& what= LineEndings );

std::string to_lower_mod(std::string& str);

std::string to_upper_mod(std::string& str);


/*
** tool functions (not modifying):
*/

std::string trim(const std::string& str, const std::string& charlist = Whitespaces);

std::string chomp(const std::string& str, const std::string& what= LineEndings );

std::string to_lower(const std::string& str);

std::string to_upper(const std::string& str);


std::string remove_suffix(const std::string& str, const std::string& suffix);

std::string remove_prefix(const std::string& str, const std::string& prefix);



/*
** split and join:
*/


bool pair_split(
   const std::string& str,
   std::string& key,
   std::string& value,
   char delimiter = '=');


void split_string(
   const std::string& str,
   std::list< std::string >& result,
   const std::string& delimiter= "\n",
   bool omit_empty= false,
   const std::string& trim_list= std::string()
);

std::list< std::string > split_string(
   const std::string& str,
   const std::string& delimiter = "\n",
   bool omit_empty= false,
   const std::string& trim_list= std::string()
);


std::string join_string(
   const std::list< std::string >& parts,
   const std::string& delimiter = "\n"
);


/*
** conversions:
*/


std::string convert_binary_to_hex(const std::string&str, bool upper_case_digits= false);

std::string convert_hex_to_binary(const std::string& str) throw(std::runtime_error);



/*
** "type conversions":
*/


/**
 * convert a datatype @a T to a string via string stream.
 *
 * @param s the string which should be converted to @a T.
 * @return the value of type T.
 */
template<
class T
>
T string_to(const std::string& s)
{
   std::istringstream istr(s);
   T result;
   istr >> result;
   return result;
} // eo string_to(const std::string&)


/**
 * convert a datatype @a T to a string via string stream.
 *
 * @param s the string which should be converted to @a T.
 * @param result the resulting value of type @a T.
 * @return @a true iff the internal string stream was EOF after the conversion.
 */
template<
class T
>
bool string_to(const std::string& s, T& result)
{
   std::istringstream istr(s);
   istr >> result;
   return istr.eof();
} // eo string_to(const std::string&)


/**
 * convert a string to another datatype @a T via string stream.
 *
 * @param v the value (of type @a T) which should be converted to a string.
 * @return the resulting string.
 */
template<
class T
>
std::string to_string(const T& v)
{
   std::ostringstream ostr;
   ostr << v;
   return ostr.str();
} // eo to_string(const T&)


} // eo namespace I2n


#if 0
std::string to_lower(const std::string &src);
std::string to_upper(const std::string &src);
#else
// compatibility: import lower/upper funcs from I2n:
using I2n::to_lower;
using I2n::to_upper;
#endif

std::string nice_unit_format(const int64_t input);

bool replace_all(std::string &base, const std::string *ist, const std::string *soll);
bool replace_all(std::string &base, const char *ist, const char *soll);
bool replace_all(std::string &base, const char *ist, const std::string *soll);
bool replace_all(std::string &base, const std::string &ist, const char *soll);
bool replace_all(std::string &base, const std::string &ist, const std::string &soll);

std::string iso_to_utf8(const std::string& isostring);
std::string utf8_to_iso(const std::string& utf8string);
std::string utf7imap_to_utf8(const std::string &utf7imapstring);
std::string utf8_to_utf7imap(const std::string &utf8string);

std::string strip_html_tags(const std::string &input);
std::string smart_html_entities(const std::string &input);
std::string html_entities(std::string str);

std::string escape(const std::string &s);

std::string descape(const std::string &s, int startpos, int &endpos);
inline std::string descape(const std::string &s)
{
   int endpos;
   return descape(s,0,endpos);
}

std::string escape_shellarg(const std::string &input);

#endif