Instance Method

enumerateSubstringsInRange:options:usingBlock:

Enumerates the substrings of the specified type in the specified range of the string.

Declaration

- (void)enumerateSubstringsInRange:(NSRange)range options:(NSStringEnumerationOptions)opts usingBlock:(void (^)(NSString *substring, NSRange substringRange, NSRange enclosingRange, BOOL *stop))block;

Parameters

range

The range within the string to enumerate substrings.

opts

Options specifying types of substrings and enumeration styles.

block

The block executed for the enumeration.

The block takes four arguments:

substring

The enumerated string.

substringRange

The range of the enumerated string in the receiver.

enclosingRange

The range that includes the substring as well as any separator or filler characters that follow. For instance, for lines, enclosingRange contains the line terminators. The enclosingRange for the first string enumerated also contains any characters that occur before the string. Consecutive enclosing ranges are guaranteed not to overlap, and every single character in the enumerated range is included in one and only one enclosing range.

stop

A reference to a Boolean value that the block can use to stop the enumeration by setting *stop = YES; it should not touch *stop otherwise.

Discussion

If this method is sent to an instance of NSMutableString, mutation (deletion, addition, or change) is allowed, as long as it is within enclosingRange. After a mutation, the enumeration continues with the range immediately following the processed range, after the length of the processed range is adjusted for the mutation. (The enumerator assumes any change in length occurs in the specified range.)

For example, if the block is called with a range starting at location N, and the block deletes all the characters in the supplied range, the next call will also pass N as the index of the range. This is the case even if mutation of the previous range changes the string in such a way that the following substring would have extended to include the already enumerated range. For example, if the string "Hello World" is enumerated via words, and the block changes "Hello " to "Hello", thus forming "HelloWorld", the next enumeration will return "World" rather than "HelloWorld".

See Also

Finding Characters and Substrings

- containsString:

Returns a Boolean value indicating whether the string contains a given string by performing a case-sensitive, locale-unaware search.

- localizedCaseInsensitiveContainsString:

Returns a Boolean value indicating whether the string contains a given string by performing a case-insensitive, locale-aware search.

- localizedStandardContainsString:

Returns a Boolean value indicating whether the string contains a given string by performing a case and diacritic insensitive, locale-aware search.

- rangeOfCharacterFromSet:

Finds and returns the range in the string of the first character from a given character set.

- rangeOfCharacterFromSet:options:

Finds and returns the range in the string of the first character, using given options, from a given character set.

- rangeOfCharacterFromSet:options:range:

Finds and returns the range in the string of the first character from a given character set found in a given range with given options.

- rangeOfString:

Finds and returns the range of the first occurrence of a given string within the string.

- rangeOfString:options:

Finds and returns the range of the first occurrence of a given string within the string, subject to given options.

- rangeOfString:options:range:

Finds and returns the range of the first occurrence of a given string, within the given range of the string, subject to given options.

- rangeOfString:options:range:locale:

Finds and returns the range of the first occurrence of a given string within a given range of the string, subject to given options, using the specified locale, if any.

- localizedStandardRangeOfString:

Finds and returns the range of the first occurrence of a given string within the string by performing a case and diacritic insensitive, locale-aware search.

- enumerateLinesUsingBlock:

Enumerates all the lines in the string.