Merge refined doxygen comments of Base header files
[platform/framework/native/appfw.git] / inc / FBaseUtilRegularExpression.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  * @file                FBaseUtilRegularExpression.h
20  * @brief               This is the header file for the %RegularExpression class.
21  *
22  * This header file contains the declarations of the %RegularExpression class.
23  */
24 #ifndef _FBASE_UTIL_REGULAR_EXPRESSION_H_
25 #define _FBASE_UTIL_REGULAR_EXPRESSION_H_
26
27 #include <FBaseColIList.h>
28 #include <FBaseString.h>
29
30
31 namespace Tizen { namespace Base { namespace Utility
32 {
33
34 /**
35  *      @enum   RegularExpressionOptions
36  *
37  *      Defines the options available for a regular expression.
38  *
39  *      @since 2.0
40  */
41 enum RegularExpressionOptions
42 {
43         REGEX_CASELESS = 0x00000001,                /**< The case insensitive match option */
44         REGEX_MULTI_LINE = 0x00000002,              /**< The multiple lines match option @n
45                                                                     Without this option, (^) matches only at the start of the string, while ($) matches only at
46                                                                     the end of the string, or  before a terminating newline. */
47         REGEX_DOTALL = 0x00000004,                  /**< The dot matches newlines option @n
48                                                                                                         Without this option, a dot does not match when the current position is at a newline. */
49         REGEX_EXTENDED = 0x00000008,            /**< The ignored whitespaces in a pattern */
50         REGEX_DOLLAR_ENDONLY = 0x00000020,              /**< The option to match the dollar symbol ($) only at the end @n
51                                                         Without this option, a dollar symbol also matches immediately before a newline. */
52         REGEX_UNGREEDY = 0x00000200,                /**< The option to reverse the (*) and (*?) symbols @n
53                                                                     If this option is set, the quantifiers are not greedy by default, however they are, if followed by a question mark. */
54         REGEX_UNICODE = 0x01000000,                 /**< The option to support the unicode characters @n
55                                                                     Without this option, only the ASCII characters are recognized. */
56 };
57
58 /**
59  * @class       RegularExpression
60  * @brief               This class provides the functionality for a regular expression.
61  *
62  * @since 2.0
63  *
64  * The %RegularExpression class provides operations of a regular expression based on PCRE and the syntax based on
65  * the Perl regular expression.
66  * The various supported operations are Match(), Replace(), and Consume().
67  *
68  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/regular_expression.htm">Regular Expression</a>.
69  *
70  * The following example demonstrates how to use the %RegularExpression class.
71  *
72  * @code
73  *
74  *      #include <FBase.h>
75  *
76  *      using namespace Tizen::Base;
77  *      using namespace Tizen::Base::Collection;
78  *      using namespace Tizen::Base::Utility;
79  *
80  *      void
81  *      MyClass:RegularExpressionSample(void)
82  *      {
83  *              bool ret = false;
84  *
85  *              String pattern(L"the quick brown fox");
86  *              String text(L"What do you know about the quick brown fox?");
87  *              String out;
88  *
89  *              RegularExpression regex;
90  *              regex.Construct(pattern, REGEX_CASELESS);
91  *
92  *              ret = regex.Match(text, false); // This returns true value
93  *      }
94  *
95  * @endcode
96  */
97 class _OSP_EXPORT_ RegularExpression
98         : public Tizen::Base::Object
99 {
100 public:
101         /**
102          * The object is not fully constructed after this constructor is called. @n
103          * For full construction, the Construct() method must be called right after calling this constructor.
104          *
105          * @since 2.0
106          */
107         RegularExpression(void);
108
109         /**
110          * This destructor overrides Tizen::Base::Object::~Object().
111          *
112          * @since 2.0
113          */
114         virtual ~RegularExpression(void);
115
116         /**
117          * Initializes this instance of %RegularExpression with the specified parameters.
118          *
119          * @since 2.0
120          *
121          * @return                      An error code
122          * @param[in]           pattern The pattern to use
123          * @param[in]           options The option for the regular expression
124          * @exception           E_SUCCESS               The method is successful.
125          * @exception           E_INVALID_STATE         This instance has already been constructed.
126          * @exception           E_INVALID_ARG           The length of the specified @c pattern parameter is @c 0.
127          *
128          * The following example demonstrates how to use the %Construct() method.
129          * @code
130          *
131          *      bool ret = false;
132          *
133          *      String pattern(L"^CRUEL$");
134          *      String text(L"Hello\ncruel\nworld");
135          *
136          *      RegularExpression regex;
137          *      regex.Construct(pattern, REGEX_CASELESS | REGEX_MULTI_LINE);
138          *      ret = regex.Match(text, false);         // This returns true value
139          *
140          * @endcode
141          */
142         result Construct(const Tizen::Base::String& pattern, unsigned long options = 0x0);
143
144         /**
145          * Checks whether the specified text matches completely or partially.
146          *
147          * @since 2.0
148          *
149          * @return                      @c true if the text matches successfully, @n
150          *                                      else @c false
151          * @param[in]           text  The text to match
152          * @param[in]           fullMatch               Set to @c true to match exactly, @n
153          *                                                              else @c false to match any substring of the text
154          * @param[out]          pMatchedString  A list of the matched string instances @n
155                                         The count of the matched items is acquired from IList::GetCount() and
156          *                                      the maximum count of the items is @c 16.
157          * @exception           E_SUCCESS                       The method is successful.
158          * @exception           E_INVALID_STATE         This instance has not been constructed as yet.
159          * @exception           E_INVALID_ARG           The length of the specified @c text parameter is @c 0.
160          * @remarks                     The specific error code can be accessed using the GetLastResult() method.       
161          * @remarks                     If the grouping subpatterns are used in a pattern,
162          *                              the @c pMatchedString list will contain the grouping data. @n
163          *                                      For example, if the pattern has two grouping subpatterns,
164          *                              there will be three data sets in the @c pMatchedString list. @n
165          *                                      The first data set will be a full grouping data and the second
166          *                              and the third data sets will contain individual grouping data.
167          *
168          * The following example demonstrates how to use the %Match() method.
169          *
170          * @code
171          *
172          *      bool ret = false;
173          *
174          *      String pattern(L"(\\d\\d)-(\\d\\d)-(\\d\\d\\d\\d)");
175          *      String text(L"04-12-1979");
176          *      String out;
177          *
178          *      RegularExpression regex;
179          *      regex.Construct(pattern);
180          *
181          *      ArrayList list;
182          *      list.Construct();
183          *
184          *      // Match
185          *      ret = regex.Match(text, true, &list);           // The list will contain four string instances
186          *
187          *      out = *(String *)list.GetAt(0);         //  L"04-12-1979"
188          *      out = *(String *)list.GetAt(1);         //  L"04"
189          *      out = *(String *)list.GetAt(2);         //  L"12"
190          *      out = *(String *)list.GetAt(3);         //  L"1979"
191          *
192          *      list.RemoveAll(true);
193          * @endcode
194          */
195         bool Match(const Tizen::Base::String& text, bool fullMatch, Tizen::Base::Collection::IList* pMatchedString = null) const;
196
197         /**
198          * Matches the pattern from the starting point of the text and removes the matched string. @n
199          * If the pattern does not match the text at the starting point, it will return @c false.
200          *
201          * @since 2.0
202          *
203          * @return                      @c true if the text matches successfully, @n
204          *                                      else @c false
205          * @param[in, out]  text  The text to consume
206          * @param[out]      pMatchedString      A list of matched string instances  @n
207          *                                 The count of the matched items is acquired from IList::GetCount() and
208          *                                                                 the maximum count of the items is @c 16.
209          * @exception           E_SUCCESS                       The method is successful.
210          * @exception           E_INVALID_STATE         This instance has not been constructed as yet.
211          * @exception           E_INVALID_ARG           The length of the specified @c text parameter is @c 0.
212          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
213          * @remarks                     If the grouping subpatterns are used in a pattern, the @c pMatchedString list will
214          *                              contain the grouping data. @n
215          *                                      For example, if the pattern has two grouping subpatterns,
216          *                              there will be three data sets in the @c pMatchedString list. @n
217          *                                      The first data set will be a full grouping data and the second
218          *                              and the third data sets will contain individual grouping data.
219
220          *
221          * The following example demonstrates how to use the %Consume() method.
222          * @code
223          *
224          *      bool ret = false;
225          *      String out;
226          *
227          *      String pattern(L"(\\s+)([a-z]+)(\\d+)");
228          *      String text(L"    abcd1234test");
229          *      ArrayList list;
230          *      list.Construct();
231          *
232          *      RegularExpression regex;
233          *      regex.Construct(pattern);
234          *      ret = regex.Consume(text, &list);               // The list will contain four string instances
235          *                                                                      // and the text instance will be changed to L"test"
236          *      out = *(String *)list.GetAt(0);         //  L"    abcd1234"
237          *      out = *(String *)list.GetAt(1);         //  L"    "
238          *      out = *(String *)list.GetAt(2);         //  L"abcd"
239          *      out = *(String *)list.GetAt(3);         //  L"1234"
240          *
241          *      list.RemoveAll(true);
242          * @endcode
243          */
244         bool Consume(Tizen::Base::String& text, Tizen::Base::Collection::IList* pMatchedString = null) const;
245
246         /**
247          * Matches the pattern in strings similar to the Consume() method but does not anchor the match at the beginning of the string. @n
248          * This operation can be used to find certain patterns in the text and extract the required information.
249          *
250          * @since 2.0
251          *
252          * @return                      @c true if the text matches successfully, @n
253          *                                      else @c false
254          * @param[in, out]      text  The text to find and consume
255          * @param[out]          pMatchedString  A list of matched string instances @n
256          *                  The count of the matched items is acquired from IList::GetCount() and
257          *                                              the maximum count of the items is @c 16.
258          * @exception           E_SUCCESS                       The method is successful.
259          * @exception           E_INVALID_STATE         This instance has not been constructed as yet.
260          * @exception           E_INVALID_ARG           The length of the specified @c text parameter is @c 0.
261          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
262          * @remarks                     If the grouping subpatterns are used in a pattern,
263          *                              the @c pMatchedString list will contain the grouping data. @n
264          *                                      For example, if the pattern has two grouping subpatterns,
265          *                              there will be three data sets in the @c pMatchedString list. @n
266          *                                      The first data set will be a full grouping data and the second
267          *                              and the third data sets will contain individual grouping data.
268          *
269          * The following example demonstrates how to use the %FindAndConsume() method.
270          *
271          * @code
272          *
273          *      bool ret = false;
274          *      String out;
275          *
276          *      String pattern(L"(\\s+)([a-z]+)(\\d+)");
277          *      String text(L"test    abcd1234test");
278          *      ArrayList list;
279          *      list.Construct();
280          *
281          *      RegularExpression regex;
282          *      regex.Construct(pattern);
283          *      ret = regex.FindAndConsume(text, &list);                // The list will contain four String instances
284          *                                                                      // and text instance will be changed to  L"test"
285          *      out = *(String *)list.GetAt(0);         //  L"    abcd1234"
286          *      out = *(String *)list.GetAt(1);         //  L"    "
287          *      out = *(String *)list.GetAt(2);         //  L"abcd"
288          *      out = *(String *)list.GetAt(3);         //  L"1234"
289          *
290          *      list.RemoveAll(true);
291          * @endcode
292          */
293         bool FindAndConsume(Tizen::Base::String& text, Tizen::Base::Collection::IList* pMatchedString = null) const;
294
295         /**
296          * Replaces either the first match of a pattern in the text with the @c rewrite string or
297          * all the occurrences of a pattern in the text.
298          *
299          * @since 2.0
300          *
301          * @return                      @c true if the text is replaced successfully, @n
302          *                                      else @c false
303          * @param[in, out]      text  The text to replace when it is matched to a pattern
304          * @param[in]           rewrite         The text with which to replace
305          * @param[in]           globalReplace   Set to @c true to replace globally, @n
306          *                                                                  else @c false to replace the first match of the pattern in the text
307          * @param[in]           startPos       The starting position of the text
308          * @exception           E_SUCCESS                       The method is successful.
309          * @exception           E_INVALID_STATE         This instance has not been constructed as yet.
310          * @exception           E_INVALID_ARG           The length of the specified @c pattern parameter is @c 0, or
311          *                                                                              the size of @c pMatchedString exceeds limitations.
312          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
313          *
314          * The following example demonstrates how to use the %Replace() method.
315          *
316          * @code
317          *
318          *      bool ret = false;
319          *
320          *      String pattern(L"replace");
321          *      String text(L"test replace method");
322          *      String rewrite(L"REPLACE");
323          *
324          *      RegularExpression regex;
325          *      regex.Construct(pattern);
326          *      ret = regex.Replace(text, rewrite, false);              // text = L"test REPLACE method"
327          *
328          * @endcode
329          */
330         bool Replace(Tizen::Base::String& text, const Tizen::Base::String& rewrite, bool globalReplace, int startPos = 0) const;
331
332         /**
333          * Extracts the first match of the pattern in the text. @n
334          * Similar to Replace() but @c rewrite is copied to @c out with substitutions.
335          *
336          * @since 2.0
337          *
338          * @return                      @c true if the text is extracted successfully, @n
339          *                                      else @c false
340          * @param[in]           text     The text to match
341          * @param[in]           rewrite  The text to replace
342          * @param[out]          out      The text to extract
343          * @exception           E_SUCCESS                       The method is successful.
344          * @exception           E_INVALID_STATE         This instance has not been constructed as yet.
345          * @exception           E_INVALID_ARG           The length of the specified @c pattern parameter is @c 0, or
346          *                                                                              the size of @c pMatchedString exceeds limitations.
347          * @remarks                The specific error code can be accessed using the GetLastResult() method.
348          *
349          * The following example demonstrates how to use the %Extract() method.
350          *
351          * @code
352          *
353          *      bool ret = false;
354          *      String out;
355          *
356          *      String pattern(L"(.*)@([^.]*)");
357          *      String text(L"test@email.com");
358          *      String rewrite(L"\\2!\\1");
359          *
360          *      RegularExpression regex;
361          *      regex.Construct(pattern);
362          *      ret = regex.Extract(text, rewrite, out);                // out = L"email!test"
363          *
364          * @endcode
365          */
366         bool Extract(const Tizen::Base::String& text, const Tizen::Base::String& rewrite, Tizen::Base::String& out) const;
367
368         /**
369          * Compares the specified instance to the calling instance.
370          *
371          * @since 2.0
372          *
373          * @return              @c true if the specified instance is equal to the current instance, @n
374          *                              else @c false
375          * @param[in]   obj     The object to compare with the current instance
376          * @remarks     This method returns @c true if all the attributes in the instance are the same.
377          */
378         virtual bool Equals(const Tizen::Base::Object& obj) const;
379
380         /**
381          * Gets the hash value of the current instance.
382          *
383          * @since 2.0
384          *
385          * @return              The hash value of the current instance
386          */
387         virtual int GetHashCode(void) const;
388
389         /**
390         * Gets the pattern used to compile the regular expression.
391         *
392         * @since 2.0
393         *
394         * @return       The pattern used to compile the regular expression @n An empty string if this instance is not initialized
395         */
396         Tizen::Base::String GetPattern(void) const;
397
398
399         /**
400          * Sets the value of the regular expression options.
401          *
402          * @since 2.0
403          *
404          * @param[in]           options          The logical OR operator values of RegularExpressionOptions
405          * @exception           E_SUCCESS                       The method is successful.
406          * @exception           E_INVALID_ARG           The value of @c options is invalid.
407          */
408         result SetOptions(unsigned long options);
409
410
411         /**
412          * Gets the value of the regular expression options.
413          *
414          * @since 2.0
415          *
416          * @return                      The logical OR operator values of RegularExpressionOptions
417          */
418         unsigned long GetOptions(void) const;
419
420 private:
421         /**
422          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
423          *
424          * @param [in]          regularExpression               The instance of the %RegularExpression class to copy from
425          * @remarks                     This constructor is hidden.
426          */
427         RegularExpression(const RegularExpression& regularExpression);
428
429         /**
430          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
431          *
432          * @param [in]          regularExpression               An instance of %RegularExpression
433          * @remarks                     This operator is hidden.
434          */
435         RegularExpression& operator =(const RegularExpression& regularExpression);
436
437
438         friend class _RegularExpressionImpl;
439         class _RegularExpressionImpl* __pRegularExpressionImpl;
440
441 }; // RegularExpression
442
443 }}} // Tizen::Base::Utility
444
445 #endif // _FBASE_UTIL_REGULAR_EXPRESSION_H_