inc/FBaseUtilRegularExpression.h

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