RKRegex Class Reference

The RKRegex class declares the programmatic interface for the RKRegex framework to the PCRE regular expression pattern matching library.

Some of the noteworthy features provided by the RKRegex class are:

• Multithreading safe.
• The PCRE compiled regular expression is cached. See RKCache for more information.
• Makes extensive use of the stack for temporary results, avoiding expensive and time consuming memory allocations.

The RKRegex class provides the low level primitives necessary to perform regular expression matching. The matching functions perform their work on raw byte buffers and provide match results in the form of NSRange structures containing the range of a match and the range of any matching subpatterns of a regular expression.

In addition to the low level matching primitives, the RKRegex class provides information about the underlying PCRE library, such as the version with the method PCREVersionString and PCRE compile time options via PCREBuildConfig. Various methods for obtaining information about the instantiated RKRegex compiled regular expression named capture subpatterns, if any, are provided.

In general, the RKRegex class is not used by end-user applications directly. Since the RKRegex class only provides low level primitives, end-user functionality is provided via various category extensions to common Foundation objects, such as the RegexKit framework additions to NSArray, NSDictionary, NSSet, NSString, and their mutable variants. Match enumeration is provided by the RKEnumerator class.

Unicode Support

Unicode strings are fully supported by RegexKit, both in the regular expression pattern and the string to search.

Foundation Additions RKCompileOption Requirements

The Foundation additions use Unicode strings exclusively for the buffer that RKRegex performs matches against. If a NSString has an encoding format other than ASCII, it is first converted to UTF8 before any matching can occur. Because of this, RKRegex objects must have the RKCompileOption flags RKCompileUTF8 and RKCompileNoUTF8Check set. Bytes with the most significant bit set in UTF8 encoded strings have special meaning that must be interpreted. Without these options set, PCRE treats the buffer as a collection of 8 bit bytes without the required UTF8 decoding.

The various Foundation additions will accept either a RKRegex or a NSString for the regex argument. If the supplied object is a NSString, it is automatically converted to a RKRegex object via the regexWithRegexString:options: method with an option argument of (RKCompileUTF8 | RKCompileNoUTF8Check).

If you are supplying an instantiated RKRegex object instead of using the NSString auto-compile functionality, the RKCompileOption options RKCompileUTF8 and RKCompileNoUTF8Check must be set.

Important NSRange Differences

For the purposes of calculating character indexes, Foundation treats all strings as if they were UTF16 encoded. PCRE, on the other hand, uses UTF8 exclusively. This has important consequences when using strings that are encoded in anything but ASCII. It is important to understand that all of the Foundation additions, and the RKEnumerator class, calculate all character index values as UTF16 character indexes. Since PCRE can only operate on UTF8 encoded strings, this requires any NSRange values to be converted between the two character index spaces. This provides transparent interoperability with the rest of Foundation at the expense of having to perform the character index conversation.

However, the RKRegex methods use UTF8 character indexes for all NSRange values. This is an important distinction as NSRange values returned by RKRegex objects will result in undefined behavior if passed to NSString objects without converting to the equivalent UTF16 character indexes. The functions RKConvertUTF8ToUTF16RangeForString and RKConvertUTF16ToUTF8RangeForString can be used to perform the necessary conversions, if required.

The reasoning behind this is that the RKRegex class provides low level access to the PCRE engine. The Foundation additions provide abstracted access to the underlying pattern matching engine. There are still many useful tasks that can be performed with low-level access, such as not enabling RKCompileUTF8 and matching raw binary byte buffers. Therefore, the RKRegex class tries to provide unadulterated access to the PCRE matching engine or those users who have special requirements.

NSCoding Support

The RKRegex class fully supports the NSCoding protocol. When a RKRegex is archived, the regular expression string used to create the receiver is coded, along with any RKCompileOption options. In addition to these two main items, the version and RKBuildConfig flags are also encoded to aid in debugging any unarchiving issues.

If problems are encountered when attempting to initialize a coded RKRegex regular expression, a NSInvalidUnarchiveOperationException is raised. The userInfo portion of the exception contains additional information regarding the failed attempt. Some of the additional information includes any difference in the archiving RKRegex PCRE version, any unknown or unsupported RKCompileOption flags for the current RegexKit, and any differences in RKBuildConfig flags.