NSString

The NSString class declares the programmatic interface for an object that manages immutable strings. An immutable string is a text string that is defined when it is created and subsequently cannot be changed. NSString is implemented to represent an array of Unicode characters, in other words, a text string.

The NSString class has two primitive methods—length and characterAtIndex:—that provide the basis for all other methods in its interface. The length method returns the total number of Unicode characters in the string. characterAtIndex: gives access to each character in the string by index, with index values starting at 0.

NSString declares methods for finding and comparing strings. It also declares methods for reading numeric values from strings, for combining strings in various ways, and for converting a string to different forms (such as encoding and case changes).

The Application Kit also uses NSParagraphStyle and its subclass NSMutableParagraphStyle to encapsulate the paragraph or ruler attributes used by the NSAttributedString classes. Additionally, methods to support string drawing are described in NSString Additions, found in the Application Kit.

NSString is “toll-free bridged” with its Core Foundation counterpart, CFStringRef. See Toll-Free Bridging for more information on toll-free bridging.

String Objects

NSString objects represent character strings in frameworks. Representing strings as objects allows you to use strings wherever you use other objects. It also provides the benefits of encapsulation, so that string objects can use whatever encoding and storage are needed for efficiency while simply appearing as arrays of characters. The cluster’s two public classes, NSString and NSMutableString, declare the programmatic interface for non-editable and editable strings, respectively.

Note

An immutable string is a text string that is defined when it is created and subsequently cannot be changed. An immutable string is implemented as an array of Unicode characters (in other words, a text string). To create and manage an immutable string, use the NSString class. To construct and manage a string that can be changed after it has been created, use NSMutableString.

The objects you create using NSString and NSMutableString are referred to as string objects (or, when no confusion will result, merely as strings). The term C string refers to the standard char * type. Because of the nature of class clusters, string objects aren’t actual instances of the NSString or NSMutableString classes but of one of their private subclasses. Although a string object’s class is private, its interface is public, as declared by these abstract superclasses, NSString and NSMutableString. The string classes adopt the NSCopying and NSMutableCopying protocols, making it convenient to convert a string of one type to the other.

Understanding characters

A string object presents itself as an array of Unicode characters (Unicode is a registered trademark of Unicode, Inc.). You can determine how many characters a string object contains with the length method and can retrieve a specific character with the characterAtIndex: method. These two “primitive” methods provide basic access to a string object.

Most use of strings, however, is at a higher level, with the strings being treated as single entities: You compare strings against one another, search them for substrings, combine them into new strings, and so on. If you need to access string objects character by character, you must understand the Unicode character encoding, specifically issues related to composed character sequences. For details see The Unicode Standard, Version 4.0 (The Unicode Consortium, Boston: Addison-Wesley, 2003, ISBN 0-321-18578-1) and the Unicode Consortium web site: http://www.unicode.org/. See also Characters and Grapheme Clusters in String Programming Guide.

Localized string comparisons are based on the Unicode Collation Algorithm, as tailored for different languages by CLDR (Common Locale Data Repository). Both are projects of the Unicode Consortium.

Interpreting UTF-16-encoded data

When creating an NSString object from a UTF-16-encoded string (or a byte stream interpreted as UTF-16), if the byte order is not otherwise specified, NSString assumes that the UTF-16 characters are big-endian, unless there is a BOM (byte-order mark), in which case the BOM dictates the byte order. When creating an NSString object from an array of Unicode characters, the returned string is always native-endian, since the array always contains Unicode characters in native byte order.

Distributed objects

Subclassing Notes

It is possible to subclass NSString (and NSMutableString), but doing so requires providing storage facilities for the string (which is not inherited by subclasses) and implementing two primitive methods. The abstract NSString and NSMutableString classes are the public interface of a class cluster consisting mostly of private, concrete classes that create and return a string object appropriate for a given situation. Making your own concrete subclass of this cluster imposes certain requirements (discussed in Methods to Override).

Make sure your reasons for subclassing NSString are valid. Instances of your subclass should represent a string and not something else. Thus the only attributes the subclass should have are the length of the character buffer it’s managing and access to individual characters in the buffer. Valid reasons for making a subclass of NSString include providing a different backing store (perhaps for better performance) or implementing some aspect of object behavior differently, such as memory management. If your purpose is to add non-essential attributes or metadata to your subclass of NSString, a better alternative would be object composition (see Alternatives to Subclassing). Cocoa already provides an example of this with the NSAttributedString class.

Methods to Override

Any subclass of NSStringmust override the primitive instance methods length and characterAtIndex:. These methods must operate on the backing store that you provide for the characters of the string. For this backing store you can use a static array, a dynamically allocated buffer, a standard NSString object, or some other data type or mechanism. You may also choose to override, partially or fully, any other NSString method for which you want to provide an alternative implementation. For example, for better performance it is recommended that you override getCharacters:range: and give it a faster implementation.

You might want to implement an initializer for your subclass that is suited to the backing store that the subclass is managing. The NSString class does not have a designated initializer, so your initializer need only invoke the init method of super. The NSString class adopts the NSCopying, NSMutableCopying, and NSCoding protocols; if you want instances of your own custom subclass created from copying or coding, override the methods in these protocols.

Alternatives to Subclassing

Often a better and easier alternative to making a subclass of NSString—or of any other abstract, public class of a class cluster, for that matter—is object composition. This is especially the case when your intent is to add to the subclass metadata or some other attribute that is not essential to a string object. In object composition, you would have an NSString object as one instance variable of your custom class (typically a subclass of NSObject) and one or more instance variables that store the metadata that you want for the custom object. Then just design your subclass interface to include accessor methods for the embedded string object and the metadata.

If the behavior you want to add supplements that of the existing class, you could write a category on NSString. Keep in mind, however, that this category will be in effect for all instances of NSString that you use, and this might have unintended consequences.

Parameters

If YEStrue, the receiver frees the memory when it no longer needs the data; if NOfalse it won’t.

Return Value

