NSString(StringRegex)


Addition of regular expressions operations to the NSString class

Extends Class: NSString
Declared In: StringRegex.h

Discussion

This category adds regular expressions to strings, similar to the functionality built into languages like Perl and Python. It uses version 7.4 of the Perl-Compatible Regular Expressions library as the engine, and an adapted version of the AGRegex framework as an Objective-C wrapper.



Methods

-allCaptures:
-captures:
-matches:
-replace:with:
-replace:withBlock:
-split:

allCaptures:


- (NSArray*) allCaptures:(NSString*)pattern; 
Discussion

Returns all the captures of the specified pattern in the string. Each element of the array is an FSRegexMatch object; these objects can be queried for specific captured subpatterns. If you know that the pattern will only match once, and you are not using named subpatterns, the method captures: will be more convenient


captures:


- (NSArray*) captures:(NSString*)pattern; 
Discussion

Returns an array of subpattern matches from the first match of the pattern in the string. The entire matched portion will be the first element in the array. Using this method, the following Perl code:

$string =~ /(\d+) +(\w+)/);
my $word = $1;
my $number = $2;


can be reproduced in F-Script as the following:

subpatterns := string captures:'(\\d+) +(\\w+)'.
word := subpatterns at:1.
number := subpatterns at:2.


Any subpatterns that were not captured (such as groupings made optional with the ? modifier) will be returned as empty strings in the array. If the string did not match the pattern at all, this method will return nil.

If you want to find all the matches of the pattern in the string, or need to access named subpatterns, use the allMatches: method instead.


matches:


- (FSBoolean*) matches:(NSString*)pattern; 
Discussion

Returns true if the receiver matches the supplied regular expression. The Perl code

$string = ".....";
if ($string =~ /pattern/) {
 ....
}


can be expressed in F-Script as:

string := '.....'.
(string matches:'pattern') ifTrue:[
 ....
].


replace:with:


- (NSString*) replace:(NSString*)pattern with:(NSString*)replacementString; 
Discussion

Replaces all occurrences of pattern in the receiver with replacementString. Subpatterns captured with parentheses are available using the notation $1, $2, etc. ($0 refers to the entire match). Python-style named captures are also available. For more information, see the PCRE documentation.

The Perl code string =~ s/pa(tt)ern/replacement$1/g; can be expressed in F-Script as: string := string replace:'pa(tt)ern' with:'replacement$1'.. The assignment is necessary because the original string is not directly modified, as it is in Perl.


replace:withBlock:


- (NSString*) replace:(NSString*)pattern withBlock:(Block*)block; 
Discussion

Similar to the s///x replacement operator in Perl, this method executes an F-Script block for every match of the pattern in the receiver, supplying the match and subpatterns to the block as arguments. The first argument is the entire match, and subpatterns are passed as the subsequent arguments. If the block does not accept the same number of arguments as there are subpatterns in the regular expression, the F-Script intepreter will throw an exception.

The entire match is the original string is then replaced with the return value of the block. The return value does not have to be an NSString; if another object (such as an NSNumber) is returned, the description method will be used to obtain a string value to use as a replacement.

The following code will replace all pairs of integers separated with a plus sign in a string with their sums:

string := '12+13, 45+2, 10 + 200'.
string := string replace:'(\\d+)\\s*\\+\\s*(\\d+)' withBlock:[ :group :pat1 :pat2 | pat1 intValue + pat2 intValue ].
"string is now '25, 47, 210'"


split:


- (NSArray*) split:(NSString*)pattern;
Discussion

Like the split function in Perl, this method separates a string into components, using a regular expression to identify the separators (instead of a plain string, as the NSString method componentsSeparatedByString: does). Returns an array containing the components.

© Andrew Weinrich Last Updated: Wednesday, October 15, 2008