00001 #ifndef s11n_STRING_H_INCLUDED 00002 #define s11n_STRING_H_INCLUDED 1 00003 00004 #include <string> 00005 #include <map> 00006 namespace s11n { 00007 00008 /** 00009 Convenience typedef for use with translate_entities() and xml_entity_map(). 00010 */ 00011 typedef std::map<std::string,std::string> EntityMap; 00012 00013 /** 00014 For each entry in the input string, the characters are 00015 mapped to string sequences using the given 00016 translation_map. Where no mappings exist, the input 00017 characters are left as-is. 00018 00019 It returns the number of translations made. 00020 00021 If reverse_translation == true then a reverse mapping is 00022 done: map values are treated as keys. 00023 00024 This is useful, for example, for doing XML-entity-to-char 00025 conversions. 00026 00027 It is amazingly INefficient, but seems to work okay. 00028 00029 */ 00030 unsigned long translate_entities( std::string &, const EntityMap & translation_map, bool reverse_translation = false ); 00031 00032 00033 /** 00034 A policy enum used by trim_string(). 00035 */ 00036 enum TrimPolicy { 00037 /** 00038 Trim only leading spaces. 00039 */ 00040 TrimLeading = 0x01, 00041 /** 00042 Trim only trailing spaces. 00043 */ 00044 TrimTrailing = 0x02, 00045 /** 00046 Trim leading and trailing spaces. 00047 */ 00048 TrimAll = TrimLeading + TrimTrailing 00049 }; 00050 00051 /** 00052 Trims leading and trailing whitespace from the input string 00053 and returns the number of whitespace characters removed. 00054 */ 00055 unsigned int trim_string( std::string &, TrimPolicy = TrimAll ); 00056 /** 00057 Trims leading and trailing whitespace from the input string 00058 and returns the trimmed string. 00059 */ 00060 std::string trim_string( const std::string &, TrimPolicy = TrimAll ); 00061 00062 00063 /** 00064 Attempts to remove all backslash-escaped chars from str. 00065 00066 Removes backslash-escaped newlines from the input string, including 00067 any whitespace immediately following each backslash. 00068 00069 The optional slash parameter defines the escape character. 00070 */ 00071 unsigned long strip_slashes( std::string &str, const char slash = '\\' ); 00072 00073 /** 00074 Adds an escape sequence in front of any characters in 00075 instring which are also in the list of chars_to_escape. 00076 Returns the number of escapes added. 00077 00078 e.g., to escape (with a single backslash) all $, % and \ in 00079 mystring with a backslash: 00080 00081 <pre> 00082 escape_string( mystring, "$%\\", "\\" ); 00083 </pre> 00084 00085 (WARNING: the doxygen-generated HTML version of these docs 00086 may incorrectly show single backslashes in the above example!) 00087 00088 00089 */ 00090 unsigned long escape_string( std::string & instring, const std::string & chars_to_escape, const std::string & escape_seq = "\\" ); 00091 00092 /** 00093 normalize_string() is like trim_string() and 00094 strip_slashes(), combined, plus it removes leading/trailing 00095 quotes: 00096 00097 <pre> 00098 "this is a \ 00099 sample multi-line, backslash-escaped \ 00100 string." 00101 </pre> 00102 00103 Will translate to: 00104 <pre> 00105 this is a sample multi-line, backslash-escaped string. 00106 </pre> 00107 */ 00108 void normalize_string( std::string & ); 00109 00110 00111 /** 00112 Returns the first whitespace-delimited token from the given 00113 string. 00114 */ 00115 std::string first_token( const std::string & ); 00116 00117 /** 00118 Returns the passed-in string, minus the first token. 00119 */ 00120 std::string after_first_token( const std::string & ); 00121 00122 00123 00124 /** 00125 Returns int values for chars '0'-'9', 'a'-'f' and 'A'-'F', 00126 else -1. 00127 */ 00128 unsigned int int4hexchar( char c ); 00129 00130 /** 00131 Assumes wd to be a hex-encoded number. Returns it's decimal 00132 value. It may optionally be prefixed with '#', as in 00133 \#ff00ff. Case is insignificant. 00134 */ 00135 int hex2int( const std::string & wd ); 00136 00137 00138 00139 } // namespace s11n 00140 00141 #endif // s11n_STRING_H_INCLUDED