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
25U_NAMESPACE_BEGIN
26
27class UnicodeMatcher;
28
29class 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 static inline UnicodeString makeBogusString() {
51 UnicodeString result;
52 result.setToBogus();
53 return result;
54 }
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
259private:
260 // do not instantiate
261 ICU_Utility() = delete;
262};
263
264U_NAMESPACE_END
265
266#endif
267//eof
268