CFStringFind

Header: CFString.h Carbon status: Supported

Searches for a substring within a CFString object and, if it is found, yields the range of the substring within the object's characters.

CFRange CFStringFind (
    CFStringRef theString, 
    CFStringRef stringToFind, 
    CFOptionFlags compareOptions
);
Parameter descriptions
theString

Pass a reference to the CFString object to be searched.

stringToFind

Pass a reference to the CFString object containing the substring to search for in theString.

compareOptions

Pass a bitfield of type CFOptionFlags containing one or more comparison-option flags (OR'd together if multiple) or, if you want no options, pass zero. The options include such features as localized comparison, case-insensitive comparison, and non-literal compariosn.

function result

The starting location (and length) of the substring within the CFString object or, if not found, a CFRange structure with a location of kCFNotFound and a length of 0 (either of which is enough to indicate failure).

DISCUSSION

The CFStringFind function is a convenience when you want to know if the entire range of characters represented by a CFString object contains a particular substring. If you want to search only part of the characters of a CFString object, use the CFStringFindWithOptions function. Both of these functions return upon finding the first occurrence of the substring, so if you want to find out about multiple occurrences, call the CFStringCreateArrayWithFindResults function.

Depending on the comparison-option flags specified, the length of the resulting range might be different than the length of the search string.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)