icuSources/common/util.h

   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