RKEnumerator Class Reference
PCRE7.6
AvailabilityAvailable in Mac OS X v10.4 or later.
Overview
The RKEnumerator class enables you to enumerate each successive match of a regular expression over a NSString, and optionally confined to a specific range of the NSString.
Important:
Modifying a NSMutableString while it is being enumerated is not supported and will result in undefined behavior.
An instantiated RKEnumerator records the NSRange for the current match of a regular expression, along with all the ranges for each capture subpattern of a regular expression. This is done by creating a private buffer that is sizeof(NSRange) * [regex captureCount] bytes large and invoking getRanges:withCharacters:length:inRange:options: to obtain the matches range information. The inRange parameter for each successive call is set the location of the last character of the previous match, or the start of the requested enumeration range for the first match.
Note:
The RKEnumerator class is currently only capable of enumerating the matches of a NSString class object.
The RKEnumerator class provides a number of methods to make use of the current match result. Some of these include:
- Obtaining the range of the current match, or the range of a particular capture subpattern.
- Extracting a capture subpattern from the current match, or type converting a capture subpattern.
- Creating a new string with capture subpattern references to the current match.
When all of the matches have been exhausted, the instantiated RKEnumerator sends a release to the NSString and RKRegex used for matching. Like a NSEnumerator, once all of the matches have been enumerated, the enumerator can not be reset. A new RKEnumerator is required to enumerate the matches again.
Advancing to the Next Match
RKEnumerator Match Advancement Methods
| Method | Returns | Returns When Exhausted | Speed | Description |
|---|
| nextObject | NSArray * | NULL | Slowest | Creates a NSArray of NSValue objects containing a NSRange of the match range of the next enumeration for each capture subpattern. |
| nextRange | NSRange | {NSNotFound, 0} | Fast | Returns the entire range of the next enumeration that was matched by the regular expression. |
| nextRangeForCapture: | NSRange | {NSNotFound, 0} | Medium | Returns the matching range of the next enumeration for a particular capture subpattern. |
| nextRangeForCaptureName: | NSRange | {NSNotFound, 0} | Slow | Returns the matching range of the next enumeration for a particular named capture subpattern. |
| nextRanges | NSRange * | NULL | Fastest | Updates the objects private buffer of NSRange structures with the results of the next enumeration and then returns a pointer to the buffer. |
The standard NSEnumerator method nextObject incurs a substantial amount of overhead in the creation of NSValue objects to contain the NSRange results for each capture subpattern, and then storing those in a NSArray. The result is quite flexible, and can easily be stored in various collection objects without any additional work. However, if you don't require this flexibility, it is recommended that you use one of the other methods, such as nextRanges, which do not create any intermediate objects to advance to the next match.
The nextRanges method returns a pointer to the RKEnumerator objects private buffer of an array of NSRange structures. Repeated calls to nextRanges will return the same address, only the data at the pointer location is updated. See the documentation for nextRanges for important information regarding this and other data lifetime issues when using this method. This method offers the highest performance and can be safely used as the conditional test in a while loop, for example:
while([anEnumerator nextRanges] != NULL) {
// Do something with the current match results of anEnumerator
NSRange matchRange = [anEnumerator currentRange];
}
It is important to note that the public API for the RKEnumerator class returns and accepts character index values for strings, and therefore the location and length for NSRange values, as if they were calculated as UTF16 characters. This is the same method that is used by Foundation natively and therefore no coversions between UTF16 and other string encodings, such as UTF8 need to be performed.
Additional details can be found in the NSString RegexKit Additions Reference and RKRegex Class Reference.
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.
Tasks
Class Methods
Convenience method that returns an autoreleased RKEnumerator object initialized with the regular expression regex starting at location 0 of string.
+ (id)enumeratorWithRegex:(id)aRegex string:(NSString * const)string;
Convenience method that returns an autoreleased RKEnumerator object initialized with the regular expression regex that will enumerate that matches of string within range.
+ (id)enumeratorWithRegex:(id)aRegex string:(NSString * const)string inRange:(const NSRange)range;
Convenience method that returns an autoreleased RKEnumerator object initialized with the regular expression regex that will enumerate that matches of string within range.
+ (id)enumeratorWithRegex:(id)initRegex string:(NSString * const)initString inRange:(const NSRange)initRange error:(NSError **)error;
Instance Methods
Returns the range of the current match.
- (NSRange)currentRange;
Returns {NSNotFound, 0} if receiver has enumerated all the matches.
Returns the range of the current match for capture subpattern capture.
- (NSRange)currentRangeForCapture:(const
RKUInteger)capture;
Returns {NSNotFound, 0} if receiver has enumerated all the matches.
Returns the range of the current match for named capture subpattern captureNameString.
- (NSRange)currentRangeForCaptureName:(NSString * const)captureNameString;
Returns {NSNotFound, 0} if receiver has enumerated all the matches.
Returns a pointer to an array of NSRange structures corresponding the the capture subpatterns of the receivers regular expression for the current match.
- (NSRange *)currentRanges;
Returns a pointer to an array of NSRange structures containing the current match results returned by getRanges:withCharacters:length:inRange:options:.
Important:
For speed and efficiency, the pointer returned is the receivers private buffer of
NSRange results which must not be modified, retained, or released by the caller. The pointer returned by successive invocations of
currentRanges will be identical, however the information at the results location will be updated when the receiver is advanced to the next match with the new match results.
Since the buffer returned by currentRanges is overwritten with the results of the next match, the caller must not use a pointer to the results once the receiver has advanced to the next match. If a range result is required after the receiver has advanced to the next result, the caller must make a private copy of any required results.
Returns a pointer to an array of
NSRange structures that contains
[receiversRegex captureCount] elements corresponding the the capture subpatterns of the receivers regular expression. If all of the match results have been enumerated,
NULL is returned.
Takes a variable length list of capture subpattern reference and pointer to a pointer type conversion specification pairs and applies them to the receivers current match enumeration.
- (BOOL)getCapturesWithReferences:(NSString * const)firstReference, ... ;
-
firstReference
The first capture subpattern type conversion reference.
-
...
First the pointer to a pointer for firstReference, then a comma-separated list of capture subpattern reference and pointer to a pointer type conversion specification pairs, terminated with a nil.
Warning:
Failure to terminate the argument list with a nil will result in a crash.
This method is similar to getCapturesWithRegexAndReferences: except that instead of extracting the capture subpatterns of the first match of a regular expression, this method extracts the capture subpatterns of the current match enumeration of the receiver.
See Capture Subpattern Reference and Type Conversion Syntax for information on how to specify capture subpatterns and the different types of conversions that can be performed on the matched text. If the optional type conversion is not specified then the default conversion to a NSString containing the text of the requested capture subpattern will be returned via pointer to a pointer.
Returns YES if the receiver successfully converted the requested capture subpatterns, NO otherwise.
Returns a RKEnumerator object initialized with the regular expression initRegex starting at location 0 of initString.
- (id)initWithRegex:(id)initRegex string:(NSString * const)initString;
Returns a RKEnumerator object if successful, nil otherwise.
Returns a RKEnumerator object initialized with the regular expression initRegex that will enumerate that matches of initString within initRange.
- (id)initWithRegex:(id)initRegex string:(NSString * const)initString inRange:(const NSRange)initRange;
Returns a RKEnumerator object if successful, nil otherwise.
Returns a RKEnumerator object initialized with the regular expression initRegex that will enumerate that matches of initString within initRange.
- (id)initWithRegex:(id)initRegex string:(NSString * const)initString inRange:(const NSRange)initRange error:(NSError **)error;
-
initRegex
A regular expression string or
RKRegex object.
-
initString
A NSString to scan and return matches by initRegex.
-
initRange
The range of initString to enumerate matches.
-
error
An optional parameter that if set and an error occurs, will contain a NSError object that describes the problem. This may be set to NULL if information about any errors is not required.
Returns a RKEnumerator object if successful, nil otherwise.
Advances to the next match of the receivers regular expression and returns a NSArray of NSValue set to the range of the match for each of the receivers capture subpatterns.
- (id)nextObject;
Returns NULL if there are no additional matches.
Advances to the next match of the receivers regular expression and returns the range of the entire match.
- (NSRange)nextRange;
Returns {NSNotFound, 0} if there are no additional matches.
Advances to the next match of the receivers regular expression and returns the range of the match for capture subpattern capture.
- (NSRange)nextRangeForCapture:(const
RKUInteger)capture;
Returns {NSNotFound, 0} if there are no additional matches.
Advances to the next match of the receivers regular expression and returns the range of the match for named capture subpattern captureNameString.
- (NSRange)nextRangeForCaptureName:(NSString * const)captureNameString;
Returns {NSNotFound, 0} if there are no additional matches.
Advances to the next match of the receivers regular expression and returns a pointer to an array of NSRange structures corresponding the the capture subpatterns of the receivers regular expression.
- (NSRange *)nextRanges;
This method only updates the receivers internal state with the ranges for next consecutive match of the receivers regular expression, if any. This is the preferred means of iterating matches when methods such as stringWithReferenceString: or stringWithReferenceFormat: are to be used with the results of a match since no extraneous objects are created or memory allocated as a result.
Important:
See
currentRanges for information regarding the array of results returned.
Returns NULL if there are no additional matches.
Returns the
RKRegex regular expression used to create receiver.
Returns the string to enumerate matches from that was used to create receiver.
- (NSString *)string;
(brief description)
- (NSString *)stringWithReferenceFormat:(NSString * const)referenceFormatString, ...;
-
referenceFormatString
(description)
(comprehensive description)
(description)
(brief description)
- (NSString *)stringWithReferenceFormat:(NSString * const)referenceFormatString arguments:(va_list)argList;
(comprehensive description)
(description)
Returns a new NSString containing the results of expanding the capture subpatterns in referenceString with the current match results.
- (NSString *)stringWithReferenceString:(NSString * const)referenceString;
-
referenceString
(description)
(comprehensive description)
(description)