1 /* 2 ********************************************************************** 3 * Copyright (c) 2001-2007, International Business Machines 4 * Corporation and others. All Rights Reserved. 5 ********************************************************************** 6 * Date Name Description 7 * 11/19/2001 aliu Creation. 8 ********************************************************************** 9 */ 10 11 #ifndef ICU_UTIL_H 12 #define ICU_UTIL_H 13 14 #include "unicode/utypes.h" 15 #include "unicode/uobject.h" 16 #include "unicode/unistr.h" 17 18 //-------------------------------------------------------------------- 19 // class ICU_Utility 20 // i18n utility functions, scoped into the class ICU_Utility. 21 //-------------------------------------------------------------------- 22 23 U_NAMESPACE_BEGIN 24 25 class UnicodeMatcher; 26 class UnicodeSet; 27 28 class U_COMMON_API ICU_Utility /* not : public UObject because all methods are static */ { 29 public: 30 31 /** 32 * Append a number to the given UnicodeString in the given radix. 33 * Standard digits '0'-'9' are used and letters 'A'-'Z' for 34 * radices 11 through 36. 35 * @param result the digits of the number are appended here 36 * @param n the number to be converted to digits; may be negative. 37 * If negative, a '-' is prepended to the digits. 38 * @param radix a radix from 2 to 36 inclusive. 39 * @param minDigits the minimum number of digits, not including 40 * any '-', to produce. Values less than 2 have no effect. One 41 * digit is always emitted regardless of this parameter. 42 * @return a reference to result 43 */ 44 static UnicodeString& appendNumber(UnicodeString& result, int32_t n, 45 int32_t radix = 10, 46 int32_t minDigits = 1); 47 48 /** 49 * Return true if the character is NOT printable ASCII. 50 * 51 * This method should really be in UnicodeString (or similar). For 52 * now, we implement it here and share it with friend classes. 53 */ 54 static UBool isUnprintable(UChar32 c); 55 56 /** 57 * Escape unprintable characters using \uxxxx notation for U+0000 to 58 * U+FFFF and \Uxxxxxxxx for U+10000 and above. If the character is 59 * printable ASCII, then do nothing and return FALSE. Otherwise, 60 * append the escaped notation and return TRUE. 61 */ 62 static UBool escapeUnprintable(UnicodeString& result, UChar32 c); 63 64 /** 65 * Returns the index of a character, ignoring quoted text. 66 * For example, in the string "abc'hide'h", the 'h' in "hide" will not be 67 * found by a search for 'h'. 68 * @param text text to be searched 69 * @param start the beginning index, inclusive; <code>0 <= start 70 * <= limit</code>. 71 * @param limit the ending index, exclusive; <code>start <= limit 72 * <= text.length()</code>. 73 * @param c character to search for 74 * @return Offset of the first instance of c, or -1 if not found. 75 */ 76 //?FOR FUTURE USE. DISABLE FOR NOW for coverage reasons. 77 // static int32_t quotedIndexOf(const UnicodeString& text, 78 // int32_t start, int32_t limit, 79 // UChar c); 80 81 /** 82 * Skip over a sequence of zero or more white space characters at pos. 83 * @param advance if true, advance pos to the first non-white-space 84 * character at or after pos, or str.length(), if there is none. 85 * Otherwise leave pos unchanged. 86 * @return the index of the first non-white-space character at or 87 * after pos, or str.length(), if there is none. 88 */ 89 static int32_t skipWhitespace(const UnicodeString& str, int32_t& pos, 90 UBool advance = FALSE); 91 92 /** 93 * Skip over whitespace in a Replaceable. Whitespace is defined by 94 * uprv_isRuleWhiteSpace(). Skipping may be done in the forward or 95 * reverse direction. In either case, the leftmost index will be 96 * inclusive, and the rightmost index will be exclusive. That is, 97 * given a range defined as [start, limit), the call 98 * skipWhitespace(text, start, limit) will advance start past leading 99 * whitespace, whereas the call skipWhitespace(text, limit, start), 100 * will back up limit past trailing whitespace. 101 * @param text the text to be analyzed 102 * @param pos either the start or limit of a range of 'text', to skip 103 * leading or trailing whitespace, respectively 104 * @param stop either the limit or start of a range of 'text', to skip 105 * leading or trailing whitespace, respectively 106 * @return the new start or limit, depending on what was passed in to 107 * 'pos' 108 */ 109 //?FOR FUTURE USE. DISABLE FOR NOW for coverage reasons. 110 //? static int32_t skipWhitespace(const Replaceable& text, 111 //? int32_t pos, int32_t stop); 112 113 /** 114 * Parse a single non-whitespace character 'ch', optionally 115 * preceded by whitespace. 116 * @param id the string to be parsed 117 * @param pos INPUT-OUTPUT parameter. On input, pos[0] is the 118 * offset of the first character to be parsed. On output, pos[0] 119 * is the index after the last parsed character. If the parse 120 * fails, pos[0] will be unchanged. 121 * @param ch the non-whitespace character to be parsed. 122 * @return true if 'ch' is seen preceded by zero or more 123 * whitespace characters. 124 */ 125 static UBool parseChar(const UnicodeString& id, int32_t& pos, UChar ch); 126 127 /** 128 * Parse a pattern string starting at offset pos. Keywords are 129 * matched case-insensitively. Spaces may be skipped and may be 130 * optional or required. Integer values may be parsed, and if 131 * they are, they will be returned in the given array. If 132 * successful, the offset of the next non-space character is 133 * returned. On failure, -1 is returned. 134 * @param pattern must only contain lowercase characters, which 135 * will match their uppercase equivalents as well. A space 136 * character matches one or more required spaces. A '~' character 137 * matches zero or more optional spaces. A '#' character matches 138 * an integer and stores it in parsedInts, which the caller must 139 * ensure has enough capacity. 140 * @param parsedInts array to receive parsed integers. Caller 141 * must ensure that parsedInts.length is >= the number of '#' 142 * signs in 'pattern'. 143 * @return the position after the last character parsed, or -1 if 144 * the parse failed 145 */ 146 static int32_t parsePattern(const UnicodeString& rule, int32_t pos, int32_t limit, 147 const UnicodeString& pattern, int32_t* parsedInts); 148 149 /** 150 * Parse a pattern string within the given Replaceable and a parsing 151 * pattern. Characters are matched literally and case-sensitively 152 * except for the following special characters: 153 * 154 * ~ zero or more uprv_isRuleWhiteSpace chars 155 * 156 * If end of pattern is reached with all matches along the way, 157 * pos is advanced to the first unparsed index and returned. 158 * Otherwise -1 is returned. 159 * @param pat pattern that controls parsing 160 * @param text text to be parsed, starting at index 161 * @param index offset to first character to parse 162 * @param limit offset after last character to parse 163 * @return index after last parsed character, or -1 on parse failure. 164 */ 165 static int32_t parsePattern(const UnicodeString& pat, 166 const Replaceable& text, 167 int32_t index, 168 int32_t limit); 169 170 /** 171 * Parse an integer at pos, either of the form \d+ or of the form 172 * 0x[0-9A-Fa-f]+ or 0[0-7]+, that is, in standard decimal, hex, 173 * or octal format. 174 * @param pos INPUT-OUTPUT parameter. On input, the first 175 * character to parse. On output, the character after the last 176 * parsed character. 177 */ 178 static int32_t parseInteger(const UnicodeString& rule, int32_t& pos, int32_t limit); 179 180 /** 181 * Parse a Unicode identifier from the given string at the given 182 * position. Return the identifier, or an empty string if there 183 * is no identifier. 184 * @param str the string to parse 185 * @param pos INPUT-OUPUT parameter. On INPUT, pos is the 186 * first character to examine. It must be less than str.length(), 187 * and it must not point to a whitespace character. That is, must 188 * have pos < str.length() and 189 * !UCharacter::isWhitespace(str.char32At(pos)). On 190 * OUTPUT, the position after the last parsed character. 191 * @return the Unicode identifier, or an empty string if there is 192 * no valid identifier at pos. 193 */ 194 static UnicodeString parseUnicodeIdentifier(const UnicodeString& str, int32_t& pos); 195 196 /** 197 * Parse an unsigned 31-bit integer at the given offset. Use 198 * UCharacter.digit() to parse individual characters into digits. 199 * @param text the text to be parsed 200 * @param pos INPUT-OUTPUT parameter. On entry, pos is the 201 * offset within text at which to start parsing; it should point 202 * to a valid digit. On exit, pos is the offset after the last 203 * parsed character. If the parse failed, it will be unchanged on 204 * exit. Must be >= 0 on entry. 205 * @param radix the radix in which to parse; must be >= 2 and <= 206 * 36. 207 * @return a non-negative parsed number, or -1 upon parse failure. 208 * Parse fails if there are no digits, that is, if pos does not 209 * point to a valid digit on entry, or if the number to be parsed 210 * does not fit into a 31-bit unsigned integer. 211 */ 212 static int32_t parseNumber(const UnicodeString& text, 213 int32_t& pos, int8_t radix); 214 215 static void appendToRule(UnicodeString& rule, 216 UChar32 c, 217 UBool isLiteral, 218 UBool escapeUnprintable, 219 UnicodeString& quoteBuf); 220 221 static void appendToRule(UnicodeString& rule, 222 const UnicodeString& text, 223 UBool isLiteral, 224 UBool escapeUnprintable, 225 UnicodeString& quoteBuf); 226 227 static void appendToRule(UnicodeString& rule, 228 const UnicodeMatcher* matcher, 229 UBool escapeUnprintable, 230 UnicodeString& quoteBuf); 231 232 private: 233 // do not instantiate 234 ICU_Utility(); 235 }; 236 237 U_NAMESPACE_END 238 239 /** 240 * Get the set of "white space" characters in the sense of ICU rule 241 * parsers. Caller must close/delete result. 242 * Equivalent to the set of characters with the Pattern_White_Space Unicode property. 243 * Stable set of characters, won't change. 244 * See UAX #31 Identifier and Pattern Syntax: http://www.unicode.org/reports/tr31/ 245 * @internal 246 */ 247 U_CAPI U_NAMESPACE_QUALIFIER UnicodeSet* U_EXPORT2 248 uprv_openRuleWhiteSpaceSet(UErrorCode* ec); 249 250 /** 251 * Is this character a "white space" in the sense of ICU rule parsers? 252 * Equivalent to test for Pattern_White_Space Unicode property. 253 * Stable set of characters, won't change. 254 * See UAX #31 Identifier and Pattern Syntax: http://www.unicode.org/reports/tr31/ 255 * @internal 256 */ 257 U_CAPI UBool U_EXPORT2 258 uprv_isRuleWhiteSpace(UChar32 c); 259 260 #endif 261 //eof 262