An initialized NSString object containing length bytes from bytes interpreted using the encoding encoding. The returned object may be different from the original receiver.

Special Considerations

If an error occurs during the creation of the string, then bytes is not freed even if flag is YEStrue. In this case, the caller is responsible for freeing the buffer. This allows the caller to continue trying to create a string with the buffer, without having the buffer deallocated.

Parameters

If YEStrue, the receiver will free the memory when it no longer needs the characters; if NOfalse it won’t.

Return Value

An initialized NSString object that contains length characters from characters. The returned object may be different from the original receiver.

Special Considerations

If an error occurs during the creation of the string, then bytes is not freed even if flag is YEStrue. In this case, the caller is responsible for freeing the buffer. This allows the caller to continue trying to create a string with the buffer, without having the buffer deallocated.

Return Value

An NSString object initialized by using format as a template into which the remaining argument values are substituted according to the system locale. The returned object may be different from the original receiver.

Discussion

Invokes initWithFormat:locale:arguments: with nil as the locale, hence using the system locale to format numbers. This is useful, for example, if you want to produce "non-localized" formatting which needs to be written out to files and parsed back later.

Return Value

An NSString object initialized by using format as a template into which the values in argList are substituted according to the current locale. The returned object may be different from the original receiver.

An NSLocale object specifying the locale to use. To use the current locale (specified by user preferences), pass [NSLocalecurrentLocale]. To use the system locale, pass nil.

For legacy support, this may be an instance of NSDictionary containing locale information.

argList

A list of arguments to substitute into format.

Return Value

An NSString object initialized by using format as a template into which values in argList are substituted according the locale information in locale. The returned object may be different from the original receiver.

Discussion

The following code fragment illustrates how to create a string from myArgs, which is derived from a string object with the value “Cost:” and an int with the value 32:

Declaration

Parameters

An NSData object containing bytes in encoding and the default plain text format (that is, pure content with no attributes or other markups) for that encoding.

encoding

The encoding used by data.

Return Value

An NSString object initialized by converting the bytes in data into Unicode characters using encoding. The returned object may be different from the original receiver. Returns nil if the initialization fails for some reason (for example if data does not represent valid data for encoding).

Return Value

A string created by using format as a template into which the remaining argument values are substituted according to the system locale.

Discussion

This method is similar to localizedStringWithFormat:, but using the system locale to format numbers. This is useful, for example, if you want to produce “non-localized” formatting which needs to be written out to files and parsed back later.

Deprecation Statement

Declaration

Discussion

This method converts length * sizeof(char) bytes from cString and doesn’t stop short at a zero character. cString must contain bytes in the default C-string encoding and may not be NULL. Returns an initialized object, which might be different from the original receiver.

Deprecation Statement

Declaration

Discussion

This method converts length * sizeof(char) bytes from cString and doesn’t stop short at a zero character. cString must contain data in the default C-string encoding and may not be NULL. The receiver becomes the owner of cString; if flag is YEStrue it will free the memory when it no longer needs it, but if flag is NOfalse it won’t. Returns an initialized object, which might be different from the original receiver.

You can use this method to create an immutable string from an immutable (const char *) C-string buffer. If you receive a warning message, you can disregard it; its purpose is simply to warn you that the C string passed as the method’s first argument may be modified. If you make certain the freeWhenDone argument to initWithStringNoCopy is NOfalse, the C string passed as the method’s first argument cannot be modified, so you can safely use initWithStringNoCopy to create an immutable string from an immutable (const char *) C-string buffer.

Parameters

If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, pass in NULL.

Return Value

An NSString object initialized by reading data from the file named by path using the encoding, enc. The returned object may be different from the original receiver. If the file can’t be opened or there is an encoding error, returns nil.

Parameters

Upon return, if the file is read successfully, contains the encoding used to interpret the file at path.

error

If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, pass in NULL.

Return Value

An NSString object initialized by reading data from the file named by path. The returned object may be different from the original receiver. If the file can’t be opened or there is an encoding error, returns nil.

Deprecation Statement

Declaration

Objective-C

+ (id)stringWithContentsOfFile:(NSString *)path

Discussion

If the contents begin with a Unicode byte-order mark (U+FEFF or U+FFFE), interprets the contents as Unicode characters. If the contents begin with a UTF-8 byte-order mark (EFBBBF), interprets the contents as UTF-8. Otherwise, interprets the contents as data in the default C string encoding. Since the default C string encoding will vary with the user’s configuration, do not depend on this method unless you are using Unicode or UTF-8 or you can verify the default C string encoding. Returns nil if the file can’t be opened.

Deprecation Statement

Declaration

Objective-C

- (id)initWithContentsOfFile:(NSString *)path

Discussion

Initializes the receiver, a newly allocated NSString object, by reading data from the file named by path. If the contents begin with a byte-order mark (U+FEFF or U+FFFE), interprets the contents as Unicode characters; otherwise interprets the contents as data in the default C string encoding. Returns an initialized object, which might be different from the original receiver, or nil if the file can’t be opened.

Parameters

Upon return, if url is read successfully, contains the encoding used to interpret the data.

error

If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, pass in NULL.

Return Value

An NSString object initialized by reading data from url. If url can’t be opened or the encoding cannot be determined, returns nil. The returned initialized object might be different from the original receiver

Discussion

To read data with an unknown encoding, pass 0 as the enc parameter as in:

Deprecation Statement

Declaration

Discussion

If the contents begin with a byte-order mark (U+FEFF or U+FFFE), interprets the contents as Unicode characters. If the contents begin with a UTF-8 byte-order mark (EFBBBF), interprets the contents as UTF-8. Otherwise interprets the contents as data in the default C string encoding. Since the default C string encoding will vary with the user’s configuration, do not depend on this method unless you are using Unicode or UTF-8 or you can verify the default C string encoding. Returns nil if the location can’t be opened.

Deprecation Statement

Declaration

Discussion

