2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
20 * @file FBaseUtilScanner.h
21 * @brief This is the header file for the %Scanner class.
23 * This header file contains declarations and definitions of the %Scanner class.
27 #ifndef _FBASE_UTIL_SCANNER_H_
28 #define _FBASE_UTIL_SCANNER_H_
30 #include <FBaseString.h>
31 #include <FBaseUtilRegularExpression.h>
33 namespace Tizen { namespace Base { namespace Utility
37 * @brief This class provides to parse primitive types and strings, and supports to use regular expressions and various encoding schemes.
40 * The %Scanner class breaks the input, which can be either a %String instance or strings from a file, into tokens using a delimiter.
41 * The delimiter is set by whitespace as a default value. The resulting tokens are converted into values of different types according
42 * to the methods in %Scanner.
44 * The following example demonstrates how to use the %Scanner class.
47 * String str = L"1 12 34.5 58 false";
51 * scan.Construct(str);
53 * ret = scan.IsNextTokenConvertibleToSignedChar(); //ret true
55 * scan.GetNextSignedChar(val); //val 1
57 * ret = scan.IsNextTokenConvertibleToShort(10); //ret true
59 * scan.GetNextShort(shortVal); //shortVal 12
61 * ret = scan.IsNextTokenConvertibleToInt(10); //ret false
62 * ret = scan.IsNextTokenConvertibleToFloat(); //ret true
64 * scan.GetNextFloat(floatVal); //floatVal 34.5
66 * ret = scan.IsNextTokenConvertibleToInt(16); //ret true
68 * scan.GetNextInt(intVal, 16); //intVal 88
70 * ret = scan.IsNextTokenConvertibleToBool(); //ret true
71 * scan.GetNextBool(ret); //ret false
75 class _OSP_EXPORT_ Scanner
76 : public Tizen::Base::Object
81 * The object is not fully constructed after this constructor is called. @n
82 * For full construction, the Construct() method must be called right after calling this constructor.
89 * This destructor overrides Tizen::Base::Object::~Object().
93 virtual ~Scanner(void);
96 * Initializes the current instance of %Scanner with the specified instance of string.
99 * @return An error code
100 * @param[in] inputStr The string to scan.
101 * @exception E_SUCCESS The method is successful.
102 * @exception E_INVALID_ARG The length of the specified @c string parameter is @c 0.
104 result Construct(const String& inputStr);
107 * Initializes the current instance of %Scanner with a file which includes the strings being scanned.
110 * @return An error code
111 * @param[in] inputFilePath The file to be read to construct input data
112 * @param[in] encodingScheme The encoding type of the file.
113 * @exception E_SUCCESS The method is successful.
114 * @exception E_FILE_NOT_FOUND The input file does not exist.
115 * @exception E_IO Invalid file operation
116 * @exception E_INVALID_ARG The specified encoding scheme does not exist.
117 * @remarks The supported encoding schemes are ASCII, GSM, UCS-2, UCS-2LE, UCS-2BE, UCS-4, UCS-4LE, UCS-4BE, UTF-8, UTF-16, UTF-16LE, UTF-16BE, UTF-32, UTF-32LE, UTF-32BE, ISO-8859-1~16 (except ISO-8859-12), Windows-874, Windows-1250 ~ Windows-1258,KSC5601, BIG5, GB2312, Shift_JIS and ISO-2022-jp.
119 result Construct(const String& inputFilePath, const String& encodingScheme);
122 * Gets the substring of the input data matching to the pattern constructed from the specified string.
123 * Delimiter will be ignored and the returned string does not include any line terminator.
124 * If not found such pattern in the input data up to the next line terminator, return an empty string through the out parameter, matchedStr.
127 * @return An error code
128 * @param[in] patternStr The string to construct the pattern.
129 * @param[out] matchedStr The matched string or empty string.
130 * @exception E_SUCCESS The method is successful.
131 * @exception E_INVALID_ARG The length of the specified @c string parameter is @c 0.
132 * @exception E_DATA_NOT_FOUND No substring is found in the input data of current instance.
134 result FindInLine(const String& patternStr, String& matchedStr);
137 * Gets the substring matching the pattern from the input data.
138 * Delimiter will be ignored and the returned string does not include any line terminator.
139 * If not found such pattern in the input data up to the next line terminator, return an empty string through the out parameter, matchedStr.
142 * @return An error code
143 * @param[in] pattern The pattern to be compiled for finding substring from input data.
144 * @param[out] matchedStr The matched string or empty string.
145 * @exception E_SUCCESS The method is successful.
146 * @exception E_DATA_NOT_FOUND No substring is found in the input data of current instance.
149 result FindInLine(const RegularExpression& pattern, String& matchedStr);
152 * Gets the next token as %signed char. Next token is converted to signed char using default radix.
153 * The signed char can hold value from -128 to 127.
156 * @return An error code
157 * @param[out] nextSignedChar The next token as a signed char.
158 * @exception E_SUCCESS The method is successful.
159 * @exception E_NUM_FORMAT The next token cannot be translated into a valid %signed char value.
160 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
162 result GetNextSignedChar(signed char& nextSignedChar) const;
165 * Gets the next token as %signed char. Next token is converted to signed char using specified radix.
166 * The signed char can hold value from -128 to 127.
169 * @return An error code
170 * @param[out] nextSignedChar The next token as a signed char.
171 * @param[in] radix The radix to be used for conversion.
172 * @exception E_SUCCESS The method is successful.
173 * @exception E_NUM_FORMAT The next token cannot be translated into a valid %signed char value.
174 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
177 result GetNextSignedChar(signed char& nextSignedChar, int radix) const;
180 * Gets the next token as %int. Next token is converted to signed integer using default radix.
181 * The signed integer can hold value from -2^31 to 2^31-1.
184 * @return An error code
185 * @param[out] nextInt The next token as a signed integer.
186 * @exception E_SUCCESS The method is successful.
187 * @exception E_NUM_FORMAT The next token cannot be translated into a valid %integer value.
188 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
190 result GetNextInt(int& nextInt) const;
193 * Gets the next token as %int. Next token is converted to signed integer using specified radix.
194 * The signed integer can hold value from -2^31 to 2^31-1.
197 * @return An error code
198 * @param[out] nextInt The next token as a signed integer.
199 * @param[in] radix The radix to be used for conversion.
200 * @exception E_SUCCESS The method is successful.
201 * @exception E_NUM_FORMAT The next token cannot be translated into a valid %integer value.
202 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
204 result GetNextInt(int& nextInt, int radix) const;
207 * Gets the next token as %short. Next token is converted to signed short using default radix.
208 * The signed short can hold value from -2^15 to 2^15-1.
211 * @return An error code
212 * @param[out] nextShort The next token as a signed short.
213 * @exception E_SUCCESS The method is successful.
214 * @exception E_NUM_FORMAT The next token cannot be translated into a valid %short value.
215 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
217 result GetNextShort(short& nextShort) const;
220 * Gets the next token as %short. Next token is converted to signed short using specified radix.
221 * The signed short can hold value from -2^15 to 2^15-1.
224 * @return An error code
225 * @param[out] nextShort The next token as a signed short.
226 * @param[in] radix The radix to be used for conversion.
227 * @exception E_SUCCESS The method is successful.
228 * @exception E_NUM_FORMAT The next token cannot be translated into a valid %short value.
229 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
231 result GetNextShort(short& nextShort, int radix) const;
234 * Gets the next token as %long long. Next token is converted to signed long long using default radix.
235 * The signed long can hold value from -2^63 to 2^63-1.
238 * @return An error code
239 * @param[out] nextLongLong The next token as a signed long long.
240 * @exception E_SUCCESS The method is successful.
241 * @exception E_NUM_FORMAT The next token cannot be translated into a valid %long long value.
242 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
244 result GetNextLongLong(long long& nextLongLong) const;
247 * Gets the next token as %long long. Next token is converted to signed long long using specified radix.
248 * The signed long can hold value from -2^63 to 2^63-1.
251 * @return An error code
252 * @param[out] nextLongLong The next token as a signed short.
253 * @param[in] radix The radix to be used for conversion.
254 * @exception E_SUCCESS The method is successful.
255 * @exception E_NUM_FORMAT The next token cannot be translated into a valid %short value.
256 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
258 result GetNextLongLong(long long& nextLongLong, int radix) const;
261 * Gets the next token as %float. Next token is converted to float.
262 * The signed float can hold a single-precision 32-bit floating number.
265 * @return An error code
266 * @param[out] nextFloat The next token as a float.
267 * @exception E_SUCCESS The method is successful.
268 * @exception E_NUM_FORMAT The next token cannot be translated into a valid %float value.
269 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
271 result GetNextFloat(float& nextFloat) const;
274 * Gets the next token as %double. Next token is converted to double.
275 * The signed double can hold a double-precision 64-bit floating number.
278 * @return An error code
279 * @param[out] nextDouble The next token as a double.
280 * @exception E_SUCCESS The method is successful.
281 * @exception E_NUM_FORMAT The next token cannot be translated into a valid %double value.
282 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
284 result GetNextDouble(double& nextDouble) const;
287 * Gets the next token as %bool. Next token is converted to boolean.
288 * Nothing can be converted, except true/TRUE or false/FALSE.
291 * @return An error code
292 * @param[out] nextBool The next token as bool.
293 * @exception E_SUCCESS The method is successful.
294 * @exception E_NUM_FORMAT The next token cannot be translated into a valid %bool value.
295 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
297 result GetNextBool(bool& nextBool) const;
300 * Gets the input string up to next line delimiter and advances the %Scanner to the beginning of the next line.
301 * The returned string does not include any line terminator.
304 * @return An error code
305 * @param[out] nextLine The next line as an instance of string.
306 * @exception E_SUCCESS The method is successful.
307 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining line.
309 * The following example demonstrates how to use this method.
313 * String str = "1 hundred bricks\n2 bricks\n3 hundred bricks\n4 bricks";
318 * scan.Construct(str);
320 * if (scan.HasNextLine())
322 * scan.GetNextLine(out); //returns 1 hundred bricks
331 result GetNextLine(String& nextLine) const;
334 * Gets the next token as %String.
337 * @return An error code
338 * @param[out] nextTok The next token as an instance of string.
339 * @exception E_SUCCESS The method is successful.
340 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
342 * The following example demonstrates how to use this method.
345 * String str = "1 hundred bricks 2 bricks 3 hundred bricks 4 bricks";
350 * scan.Construct(str);
351 * String delimiter(L"\\s*bricks\\s*");
352 * scan.SetDelimiter(delimiter);
354 * if (scan.HasNext())
356 * scan.GetNextToken(out); //returns 1 hundred
365 result GetNextToken(String& nextTok) const;
368 * Gets the next token as %String if it matches to the pattern constructed from the specified string.
371 * @return An error code
372 * @param[in] pattern The string to construct the pattern.
373 * @param[out] nextTok The next token as an instance of string, or empty string if not matched.
374 * @exception E_SUCCESS The method is successful.
375 * @exception E_DATA_NOT_FOUND The next token does not match to the pattern.
376 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
378 result GetNextToken(const String& pattern, String& nextTok) const;
381 * Gets the next token as %String if it matches to the pattern.
384 * @return An error code
385 * @param[in] pattern The pattern to find.
386 * @param[out] nextTok The next token as an instance of string, or empty string if not matched.
387 * @exception E_SUCCESS The method is successful.
388 * @exception E_DATA_NOT_FOUND The next token does not match to the pattern.
389 * @exception E_DATA_NOT_ENOUGH The current instance of %Scanner has no remaining token.
391 result GetNextToken(const RegularExpression& pattern, String& nextTok) const;
394 * Gets the radix of this %Scanner.
397 * @return The current radix value
399 int GetRadix(void) const;
402 * Gets the delimiter of this %Scanner.
405 * @return The current delimiter string
407 String GetDelimiter(void) const;
410 * Checks whether the current instance of %Scanner has another token.
413 * @return @c true if the current instance has another token, @n
416 bool HasNextToken(void) const;
419 * Checks whether the next token matches to the pattern constructed from the specified string.
422 * @return @c true if the next token matches to the pattern constructed from the specified string, @n
424 * @param[in] pattern The string to construct the pattern.
426 bool HasNextToken(const String& pattern) const;
429 * Checks whether the next token matches to the pattern.
432 * @return @c true if the next token matches to the pattern, @n
434 * @param[in] pattern The pattern to find.
436 bool HasNextToken(const RegularExpression& pattern) const;
439 * Checks whether the next token can be translated into a valid %signed char value in the default radix.
440 * The signed char can hold value from -128 to 127.
443 * @return @c true if the next token can be translated into a valid %signed char value in the current radix, @n
446 bool IsNextTokenConvertibleToSignedChar(void) const;
449 * Checks whether the next token can be translated into a valid %signed char value in the specified radix.
450 * The signed char can hold value from -128 to 127.
453 * @return @c true if the next token can be translated into a valid %signed char value in the current radix, @n
455 * @param[in] radix The radix used to translate the token as a valid %signed char value
457 bool IsNextTokenConvertibleToSignedChar(int radix) const;
460 * Checks whether the next token can be translated into a valid %int value in the default radix.
461 * The signed integer can hold value from -2^31 to 2^31-1.
464 * @return @c true if the next token can be translated into a valid %int value in the current radix, @n
467 bool IsNextTokenConvertibleToInt(void) const;
470 * Checks whether the next token can be translated into a valid %int value in the specified radix.
471 * The signed integer can hold value from -2^31 to 2^31-1.
474 * @return @c true if the next token can be translated into a valid %int value in the current radix, @n
476 * @param[in] radix The radix used to translate the token as a valid %int value
478 bool IsNextTokenConvertibleToInt(int radix) const;
481 * Checks whether the next token can be translated into a valid %short value in the default radix.
482 * The signed short can hold value from -2^15 to 2^15-1.
485 * @return @c true if the next token can be translated into a valid %short value in the current radix, @n
488 bool IsNextTokenConvertibleToShort(void) const;
491 * Checks whether the next token can be translated into a valid %short value in the specified radix.
492 * The signed short can hold value from -2^15 to 2^15-1.
495 * @return @c true if the next token can be translated into a valid %short value in the current radix, @n
497 * @param[in] radix The radix used to translate the token as a valid %short value
499 bool IsNextTokenConvertibleToShort(int radix) const;
502 * Checks whether the next token can be translated into a valid %long long value.
503 * The signed long can hold value from -2^63 to 2^63-1.
506 * @return @c true if the next token can be translated into a valid %long long value in the current radix, @n
509 bool IsNextTokenConvertibleToLongLong(void) const;
512 * Checks whether the next token can be translated into a valid %float value.
513 * The signed float can hold a single-precision 32-bit floating number.
516 * @return @c true if the next token can be translated into a valid %float value in the current radix, @n
519 bool IsNextTokenConvertibleToFloat(void) const;
522 * Checks whether the next token can be translated into a valid %double value.
523 * The signed double can hold a double-precision 64-bit floating number.
526 * @return @c true if the next token can be translated into a valid %double value in the current radix, @n
529 bool IsNextTokenConvertibleToDouble(void) const;
532 * Checks whether the next token can be translated into a valid %bool value.
533 * Nothing can be converted except true/TRUE or false/FALSE
536 * @return @c true if the next token can be translated into a valid %bool value, @n
539 bool IsNextTokenConvertibleToBool(void) const;
542 * Checks whether the input data of the current instance of %Scanner has another line.
545 * @return @c true if the input data of the current instance of %Scanner has another line, @n
548 bool HasNextLine(void) const;
551 * Sets the radix of the current instance of %Scanner to the specified radix
554 * @param[in] radix The radix used for conversion.
557 void SetRadix(int radix);
560 * Sets the delimiter of the current instance of %Scanner to the pattern constructed from the specified delimiter.
563 * @param[in] patternStr The delimiter to construct the pattern.
565 void SetDelimiter(const String& patternStr);
568 * Sets the delimiter of the current instance of %Scanner to the specified pattern.
571 * @param[in] pattern The pattern used as a delimiter.
573 void SetDelimiter(const RegularExpression& pattern);
576 * Skips the pattern constructed from the specified string.
579 * @param[in] patternStr The string to construct the pattern.
580 * @remarks If no match to the specified pattern is found at the current position, nothing is skipped.
582 * The following example demonstrates how to use this method.
586 * const String str("28 1 Ball 2 Ball 3.4 Ball 5 Ball red Ball blue Ball 8 89 67 21474836899.11 NaN 3.4e+5 +23 89 01010 456 123.456");
587 * const String skipStr("28 1 ");
592 * scan.Construct(str);
594 * //Skips "28 1" from input string
595 * scan.Skip(skipStr);
597 * if (scan1.HasNextToken())
599 * scan.GetNextToken(out); //returns Ball
608 void Skip(const String& patternStr);
611 * Skips the specified pattern.
614 * @param[in] pattern The pattern used to skip.
615 * @remarks If no match to the specified pattern is found at the current position, nothing is skipped.
617 void Skip(const RegularExpression& pattern);
620 friend class _ScannerImpl;
621 class _ScannerImpl* __pScannerImpl;
624 }}} // Tizen::Base::Utility
626 #endif // _FBASE_UTIL_SCANNER_H_