/src/icu/icu4c/source/common/util.h

Source
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
 **********************************************************************
 *   Copyright (c) 2001-2011, International Business Machines
 *   Corporation and others.  All Rights Reserved.
 **********************************************************************
 *   Date        Name        Description
 *   11/19/2001  aliu        Creation.
 **********************************************************************
 */

#ifndef ICU_UTIL_H
#define ICU_UTIL_H

#include "charstr.h"
#include "unicode/unistr.h"
#include "unicode/uobject.h"
#include "unicode/utypes.h"
//--------------------------------------------------------------------
// class ICU_Utility
// i18n utility functions, scoped into the class ICU_Utility.
//--------------------------------------------------------------------

U_NAMESPACE_BEGIN

class UnicodeMatcher;

class U_COMMON_API ICU_Utility /* not : public UObject because all methods are static */ {
 public:

    /**
     * Append a number to the given UnicodeString in the given radix.
     * Standard digits '0'-'9' are used and letters 'A'-'Z' for
     * radices 11 through 36.
     * @param result the digits of the number are appended here
     * @param n the number to be converted to digits; may be negative.
     * If negative, a '-' is prepended to the digits.
     * @param radix a radix from 2 to 36 inclusive.
     * @param minDigits the minimum number of digits, not including
     * any '-', to produce.  Values less than 2 have no effect.  One
     * digit is always emitted regardless of this parameter.
     * @return a reference to result
     */
    static UnicodeString& appendNumber(UnicodeString& result, int32_t n,
                                       int32_t radix = 10,
                                       int32_t minDigits = 1);

    /** Returns a bogus UnicodeString by value. */
    static inline UnicodeString makeBogusString() {
        UnicodeString result;
        result.setToBogus();
        return result;
    }

    /**
     * Return true if the character is NOT printable ASCII.
     * The tab, newline and linefeed characters are considered unprintable.
     */
    static UBool isUnprintable(UChar32 c);

    /**
     * @return true for control codes and for surrogate and noncharacter code points
     */
    static UBool shouldAlwaysBeEscaped(UChar32 c);

    /**
     * Escapes one unprintable code point using \uxxxx notation for U+0000 to
     * U+FFFF and \Uxxxxxxxx for U+10000 and above.  If the character is
     * printable ASCII, then do nothing and return false.  Otherwise,
     * append the escaped notation and return true.
     */
    static UBool escapeUnprintable(UnicodeString& result, UChar32 c);

    /**
     * Escapes one code point using \uxxxx notation
     * for U+0000 to U+FFFF and \Uxxxxxxxx for U+10000 and above.
     * @return result
     */
    static UnicodeString &escape(UnicodeString& result, UChar32 c);

    /**
     * Returns the index of a character, ignoring quoted text.
     * For example, in the string "abc'hide'h", the 'h' in "hide" will not be
     * found by a search for 'h'.
     * @param text text to be searched
     * @param start the beginning index, inclusive; <code>0 <= start
     * <= limit</code>.
     * @param limit the ending index, exclusive; <code>start <= limit
     * <= text.length()</code>.
     * @param c character to search for
     * @return Offset of the first instance of c, or -1 if not found.
     */
//?FOR FUTURE USE.  DISABLE FOR NOW for coverage reasons.
//    static int32_t quotedIndexOf(const UnicodeString& text,
//                                 int32_t start, int32_t limit,
//                                 char16_t c);

    /**
     * Skip over a sequence of zero or more white space characters at pos.
     * @param advance if true, advance pos to the first non-white-space
     * character at or after pos, or str.length(), if there is none.
     * Otherwise leave pos unchanged.
     * @return the index of the first non-white-space character at or
     * after pos, or str.length(), if there is none.
     */
    static int32_t skipWhitespace(const UnicodeString& str, int32_t& pos,
                                  UBool advance = false);

    /**
     * Skip over Pattern_White_Space in a Replaceable.
     * Skipping may be done in the forward or
     * reverse direction.  In either case, the leftmost index will be
     * inclusive, and the rightmost index will be exclusive.  That is,
     * given a range defined as [start, limit), the call
     * skipWhitespace(text, start, limit) will advance start past leading
     * whitespace, whereas the call skipWhitespace(text, limit, start),
     * will back up limit past trailing whitespace.
     * @param text the text to be analyzed
     * @param pos either the start or limit of a range of 'text', to skip
     * leading or trailing whitespace, respectively
     * @param stop either the limit or start of a range of 'text', to skip
     * leading or trailing whitespace, respectively
     * @return the new start or limit, depending on what was passed in to
     * 'pos'
     */
//?FOR FUTURE USE.  DISABLE FOR NOW for coverage reasons.
//?    static int32_t skipWhitespace(const Replaceable& text,
//?                                  int32_t pos, int32_t stop);

    /**
     * Parse a single non-whitespace character 'ch', optionally
     * preceded by whitespace.
     * @param id the string to be parsed
     * @param pos INPUT-OUTPUT parameter.  On input, pos[0] is the
     * offset of the first character to be parsed.  On output, pos[0]
     * is the index after the last parsed character.  If the parse
     * fails, pos[0] will be unchanged.
     * @param ch the non-whitespace character to be parsed.
     * @return true if 'ch' is seen preceded by zero or more
     * whitespace characters.
     */
    static UBool parseChar(const UnicodeString& id, int32_t& pos, char16_t ch);