Initializes the receiver, a newly allocated NSString object, by reading data from the location named by aURL. If the contents begin with a byte-order mark (U+FEFF or U+FFFE), interprets the contents as Unicode characters; otherwise interprets the contents as data in the default C string encoding. Returns an initialized object, which might be different from the original receiver, or nil if the location can’t be opened.

Parameters

path

The file to which to write the receiver. If path contains a tilde (~) character, you must expand it with stringByExpandingTildeInPath before invoking this method.

useAuxiliaryFile

If YEStrue, the receiver is written to an auxiliary file, and then the auxiliary file is renamed to path. If NOfalse, the receiver is written directly to path. The YEStrue option guarantees that path, if it exists at all, won’t be corrupted even if the system should crash during writing.

enc

The encoding to use for the output.

error

If there is an error, upon return contains an NSError object that describes the problem. If you are not interested in details of errors, you may pass in NULL.

Return Value

YEStrue if the file is written successfully, otherwise NOfalse (if there was a problem writing to the file or with the encoding).

Discussion

This method overwrites any existing file at path.

This method stores the specified encoding with the file in an extended attribute under the name com.apple.TextEncoding. The value contains the IANA name for the encoding and the CFStringEncoding value for the encoding, separated by a semicolon. The CFStringEncoding value is written as an ASCII string containing an unsigned 32-bit decimal integer and is not terminated by a null character. One or both of these values may be missing. Examples of the value written include the following:

In the future this attribute may be extended compatibly by adding additional information after what's there now, so any readers should be prepared for an arbitrarily long value for this attribute, with stuff following the CFStringEncoding value, separated by a non-digit.

Deprecation Statement

Declaration

Objective-C

- (BOOL)writeToFile:(NSString *)pathatomically:(BOOL)useAuxiliaryFile

Return Value

YEStrue if the file is written successfully, otherwise NOfalse.

Discussion

Writes the contents of the receiver to the file specified by path (overwriting any existing file at path). path is written in the default C-string encoding if possible (that is, if no information would be lost), in the Unicode encoding otherwise.

If flag is YEStrue, the receiver is written to an auxiliary file, and then the auxiliary file is renamed to path. If flag is NOfalse, the receiver is written directly to path. The YEStrue option guarantees that path, if it exists at all, won’t be corrupted even if the system should crash during writing.

Parameters

url

The URL to which to write the receiver. Only file URLs are supported.

useAuxiliaryFile

If YEStrue, the receiver is written to an auxiliary file, and then the auxiliary file is renamed to url. If NOfalse, the receiver is written directly to url. The YEStrue option guarantees that url, if it exists at all, won’t be corrupted even if the system should crash during writing.

The useAuxiliaryFile parameter is ignored if url is not of a type that can be accessed atomically.

enc

The encoding to use for the output.

error

If there is an error, upon return contains an NSError object that describes the problem. If you are not interested in details of errors, you may pass in NULL.

Return Value

YEStrue if the URL is written successfully, otherwise NOfalse (if there was a problem writing to the URL or with the encoding).

Discussion

This method stores the specified encoding with the file in an extended attribute under the name com.apple.TextEncoding. The value contains the IANA name for the encoding and the CFStringEncoding value for the encoding, separated by a semicolon. The CFStringEncoding value is written as an ASCII string containing an unsigned 32-bit decimal integer and is not terminated by a null character. One or both of these values may be missing. Examples of the value written include the following:

In the future this attribute may be extended compatibly by adding additional information after what's there now, so any readers should be prepared for an arbitrarily long value for this attribute, with stuff following the CFStringEncoding value, separated by a non-digit.

Deprecation Statement

Declaration

Return Value

YEStrue if the location is written successfully, otherwise NOfalse.

Discussion

If atomically is YEStrue, the receiver is written to an auxiliary location, and then the auxiliary location is renamed to aURL. If atomically is NOfalse, the receiver is written directly to aURL. The YEStrue option guarantees that aURL, if it exists at all, won’t be corrupted even if the system should crash during writing.

The atomically parameter is ignored if aURL is not of a type that can be accessed atomically.

Declaration

Parameters

enc

The encoding for which to determine the receiver's length.

Return Value

The number of bytes required to store the receiver in the encoding enc in a non-external representation. The length does not include space for a terminating NULL character. Returns 0 if the specified encoding cannot be used to convert the receiver or if the amount of memory required for storing the results of the encoding conversion would exceed NSIntegerMax.

Declaration

Parameters

enc

The encoding for which to determine the receiver's length.

Return Value

The maximum number of bytes needed to store the receiver in encoding in a non-external representation. The length does not include space for a terminating NULL character. Returns 0 if the amount of memory required for storing the results of the encoding conversion would exceed NSIntegerMax.

Discussion

The result is an estimate and is returned in O(1) time; the estimate may be considerably greater than the actual length needed.

Declaration

Parameters

Upon return, contains the characters from the receiver. buffer must be large enough to contain the characters in the range aRange (aRange.length*sizeof(unichar)).

aRange

The range of characters to retrieve. The range must not exceed the bounds of the receiver.

Important

Raises an NSRangeException if any part of aRange lies beyond the bounds of the receiver.

Discussion

This method does not add a NULL character.

The abstract implementation of this method uses characterAtIndex: repeatedly, correctly extracting the characters, though very inefficiently. Subclasses should override it to provide a fast implementation.

Declaration

Parameters

Return Value

A C string representation of the receiver using the encoding specified by encoding. Returns NULL if the receiver cannot be losslessly converted to encoding.

Discussion

The returned C string is guaranteed to be valid only until either the receiver is freed, or until the current memory is emptied, whichever occurs first. You should copy the C string or use getCString:maxLength:encoding: if it needs to store the C string beyond this time.

You can use canBeConvertedToEncoding: to check whether a string can be losslessly converted to encoding. If it can’t, you can use dataUsingEncoding:allowLossyConversion: to get a C-string representation using encoding, allowing some loss of information (note that the data returned by dataUsingEncoding:allowLossyConversion: is not a strict C-string since it does not have a NULL terminator).

