michael@0: /*
michael@0:  **********************************************************************
michael@0:  *   Copyright (c) 2001-2011, International Business Machines
michael@0:  *   Corporation and others.  All Rights Reserved.
michael@0:  **********************************************************************
michael@0:  *   Date        Name        Description
michael@0:  *   11/19/2001  aliu        Creation.
michael@0:  **********************************************************************
michael@0:  */
michael@0: 
michael@0: #ifndef ICU_UTIL_H
michael@0: #define ICU_UTIL_H
michael@0: 
michael@0: #include "unicode/utypes.h"
michael@0: #include "unicode/uobject.h"
michael@0: #include "unicode/unistr.h"
michael@0: 
michael@0: //--------------------------------------------------------------------
michael@0: // class ICU_Utility
michael@0: // i18n utility functions, scoped into the class ICU_Utility.
michael@0: //--------------------------------------------------------------------
michael@0: 
michael@0: U_NAMESPACE_BEGIN
michael@0: 
michael@0: class UnicodeMatcher;
michael@0: 
michael@0: class U_COMMON_API ICU_Utility /* not : public UObject because all methods are static */ {
michael@0:  public:
michael@0: 
michael@0:     /**
michael@0:      * Append a number to the given UnicodeString in the given radix.
michael@0:      * Standard digits '0'-'9' are used and letters 'A'-'Z' for
michael@0:      * radices 11 through 36.
michael@0:      * @param result the digits of the number are appended here
michael@0:      * @param n the number to be converted to digits; may be negative.
michael@0:      * If negative, a '-' is prepended to the digits.
michael@0:      * @param radix a radix from 2 to 36 inclusive.
michael@0:      * @param minDigits the minimum number of digits, not including
michael@0:      * any '-', to produce.  Values less than 2 have no effect.  One
michael@0:      * digit is always emitted regardless of this parameter.
michael@0:      * @return a reference to result
michael@0:      */
michael@0:     static UnicodeString& appendNumber(UnicodeString& result, int32_t n,
michael@0:                                        int32_t radix = 10,
michael@0:                                        int32_t minDigits = 1);
michael@0: 
michael@0:     /**
michael@0:      * Return true if the character is NOT printable ASCII.
michael@0:      *
michael@0:      * This method should really be in UnicodeString (or similar).  For
michael@0:      * now, we implement it here and share it with friend classes.
michael@0:      */
michael@0:     static UBool isUnprintable(UChar32 c);
michael@0: 
michael@0:     /**
michael@0:      * Escape unprintable characters using \uxxxx notation for U+0000 to
michael@0:      * U+FFFF and \Uxxxxxxxx for U+10000 and above.  If the character is
michael@0:      * printable ASCII, then do nothing and return FALSE.  Otherwise,
michael@0:      * append the escaped notation and return TRUE.
michael@0:      */
michael@0:     static UBool escapeUnprintable(UnicodeString& result, UChar32 c);
michael@0: 
michael@0:     /**
michael@0:      * Returns the index of a character, ignoring quoted text.
michael@0:      * For example, in the string "abc'hide'h", the 'h' in "hide" will not be
michael@0:      * found by a search for 'h'.
michael@0:      * @param text text to be searched
michael@0:      * @param start the beginning index, inclusive; <code>0 <= start
michael@0:      * <= limit</code>.
michael@0:      * @param limit the ending index, exclusive; <code>start <= limit
michael@0:      * <= text.length()</code>.
michael@0:      * @param c character to search for
michael@0:      * @return Offset of the first instance of c, or -1 if not found.
michael@0:      */
michael@0: //?FOR FUTURE USE.  DISABLE FOR NOW for coverage reasons.
michael@0: //    static int32_t quotedIndexOf(const UnicodeString& text,
michael@0: //                                 int32_t start, int32_t limit,
michael@0: //                                 UChar c);
michael@0: 
michael@0:     /**
michael@0:      * Skip over a sequence of zero or more white space characters at pos.
michael@0:      * @param advance if true, advance pos to the first non-white-space
michael@0:      * character at or after pos, or str.length(), if there is none.
michael@0:      * Otherwise leave pos unchanged.
michael@0:      * @return the index of the first non-white-space character at or
michael@0:      * after pos, or str.length(), if there is none.
michael@0:      */
michael@0:     static int32_t skipWhitespace(const UnicodeString& str, int32_t& pos,
michael@0:                                   UBool advance = FALSE);
michael@0: 
michael@0:     /**
michael@0:      * Skip over Pattern_White_Space in a Replaceable.
michael@0:      * Skipping may be done in the forward or
michael@0:      * reverse direction.  In either case, the leftmost index will be
michael@0:      * inclusive, and the rightmost index will be exclusive.  That is,
michael@0:      * given a range defined as [start, limit), the call
michael@0:      * skipWhitespace(text, start, limit) will advance start past leading
michael@0:      * whitespace, whereas the call skipWhitespace(text, limit, start),
michael@0:      * will back up limit past trailing whitespace.
michael@0:      * @param text the text to be analyzed
michael@0:      * @param pos either the start or limit of a range of 'text', to skip
michael@0:      * leading or trailing whitespace, respectively
michael@0:      * @param stop either the limit or start of a range of 'text', to skip
michael@0:      * leading or trailing whitespace, respectively
michael@0:      * @return the new start or limit, depending on what was passed in to
michael@0:      * 'pos'
michael@0:      */
michael@0: //?FOR FUTURE USE.  DISABLE FOR NOW for coverage reasons.
michael@0: //?    static int32_t skipWhitespace(const Replaceable& text,
michael@0: //?                                  int32_t pos, int32_t stop);
michael@0: 
michael@0:     /**
michael@0:      * Parse a single non-whitespace character 'ch', optionally
michael@0:      * preceded by whitespace.
michael@0:      * @param id the string to be parsed
michael@0:      * @param pos INPUT-OUTPUT parameter.  On input, pos[0] is the
michael@0:      * offset of the first character to be parsed.  On output, pos[0]
michael@0:      * is the index after the last parsed character.  If the parse
michael@0:      * fails, pos[0] will be unchanged.
michael@0:      * @param ch the non-whitespace character to be parsed.
michael@0:      * @return true if 'ch' is seen preceded by zero or more
michael@0:      * whitespace characters.
michael@0:      */
michael@0:     static UBool parseChar(const UnicodeString& id, int32_t& pos, UChar ch);
michael@0: 
michael@0:     /**
michael@0:      * Parse a pattern string starting at offset pos.  Keywords are
michael@0:      * matched case-insensitively.  Spaces may be skipped and may be
michael@0:      * optional or required.  Integer values may be parsed, and if
michael@0:      * they are, they will be returned in the given array.  If
michael@0:      * successful, the offset of the next non-space character is
michael@0:      * returned.  On failure, -1 is returned.
michael@0:      * @param pattern must only contain lowercase characters, which
michael@0:      * will match their uppercase equivalents as well.  A space
michael@0:      * character matches one or more required spaces.  A '~' character
michael@0:      * matches zero or more optional spaces.  A '#' character matches
michael@0:      * an integer and stores it in parsedInts, which the caller must
michael@0:      * ensure has enough capacity.
michael@0:      * @param parsedInts array to receive parsed integers.  Caller
michael@0:      * must ensure that parsedInts.length is >= the number of '#'
michael@0:      * signs in 'pattern'.
michael@0:      * @return the position after the last character parsed, or -1 if
michael@0:      * the parse failed
michael@0:      */
michael@0:     static int32_t parsePattern(const UnicodeString& rule, int32_t pos, int32_t limit,
michael@0:                                 const UnicodeString& pattern, int32_t* parsedInts);
michael@0:         
michael@0:     /**
michael@0:      * Parse a pattern string within the given Replaceable and a parsing
michael@0:      * pattern.  Characters are matched literally and case-sensitively
michael@0:      * except for the following special characters:
michael@0:      *
michael@0:      * ~  zero or more Pattern_White_Space chars
michael@0:      *
michael@0:      * If end of pattern is reached with all matches along the way,
michael@0:      * pos is advanced to the first unparsed index and returned.
michael@0:      * Otherwise -1 is returned.
michael@0:      * @param pat pattern that controls parsing
michael@0:      * @param text text to be parsed, starting at index
michael@0:      * @param index offset to first character to parse
michael@0:      * @param limit offset after last character to parse
michael@0:      * @return index after last parsed character, or -1 on parse failure.
michael@0:      */
michael@0:     static int32_t parsePattern(const UnicodeString& pat,
michael@0:                                 const Replaceable& text,
michael@0:                                 int32_t index,
michael@0:                                 int32_t limit);
michael@0: 
michael@0:     /**
michael@0:      * Parse an integer at pos, either of the form \d+ or of the form
michael@0:      * 0x[0-9A-Fa-f]+ or 0[0-7]+, that is, in standard decimal, hex,
michael@0:      * or octal format.
michael@0:      * @param pos INPUT-OUTPUT parameter.  On input, the first
michael@0:      * character to parse.  On output, the character after the last
michael@0:      * parsed character.
michael@0:      */
michael@0:     static int32_t parseInteger(const UnicodeString& rule, int32_t& pos, int32_t limit);
michael@0: 
michael@0:     /**
michael@0:      * Parse a Unicode identifier from the given string at the given
michael@0:      * position.  Return the identifier, or an empty string if there
michael@0:      * is no identifier.
michael@0:      * @param str the string to parse
michael@0:      * @param pos INPUT-OUPUT parameter.  On INPUT, pos is the
michael@0:      * first character to examine.  It must be less than str.length(),
michael@0:      * and it must not point to a whitespace character.  That is, must
michael@0:      * have pos < str.length() and
michael@0:      * !UCharacter::isWhitespace(str.char32At(pos)).  On
michael@0:      * OUTPUT, the position after the last parsed character.
michael@0:      * @return the Unicode identifier, or an empty string if there is
michael@0:      * no valid identifier at pos.
michael@0:      */
michael@0:     static UnicodeString parseUnicodeIdentifier(const UnicodeString& str, int32_t& pos);
michael@0: 
michael@0:     /**
michael@0:      * Parse an unsigned 31-bit integer at the given offset.  Use
michael@0:      * UCharacter.digit() to parse individual characters into digits.
michael@0:      * @param text the text to be parsed
michael@0:      * @param pos INPUT-OUTPUT parameter.  On entry, pos is the
michael@0:      * offset within text at which to start parsing; it should point
michael@0:      * to a valid digit.  On exit, pos is the offset after the last
michael@0:      * parsed character.  If the parse failed, it will be unchanged on
michael@0:      * exit.  Must be >= 0 on entry.
michael@0:      * @param radix the radix in which to parse; must be >= 2 and <=
michael@0:      * 36.
michael@0:      * @return a non-negative parsed number, or -1 upon parse failure.
michael@0:      * Parse fails if there are no digits, that is, if pos does not
michael@0:      * point to a valid digit on entry, or if the number to be parsed
michael@0:      * does not fit into a 31-bit unsigned integer.
michael@0:      */
michael@0:     static int32_t parseNumber(const UnicodeString& text,
michael@0:                                int32_t& pos, int8_t radix);
michael@0: 
michael@0:     static void appendToRule(UnicodeString& rule,
michael@0:                              UChar32 c,
michael@0:                              UBool isLiteral,
michael@0:                              UBool escapeUnprintable,
michael@0:                              UnicodeString& quoteBuf);
michael@0:     
michael@0:     static void appendToRule(UnicodeString& rule,
michael@0:                              const UnicodeString& text,
michael@0:                              UBool isLiteral,
michael@0:                              UBool escapeUnprintable,
michael@0:                              UnicodeString& quoteBuf);
michael@0: 
michael@0:     static void appendToRule(UnicodeString& rule,
michael@0:                              const UnicodeMatcher* matcher,
michael@0:                              UBool escapeUnprintable,
michael@0:                              UnicodeString& quoteBuf);
michael@0: 
michael@0: private:
michael@0:     // do not instantiate
michael@0:     ICU_Utility();
michael@0: };
michael@0: 
michael@0: U_NAMESPACE_END
michael@0: 
michael@0: #endif
michael@0: //eof