    /**
     * Parse a pattern string starting at offset pos.  Keywords are
     * matched case-insensitively.  Spaces may be skipped and may be
     * optional or required.  Integer values may be parsed, and if
     * they are, they will be returned in the given array.  If
     * successful, the offset of the next non-space character is
     * returned.  On failure, -1 is returned.
     * @param pattern must only contain lowercase characters, which
     * will match their uppercase equivalents as well.  A space
     * character matches one or more required spaces.  A '~' character
     * matches zero or more optional spaces.  A '#' character matches
     * an integer and stores it in parsedInts, which the caller must
     * ensure has enough capacity.
     * @param parsedInts array to receive parsed integers.  Caller
     * must ensure that parsedInts.length is >= the number of '#'
     * signs in 'pattern'.
     * @return the position after the last character parsed, or -1 if
     * the parse failed
     */
    static int32_t parsePattern(const UnicodeString& rule, int32_t pos, int32_t limit,
                                const UnicodeString& pattern, int32_t* parsedInts);
        
    /**
     * Parse a pattern string within the given Replaceable and a parsing
     * pattern.  Characters are matched literally and case-sensitively
     * except for the following special characters:
     *
     * ~  zero or more Pattern_White_Space chars
     *
     * If end of pattern is reached with all matches along the way,
     * pos is advanced to the first unparsed index and returned.
     * Otherwise -1 is returned.
     * @param pat pattern that controls parsing
     * @param text text to be parsed, starting at index
     * @param index offset to first character to parse
     * @param limit offset after last character to parse
     * @return index after last parsed character, or -1 on parse failure.
     */
    static int32_t parsePattern(const UnicodeString& pat,
                                const Replaceable& text,
                                int32_t index,
                                int32_t limit);

    /**
     * Parse an integer at pos, either of the form \d+ or of the form
     * 0x[0-9A-Fa-f]+ or 0[0-7]+, that is, in standard decimal, hex,
     * or octal format.
     * @param pos INPUT-OUTPUT parameter.  On input, the index of the first
     * character to parse.  On output, the index of the character after the
     * last parsed character.
     */
    static int32_t parseInteger(const UnicodeString& rule, int32_t& pos, int32_t limit);

    /**
     * Parse an integer at pos using only ASCII digits.
     * Base 10 only.
     * @param pos INPUT-OUTPUT parameter.  On input, the index of the first
     * character to parse.  On output, the index of the character after the
     * last parsed character.
     */
    static int32_t parseAsciiInteger(const UnicodeString& str, int32_t& pos);

    /**
     * Parse a Unicode identifier from the given string at the given
     * position.  Return the identifier, or an empty string if there
     * is no identifier.
     * @param str the string to parse
     * @param pos INPUT-OUTPUT parameter.  On INPUT, pos is the
     * first character to examine.  It must be less than str.length(),
     * and it must not point to a whitespace character.  That is, must
     * have pos < str.length() and
     * !UCharacter::isWhitespace(str.char32At(pos)).  On
     * OUTPUT, the position after the last parsed character.
     * @return the Unicode identifier, or an empty string if there is
     * no valid identifier at pos.
     */
    static UnicodeString parseUnicodeIdentifier(const UnicodeString& str, int32_t& pos);

    /**
     * Parse an unsigned 31-bit integer at the given offset.  Use
     * UCharacter.digit() to parse individual characters into digits.
     * @param text the text to be parsed
     * @param pos INPUT-OUTPUT parameter.  On entry, pos is the
     * offset within text at which to start parsing; it should point
     * to a valid digit.  On exit, pos is the offset after the last
     * parsed character.  If the parse failed, it will be unchanged on
     * exit.  Must be >= 0 on entry.
     * @param radix the radix in which to parse; must be >= 2 and <=
     * 36.
     * @return a non-negative parsed number, or -1 upon parse failure.
     * Parse fails if there are no digits, that is, if pos does not
     * point to a valid digit on entry, or if the number to be parsed
     * does not fit into a 31-bit unsigned integer.
     */
    static int32_t parseNumber(const UnicodeString& text,
                               int32_t& pos, int8_t radix);

    static void appendToRule(UnicodeString& rule,
                             UChar32 c,
                             UBool isLiteral,
                             UBool escapeUnprintable,
                             UnicodeString& quoteBuf);
    
    static void appendToRule(UnicodeString& rule,
                             const UnicodeString& text,
                             UBool isLiteral,
                             UBool escapeUnprintable,
                             UnicodeString& quoteBuf);

    static void appendToRule(UnicodeString& rule,
                             const UnicodeMatcher* matcher,
                             UBool escapeUnprintable,
                             UnicodeString& quoteBuf);

private:
    // do not instantiate
    ICU_Utility() = delete;
};

U_NAMESPACE_END

#endif
//eof

Coverage Report

Created: 2025-06-24 06:54

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