Parameters

Upon return, contains the converted C-string plus the NULL termination byte. The buffer must include room for maxBufferCount bytes.

maxBufferCount

The maximum number of bytes in the string to return in buffer (including the NULL termination byte).

encoding

The encoding for the returned C string.

Return Value

YEStrue if the operation was successful, otherwise NOfalse. Returns NOfalse if conversion is not possible due to encoding errors or if buffer is too small.

Discussion

Note that in the treatment of the maxBufferCount argument, this method differs from the deprecated getCString:maxLength: method which it replaces. (The buffer should include room for maxBufferCount bytes; this number should accommodate the expected size of the return value plus the NULL termination byte, which this method adds.)

You can use canBeConvertedToEncoding: to check whether a string can be losslessly converted to encoding. If it can’t, you can use dataUsingEncoding:allowLossyConversion: to get a C-string representation using encoding, allowing some loss of information (note that the data returned by dataUsingEncoding:allowLossyConversion: is not a strict C-string since it does not have a NULL terminator).

Availability

See Also

Declaration

Swift

var UTF8String: UnsafePointer<Int8> { get }

Objective-C

@property(readonly)constchar*UTF8String

Discussion

This C string is a pointer to a structure inside the string object, which may have a lifetime shorter than the string object and will certainly not have a longer lifetime. Therefore, you should copy the C string if it needs to be stored outside of the memory context in which you use this property.

Deprecation Statement

Declaration

Objective-C

- (const char *)cString

Discussion

The returned C string will be automatically freed just as a returned object would be released; your code should copy the C string or use getCString: if it needs to store the C string outside of the autorelease context in which the C string is created.

Raises an NSCharacterConversionException if the receiver can’t be represented in the default C-string encoding without loss of information. Use canBeConvertedToEncoding: if necessary to check whether a string can be losslessly converted to the default C-string encoding. If it can’t, use lossyCString or dataUsingEncoding:allowLossyConversion: to get a C-string representation with some loss of information.

Deprecation Statement

Declaration

Objective-C

- (const char *)lossyCString

Discussion

This method does not raise an exception if the conversion is lossy. The returned C string will be automatically freed just as a returned object would be released; your code should copy the C string or use getCString: if it needs to store the C string outside of the autorelease context in which the C string is created.

Deprecation Statement

Declaration

Discussion

Raises if the receiver can’t be represented in the default C-string encoding without loss of information. You can also use canBeConvertedToEncoding: to check whether a string can be losslessly converted to the default C-string encoding. If it can’t, use lossyCString to get a C-string representation with some loss of information, then check its length explicitly using the ANSI function strlen().

Deprecation Statement

Declaration

Objective-C

- (void)getCString:(char *)bytes

Discussion

buffer must be large enough to contain the resulting C-string plus a terminating NULL character (which this method adds—[string cStringLength]).

Raises an NSCharacterConversionException if the receiver can’t be represented in the default C-string encoding without loss of information. Use canBeConvertedToEncoding: if necessary to check whether a string can be losslessly converted to the default C-string encoding. If it can’t, use lossyCString or dataUsingEncoding:allowLossyConversion: to get a C-string representation with some loss of information.

Deprecation Statement

Declaration

Discussion

buffer must be large enough to contain maxLengthchars plus a terminating zero char (which this method adds).

Raises an NSCharacterConversionException if the receiver can’t be represented in the default C-string encoding without loss of information. Use canBeConvertedToEncoding: if necessary to check whether a string can be losslessly converted to the default C-string encoding. If it can’t, use lossyCString or dataUsingEncoding:allowLossyConversion: to get a C-string representation with some loss of information.

Deprecation Statement

Declaration

Discussion

buffer must be large enough to contain maxLength bytes plus a terminating zero character (which this method adds). Copies and converts as many characters as possible from aRange and stores the range of those not converted in the range given by leftoverRange (if it’s non-nil). Raises an NSRangeException if any part of aRange lies beyond the end of the string.

Raises an NSCharacterConversionException if the receiver can’t be represented in the default C-string encoding without loss of information. Use canBeConvertedToEncoding: if necessary to check whether a string can be losslessly converted to the default C-string encoding. If it can’t, use lossyCString or dataUsingEncoding:allowLossyConversion: to get a C-string representation with some loss of information.

Declaration

Parameters

separator

The separator string.

Return Value

An NSArray object containing substrings from the receiver that have been divided by separator.

Discussion

The substrings in the array appear in the order they did in the receiver. Adjacent occurrences of the separator string produce empty strings in the result. Similarly, if the string begins or ends with the separator, the first or last substring, respectively, is empty. For example, this code fragment:

Declaration

Parameters

A character set containing the characters to to use to split the receiver. Must not be nil.

Return Value

An NSArray object containing substrings from the receiver that have been divided by characters in separator.

Discussion

The substrings in the array appear in the order they did in the receiver. Adjacent occurrences of the separator characters produce empty strings in the result. Similarly, if the string begins or ends with separator characters, the first or last substring, respectively, is empty.

Declaration

Parameters

Raises an NSRangeException if (aRange.location - 1) or (aRange.location + aRange.length - 1) lies beyond the end of the receiver.

Return Value

A string object containing the characters of the receiver that lie within aRange.

Special Considerations

This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.

Return Value

The range in the receiver of the first character found from aSet within aRange. Returns a range of {NSNotFound, 0} if none of the characters in aSet are found.

Discussion

Because pre-composed characters in aSet can match composed character sequences in the receiver, the length of the returned range can be greater than 1. For example, if you search for “ü” in the string “stru¨del”, the returned range is {3,2}.

Special Considerations

This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.

Declaration

Parameters

aString

The string to search for. This value must not be nil.

Important

Raises an NSInvalidArgumentException if aString is nil.

mask

A mask specifying search options. The following options may be specified by combining them with the C bitwise OR operator: NSCaseInsensitiveSearch, NSLiteralSearch, NSBackwardsSearch, NSAnchoredSearch. See String Programming Guide for details on these options.

