Further style and comment adjustments

[libs/core.git] / source / utils.h

diff --git a/source/utils.h b/source/utils.h
index 1823f667c7914e863b7c08426fa572ec884bee2d..6e145916f5cd1bbe0685525c5d3646668670a703 100644 (file)
--- a/source/utils.h
+++ b/source/utils.h
@@ -1,3 +1,10 @@
+/* $Id$
+
+This file is part of libmspstrings
+Copyright © 2006-2008 Mikko Rasa
+Distributed under the LGPL
+*/
+
 #ifndef MSP_STRINGS_UTILS_H_
 #define MSP_STRINGS_UTILS_H_
 
@@ -6,15 +13,81 @@
 
 namespace Msp {
 
-int strcasecmp(const std::string &, const std::string &);
+/** Compares two strings, ignoring upper/lower case.  Returns an integer less
+than, equal to or greater than zero depending on whether the first string
+lexicographically precedes, is equal to or follows the second one,
+respectively. */
+int strcasecmp(const std::string &s1, const std::string &s2);
+
+/** Converts a string to lower case. */
 std::string tolower(const std::string &);
+
+/** Converts a string to upper case. */
 std::string toupper(const std::string &);
-std::vector<std::string> split(const std::string &, const std::string & =" \t\r\n", bool =false);
-std::vector<std::string> split(const std::string &, char, bool =false);
-template<typename T>
-std::string join(const T &, const std::string & =" ");
+
+/** Checks whether a string consists of digits only. */
+bool isnumrc(const std::string &);
+
+/** Checks whether a string consists of alphabetic characters only. */
+bool isalpha(const std::string &);
+
+/** Checks whether a string consists of alphanumeric characters only. */
+bool isalnum(const std::string &);
+
+/* These are required to make the standard version work from inside the Msp
+namespace */
+using std::tolower;
+using std::toupper;
+using std::isalpha;
+using std::isalnum;
+
+/** Splits a string at occurrences of any of the characters in sep.  Default
+is to split at whitespace.  Two or more consecutive separator characters will
+be treated as a single separator.
+
+If max_split is non-negative, at most that many split will be performed, i.e.
+the resulting vector will contain at most max_split+1 elements. */
+std::vector<std::string> split(const std::string &str, const std::string &sep = " \t\r\n", int max_split = -1);
+
+/** Splits a string on occurrences of a single character. */
+std::vector<std::string> split(const std::string &str, char sep, int max_split = -1);
+
+/** Splits a string on occurrences of another string. */
+std::vector<std::string> split_long(const std::string &str, const std::string &sep, int max_split = -1);
+
+/** Splits a string on occurrences of another string.  Two consecutive
+separators will cause an empty string to be placed in the result. */
+std::vector<std::string> split_fields(const std::string &str, const std::string &sep, int max_split = -1);
+
+/** Splits a string on occurrences of a single character.  Two consecutive
+separators will cause an empty string to be placed in the result. */
+std::vector<std::string> split_fields(const std::string &str, char sep, int max_split = -1);
+
+/** Concatenates strings from an iterator range. */
+template<typename Iter>
+std::string join(Iter begin, Iter end, const std::string &sep = " ")
+{
+       std::string result;
+       for(Iter i=begin; i!=end; ++i)
+       {
+               if(i!=begin)
+                       result += sep;
+               result += *i;
+       }
+
+       return result;
+}
+
+/** Strips leading and trailing whitespace from a string. */
 std::string strip(const std::string &);
 
+/** Unescapes a string with C escape sequences. */
+std::string c_unescape(const std::string &str);
+
+/** Escapes any non-printable characters in a string with C escape sequences.
+Optionally, any characters with the high bit set can be escaped as well. */
+std::string c_escape(const std::string &str, bool escape_8bit = true);
+
 } // namespace Msp
 
 #endif