Add some utility functions for joining strings
[libs/core.git] / source / strings / utils.h
1 #ifndef MSP_STRINGS_UTILS_H_
2 #define MSP_STRINGS_UTILS_H_
3
4 #include <string>
5 #include <vector>
6
7 namespace Msp {
8
9 /** Compares two strings, ignoring upper/lower case.  Returns an integer less
10 than, equal to or greater than zero depending on whether the first string
11 lexicographically precedes, is equal to or follows the second one,
12 respectively. */
13 int strcasecmp(const std::string &s1, const std::string &s2);
14
15 /** Converts a string to lower case. */
16 std::string tolower(const std::string &);
17
18 /** Converts a string to upper case. */
19 std::string toupper(const std::string &);
20
21 /** Checks whether a string consists of digits only. */
22 bool isnumrc(const std::string &);
23
24 /** Checks whether a string consists of alphabetic characters only. */
25 bool isalpha(const std::string &);
26
27 /** Checks whether a string consists of alphanumeric characters only. */
28 bool isalnum(const std::string &);
29
30 /* These are required to make the standard version work from inside the Msp
31 namespace */
32 using std::tolower;
33 using std::toupper;
34 using std::isalpha;
35 using std::isalnum;
36
37 /** Splits a string at occurrences of any of the characters in sep.  Default
38 is to split at whitespace.  Two or more consecutive separator characters will
39 be treated as a single separator.
40
41 If max_split is non-negative, at most that many split will be performed, i.e.
42 the resulting vector will contain at most max_split+1 elements. */
43 std::vector<std::string> split(const std::string &str, const std::string &sep = " \t\r\n", int max_split = -1);
44
45 /** Splits a string on occurrences of a single character. */
46 std::vector<std::string> split(const std::string &str, char sep, int max_split = -1);
47
48 /** Splits a string on occurrences of another string. */
49 std::vector<std::string> split_long(const std::string &str, const std::string &sep, int max_split = -1);
50
51 /** Splits a string on occurrences of another string.  Two consecutive
52 separators will cause an empty string to be placed in the result. */
53 std::vector<std::string> split_fields(const std::string &str, const std::string &sep, int max_split = -1);
54
55 /** Splits a string on occurrences of a single character.  Two consecutive
56 separators will cause an empty string to be placed in the result. */
57 std::vector<std::string> split_fields(const std::string &str, char sep, int max_split = -1);
58
59 /** Appends a string to another, using a separator if both are non-empty. */
60 std::string &append(std::string &str, const std::string &sep, const std::string &other);
61
62 /** Joins two strings, using a separator if both are non-empty. */
63 std::string join(const std::string &str1, const std::string &sep, const std::string &str2);
64
65 /** Concatenates strings from an iterator range. */
66 template<typename Iter>
67 std::string join(Iter begin, Iter end, const std::string &sep = " ")
68 {
69         std::string result;
70         for(Iter i=begin; i!=end; ++i)
71                 append(result, sep, *i);
72
73         return result;
74 }
75
76 /** Strips leading and trailing whitespace from a string. */
77 std::string strip(const std::string &);
78
79 /** Unescapes a string with C escape sequences. */
80 std::string c_unescape(const std::string &str);
81
82 /** Escapes any non-printable characters in a string with C escape sequences.
83 Optionally, any characters with the high bit set can be escaped as well. */
84 std::string c_escape(const std::string &str, bool escape_8bit = true);
85
86 } // namespace Msp
87
88 #endif