Return Value

An NSRange structure giving the location and length in the receiver of the first occurrence of aString, modulo the options in mask. Returns {NSNotFound, 0} if aString is not found or is empty (@"").

Parameters

aString

The string for which to search. This value must not be nil.

Raises an NSInvalidArgumentException if aString is nil.

mask

A mask specifying search options. The following options may be specified by combining them with the C bitwise OR operator: NSCaseInsensitiveSearch, NSLiteralSearch, NSBackwardsSearch, and NSAnchoredSearch. See String Programming Guide for details on these options.

aRange

The range within the receiver for which to search for aString.

Raises an NSRangeException if aRange is invalid.

Return Value

An NSRange structure giving the location and length in the receiver of aString within aRange in the receiver, modulo the options in mask. The range returned is relative to the start of the string, not to the passed-in range. Returns {NSNotFound, 0} if aString is not found or is empty (@"").

Discussion

The length of the returned range and that of aString may differ if equivalent composed character sequences are matched.

Special Considerations

This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.

Parameters

A mask specifying search options. The following options may be specified by combining them with the C bitwise OR operator: NSCaseInsensitiveSearch, NSLiteralSearch, NSBackwardsSearch, and NSAnchoredSearch. See String Programming Guide for details on these options.

The locale to use when comparing the receiver with aString. To use the current locale, pass [NSLocalecurrentLocale]. To use the system locale, pass nil.

The locale argument affects the equality checking algorithm. For example, for the Turkish locale, case-insensitive compare matches “I” to “ı” (Unicode code point U+0131, Latin Small Dotless I), not the normal “i” character.

Return Value

An NSRange structure giving the location and length in the receiver of aString within aRange in the receiver, modulo the options in mask. The range returned is relative to the start of the string, not to the passed-in range. Returns {NSNotFound, 0} if aString is not found or is empty (@"").

Discussion

The length of the returned range and that of aString may differ if equivalent composed character sequences are matched.

Special Considerations

This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.

Declaration

Parameters

block

The block executed for the enumeration.

The block takes two arguments:

line

The current line of the string being enumerated. The line contains just the contents of the line, without the line terminators. See getLineStart:end:contentsEnd:forRange: for a discussion of line terminators.

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.

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".

Parameters

startIndex

Upon return, contains the index of the first character of the line containing the beginning of aRange. Pass NULL if you do not need this value (in which case the work to compute the value isn’t performed).

lineEndIndex

Upon return, contains the index of the first character past the terminator of the line containing the end of aRange. Pass NULL if you do not need this value (in which case the work to compute the value isn’t performed).

contentsEndIndex

Upon return, contains the index of the first character of the terminator of the line containing the end of aRange. Pass NULL if you do not need this value (in which case the work to compute the value isn’t performed).

aRange

A range within the receiver. The value must not exceed the bounds of the receiver.

Raises an NSRangeException if aRange is invalid.

Discussion

A line is delimited by any of these characters, the longest possible sequence being preferred to any shorter:

U+000D (\r or CR)

U+2028 (Unicode line separator)

U+000A (\n or LF)

U+2029 (Unicode paragraph separator)

\r\n, in that order (also known as CRLF)

If aRange is contained with a single line, of course, the returned indexes all belong to that line. You can use the results of this method to construct ranges for lines by using the start index as the range’s location and the difference between the end index and the start index as the range’s length.

Special Considerations

This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.

Parameters

startIndex

Upon return, contains the index of the first character of the paragraph containing the beginning of aRange. Pass NULL if you do not need this value (in which case the work to compute the value isn’t performed).

endIndex

Upon return, contains the index of the first character past the terminator of the paragraph containing the end of aRange. Pass NULL if you do not need this value (in which case the work to compute the value isn’t performed).

contentsEndIndex

Upon return, contains the index of the first character of the terminator of the paragraph containing the end of aRange. Pass NULL if you do not need this value (in which case the work to compute the value isn’t performed).

aRange

A range within the receiver. The value must not exceed the bounds of the receiver.

Discussion

If aRange is contained with a single paragraph, of course, the returned indexes all belong to that paragraph. Similar to getLineStart:end:contentsEnd:forRange:, you can use the results of this method to construct the ranges for paragraphs.

Declaration

Return Value

A dictionary object initialized with the keys and values found in the receiver

Discussion

The receiver must contain text in the format used for .strings files. In this format, keys and values are separated by an equal sign, and each key-value pair is terminated with a semicolon. The value is optional—if not present, the equal sign is also omitted. The keys and values themselves are always strings enclosed in straight quotation marks. Comments may be included, delimited by /* and */ as for ANSI C comments. Here’s a short example of a strings file:

The range of the receiver over which to perform the comparison. The range must not exceed the bounds of the receiver.

Important

Raises an NSRangeException if range exceeds the bounds of the receiver.

locale

An instance of NSLocale. To use the current locale, pass [NSLocalecurrentLocale]. For example, if you are comparing strings to present to the end-user, use the current locale. To use the system locale, pass nil.

Return Value

Returns an NSComparisonResult value that indicates the lexical ordering of a specified range within the receiver and a given string. NSOrderedAscending if the substring of the receiver given by range precedes aString in lexical ordering for the locale given in dict, NSOrderedSame if the substring of the receiver and aString are equivalent in lexical value, and NSOrderedDescending if the substring of the receiver follows aString.

Discussion

The locale argument affects both equality and ordering algorithms. For example, in some locales, accented characters are ordered immediately after the base; other locales order them after “z”.

Special Considerations

Prior to OS X v10.5, the locale argument was an instance of NSDictionary. On OS X v10.5 and later, if you pass an instance of NSDictionary the current locale is used instead.

Declaration

Parameters

string

The string to compare with the receiver.

Return Value

The result of the comparison.

Discussion

This method should be used whenever file names or other strings are presented in lists and tables where Finder-like sorting is appropriate. The exact sorting behavior of this method is different under different locales and may be changed in future releases. This method uses the current locale.

