NSString RegexKit Additions Reference

NSRange Compatibility with Foundation

As of version 0.4, all NSRange arguments and results of the RegexKit NSString additions and RKEnumerator class use the same method as Foundation for calculating character index values. Specifically, Foundation treats all strings as if they were UTF16 encoded, whereas PCRE requires all strings to be UTF8 encoded. The details of converting between UTF8 and UTF16 character index values, and therefore NSRange values, are now handled automatically by the framework, providing a consistant UTF16 character index API for all Foundation additions and RKEnumerator class objects.

For UTF8 encoded strings, only character values < 128 / 0x80 can be represented with a single byte, which is a one to one mapping to ASCII characters. To represent non-ASCII characters, UTF8 uses a special encoding format that uses a variable number of additional bytes, from one to five, to represent a single Unicode character. Therefore, when dealing with international text, there is no longer a one to one relationship between a 'character' and a byte as there is in ASCII text.

UTF16 encoded strings use two bytes as its fundamental date type. The vast majority of text can be encoded in to a single UTF16 character, but some character encodings will require two or more UTF16 characters to represent a single Unicode character. Only UTF32 has a fixed length at four bytes, which simplifies 'character index' issues, but is not space efficient for the majority of text. Even ASCII requires four bytes to encode one character in UTF32, of which there are only 127 possible ASCII characters.

As of version 0.4, these issues are now abstracted by the framework. All strings are treated logically as if they were encoded as UTF16 for NSRange calculation purposes. Previous versions calculated NSRange values based on PCRE's native UTF8 encoding format. This meant that NSRange results from RegexKit could be used as arguments by another RegexKit method correctly for international text, but could not be used as arguments for native Foundation methods and vice-versa. In short, NSRange results and arguments should 'just work' as expected with NSRange results from native Foundation methods.

Reference and Replacement String Syntax

Several methods are available that allow you to create new strings, or replace the matched text, with a string that contains references to the capture subpatterns. The syntax is modeled after Perls dollar sign variable references, i.e. $1. In addition to capture subpattern references, you can also covert the case of the text. Case conversion is also modeled after Perls \u, \l, \U, \L, and \E escape sequences.

Capture Subpattern Reference Syntax

Capture subpattern references have the following three forms:

Or,

Or,

Order of Format Specifier Argument Substitution and Expansion of Capture Subpattern Match References

In order to prevent the accidental interpretation of the expanded text of a capture subpattern match reference as a format specifier, the order of substitution and expansion is as follows:

• First, the referenceFormatString format specifiers are substituted with the variable length arguments.
• Second, the capture subpattern references are expanded and replaced.

Expansion of Capture Subpattern Match References in Strings

When a capture subpattern reference is expanded in a string, the text of the capture subpattern reference is replaced with the text of the subpattern that was matched by the regular expression.

Preventing the interpretation of $

To include a $ from the reference string in the final replacement text without the possibility of additional interpretation, you may specify two dollar signs consecutively. Only a single dollar sign will be copied to the final expanded text. For example: You owe: $$1234.56 will be copied as You owe: $1234.56. Another example: Does not reference the $${0} capture subpattern is copied as Does not reference the ${0} capture subpattern.

Case Conversion Syntax

The following escape sequences allow you to convert the text in the reference and replacement string. The NSString uppercaseString and lowercaseString methods are used to perform the actual case conversion.

The following is the example given in Apples NSString lowercaseString method documentation, modified to illustrate the case conversion escape sequences. As the example given in apples documentation illustrates, Unicode case conversion is not necessarily symmetrical.

The following example uses a regular expression that matches all the characters between a and e to replace the matched text with \U$1\E.

The same regular expression is used in the following example, but the replacement reference string is now \u$1. The \u escape sequences causes the next character to be converted to uppercase, and in this case ß is converted to SS. The result string, StraSSe, has the same regular expression applied to it and the replacement reference string is changed to \l$1, which converts the next character to lower case. The final result is StrasSe.

Capture Subpattern Reference and Type Conversion Syntax

Capture subpattern references and type conversions extend regular capture subpattern references by allowing an optional type argument:

Or,

Or,

Conversion Type Syntax

There are two major classes of conversion types:

• Conversions to basic C data types, such as int.
• Conversions to Objective-C objects, such as NSNumber or NSCalendarDate.

The first form, conversion to basic C data types, uses the familiar percent (character '%') style specification. For example, %d converts the string "12345" to an int with the value of 12345.

The second form uses an at sign (character '@') to specify conversion to an Objective-C object. The rest of the conversion specification, such as what type to convert to and conversion options, is similar to the percent style conversion syntax.

C Data Type Conversions

Conversions to basic C data types are handled by the scanf standard library function. If the first character of the conversion specification begins with a % (percent), then the remaining text up to the end of the conversion is passed to scanf unaltered. Any conversion types or conversion options supported by the libraries scanf are available.

Since the conversion specification is passed unaltered to scanf, care should be taken to ensure that only a single conversion is specified. Requesting two or more conversions will result in a crash since the framework will only supply scanf a single valid pointer in which to store the conversion result. It is also not safe to specify a different pointer argument position using the %n$ syntax.

The following table lists some of the common percent C data type conversion specifiers. Consult the scanf man page for additional information.

On Mac OS X the floating point conversions will actually accept and convert a wide variety of string formats. For example, hex values such as 0x1234abcd will be correctly converted to 305441741.0 for the requested floating point type. Even signed hex values, such as -0xfedc9876 are correctly converted. Additionally, C99 style hex floats, such as 0x3.fe69149f758p+45, are also correctly converted.

Objective-C Object Conversions

Ownership of objects returned by a conversion is the same as ownership of other convenience methods such as [NSString stringWithFormat:]. Specifically, they have been sent a autorelease message and they do not require any additional release messages.

However, if you require use of a converted object past the current NSAutoreleasePool context, you must take ownership of it by sending a retain message.

Conversions to NSNumber

NSNumber object conversions are specified with @n and the conversions are performed with a thread private NSNumberFormatter. A threads NSNumberFormatter is created when the first NSNumber conversion is requested and is released when the thread exits.

The different types of NSNumberFormatterStyle are made available using certain option characters. For example, the NSNumberFormatterCurrencyStyle is specified as @$n.

Conversion to NSCalendarDate

NSCalendarDate object conversions are specified with @d and the conversions are performed with the NSDate class method dateWithNaturalLanguageString:. Since the conversions are performed by a class method, conversions are serialized with a lock to ensure correct multithreading behavior.

Specifying a Regular Expression

When specifying a regular expression, the regular expression can be either a RKRegex object or a NSString containing the text of a regular expression. When specified as a NSString, as determined by sending isKindOfClass:, the receiver will convert the string to a RKRegex object via regexWithRegexString:options:.

Determining if an Object Matches a Regular Expression

Objects are sent isMatchedByRegex: to determine whether or not they are matched by the specified regular expression.