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 to 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 that includes the strings that are being scanned.
110 * @return An error code
111 * @param[in] inputFilePath The file to 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 The file operation is invalid.
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. @n
123 * Delimiter will be ignored and the returned string does not include any line terminator.
124 * If such a pattern in the input data is not found upto 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. @n
138 * Delimiter will be ignored and the returned string does not include any line terminator.
139 * If such a pattern in the input data is not found upto 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 compile 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 @c signed @c char. @n Next token is converted to @c signed @c char using default radix.
153 * The @c signed @c char can hold value from -128 to 127.
156 * @return An error code
157 * @param[out] nextSignedChar The next token as a @c signed @c char
158 * @exception E_SUCCESS The method is successful.
159 * @exception E_NUM_FORMAT The next token cannot be translated into a valid signed @c char value.
160 * @exception E_DATA_NOT_ENOUGH There are no remaining tokens for the current instance of %Scanner.
162 result GetNextSignedChar(signed char& nextSignedChar) const;
165 * Gets the next token as @c signed @c char. @n Next token is converted to @c signed @c char using specified @c radix.
166 * The @c signed @c char can hold value from -128 to 127.
169 * @return An error code
170 * @param[out] nextSignedChar The next token as a @c signed @c char
171 * @param[in] radix The radix to use for conversion
172 * @exception E_SUCCESS The method is successful.
173 * @exception E_NUM_FORMAT The next token cannot be translated into a valid @c signed @c char value.
174 * @exception E_DATA_NOT_ENOUGH There are no remaining tokens for the current instance of %Scanner.
177 result GetNextSignedChar(signed char& nextSignedChar, int radix) const;
180 * Gets the next token as @c int. @n 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 There are no remaining tokens for the current instance of %Scanner.
190 result GetNextInt(int& nextInt) const;
193 * Gets the next token as @c int. @n Next token is converted to signed integer using specified @c 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 use 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 There are no remaining tokens for the current instance of %Scanner.
204 result GetNextInt(int& nextInt, int radix) const;
207 * Gets the next token as @c short. @n Next token is converted to signed @c short using default radix.
208 * The signed @c 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 @c short
213 * @exception E_SUCCESS The method is successful.
214 * @exception E_NUM_FORMAT The next token cannot be translated into a valid @c short value.
215 * @exception E_DATA_NOT_ENOUGH There are no remaining tokens for the current instance of %Scanner.
217 result GetNextShort(short& nextShort) const;
220 * Gets the next token as @c short. @n Next token is converted to signed @c short using specified @c radix.
221 * The signed @c 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 @c short
226 * @param[in] radix The radix to use for conversion
227 * @exception E_SUCCESS The method is successful.
228 * @exception E_NUM_FORMAT The next token cannot be translated into a valid @c short value.
229 * @exception E_DATA_NOT_ENOUGH There are no remaining tokens for the current instance of %Scanner.
231 result GetNextShort(short& nextShort, int radix) const;
234 * Gets the next token as @c long @c long. @n Next token is converted to signed @c long @c long using default radix.
235 * The signed @c long @c 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 @c long @c long
240 * @exception E_SUCCESS The method is successful.
241 * @exception E_NUM_FORMAT The next token cannot be translated into a valid @c long @c long value.
242 * @exception E_DATA_NOT_ENOUGH There are no remaining tokens for the current instance of %Scanner.
244 result GetNextLongLong(long long& nextLongLong) const;
247 * Gets the next token as @c long @c long. @n Next token is converted to signed @c long @c long using specified @c radix.
248 * The signed @c long @c 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 @c long @c long
253 * @param[in] radix The radix to use for conversion
254 * @exception E_SUCCESS The method is successful.
255 * @exception E_NUM_FORMAT The next token cannot be translated into a valid @c long @c long value.
256 * @exception E_DATA_NOT_ENOUGH There are no remaining tokens for the current instance of %Scanner.
258 result GetNextLongLong(long long& nextLongLong, int radix) const;
261 * Gets the next token as @c float. @n Next token is converted to @c float.
262 * The signed @c float can hold a single-precision 32-bit floating number.
265 * @return An error code
266 * @param[out] nextFloat The next token as a @c float
267 * @exception E_SUCCESS The method is successful.
268 * @exception E_NUM_FORMAT The next token cannot be translated into a valid @c float value.
269 * @exception E_DATA_NOT_ENOUGH There are no remaining tokens for the current instance of %Scanner.
271 result GetNextFloat(float& nextFloat) const;
274 * Gets the next token as @c double. @n Next token is converted to @c double.
275 * The signed @c double can hold a double-precision 64-bit floating number.
278 * @return An error code
279 * @param[out] nextDouble The next token as a @c double
280 * @exception E_SUCCESS The method is successful.
281 * @exception E_NUM_FORMAT The next token cannot be translated into a valid @c double value.
282 * @exception E_DATA_NOT_ENOUGH There are no remaining tokens for the current instance of %Scanner.
284 result GetNextDouble(double& nextDouble) const;
287 * Gets the next token as @c bool. @n 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 @c bool
293 * @exception E_SUCCESS The method is successful.
294 * @exception E_NUM_FORMAT The next token cannot be translated into a valid @c bool value.
295 * @exception E_DATA_NOT_ENOUGH There are no remaining tokens for the current instance of %Scanner.
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. @n
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 There are no remaining lines for the current instance of %Scanner.
309 * The following example demonstrates how to use the %GetNextLine() 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 There are no remaining tokens for the current instance of %Scanner.
342 * The following example demonstrates how to use the %GetNextToken() 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, @n
374 * else an empty string if not matched
375 * @exception E_SUCCESS The method is successful.
376 * @exception E_DATA_NOT_FOUND The next token does not match to the pattern.
377 * @exception E_DATA_NOT_ENOUGH There are no remaining tokens for the current instance of %Scanner.
379 result GetNextToken(const String& pattern, String& nextTok) const;
382 * Gets the next token as String if it matches to the pattern.
385 * @return An error code
386 * @param[in] pattern The pattern to find.
387 * @param[out] nextTok The next token as an instance of String, @n
388 * else an empty string if not matched
389 * @exception E_SUCCESS The method is successful.
390 * @exception E_DATA_NOT_FOUND The next token does not match to the pattern.
391 * @exception E_DATA_NOT_ENOUGH There are no remaining tokens for the current instance of %Scanner.
393 result GetNextToken(const RegularExpression& pattern, String& nextTok) const;
396 * Gets the radix of this %Scanner.
399 * @return The current radix value
401 int GetRadix(void) const;
404 * Gets the delimiter of this %Scanner.
407 * @return The current delimiter string
409 String GetDelimiter(void) const;
412 * Checks whether the current instance of %Scanner has another token.
415 * @return @c true if the current instance has another token, @n
418 bool HasNextToken(void) const;
421 * Checks whether the next token matches to the pattern constructed from the specified string.
424 * @return @c true if the next token matches to the pattern constructed from the specified string, @n
426 * @param[in] pattern The string to construct the pattern
428 bool HasNextToken(const String& pattern) const;
431 * Checks whether the next token matches to the pattern.
434 * @return @c true if the next token matches to the pattern, @n
436 * @param[in] pattern The pattern to find
438 bool HasNextToken(const RegularExpression& pattern) const;
441 * Checks whether the next token can be translated into a valid @c signed @c char value in the default radix.
442 * The @c signed @c char can hold value from -128 to 127.
445 * @return @c true if the next token can be translated into a valid @c signed @c char value in the current radix, @n
448 bool IsNextTokenConvertibleToSignedChar(void) const;
451 * Checks whether the next token can be translated into a valid @c signed @c char value in the specified @c radix.
452 * The @c signed @c char can hold value from -128 to 127.
455 * @return @c true if the next token can be translated into a valid @c signed @c char value in the current radix, @n
457 * @param[in] radix The radix to use to translate the token as a valid @c signed @c char value
459 bool IsNextTokenConvertibleToSignedChar(int radix) const;
462 * Checks whether the next token can be translated into a valid @c int value in the default radix. @n
463 * The signed integer can hold value from -2^31 to 2^31-1.
466 * @return @c true if the next token can be translated into a valid @c int value in the current radix, @n
469 bool IsNextTokenConvertibleToInt(void) const;
472 * Checks whether the next token can be translated into a valid @c int value in the specified @c radix. @n
473 * The signed integer can hold value from -2^31 to 2^31-1.
476 * @return @c true if the next token can be translated into a valid @c int value in the current radix, @n
478 * @param[in] radix The radix to use to translate the token as a valid @c int value
480 bool IsNextTokenConvertibleToInt(int radix) const;
483 * Checks whether the next token can be translated into a valid @c short value in the default radix. @n
484 * The signed @c short can hold value from -2^15 to 2^15-1.
487 * @return @c true if the next token can be translated into a valid @c short value in the current radix, @n
490 bool IsNextTokenConvertibleToShort(void) const;
493 * Checks whether the next token can be translated into a valid @c short value in the specified @c radix. @n
494 * The signed @c short can hold value from -2^15 to 2^15-1.
497 * @return @c true if the next token can be translated into a valid @c short value in the current radix, @n
499 * @param[in] radix The radix to use to translate the token as a valid @c short value
501 bool IsNextTokenConvertibleToShort(int radix) const;
504 * Checks whether the next token can be translated into a valid @c long @c long value. @n
505 * The signed @c long @c long can hold value from -2^63 to 2^63-1.
508 * @return @c true if the next token can be translated into a valid @c long @c long value in the current radix, @n
511 bool IsNextTokenConvertibleToLongLong(void) const;
514 * Checks whether the next token can be translated into a valid @c float value. @n
515 * The signed @c float can hold a single-precision 32-bit floating number.
518 * @return @c true if the next token can be translated into a valid @c float value in the current radix, @n
521 bool IsNextTokenConvertibleToFloat(void) const;
524 * Checks whether the next token can be translated into a valid @c double value. @n
525 * The signed @c double can hold a double-precision 64-bit floating number.
528 * @return @c true if the next token can be translated into a valid @c double value in the current radix, @n
531 bool IsNextTokenConvertibleToDouble(void) const;
534 * Checks whether the next token can be translated into a valid @c bool value. @n
535 * Nothing can be converted except true/TRUE or false/FALSE.
538 * @return @c true if the next token can be translated into a valid @c bool value, @n
541 bool IsNextTokenConvertibleToBool(void) const;
544 * Checks whether the input data of the current instance of %Scanner has another line.
547 * @return @c true if the input data of the current instance of %Scanner has another line, @n
550 bool HasNextLine(void) const;
553 * Sets the radix of the current instance of %Scanner to the specified @c radix.
556 * @param[in] radix The radix to use for conversion
559 void SetRadix(int radix);
562 * Sets the delimiter of the current instance of %Scanner to the pattern constructed from the specified delimiter.
565 * @param[in] patternStr The delimiter to construct the pattern
567 void SetDelimiter(const String& patternStr);
570 * Sets the delimiter of the current instance of %Scanner to the specified @c pattern.
573 * @param[in] pattern The pattern to use as a delimiter
575 void SetDelimiter(const RegularExpression& pattern);
578 * Skips the pattern constructed from the specified string.
581 * @param[in] patternStr The string to construct the pattern
582 * @remarks If no match to the specified pattern is found at the current position, nothing is skipped.
584 * The following example demonstrates how to use the %Skip() method.
588 * 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");
589 * const String skipStr("28 1 ");
594 * scan.Construct(str);
596 * //Skips "28 1" from input string
597 * scan.Skip(skipStr);
599 * if (scan1.HasNextToken())
601 * scan.GetNextToken(out); //returns Ball
610 void Skip(const String& patternStr);
613 * Skips the specified @c pattern.
616 * @param[in] pattern The pattern to use to skip
617 * @remarks If no match to the specified pattern is found at the current position, nothing is skipped.
619 void Skip(const RegularExpression& pattern);
622 friend class _ScannerImpl;
623 class _ScannerImpl* __pScannerImpl;
626 }}} // Tizen::Base::Utility
628 #endif // _FBASE_UTIL_SCANNER_H_