Declaration

Parameters

Return Value

YEStrue if aString is equivalent to the receiver (if they have the same id or if they are NSOrderedSame in a literal comparison), otherwise NOfalse.

Discussion

The comparison uses the canonical representation of strings, which for a particular string is the length of the string plus the Unicode characters that make up the string. When this method compares two strings, if the individual Unicodes are the same, then the strings are equal, regardless of the backing store. “Literal” when applied to string comparison means that various Unicode decomposition rules are not applied and Unicode characters are individually compared. So, for instance, “Ö” represented as the composed character sequence “O” and umlaut would not compare equal to “Ö” represented as one Unicode character.

Special Considerations

When you know both objects are strings, this method is a faster way to check equality than isEqual:.

Declaration

Parameters

aString

The string with which to compare the receiver.

mask

Options for the comparison. The following search options may be specified by combining them with the C bitwise OR operator: NSCaseInsensitiveSearch, NSLiteralSearch. See String Programming Guide for details on these options.

Return Value

A string containing characters the receiver and aString have in common, starting from the beginning of each up to the first characters that aren’t equivalent.

Discussion

The returned string is based on the characters of the receiver. For example, if the receiver is “Ma¨dchen” and aString is “Mädchenschule”, the string returned is “Ma¨dchen”, not “Mädchen”.

Declaration

Discussion

A string with the first character in each word changed to its corresponding uppercase value, and all remaining characters set to their corresponding lowercase values.

A “word” is any sequence of characters delimited by spaces, tabs, or line terminators (listed under getLineStart:end:contentsEnd:forRange:). Some common word delimiting punctuation isn’t considered, so this property may not generally produce the desired results for multiword strings.

Case transformations aren’t guaranteed to be symmetrical or to produce strings of the same lengths as the originals. See lowercaseString for an example.

Note

This property performs the canonical (non-localized) mapping. It is suitable for programming operations that require stable results not depending on the current locale. For localized case mapping for strings presented to users, use the capitalizedStringWithLocale: method.

Declaration

Parameters

The locale. For strings presented to users, pass the current locale ([NSLocalecurrentLocale]). To use the system locale, pass nil.

Return Value

A string with the first character from each word in the receiver changed to its corresponding uppercase value, and all remaining characters set to their corresponding lowercase values.

Discussion

A “word” is any sequence of characters delimited by spaces, tabs, or line terminators (listed under getLineStart:end:contentsEnd:forRange:). Some common word delimiting punctuation isn’t considered, so this method may not generally produce the desired results for multiword strings.

Declaration

Discussion

Case transformations aren’t guaranteed to be symmetrical or to produce strings of the same lengths as the originals. The result of this statement:

lcString=[myStringlowercaseString];

might not be equal to this statement:

lcString=[[myStringuppercaseString]lowercaseString];

For example, the uppercase form of “ß” in German is “SS”, so converting “Straße” to uppercase, then lowercase, produces this sequence of strings:

“Straße”

“STRASSE”

“strasse”

Note

This property performs the canonical (non-localized) mapping. It is suitable for programming operations that require stable results not depending on the current locale. For localized case mapping for strings presented to users, use lowercaseStringWithLocale:.

Declaration

Discussion

Case transformations aren’t guaranteed to be symmetrical or to produce strings of the same lengths as the originals. See lowercaseString for an example.

Note

This property performs the canonical (non-localized) mapping. It is suitable for programming operations that require stable results not depending on the current locale. For localized case mapping for strings presented to users, use the uppercaseStringWithLocale: method.

Declaration

Discussion

This property doesn’t include any whitespace at the beginning of the string. This property is HUGE_VAL or –HUGE_VAL on overflow, 0.0 on underflow. This property is 0.0 if the string doesn’t begin with a valid text representation of a floating-point number.

This property uses formatting information stored in the non-localized value; use an NSScanner object for localized scanning of numeric values from a string.

Availability

See Also

Declaration

Swift

var floatValue: Float { get }

Objective-C

@property(readonly)floatfloatValue

Discussion

This property doesn’t include whitespace at the beginning of the string. This property is HUGE_VAL or –HUGE_VAL on overflow, 0.0 on underflow. This property is 0.0 if the string doesn’t begin with a valid text representation of a floating-point number.

This method uses formatting information stored in the non-localized value; use an NSScanner object for localized scanning of numeric values from a string.

Availability

See Also

Declaration

Swift

var intValue: Int32 { get }

Objective-C

@property(readonly)intintValue

Discussion

The integer value of the string, assuming a decimal representation and skipping whitespace at the beginning of the string. This property is INT_MAX or INT_MIN on overflow. This property is 0 if the string doesn’t begin with a valid decimal text representation of a number.

This property uses formatting information stored in the non-localized value; use an NSScanner object for localized scanning of numeric values from a string.

Declaration

Discussion

The NSInteger value of the string, assuming a decimal representation and skipping whitespace at the beginning of the string. This property is 0 if the string doesn’t begin with a valid decimal text representation of a number.

This property uses formatting information stored in the non-localized value; use an NSScanner object for localized scanning of numeric values from a string.

Availability

See Also

Declaration

Swift

var longLongValue: Int64 { get }

Objective-C

@property(readonly)longlonglongLongValue

Discussion

The long long value of the string, assuming a decimal representation and skipping whitespace at the beginning of the string. This property is LLONG_MAX or LLONG_MIN on overflow. This property is 0 if the receiver doesn’t begin with a valid decimal text representation of a number.

This property uses formatting information stored in the non-localized value; use an NSScanner object for localized scanning of numeric values from a string.

Availability

See Also

Declaration

Swift

var boolValue: Bool { get }

Objective-C

@property(readonly)BOOLboolValue

Discussion

This property is YEStrue on encountering one of "Y", "y", "T", "t", or a digit 1-9—the method ignores any trailing characters. This property is NOfalse if the receiver doesn’t begin with a valid decimal text representation of a number.

