456deb2a2c25116cadd9a2baff2caa52572efa58
[platform/framework/native/appfw.git] / inc / FBaseUtilScanner.h
1 //
2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 //
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
8 //
9 //     http://www.apache.org/licenses/LICENSE-2.0
10 //
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.
16 //
17
18
19 /**
20  * @file        FBaseUtilScanner.h
21  * @brief       This is the header file for the %Scanner class.
22  *
23  * This header file contains declarations and definitions of the %Scanner class.
24  *
25  */
26
27 #ifndef _FBASE_UTIL_SCANNER_H_
28 #define _FBASE_UTIL_SCANNER_H_
29
30 #include <FBaseString.h>
31 #include <FBaseUtilRegularExpression.h>
32
33 namespace Tizen { namespace Base { namespace Utility
34 {
35 /**
36  * @class       Scanner
37  * @brief       This class provides to parse primitive types and strings, and supports to use regular expressions and various encoding schemes.
38  * @since 2.1
39  *
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.
43  *
44  * The following example demonstrates how to use the %Scanner class.
45  * @code
46  *
47  *      String str = L"1 12 34.5 58 false";
48  *      Scanner scan;
49  *      bool ret = false;
50  *
51  *      scan.Construct(str);
52  *
53  *      ret = scan.IsNextTokenConvertibleToSignedChar();        //ret true
54  *      signed char val;
55  *  scan.GetNextSignedChar(val);        //val 1
56  *
57  *      ret = scan.IsNextTokenConvertibleToShort(10);   //ret true
58  *      short shortVal;
59  *  scan.GetNextShort(shortVal);        //shortVal 12
60  *
61  *      ret = scan.IsNextTokenConvertibleToInt(10);     //ret false
62  *      ret = scan.IsNextTokenConvertibleToFloat();     //ret true
63  *      float floatVal;
64  *  scan.GetNextFloat(floatVal);        //floatVal 34.5
65  *
66  *      ret = scan.IsNextTokenConvertibleToInt(16);     //ret true
67  *      int intVal;
68  *  scan.GetNextInt(intVal, 16);        //intVal 88
69  *
70  *      ret = scan.IsNextTokenConvertibleToBool();      //ret true
71  *      scan.GetNextBool(ret);  //ret false
72  *
73  * @endcode
74  */
75 class _OSP_EXPORT_ Scanner
76         : public Tizen::Base::Object
77 {
78
79 public:
80         /**
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.
83         *
84         * @since 2.1
85         */
86         Scanner(void);
87
88         /**
89         * This destructor overrides Tizen::Base::Object::~Object().
90         *
91         * @since 2.1
92         */
93         virtual ~Scanner(void);
94
95         /**
96         * Initializes the current instance of %Scanner with the specified instance of string.
97         *
98         * @since 2.1
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.
103         */
104         result Construct(const String& inputStr);
105
106         /**
107         * Initializes the current instance of %Scanner with a file which includes the strings being scanned.
108         *
109         * @since 2.1
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.
118         */
119         result Construct(const String& inputFilePath, const String& encodingScheme);
120
121         /**
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.
125         *
126         * @since 2.1
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.
133         */
134         result FindInLine(const String& patternStr, String& matchedStr);
135
136         /**
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.
140         *
141         * @since 2.1
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.
147         */
148
149         result FindInLine(const RegularExpression& pattern, String& matchedStr);
150
151         /**
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.
154         *
155         * @since 2.1
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.
161         */
162         result GetNextSignedChar(signed char& nextSignedChar) const;
163
164         /**
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.
167         *
168         * @since 2.1
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.
175         */
176
177         result GetNextSignedChar(signed char& nextSignedChar, int radix) const;
178
179         /**
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.
182         *
183         * @since 2.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.
189         */
190         result GetNextInt(int& nextInt) const;
191
192         /**
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.
195         *
196         * @since 2.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.
203         */
204         result GetNextInt(int& nextInt, int radix) const;
205
206         /**
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.
209         *
210         * @since 2.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.
216         */
217         result GetNextShort(short& nextShort) const;
218
219         /**
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.
222         *
223         * @since 2.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.
230         */
231         result GetNextShort(short& nextShort, int radix) const;
232
233         /**
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.
236         *
237         * @since 2.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.
243         */
244         result GetNextLongLong(long long& nextLongLong) const;
245
246         /**
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.
249         *
250         * @since 2.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.
257         */
258         result GetNextLongLong(long long& nextLongLong, int radix) const;
259
260         /**
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.
263         *
264         * @since 2.1
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.
270         */
271         result GetNextFloat(float& nextFloat) const;
272
273         /**
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.
276         *
277         * @since 2.1
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.
283         */
284         result GetNextDouble(double& nextDouble) const;
285
286         /**
287         * Gets the next token as %bool. Next token is converted to boolean.
288         * Nothing can be converted, except true/TRUE or false/FALSE.
289         *
290         * @since 2.1
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.
296         */
297         result GetNextBool(bool& nextBool) const;
298
299         /**
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.
302         *
303         * @since 2.1
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.
308         *
309         * The following example demonstrates how to use this method.
310         *
311         * @code
312         *
313         *       String str = "1 hundred bricks\n2 bricks\n3 hundred bricks\n4 bricks";
314         *       bool res = false;
315         *       String out;
316         *       Scanner scan;
317         *
318         *       scan.Construct(str);
319         *
320         *       if (scan.HasNextLine())
321         *       {
322         *               scan.GetNextLine(out); //returns 1 hundred bricks
323         *       }
324         *       else
325         *       {
326         *               return;
327         *       }
328         *
329         * @endcode
330         */
331         result GetNextLine(String& nextLine) const;
332
333         /**
334         * Gets the next token as %String.
335         *
336         * @since 2.1
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.
341         *
342         * The following example demonstrates how to use this method.
343         * @code
344         *
345         *       String str = "1 hundred bricks 2 bricks 3 hundred bricks 4 bricks";
346         *       bool res =  false;
347         *       String out;
348         *       Scanner scan;
349         *
350         *       scan.Construct(str);
351         *       String delimiter(L"\\s*bricks\\s*");
352         *       scan.SetDelimiter(delimiter);
353         *
354         *       if (scan.HasNext())
355         *       {
356         *               scan.GetNextToken(out); //returns 1 hundred
357         *       }
358         *       else
359         *       {
360         *               return;
361         *       }
362         *
363         * @endcode
364         */
365         result GetNextToken(String& nextTok) const;
366
367         /**
368         * Gets the next token as %String if it matches to the pattern constructed from the specified string.
369         *
370         * @since 2.1
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.
377         */
378         result GetNextToken(const String& pattern, String& nextTok) const;
379
380         /**
381         * Gets the next token as %String if it matches to the pattern.
382         *
383         * @since 2.1
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.
390         */
391         result GetNextToken(const RegularExpression& pattern, String& nextTok) const;
392
393         /**
394         * Gets the radix of this %Scanner.
395         *
396         * @since 2.1
397         * @return       The current radix value
398         */
399         int GetRadix(void) const;
400
401         /**
402         * Gets the delimiter of this %Scanner.
403         *
404         * @since 2.1
405         * @return       The current delimiter string
406         */
407         String GetDelimiter(void) const;
408
409         /**
410         * Checks whether the current instance of %Scanner has another token.
411         *
412         * @since 2.1
413         * @return       @c true if the current instance has another token, @n
414         *               else @c false
415         */
416         bool HasNextToken(void) const;
417
418         /**
419         * Checks whether the next token matches to the pattern constructed from the specified string.
420         *
421         * @since 2.1
422         * @return       @c true if the next token matches to the pattern constructed from the specified string, @n
423         *               else @c false
424         * @param[in]    pattern  The string to construct the pattern.
425         */
426         bool HasNextToken(const String& pattern) const;
427
428         /**
429         * Checks whether the next token matches to the pattern.
430         *
431         * @since 2.1
432         * @return       @c true if the next token matches to the pattern, @n
433         *               else @c false
434         * @param[in]    pattern  The pattern to find.
435         */
436         bool HasNextToken(const RegularExpression& pattern) const;
437
438         /**
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.
441         *
442         * @since 2.1
443         * @return       @c true if the next token can be translated into a valid %signed char value in the current radix, @n
444         *               else @c false
445         */
446         bool IsNextTokenConvertibleToSignedChar(void) const;
447
448         /**
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.
451         *
452         * @since 2.1
453         * @return       @c true if the next token can be translated into a valid %signed char value in the current radix, @n
454         *                       else @c false
455         * @param[in]    radix     The radix used to translate the token as a valid %signed char value
456         */
457         bool IsNextTokenConvertibleToSignedChar(int radix) const;
458
459         /**
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.
462         *
463         * @since 2.1
464         * @return       @c true if the next token can be translated into a valid %int value in the current radix, @n
465         *               else @c false
466         */
467         bool IsNextTokenConvertibleToInt(void) const;
468
469         /**
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.
472         *
473         * @since 2.1
474         * @return       @c true if the next token can be translated into a valid %int value in the current radix, @n
475         *               else @c false
476         * @param[in]    radix     The radix used to translate the token as a valid %int value
477         */
478         bool IsNextTokenConvertibleToInt(int radix) const;
479
480         /**
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.
483         *
484         * @since 2.1
485         * @return       @c true if the next token can be translated into a valid %short value in the current radix, @n
486         *               else @c false
487         */
488         bool IsNextTokenConvertibleToShort(void) const;
489
490         /**
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.
493         *
494         * @since 2.1
495         * @return       @c true if the next token can be translated into a valid %short value in the current radix, @n
496         *               else @c false
497         * @param[in]    radix     The radix used to translate the token as a valid %short value
498         */
499         bool IsNextTokenConvertibleToShort(int radix) const;
500
501         /**
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.
504         *
505         * @since 2.1
506         * @return       @c true if the next token can be translated into a valid %long long value in the current radix, @n
507         *               else @c false
508         */
509         bool IsNextTokenConvertibleToLongLong(void) const;
510
511         /**
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.
514         *
515         * @since 2.1
516         * @return       @c true if the next token can be translated into a valid %float value in the current radix, @n
517         *               else @c false
518         */
519         bool IsNextTokenConvertibleToFloat(void) const;
520
521         /**
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.
524         *
525         * @since 2.1
526         * @return       @c true if the next token can be translated into a valid %double value in the current radix, @n
527         *               else @c false
528         */
529         bool IsNextTokenConvertibleToDouble(void) const;
530
531         /**
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
534         *
535         * @since 2.1
536         * @return       @c true if the next token can be translated into a valid %bool value, @n
537         *               else @c false
538         */
539         bool IsNextTokenConvertibleToBool(void) const;
540
541         /**
542         * Checks whether the input data of the current instance of %Scanner has another line.
543         *
544         * @since 2.1
545         * @return       @c true if the input data of the current instance of %Scanner has another line, @n
546         *               else @c false
547         */
548         bool HasNextLine(void) const;
549
550         /**
551         * Sets the radix of the current instance of %Scanner to the specified radix
552         *
553         * @since 2.1
554         * @param[in]    radix     The radix used for conversion.
555         *
556         */
557         void SetRadix(int radix);
558
559         /**
560         * Sets the delimiter of the current instance of %Scanner to the pattern constructed from the specified delimiter.
561         *
562         * @since 2.1
563         * @param[in]    patternStr      The delimiter to construct the pattern.
564         */
565         void SetDelimiter(const String& patternStr);
566
567         /**
568         * Sets the delimiter of the current instance of %Scanner to the specified pattern.
569         *
570         * @since 2.1
571         * @param[in]    pattern  The pattern used as a delimiter.
572         */
573         void SetDelimiter(const RegularExpression& pattern);
574
575         /**
576         * Skips the pattern constructed from the specified string.
577         *
578         * @since 2.1
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.
581         *
582         * The following example demonstrates how to use this method.
583         *
584         * @code
585         *
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   ");
588         *       bool res = false;
589         *       String out;
590         *       Scanner scan;
591         *
592         *       scan.Construct(str);
593         *
594         *       //Skips "28 1" from input string
595         *       scan.Skip(skipStr);
596         *
597         *       if (scan1.HasNextToken())
598         *       {
599         *               scan.GetNextToken(out); //returns Ball
600         *       }
601         *       else
602         *       {
603         *               return;
604         *       }
605         *
606         * @endcode
607         */
608         void Skip(const String& patternStr);
609
610         /**
611         * Skips the specified pattern.
612         *
613         * @since 2.1
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.
616         */
617         void Skip(const RegularExpression& pattern);
618
619 private:
620         friend class _ScannerImpl;
621         class _ScannerImpl* __pScannerImpl;
622 }; // Scanner
623
624 }}}   // Tizen::Base::Utility
625
626 #endif // _FBASE_UTIL_SCANNER_H_