The property assumes a decimal representation and skips whitespace at the beginning of the string. It also skips initial whitespace characters, or optional -/+ sign followed by zeroes.

Declaration

Return Value

A zero-terminated list of the encodings string objects support in the application’s environment.

Discussion

Among the more commonly used encodings are:

NSASCIIStringEncoding

NSUnicodeStringEncoding

NSISOLatin1StringEncoding

NSISOLatin2StringEncoding

NSSymbolStringEncoding

See the Constants section for a larger list and descriptions of many supported encodings. In addition to those encodings listed here, you can also use the encodings defined for CFString in Core Foundation; you just need to call the CFStringConvertEncodingToNSStringEncoding function to convert them to a usable format.

Declaration

Return Value

The C-string encoding assumed for any method accepting a C string as an argument.

Discussion

This method returns a user-dependent encoding who value is derived from user's default language and potentially other factors. You might sometimes need to use this encoding when interpreting user documents with unknown encodings, in the absence of other hints, but in general this encoding should be used rarely, if at all. Note that some potential values might result in unexpected encoding conversions of even fairly straightforward NSString content—for example, punctuation characters with a bidirectional encoding.

Methods that accept a C string as an argument use ...CString... in the keywords for such arguments: for example, stringWithCString:—note, though, that these are deprecated. The default C-string encoding is determined from system information and can’t be changed programmatically for an individual process. See String Encodings for a full list of supported encodings.

Declaration

Parameters

Return Value

YEStrue if the receiver can be converted to encoding without loss of information. Returns NOfalse if characters would have to be changed or deleted in the process of changing encodings.

Discussion

If you plan to actually convert a string, the dataUsingEncoding:... methods return nil on failure, so you can avoid the overhead of invoking this method yourself by simply trying to convert the string.

Declaration

Parameters

encoding

A string encoding.

flag

If YEStrue, then allows characters to be removed or altered in conversion.

Return Value

An NSData object containing a representation of the receiver encoded using encoding. Returns nil if flag is NOfalse and the receiver can’t be converted without losing some information (such as accents or case).

Discussion

If flag is YEStrue and the receiver can’t be converted without losing some information, some characters may be removed or altered in conversion. For example, in converting a character from NSUnicodeStringEncoding to NSASCIIStringEncoding, the character ‘Á’ becomes ‘A’, losing the accent.

This method creates an external representation (with a byte order marker, if necessary, to indicate endianness) to ensure that the resulting NSData object can be written out to a file safely. The result of this method, when lossless conversion is made, is the default “plain text” format for encoding and is the recommended way to save or transmit a string object.

Declaration

Parameters

components

An array of NSString objects representing a file path. To create an absolute path, use a slash mark (“/”) as the first component. To include a trailing path divider, use an empty string as the last component.

Return Value

A string built from the strings in components by concatenating them (in the order they appear in the array) with a path separator between each pair.

Discussion

This method doesn’t clean up the path created; use stringByStandardizingPath to resolve empty components, references to the parent directory, and so on.

Declaration

Discussion

The strings in the array appear in the order they did in the receiver. If the string begins or ends with the path separator, then the first or last component, respectively, will contain the separator. Empty components (caused by consecutive path separators) are deleted. For example, this code excerpt:

NSString*path=@"tmp/scratch";

NSArray*pathComponents=[pathpathComponents];

produces an array with these contents:

Index

Path Component

0

“tmp”

1

“scratch”

If the receiver begins with a slash—for example, “/tmp/scratch”—the array has these contents:

Index

Path Component

0

“/”

1

“tmp”

2

“scratch”

If the receiver has no separators—for example, “scratch”—the array contains the string itself, in this case “scratch”.

Note that this method only works with file paths—not, for example, string representations of URLs.

Interprets the receiver as a path in the file system and attempts to perform filename completion, returning a numeric value that indicates whether a match was possible, and by reference the longest path that matches the receiver.

An array of NSString objects specifying path extensions to consider for completion. Only paths whose extensions (not including the extension separator) match one of these strings are included in outputArray. Pass nil if you don’t want to filter the output.

Return Value

0 if no matches are found and 1 if exactly one match is found. In the case of multiple matches, returns the actual number of matching paths if outputArray is provided, or simply a positive value if outputArray is NULL.

Discussion

You can check for the existence of matches without retrieving by passing NULL as outputArray.

Note that this method only works with file paths (not, for example, string representations of URLs).

Availability

Declaration

Swift

var fileSystemRepresentation: UnsafePointer<Int8> { get }

Objective-C

@property(readonly)constchar*fileSystemRepresentation

Discussion

The returned C string will be automatically freed just as a returned object would be released; your code should copy the representation or use getFileSystemRepresentation:maxLength: if it needs to store the representation outside of the memory context in which the representation was created.

Raises an NSCharacterConversionException if the receiver can’t be represented in the file system’s encoding. It also raises an exception if the receiver contains no characters.

Note that this method only works with file paths (not, for example, string representations of URLs).

Parameters

Upon return, contains a C-string that represent the receiver as as a system-independent path, plus the NULL termination byte. The size of buffer must be large enough to contain maxLength bytes.

maxLength

The maximum number of bytes in the string to return in buffer (including a terminating NULL character, which this method adds).

Return Value

YEStrue if buffer is successfully filled with a file-system representation, otherwise NOfalse (for example, if maxLength would be exceeded or if the receiver can’t be represented in the file system’s encoding).

Discussion

This method operates by replacing the abstract path and extension separator characters (‘/’ and ‘.’ respectively) with their equivalents for the operating system. If the system-specific path or extension separator appears in the abstract representation, the characters it is converted to depend on the system (unless they’re identical to the abstract separators).

Note that this method only works with file paths (not, for example, string representations of URLs).

The following example illustrates the use of the maxLength argument. The first method invocation returns failure as the file representation of the string (@"/mach_kernel") is 12 bytes long and the value passed as the maxLength argument (12) does not allow for the addition of a NULL termination byte.

Discussion

Note that this method only works with file paths (not, for example, string representations of URLs). The method does not check the filesystem for the existence of the path (use fileExistsAtPath: or similar methods in NSFileManager for that task).

Declaration

Discussion

The path extension is the portion of the last path component which follows the final period, if there is one. The extension divider is not included. The following table illustrates the effect of pathExtension on a variety of different paths:

Receiver’s String Value

String Returned

“/tmp/scratch.tiff”

“tiff”

“.scratch.tiff”

“tiff”

“/tmp/scratch”

“” (an empty string)

“/tmp/”

“” (an empty string)

“/tmp/scratch..tiff”

“tiff”

Note that this method only works with file paths (not, for example, string representations of URLs).

Declaration

Discussion

A new string based on the current string object. If the new string specifies a file in the current home directory, the home directory portion of the path is replaced with a tilde (~) character. If the string does not specify a file in the current home directory, this method returns a new string object whose path is unchanged from the path in the current string.

Note that this method only works with file paths. It does not work for string representations of URLs.

For sandboxed apps in OS X, the current home directory is not the same as the user’s home directory. For a sandboxed app, the home directory is the app’s home directory. So if you specified a path of /Users/<current_user>/file.txt for a sandboxed app, the returned path would be unchanged from the original. However, if you specified the same path for an app not in a sandbox, this method would replace the /Users/<current_user> portion of the path with a tilde.

Declaration

Parameters

Return Value

A new string made by appending to the receiver an extension separator followed by ext. If the receiver is empty, or the resulting path would be too long, returns nil.

Discussion

The following table illustrates the effect of this method on a variety of different paths, assuming that ext is supplied as @"tiff":

Receiver’s String Value

Resulting String

“/tmp/scratch.old”

“/tmp/scratch.old.tiff”

“/tmp/scratch.”

“/tmp/scratch..tiff”

“/tmp/”

“/tmp.tiff”

“scratch”

“scratch.tiff”

Note that adding an extension to @"/tmp/" causes the result to be @"/tmp.tiff" instead of @"/tmp/.tiff". This difference is because a file named @".tiff" is not considered to have an extension, so the string is appended to the last nonempty path component.

Note that this method only works with file paths (not, for example, string representations of URLs).

Special Considerations

Prior to OS X v10.9 this method did not allow you to append file extensions to filenames starting with the tilde character (~).

Declaration

Discussion

A new string made by deleting the extension (if any, and only the last) from the receiver. Strips any trailing path separator before checking for an extension. If the receiver represents the root path, it is returned unaltered.

The following table illustrates the effect of this method on a variety of different paths:

Receiver’s String Value

Resulting String

“/tmp/scratch.tiff”

“/tmp/scratch”

“/tmp/”

“/tmp”

“scratch.bundle/”

“scratch”

“scratch..tiff”

“scratch.”

“.tiff”

“.tiff”

“/”

“/”

Note that attempting to delete an extension from @".tiff" causes the result to be @".tiff" instead of an empty string. This difference is because a file named @".tiff" is not considered to have an extension, so nothing is deleted. Note also that this method only works with file paths (not, for example, string representations of URLs).

Declaration

Discussion

A new string made by expanding the initial component of the receiver, if it begins with “~” or “~user”, to its full path value. Returns a new string matching the receiver if the receiver’s initial component can’t be expanded.

Note that this method only works with file paths (not, for example, string representations of URLs).

Declaration

Discussion

A new string made by expanding an initial tilde expression in the receiver, then resolving all symbolic links and references to current or parent directories if possible, to generate a standardized path. If the original path is absolute, all symbolic links are guaranteed to be removed; if it’s a relative path, symbolic links that can’t be resolved are left unresolved in the returned string. Returns self if an error occurs.

If the name of the receiving path begins with /private, the stringByResolvingSymlinksInPath method strips off the /private designator, provided the result is the name of an existing file.

Note that this method only works with file paths (not, for example, string representations of URLs).

Declaration

Discussion

If an invalid pathname is provided, stringByStandardizingPath may attempt to resolve it by calling stringByResolvingSymlinksInPath, and the results are undefined. If any other kind of error is encountered (such as a path component not existing), self is returned.

Reduce empty components and references to the current directory (that is, the sequences “//” and “/./”) to single path separators.

In absolute paths only, resolve references to the parent directory (that is, the component “..”) to the real parent directory if possible using stringByResolvingSymlinksInPath, which consults the file system to resolve each potential symbolic link.

In relative paths, because symbolic links can’t be resolved, references to the parent directory are left in place.

Remove an initial component of “/private” from the path if the result still indicates an existing file or directory (checked by consulting the file system).

Note that the path returned by this method may still have symbolic link components in it. Note also that this method only works with file paths (not, for example, string representations of URLs).

Declaration

Parameters

encoding

The encoding to use for the returned string. If you are uncertain of the correct encoding you should use NSUTF8StringEncoding.

Return Value

A representation of the receiver using encoding to determine the percent escapes necessary to convert the receiver into a legal URL string. Returns nil if encoding cannot encode a particular character.

Discussion

It may be difficult to use this function to "clean up" unescaped or partially escaped URL strings where sequences are unpredictable. See CFURLCreateStringByAddingPercentEscapes for more information.

Declaration

Parameters

encoding

The encoding to use for the returned string.

Return Value

A new string made by replacing in the receiver all percent escapes with the matching characters as determined by the given encoding encoding. Returns nil if the transformation is not possible, for example, the percent escapes give a byte sequence not legal in encoding.

Parameters

The linguistic tagger options to use. See NSLinguisticTaggerOptionsfor the constants. These constants can be combined using the C-Bitwise OR operator.

orthography

The orthography of the string. If nil, the linguistic tagger will attempt to determine the orthography from the string content.

block

The Block to apply to the string.

The block takes four arguments:

tag

The tag scheme for the token. The opts parameter specifies the types of tagger options that are located.

tokenRange

The range of a string matching the tag scheme.

sentenceRange

The range of the sentence in which the token is found.

stop

A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the Block.