NSString Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Declared in
NSLinguisticTagger.h
NSPathUtilities.h
NSString.h
NSURL.h
Companion guides
Related sample code

Overview

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 mutable subclass of NSString is NSMutableString.

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.

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.

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

Over distributed-object connections, mutable string objects are passed by-reference and immutable string objects are passed by-copy.

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 NSString must 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.

Note that you shouldn’t override the hash method.

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.

Adopted Protocols

NSCoding
NSCopying
NSMutableCopying

Tasks

Creating and Initializing Strings

Creating and Initializing a String from a File

Creating and Initializing a String from an URL

Writing to a File or URL

Getting a String’s Length

Getting Characters and Bytes

Getting C Strings

Combining Strings

Dividing Strings

Finding Characters and Substrings

Replacing Substrings

Determining Line and Paragraph Ranges

Determining Composed Character Sequences

Converting String Contents Into a Property List

Identifying and Comparing Strings

Folding Strings

Getting a Shared Prefix

Changing Case

Getting Strings with Mapping

Getting Numeric Values

Working with Encodings

Working with Paths

Working with URLs

Linguistic Tagging and Analysis

Class Methods

availableStringEncodings

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

+ (const NSStringEncoding *)availableStringEncodings
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:

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

defaultCStringEncoding

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

+ (NSStringEncoding)defaultCStringEncoding
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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

localizedNameOfStringEncoding:

Returns a human-readable string giving the name of a given encoding.

+ (NSString *)localizedNameOfStringEncoding:(NSStringEncoding)encoding
Parameters
encoding

A string encoding.

Return Value

A human-readable string giving the name of encoding in the current locale’s language.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

localizedStringWithFormat:

Returns a string created by using a given format string as a template into which the remaining argument values are substituted according to the user's default locale.

+ (instancetype)localizedStringWithFormat:(NSString *)format, ...
Parameters
format

A format string. See “Formatting String Objects” for examples of how to use this method, and “String Format Specifiers” for a list of format specifiers. This value must not be nil.

Raises an NSInvalidArgumentException if format is nil.

...

A comma-separated list of arguments to substitute into format.

Return Value

A string created by using format as a template into which the following argument values are substituted according to the formatting information to the user's default locale.

Discussion

This method is equivalent to using initWithFormat:locale: and passing the system locale as the locale argument.

As an example of formatting, this method replaces the decimal according to the locale in %f and %d substitutions, and calls descriptionWithLocale: instead of description where necessary.

This code excerpt creates a string from another string and a float:

NSString *myString = [NSString localizedStringWithFormat:@"%@:  %f\n", @"Cost", 1234.56];

The resulting string has the value “Cost: 1234.560000\n” if the locale is en_US, and “Cost: 1234,560000\n” if the locale is fr_FR.

See “Formatting String Objects” for more information.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

pathWithComponents:

Returns a string built from the strings in a given array by concatenating them with a path separator between each pair.

+ (NSString *)pathWithComponents:(NSArray *)components
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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

string

Returns an empty string.

+ (instancetype)string
Return Value

An empty string.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSString.h

stringWithCharacters:length:

Returns a string containing a given number of characters taken from a given C array of Unicode characters.

+ (instancetype)stringWithCharacters:(const unichar *)chars length:(NSUInteger)length
Parameters
chars

A C array of Unicode characters; the value must not be NULL.

Important: Raises an exception if chars is NULL, even if length is 0.

length

The number of characters to use from chars.

Return Value

A string containing length Unicode characters taken (starting with the first) from chars.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

stringWithContentsOfFile:encoding:error:

Returns a string created by reading data from the file at a given path interpreted using a given encoding.

+ (instancetype)stringWithContentsOfFile:(NSString *)path encoding:(NSStringEncoding)enc error:(NSError **)error
Parameters
path

A path to a file.

enc

The encoding of 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

A string created by reading data from the file named by path using the encoding, enc. If the file can’t be opened or there is an encoding error, returns nil.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

stringWithContentsOfFile:usedEncoding:error:

Returns a string created by reading data from the file at a given path and returns by reference the encoding used to interpret the file.

+ (instancetype)stringWithContentsOfFile:(NSString *)path usedEncoding:(NSStringEncoding *)enc error:(NSError **)error
Parameters
path

A path to a file.

enc

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, you may pass in NULL.

Return Value

A string created by reading data from the file named by path. If the file can’t be opened or there is an encoding error, returns nil.

Discussion

This method attempts to determine the encoding of the file at path.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

stringWithContentsOfURL:encoding:error:

Returns a string created by reading data from a given URL interpreted using a given encoding.

+ (instancetype)stringWithContentsOfURL:(NSURL *)url encoding:(NSStringEncoding)enc error:(NSError **)error
Parameters
url

The URL to read.

enc

The encoding of the data at url.

error

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

Return Value

A string created by reading data from URL using the encoding, enc. If the URL can’t be opened or there is an encoding error, returns nil.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

stringWithContentsOfURL:usedEncoding:error:

Returns a string created by reading data from a given URL and returns by reference the encoding used to interpret the data.

+ (instancetype)stringWithContentsOfURL:(NSURL *)url usedEncoding:(NSStringEncoding *)enc error:(NSError **)error
Parameters
url

The URL from which to read data.

enc

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, you may pass in NULL.

Return Value

A string created by reading data from url. If the URL can’t be opened or there is an encoding error, returns nil.

Discussion

This method attempts to determine the encoding at url.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

stringWithCString:encoding:

Returns a string containing the bytes in a given C array, interpreted according to a given encoding.

+ (instancetype)stringWithCString:(const char *)cString encoding:(NSStringEncoding)enc
Parameters
cString

A C array of bytes. The array must end with a NULL byte; intermediate NULL bytes are not allowed.

enc

The encoding of cString.

Return Value

A string containing the characters described in cString.

Discussion

If cString is not a NULL-terminated C string, or encoding does not match the actual encoding, the results are undefined.

Special Considerations

Because NULL bytes are not allowed, 16-bit encodings are not supported because their content will typically include NULL bytes.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

stringWithFormat:

Returns a string created by using a given format string as a template into which the remaining argument values are substituted.

+ (instancetype)stringWithFormat:(NSString *)format,, ...
Parameters
format

A format string. See “Formatting String Objects” for examples of how to use this method, and “String Format Specifiers” for a list of format specifiers. This value must not be nil.

Important: Raises an NSInvalidArgumentException if format is nil.

...

A comma-separated list of arguments to substitute into format.

Return Value

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

Discussion

This method is similar to localizedStringWithFormat:, but using the canonical 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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

stringWithString:

Returns a string created by copying the characters from another given string.

+ (instancetype)stringWithString:(NSString *)aString
Parameters
aString

The string from which to copy characters. This value must not be nil.

Important: Raises an NSInvalidArgumentException if aString is nil.

Return Value

A string created by copying the characters from aString.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

stringWithUTF8String:

Returns a string created by copying the data from a given C array of UTF8-encoded bytes.

+ (instancetype)stringWithUTF8String:(const char *)bytes
Parameters
bytes

A NULL-terminated C array of bytes in UTF8 encoding.

Important: Raises an exception if bytes is NULL.

Return Value

A string created by copying the data from bytes.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

Instance Methods

boolValue

Returns the Boolean value of the receiver’s text.

- (BOOL)boolValue
Return Value

The Boolean value of the receiver’s text. Returns YES on encountering one of "Y", "y", "T", "t", or a digit 1-9—the method ignores any trailing characters. Returns NO if the receiver doesn’t begin with a valid decimal text representation of a number.

Discussion

The method 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.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
NSString.h

canBeConvertedToEncoding:

Returns a Boolean value that indicates whether the receiver can be converted to a given encoding without loss of information.

- (BOOL)canBeConvertedToEncoding:(NSStringEncoding)encoding
Parameters
encoding

A string encoding.

Return Value

YES if the receiver can be converted to encoding without loss of information. Returns NO 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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

capitalizedString

Returns a capitalized representation of the receiver.

- (NSString *)capitalizedString
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.

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

capitalizedStringWithLocale:

Returns a capitalized representation of the receiver using the specified locale.

- (NSString *)capitalizedStringWithLocale:(NSLocale *)locale
Parameters
locale

The locale. Passing nil indicates the system locale. For strings presented to users, use currentLocale.

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.

Availability
  • Available in iOS 6.0 and later.
Declared In
NSString.h

caseInsensitiveCompare:

Returns the result of invoking compare:options: with NSCaseInsensitiveSearch as the only option.

- (NSComparisonResult)caseInsensitiveCompare:(NSString *)aString
Parameters
aString

The string with which to compare the receiver.

This value must not be nil. If this value is nil, the behavior is undefined and may change in future versions of OS X.

Return Value

The result of invoking compare:options: with NSCaseInsensitiveSearch as the only option.

Discussion

If you are comparing strings to present to the end-user, you should typically use localizedCaseInsensitiveCompare: instead.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

characterAtIndex:

Returns the character at a given array position.

- (unichar)characterAtIndex:(NSUInteger)index
Parameters
index

The index of the character to retrieve. The index value must not lie outside the bounds of the receiver.

Return Value

The character at the array position given by index.

Discussion

Raises an NSRangeException if index lies beyond the end of the receiver.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

commonPrefixWithString:options:

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

- (NSString *)commonPrefixWithString:(NSString *)aString options:(NSStringCompareOptions)mask
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”.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

compare:

Returns the result of invoking compare:options:range: with no options and the receiver’s full extent as the range.

- (NSComparisonResult)compare:(NSString *)aString
Parameters
aString

The string with which to compare the receiver.

This value must not be nil. If this value is nil, the behavior is undefined and may change in future versions of OS X.

Return Value

The result of invoking compare:options:range: with no options and the receiver’s full extent as the range.

Discussion

If you are comparing strings to present to the end-user, you should typically use localizedCompare: or localizedCaseInsensitiveCompare: instead.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

compare:options:

Compares the string with the specified string using the given options.

- (NSComparisonResult)compare:(NSString *)aString options:(NSStringCompareOptions)mask
Parameters
aString

The string with which to compare the receiver.

This value must not be nil. If this value is nil, the behavior is undefined and may change in future versions of OS X.

mask

Options for the search—you can combine any of the following using a C bitwise OR operator: NSCaseInsensitiveSearch, NSLiteralSearch, NSNumericSearch. See String Programming Guide for details on these options.

Return Value

The result of invoking compare:options:range: with a given mask as the options and the receiver’s full extent as the range.

Discussion

If you are comparing strings to present to the end-user, you should typically use localizedCompare: or localizedCaseInsensitiveCompare: instead, or use compare:options:range:locale: and pass the user’s locale.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

compare:options:range:

Returns the result of invoking compare:options:range:locale: with a nil locale.

- (NSComparisonResult)compare:(NSString *)aString options:(NSStringCompareOptions)mask range:(NSRange)range
Parameters
aString

The string with which to compare the range of the receiver specified by range.

This value must not be nil. If this value is nil, the behavior is undefined and may change in future versions of OS X.

mask

Options for the search—you can combine any of the following using a C bitwise OR operator: NSCaseInsensitiveSearch, NSLiteralSearch, NSNumericSearch.

See String Programming Guide for details on these options.

range

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.

Return Value

The result of invoking compare:options:range:locale: with a nil locale.

Discussion

If you are comparing strings to present to the end-user, you should typically use compare:options:range:locale: instead and pass the user’s locale (currentLocale [NSLocale]).

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

compare:options:range:locale:

Compares the string using the specified options and returns the lexical ordering for the range.

- (NSComparisonResult)compare:(NSString *)aString options:(NSStringCompareOptions)mask range:(NSRange)range locale:(id)locale
Parameters
aString

The string with which to compare the range of the receiver specified by range.

This value must not be nil. If this value is nil, the behavior is undefined and may change in future versions of OS X.

mask

Options for the search—you can combine any of the following using a C bitwise OR operator: NSCaseInsensitiveSearch, NSLiteralSearch, NSNumericSearch.

See String Programming Guide for details on these options.

range

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. Passing nil causes the method to use the system locale. If you are comparing strings to present to the end-user, you should typically pass the user’s locale (-[NSLocale currentLocale]).

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.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

completePathIntoString:caseSensitive:matchesIntoArray:filterTypes:

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.

- (NSUInteger)completePathIntoString:(NSString **)outputName caseSensitive:(BOOL)flag matchesIntoArray:(NSArray **)outputArray filterTypes:(NSArray *)filterTypes
Parameters
outputName

Upon return, contains the longest path that matches the receiver.

flag

If YES, the methods considers case for possible completions.

outputArray

Upon return, contains all matching filenames.

filterTypes

An array of NSString objects specifying path extensions to consider for completion. only paths whose extensions (not including the extension separator) match one of those strings.

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
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

componentsSeparatedByCharactersInSet:

Returns an array containing substrings from the receiver that have been divided by characters in a given set.

- (NSArray *)componentsSeparatedByCharactersInSet:(NSCharacterSet *)separator
Parameters
separator

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

componentsSeparatedByString:

Returns an array containing substrings from the receiver that have been divided by a given separator.

- (NSArray *)componentsSeparatedByString:(NSString *)separator
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:

NSString *list = @"Karin, Carrie, David";
NSArray *listItems = [list componentsSeparatedByString:@", "];

produces an array { @"Karin", @"Carrie", @"David"" }.

If list begins with a comma and space—for example, @", Norman, Stanley, Fletcher"—the array has these contents: { @"", @"Karin", @"Carrie", @"David" }

If list has no separators—for example, "Karin"—the array contains the string itself, in this case { @"Karin" }.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

cStringUsingEncoding:

Returns a representation of the receiver as a C string using a given encoding.

- (const char *)cStringUsingEncoding:(NSStringEncoding)encoding
Parameters
encoding

The encoding for the returned C string.

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

Special Considerations

UTF16 and UTF32 are not considered to be C string encodings, and should not be used with this method—the results of passing NSUTF16StringEncoding, NSUTF32StringEncoding, or any of their variants are undefined.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

dataUsingEncoding:

Returns an NSData object containing a representation of the receiver encoded using a given encoding.

- (NSData *)dataUsingEncoding:(NSStringEncoding)encoding
Parameters
encoding

A string encoding.

Return Value

The result of invoking dataUsingEncoding:allowLossyConversion: with NO as the second argument (that is, requiring lossless conversion).

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

dataUsingEncoding:allowLossyConversion:

Returns an NSData object containing a representation of the receiver encoded using a given encoding.

- (NSData *)dataUsingEncoding:(NSStringEncoding)encoding allowLossyConversion:(BOOL)flag
Parameters
encoding

A string encoding.

flag

If YES, 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 NO and the receiver can’t be converted without losing some information (such as accents or case).

Discussion

If flag is YES 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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

decomposedStringWithCanonicalMapping

Returns a string made by normalizing the receiver’s contents using Form D.

- (NSString *)decomposedStringWithCanonicalMapping
Return Value

A string made by normalizing the receiver’s contents using the Unicode Normalization Form D.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

decomposedStringWithCompatibilityMapping

Returns a string made by normalizing the receiver’s contents using Form KD.

- (NSString *)decomposedStringWithCompatibilityMapping
Return Value

A string made by normalizing the receiver’s contents using the Unicode Normalization Form KD.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

description

Returns the receiver.

- (NSString *)description
Return Value

The receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

doubleValue

Returns the floating-point value of the receiver’s text as a double.

- (double)doubleValue
Return Value

The floating-point value of the receiver’s text as a double. Returns HUGE_VAL or –HUGE_VAL on overflow, 0.0 on underflow. Returns 0.0 if the receiver doesn’t begin with a valid text representation of a floating-point number.

Discussion

This method skips any whitespace at the beginning of the string. 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
  • Available in iOS 2.0 and later.
Declared In
NSString.h

enumerateLinesUsingBlock:

Enumerates all the lines in a string.

- (void)enumerateLinesUsingBlock:(void (^)(NSString *line, BOOL *stop))block
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.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSString.h

enumerateLinguisticTagsInRange:scheme:options:orthography:usingBlock:

Performs linguistic analysis on the specified string by enumerating the specific range of the string, providing the Block with the located tags.

- (void)enumerateLinguisticTagsInRange:(NSRange)range scheme:(NSString *)tagScheme options:(NSLinguisticTaggerOptions)opts orthography:(NSOrthography *)orthography usingBlock:(void (^)(NSString *tag, NSRange tokenRange, NSRange sentenceRange, BOOL *stop))block
Parameters
range

The range of the string to analyze.

tagScheme

The tag scheme to use. See Linguistic Tag Schemes for supported values.

opts

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 YES to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Discussion

This is a convenience method. It is the equivalent of creating an instance of NSLinguisticTagger, specifying the receiver as the string to be analyzed, and the orthography (or nil) and then invoking the NSLinguisticTagger method or enumerateTagsInRange:scheme:options:usingBlock:.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSLinguisticTagger.h

enumerateSubstringsInRange:options:usingBlock:

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

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

Availability
  • Available in iOS 4.0 and later.
Declared In
NSString.h

fastestEncoding

Returns the fastest encoding to which the receiver may be converted without loss of information.

- (NSStringEncoding)fastestEncoding
Return Value

The fastest encoding to which the receiver may be converted without loss of information.

Discussion

“Fastest” applies to retrieval of characters from the string. This encoding may not be space efficient.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

fileSystemRepresentation

Returns a file system-specific representation of the receiver.

- (const char *)fileSystemRepresentation
Return Value

A file system-specific representation of the receiver, as described for getFileSystemRepresentation:maxLength:.

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

To convert a char * path (such as you might get from a C library routine) to an NSString object, use NSFileManager‘s stringWithFileSystemRepresentation:length: method.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSPathUtilities.h

floatValue

Returns the floating-point value of the receiver’s text as a float.

- (float)floatValue
Return Value

The floating-point value of the receiver’s text as a float, skipping whitespace at the beginning of the string. Returns HUGE_VAL or –HUGE_VAL on overflow, 0.0 on underflow. Also returns 0.0 if the receiver doesn’t begin with a valid text representation of a floating-point number.

Discussion

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
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

getBytes:maxLength:usedLength:encoding:options:range:remainingRange:

Gets a given range of characters as bytes in a specified encoding.

- (BOOL)getBytes:(void *)buffer maxLength:(NSUInteger)maxBufferCount usedLength:(NSUInteger *)usedBufferCount encoding:(NSStringEncoding)encoding options:(NSStringEncodingConversionOptions)options range:(NSRange)range remainingRange:(NSRangePointer)leftover
Parameters
buffer

A buffer into which to store the bytes from the receiver. The returned bytes are not NULL-terminated.

maxBufferCount

The maximum number of bytes to write to buffer.

usedBufferCount

The number of bytes used from buffer. Pass NULL if you do not need this value.

encoding

The encoding to use for the returned bytes.

options

A mask to specify options to use for converting the receiver’s contents to encoding (if conversion is necessary).

range

The range of characters in the receiver to get.

leftover

The remaining range. Pass NULL If you do not need this value.

Return Value

YES if some characters were converted, otherwise NO.

Discussion

Conversion might stop when the buffer fills, but it might also stop when the conversion isn't possible due to the chosen encoding.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

getCharacters:range:

Copies characters from a given range in the receiver into a given buffer.

- (void)getCharacters:(unichar *)buffer range:(NSRange)aRange
Parameters
buffer

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

getCString:maxLength:encoding:

Converts the receiver’s content to a given encoding and stores them in a buffer.

- (BOOL)getCString:(char *)buffer maxLength:(NSUInteger)maxBufferCount encoding:(NSStringEncoding)encoding
Parameters
buffer

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

YES if the operation was successful, otherwise NO. Returns NO 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
  • Available in iOS 2.0 and later.
Declared In
NSString.h

getFileSystemRepresentation:maxLength:

Interprets the receiver as a system-independent path and fills a buffer with a C-string in a format and encoding suitable for use with file-system calls.

- (BOOL)getFileSystemRepresentation:(char *)buffer maxLength:(NSUInteger)maxLength
Parameters
buffer

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

YES if buffer is successfully filled with a file-system representation, otherwise NO (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.

char filenameBuffer[13];
BOOL success;
success = [@"/mach_kernel" getFileSystemRepresentation:filenameBuffer maxLength:12];
// success == NO
// Changing the length to include the NULL character does work
success = [@"/mach_kernel" getFileSystemRepresentation:filenameBuffer maxLength:13];
// success == YES
Availability
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

getLineStart:end:contentsEnd:forRange:

Returns by reference the beginning of the first line and the end of the last line touched by the given range.

- (void)getLineStart:(NSUInteger *)startIndex end:(NSUInteger *)lineEndIndex contentsEnd:(NSUInteger *)contentsEndIndex forRange:(NSRange)aRange
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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

getParagraphStart:end:contentsEnd:forRange:

Returns by reference the beginning of the first paragraph and the end of the last paragraph touched by the given range.

- (void)getParagraphStart:(NSUInteger *)startIndex end:(NSUInteger *)endIndex contentsEnd:(NSUInteger *)contentsEndIndex forRange:(NSRange)aRange
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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

hash

Returns an unsigned integer that can be used as a hash table address.

- (NSUInteger)hash
Return Value

An unsigned integer that can be used as a hash table address.

Discussion

If two string objects are equal (as determined by the isEqualToString: method), they must have the same hash value. The abstract implementation of this method fulfills this requirement, so subclasses of NSString shouldn’t override it.

You should not rely on this method returning the same hash value across releases of OS X.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

hasPrefix:

Returns a Boolean value that indicates whether a given string matches the beginning characters of the receiver.

- (BOOL)hasPrefix:(NSString *)aString
Parameters
aString

A string.

Return Value

YES if aString matches the beginning characters of the receiver, otherwise NO. Returns NO if aString is empty.

Discussion

This method is a convenience for comparing strings using the NSAnchoredSearch option. See String Programming Guide for more information.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

hasSuffix:

Returns a Boolean value that indicates whether a given string matches the ending characters of the receiver.

- (BOOL)hasSuffix:(NSString *)aString
Parameters
aString

A string.

Return Value

YES if aString matches the ending characters of the receiver, otherwise NO. Returns NO if aString is empty.

Discussion

This method is a convenience for comparing strings using the NSAnchoredSearch and NSBackwardsSearch options. See String Programming Guide for more information.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

init

Returns an initialized NSString object that contains no characters.

- (instancetype)init
Return Value

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

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSString.h

initWithBytes:length:encoding:

Returns an initialized NSString object containing a given number of bytes from a given buffer of bytes interpreted in a given encoding.

- (instancetype)initWithBytes:(const void *)bytes length:(NSUInteger)length encoding:(NSStringEncoding)encoding
Parameters
bytes

A buffer of bytes interpreted in the encoding specified by encoding.

length

The number of bytes to use from bytes.

encoding

The character encoding applied to bytes.

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.

The return byte strings are allowed to be unterminated.

If the length of the byte string is greater than the specified length a nil value is returned.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithBytesNoCopy:length:encoding:freeWhenDone:

Returns an initialized NSString object that contains a given number of bytes from a given buffer of bytes interpreted in a given encoding, and optionally frees the buffer.

- (instancetype)initWithBytesNoCopy:(void *)bytes length:(NSUInteger)length encoding:(NSStringEncoding)encoding freeWhenDone:(BOOL)flag
Parameters
bytes

A buffer of bytes interpreted in the encoding specified by encoding.

length

The number of bytes to use from bytes.

encoding

The character encoding of bytes.

flag

If YES, the receiver frees the memory when it no longer needs the data; if NO 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 YES. 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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithCharacters:length:

Returns an initialized NSString object that contains a given number of characters from a given C array of Unicode characters.

- (instancetype)initWithCharacters:(const unichar *)characters length:(NSUInteger)length
Parameters
characters

A C array of Unicode characters; the value must not be NULL.

Important: Raises an exception if characters is NULL, even if length is 0.

length

The number of characters to use from characters.

Return Value

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithCharactersNoCopy:length:freeWhenDone:

Returns an initialized NSString object that contains a given number of characters from a given C array of Unicode characters.

- (instancetype)initWithCharactersNoCopy:(unichar *)characters length:(NSUInteger)length freeWhenDone:(BOOL)flag
Parameters
characters

A C array of Unicode characters.

length

The number of characters to use from characters.

flag

If YES, the receiver will free the memory when it no longer needs the characters; if NO 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 YES. 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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithContentsOfFile:encoding:error:

Returns an NSString object initialized by reading data from the file at a given path using a given encoding.

- (instancetype)initWithContentsOfFile:(NSString *)path encoding:(NSStringEncoding)enc error:(NSError **)error
Parameters
path

A path to a file.

enc

The encoding of the file at path.

error

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithContentsOfFile:usedEncoding:error:

Returns an NSString object initialized by reading data from the file at a given path and returns by reference the encoding used to interpret the characters.

- (instancetype)initWithContentsOfFile:(NSString *)path usedEncoding:(NSStringEncoding *)enc error:(NSError **)error
Parameters
path

A path to a file.

enc

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithContentsOfURL:encoding:error:

Returns an NSString object initialized by reading data from a given URL interpreted using a given encoding.

- (instancetype)initWithContentsOfURL:(NSURL *)url encoding:(NSStringEncoding)enc error:(NSError **)error
Parameters
url

The URL to read.

enc

The encoding of 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 url. The returned object may be different from the original receiver. If the URL can’t be opened or there is an encoding error, returns nil.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithContentsOfURL:usedEncoding:error:

Returns an NSString object initialized by reading data from a given URL and returns by reference the encoding used to interpret the data.

- (instancetype)initWithContentsOfURL:(NSURL *)url usedEncoding:(NSStringEncoding *)enc error:(NSError **)error
Parameters
url

The URL from which to read data.

enc

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithCString:encoding:

Returns an NSString object initialized using the characters in a given C array, interpreted according to a given encoding.

- (instancetype)initWithCString:(const char *)nullTerminatedCString encoding:(NSStringEncoding)encoding
Parameters
nullTerminatedCString

A C array of characters. The array must end with a NULL character; intermediate NULL characters are not allowed.

encoding

The encoding of nullTerminatedCString.

Return Value

An NSString object initialized using the characters from nullTerminatedCString. The returned object may be different from the original receiver

Discussion

If nullTerminatedCString is not a NULL-terminated C string, or encoding does not match the actual encoding, the results are undefined.

Special Considerations

Because NULL bytes are not allowed, 16-bit encodings are not supported because their content will typically include NULL bytes.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithData:encoding:

Returns an NSString object initialized by converting given data into Unicode characters using a given encoding.

- (instancetype)initWithData:(NSData *)data encoding:(NSStringEncoding)encoding
Parameters
data

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithFormat:

Returns an NSString object initialized by using a given format string as a template into which the remaining argument values are substituted.

- (instancetype)initWithFormat:(NSString *)format, ...
Parameters
format

A format string. See “Formatting String Objects” for examples of how to use this method, and “String Format Specifiers” for a list of format specifiers. This value must not be nil.

Important: Raises an NSInvalidArgumentException if format is nil.

...

A comma-separated list of arguments to substitute into format.

Return Value

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

Discussion

Invokes initWithFormat:locale:arguments: with nil as the locale, hence using the canonical 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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithFormat:arguments:

Returns an NSString object initialized by using a given format string as a template into which the remaining argument values are substituted according to the user’s default locale.

- (instancetype)initWithFormat:(NSString *)format arguments:(va_list)argList
Parameters
format

A format string. See “Formatting String Objects” for examples of how to use this method, and “String Format Specifiers” for a list of format specifiers. This value must not be nil.

Important: Raises an NSInvalidArgumentException if format is nil.

argList

A list of arguments to substitute into format.

Return Value

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

Discussion

Invokes initWithFormat:locale:arguments: with nil as the locale.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithFormat:locale:

Returns an NSString object initialized by using a given format string as a template into which the remaining argument values are substituted according to given locale information.

- (instancetype)initWithFormat:(NSString *)format locale:(id)locale, ...
Parameters
format

A format string. See “Formatting String Objects” for examples of how to use this method, and “String Format Specifiers” for a list of format specifiers. This value must not be nil.

Important: Raises an NSInvalidArgumentException if format is nil.

locale

An NSLocale object specifying the locale to use. If nil, uses the system locale.

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

...

A comma-separated list of arguments to substitute into format.

Discussion

Invokes initWithFormat:locale:arguments: with locale as the locale.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithFormat:locale:arguments:

Returns an NSString object initialized by using a given format string as a template into which the remaining argument values are substituted according to given locale information.

- (instancetype)initWithFormat:(NSString *)format locale:(id)locale arguments:(va_list)argList
Parameters
format

A format string. See “Formatting String Objects” for examples of how to use this method, and “String Format Specifiers” for a list of format specifiers. This value must not be nil.

Important: Raises an NSInvalidArgumentException if format is nil.

locale

An NSLocale object specifying the locale to use. If nil, uses the system locale.

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:

va_list myArgs;
 
NSString *myString = [[NSString alloc] initWithFormat:@"%@:  %d\n"
        locale:[NSLocale currentLocale]
        arguments:myArgs];

The resulting string has the value “Cost: 32\n”.

See String Programming Guide for more information.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithString:

Returns an NSString object initialized by copying the characters from another given string.

- (instancetype)initWithString:(NSString *)aString
Parameters
aString

The string from which to copy characters. This value must not be nil.

Important: Raises an NSInvalidArgumentException if aString is nil.

Return Value

An NSString object initialized by copying the characters from aString. The returned object may be different from the original receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

initWithUTF8String:

Returns an NSString object initialized by copying the characters from a given C array of UTF8-encoded bytes.

- (instancetype)initWithUTF8String:(const char *)bytes
Parameters
bytes

A NULL-terminated C array of bytes in UTF-8 encoding. This value must not be NULL.

Important: Raises an exception if bytes is NULL.

Return Value

An NSString object initialized by copying the bytes from bytes. The returned object may be different from the original receiver.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

integerValue

Returns the NSInteger value of the receiver’s text.

- (NSInteger)integerValue
Return Value

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

Discussion

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
  • Available in iOS 2.0 and later.
Declared In
NSString.h

intValue

Returns the integer value of the receiver’s text.

- (int)intValue
Return Value

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

Discussion

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

Special Considerations

On OS X v10.5 and later, use integerValue instead.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

isAbsolutePath

Returning a Boolean value that indicates whether the receiver represents an absolute path.

- (BOOL)isAbsolutePath
Return Value

YES if the receiver (if interpreted as a path) represents an absolute path, otherwise NO (if the receiver represents a relative path).

Discussion

See String Programming Guide for more information on paths.

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

isEqualToString:

Returns a Boolean value that indicates whether a given string is equal to the receiver using a literal Unicode-based comparison.

- (BOOL)isEqualToString:(NSString *)aString
Parameters
aString

The string with which to compare the receiver.

Return Value

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

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

lastPathComponent

Returns the last path component of the receiver.

- (NSString *)lastPathComponent
Return Value

The last path component of the receiver.

Discussion

Path components are alphanumeric strings delineated by the path separator (slash “/”) or the beginning or end of the path string. Multiple path separators at the end of the string are stripped.

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

Receiver’s String Value

String Returned

/tmp/scratch.tiff

scratch.tiff

/tmp/scratch

scratch

/tmp/

tmp

scratch///

scratch

/

“/”

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

length

Returns the number of Unicode characters in the receiver.

- (NSUInteger)length
Return Value

The number of Unicode characters in the receiver.

Discussion

The number returned includes the individual characters of composed character sequences, so you cannot use this method to determine if a string will be visible when printed or how long it will appear.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

lengthOfBytesUsingEncoding:

Returns the number of bytes required to store the receiver in a given encoding.

- (NSUInteger)lengthOfBytesUsingEncoding:(NSStringEncoding)enc
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.

Discussion

The result is exact and is returned in O(n) time.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

lineRangeForRange:

Returns the range of characters representing the line or lines containing a given range.

- (NSRange)lineRangeForRange:(NSRange)aRange
Parameters
aRange

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

Return Value

The range of characters representing the line or lines containing aRange, including the line termination characters. See getLineStart:end:contentsEnd:forRange: for a discussion of line terminators.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

linguisticTagsInRange:scheme:options:orthography:tokenRanges:

Returns an array of linguistic tags for the specified range and requested tags within the receiving string.

- (NSArray *)linguisticTagsInRange:(NSRange)range scheme:(NSString *)tagScheme options:(NSLinguisticTaggerOptions)opts orthography:(NSOrthography *)orthography tokenRanges:(NSArray **)tokenRanges
Parameters
range

The range of the string to analyze.

tagScheme

The tag scheme to use. See Linguistic Tag Schemes for supported values.

opts

The linguistic tagger options to use. See NSLinguisticTaggerOptions for 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.

tokenRanges

An array returned by-reference containing the token ranges of the linguistic tags wrapped in NSValue objects.

Return Value

Returns an array containing the linguistic tags for the tokenRanges within the receiving string.

Discussion

This is a convenience method. It is the equivalent of creating an instance of NSLinguisticTagger, specifying the receiver as the string to be analyzed, and the orthography (or nil) and then invoking the NSLinguisticTagger method or linguisticTagsInRange:scheme:options:orthography:tokenRanges:.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSLinguisticTagger.h

localizedCaseInsensitiveCompare:

Compares the string and a given string using a case-insensitive, localized, comparison.

- (NSComparisonResult)localizedCaseInsensitiveCompare:(NSString *)aString
Parameters
aString

The string with which to compare the receiver.

This value must not be nil. If this value is nil, the behavior is undefined and may change in future versions of OS X.

Return Value

Returns an NSComparisonResult value that indicates the lexical ordering. NSOrderedAscending the receiver precedes aString in lexical ordering, NSOrderedSame the receiver and aString are equivalent in lexical value, and NSOrderedDescending if the receiver follows aString.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

localizedCompare:

Compares the string and a given string using a localized comparison.

- (NSComparisonResult)localizedCompare:(NSString *)aString
Parameters
aString

The string with which to compare the receiver.

This value must not be nil. If this value is nil, the behavior is undefined and may change in future versions of OS X.

Return Value

Returns an NSComparisonResult. NSOrderedAscending the receiver precedes string in lexical ordering, NSOrderedSame the receiver and string are equivalent in lexical value, and NSOrderedDescending if the receiver follows string.

Discussion

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

localizedStandardCompare:

Compares strings as sorted by the Finder.

- (NSComparisonResult)localizedStandardCompare:(NSString *)string
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.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSString.h

longLongValue

Returns the long long value of the receiver’s text.

- (long long)longLongValue
Return Value

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

Discussion

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
  • Available in iOS 2.0 and later.
Declared In
NSString.h

lowercaseString

Returns lowercased representation of the receiver.

- (NSString *)lowercaseString
Return Value

A string with each character from the receiver changed to its corresponding lowercase value.

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 = [myString lowercaseString];

might not be equal to this statement:

lcString = [[myString uppercaseString] 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”

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

lowercaseStringWithLocale:

Returns a version of the string with all letters converted to lowercase, taking into account the specified locale.

- (NSString *)lowercaseStringWithLocale:(NSLocale *)locale
Parameters
locale

The locale. Passing nil indicates the system locale. For strings presented to users, use currentLocale.

Return Value

A lowercase string using the locale. Input of @"ABcde" would result in a return of @"abcde".

Discussion

.

Availability
  • Available in iOS 6.0 and later.
Declared In
NSString.h

maximumLengthOfBytesUsingEncoding:

Returns the maximum number of bytes needed to store the receiver in a given encoding.

- (NSUInteger)maximumLengthOfBytesUsingEncoding:(NSStringEncoding)enc
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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

paragraphRangeForRange:

Returns the range of characters representing the paragraph or paragraphs containing a given range.

- (NSRange)paragraphRangeForRange:(NSRange)aRange
Parameters
aRange

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

Return Value

The range of characters representing the paragraph or paragraphs containing aRange, including the paragraph termination characters.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

pathComponents

Returns an array of NSString objects containing, in order, each path component of the receiver.

- (NSArray *)pathComponents
Return Value

An array of NSString objects containing, in order, each path component of the receiver.

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 = [path pathComponents];

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

pathExtension

Interprets the receiver as a path and returns the receiver’s extension, if any.

- (NSString *)pathExtension
Return Value

The receiver’s extension, if any (not including the extension divider).

Discussion

The path extension is the portion of the last path component which follows the final period, if there is one. 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).

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

precomposedStringWithCanonicalMapping

Returns a string made by normalizing the receiver’s contents using Form C.

- (NSString *)precomposedStringWithCanonicalMapping
Return Value

A string made by normalizing the receiver’s contents using the Unicode Normalization Form C.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

precomposedStringWithCompatibilityMapping

Returns a string made by normalizing the receiver’s contents using Form KC.

- (NSString *)precomposedStringWithCompatibilityMapping
Return Value

A string made by normalizing the receiver’s contents using the Unicode Normalization Form KC.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

propertyList

Parses the receiver as a text representation of a property list, returning an NSString, NSData, NSArray, or NSDictionary object, according to the topmost element.

- (id)propertyList
Return Value

A property list representation of returning an NSString, NSData, NSArray, or NSDictionary object, according to the topmost element.

Discussion

The receiver must contain a string in a property list format. For a discussion of property list formats, see Property List Programming Guide.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

propertyListFromStringsFileFormat

Returns a dictionary object initialized with the keys and values found in the receiver.

- (NSDictionary *)propertyListFromStringsFileFormat
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:

/* Question in confirmation panel for quitting. */
"Confirm Quit" = "Are you sure you want to quit?";
 
/* Message when user tries to close unsaved document */
"Close or Save" = "Save changes before closing?";
 
/* Word for Cancel */
"Cancel";
Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

rangeOfCharacterFromSet:

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

- (NSRange)rangeOfCharacterFromSet:(NSCharacterSet *)aSet
Parameters
aSet

A character set. This value must not be nil.

Raises an NSInvalidArgumentException if aSet is nil.

Return Value

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

Discussion

Invokes rangeOfCharacterFromSet:options: with no options.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

rangeOfCharacterFromSet:options:

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

- (NSRange)rangeOfCharacterFromSet:(NSCharacterSet *)aSet options:(NSStringCompareOptions)mask
Parameters
aSet

A character set. This value must not be nil.

Raises an NSInvalidArgumentException if aSet is nil.

mask

A mask specifying search options. The following options may be specified by combining them with the C bitwise OR operator: NSAnchoredSearch, NSBackwardsSearch.

Return Value

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

Discussion

Invokes rangeOfCharacterFromSet:options:range: with mask for the options and the entire extent of the receiver for the range.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

rangeOfCharacterFromSet:options:range:

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

- (NSRange)rangeOfCharacterFromSet:(NSCharacterSet *)aSet options:(NSStringCompareOptions)mask range:(NSRange)aRange
Parameters
aSet

A character set. This value must not be nil.

Raises an NSInvalidArgumentException if aSet is nil.

mask

A mask specifying search options. The following options may be specified by combining them with the C bitwise OR operator: NSAnchoredSearch, NSBackwardsSearch.

aRange

The range in which to search. aRange must not exceed the bounds of the receiver.

Raises an NSRangeException if aRange is invalid.

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

rangeOfComposedCharacterSequenceAtIndex:

Returns the range in the receiver of the composed character sequence located at a given index.

- (NSRange)rangeOfComposedCharacterSequenceAtIndex:(NSUInteger)anIndex
Parameters
anIndex

The index of a character in the receiver. The value must not exceed the bounds of the receiver.

Return Value

The range in the receiver of the composed character sequence located at anIndex.

Discussion

The composed character sequence includes the first base character found at or before anIndex, and its length includes the base character and all non-base characters following the base character.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

rangeOfComposedCharacterSequencesForRange:

Returns the range in the string of the composed character sequences for a given range.

- (NSRange)rangeOfComposedCharacterSequencesForRange:(NSRange)range
Parameters
range

A range in the receiver. The range must not exceed the bounds of the receiver.

Return Value

The range in the receiver that includes the composed character sequences in range.

Discussion

This method provides a convenient way to grow a range to include all composed character sequences it overlaps.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

rangeOfString:

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

- (NSRange)rangeOfString:(NSString *)aString
Parameters
aString

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

Raises an NSInvalidArgumentException if aString is nil.

Return Value

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

Discussion

Invokes rangeOfString:options: with no options.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

rangeOfString:options:

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

- (NSRange)rangeOfString:(NSString *)aString options:(NSStringCompareOptions)mask
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 (@"").

Discussion

Invokes rangeOfString:options:range: with the options specified by mask and the entire extent of the receiver as the range.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

rangeOfString:options:range:

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

- (NSRange)rangeOfString:(NSString *)aString options:(NSStringCompareOptions)mask range:(NSRange)aRange
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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

rangeOfString:options:range:locale:

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

- (NSRange)rangeOfString:(NSString *)aString options:(NSStringCompareOptions)mask range:(NSRange)searchRange locale:(NSLocale *)locale
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.

locale

The locale to use when comparing the receiver with aString. If this value is nil, uses the system locale.

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

smallestEncoding

Returns the smallest encoding to which the receiver can be converted without loss of information.

- (NSStringEncoding)smallestEncoding
Return Value

The smallest encoding to which the receiver can be converted without loss of information.

Discussion

The returned encoding may not be the fastest for accessing characters, but is space-efficient. This method may take some time to execute.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

stringByAbbreviatingWithTildeInPath

Returns a new string that replaces the current home directory portion of the current path with a tilde (~) character.

- (NSString *)stringByAbbreviatingWithTildeInPath
Return Value

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.

Discussion

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

stringByAddingPercentEncodingWithAllowedCharacters:

Returns a new string made from the receiver by replacing all characters not in the specified set with percent encoded characters.

- (NSString *)stringByAddingPercentEncodingWithAllowedCharacters:(NSCharacterSet *)allowedCharacters
Parameters
allowedCharacters

The characters not replaced in the string.

Return Value

Returns the encoded string or nil if the transformation is not possible.

Discussion

UTF-8 encoding is used to determine the correct percent encoded characters. Entire URL strings cannot be percent-encoded.

This method is intended to percent-encode an URL component or subcomponent string, NOT the entire URL string. Any characters in allowedCharacters outside of the 7-bit ASCII range are ignored.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURL.h

stringByAddingPercentEscapesUsingEncoding:

Returns a representation of the receiver using a given encoding to determine the percent escapes necessary to convert the receiver into a legal URL string.

- (NSString *)stringByAddingPercentEscapesUsingEncoding:(NSStringEncoding)encoding
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.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSURL.h

stringByAppendingFormat:

Returns a string made by appending to the receiver a string constructed from a given format string and the following arguments.

- (NSString *)stringByAppendingFormat:(NSString *)format, ...
Parameters
format

A format string. See “Formatting String Objects” for more information. This value must not be nil.

Important: Raises an NSInvalidArgumentException if format is nil.

...

A comma-separated list of arguments to substitute into format.

Return Value

A string made by appending to the receiver a string constructed from format and the following arguments, in the manner of stringWithFormat:.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

stringByAppendingPathComponent:

Returns a new string made by appending to the receiver a given string.

- (NSString *)stringByAppendingPathComponent:(NSString *)aString
Parameters
aString

The path component to append to the receiver.

Return Value

A new string made by appending aString to the receiver, preceded if necessary by a path separator.

Discussion

The following table illustrates the effect of this method on a variety of different paths, assuming that aString is supplied as “scratch.tiff”:

Receiver’s String Value

Resulting String

/tmp

/tmp/scratch.tiff

/tmp/

/tmp/scratch.tiff

/

/scratch.tiff

“” (an empty string)

scratch.tiff

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

stringByAppendingPathExtension:

Returns a new string made by appending to the receiver an extension separator followed by a given extension.

- (NSString *)stringByAppendingPathExtension:(NSString *)ext
Parameters
ext

The extension to append to the receiver.

Return Value

A new string made by appending to the receiver an extension separator followed by ext.

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 (~).

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSPathUtilities.h

stringByAppendingString:

Returns a new string made by appending a given string to the receiver.

- (NSString *)stringByAppendingString:(NSString *)aString
Parameters
aString

The string to append to the receiver. This value must not be nil.

Important: Raises an NSInvalidArgumentException if aString is nil.

Return Value

A new string made by appending aString to the receiver.

Discussion

This code excerpt, for example:

NSString *errorTag = @"Error: ";
NSString *errorString = @"premature end of file.";
NSString *errorMessage = [errorTag stringByAppendingString:errorString];

produces the string “Error: premature end of file.”.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

stringByDeletingLastPathComponent

Returns a new string made by deleting the last path component from the receiver, along with any final path separator.

- (NSString *)stringByDeletingLastPathComponent
Return Value

A new string made by deleting the last path component from the receiver, along with any final path separator. If the receiver represents the root path it is returned unaltered.

Discussion

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

/tmp/lock/

/tmp

/tmp/

/

/tmp

/

/

/

scratch.tiff

“” (an empty string)

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

stringByDeletingPathExtension

Returns a new string made by deleting the extension (if any, and only the last) from the receiver.

- (NSString *)stringByDeletingPathExtension
Return Value

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.

Discussion

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

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSPathUtilities.h

stringByExpandingTildeInPath

Returns a new string made by expanding the initial component of the receiver to its full path value.

- (NSString *)stringByExpandingTildeInPath
Return Value

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.

Discussion

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

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSPathUtilities.h

stringByFoldingWithOptions:locale:

Returns a string with the given character folding options applied.

- (NSString *)stringByFoldingWithOptions:(NSStringCompareOptions)options locale:(NSLocale *)locale
Parameters
options

A mask of compare flags with a suffix InsensitiveSearch.

locale

The locale to use for the folding. If this value is nil, uses the system locale.

Return Value

A string with the character folding options applied.

Discussion

Character folding operations remove distinctions between characters. For example, case folding may replace uppercase letters with their lowercase equivalents.

The locale affects the folding logic. 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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

stringByPaddingToLength:withString:startingAtIndex:

Returns a new string formed from the receiver by either removing characters from the end, or by appending as many occurrences as necessary of a given pad string.

- (NSString *)stringByPaddingToLength:(NSUInteger)newLength withString:(NSString *)padString startingAtIndex:(NSUInteger)padIndex
Parameters
newLength

The new length for the receiver.

padString

The string with which to extend the receiver.

padIndex

The index in padString from which to start padding.

Return Value

A new string formed from the receiver by either removing characters from the end, or by appending as many occurrences of padString as necessary.

Discussion

Here are some examples of usage:

[@"abc" stringByPaddingToLength: 9 withString: @"." startingAtIndex:0];
    // Results in "abc......"
[@"abc" stringByPaddingToLength: 2 withString: @"." startingAtIndex:0];
    // Results in "ab"
[@"abc" stringByPaddingToLength: 9 withString: @". " startingAtIndex:1];
    // Results in "abc . . ."
    // Notice that the first character in the padding is " "
Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

stringByRemovingPercentEncoding

Returns a new string made from the receiver by replacing all percent encoded sequences with the matching UTF-8 characters.

- (NSString *)stringByRemovingPercentEncoding
Return Value

A new string with the percent encoded sequences removed.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSURL.h

stringByReplacingCharactersInRange:withString:

Returns a new string in which the characters in a specified range of the receiver are replaced by a given string.

- (NSString *)stringByReplacingCharactersInRange:(NSRange)range withString:(NSString *)replacement
Parameters
range

A range of characters in the receiver.

replacement

The string with which to replace the characters in range.

Return Value

A new string in which the characters in range of the receiver are replaced by replacement.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

stringByReplacingOccurrencesOfString:withString:

Returns a new string in which all occurrences of a target string in the receiver are replaced by another given string.

- (NSString *)stringByReplacingOccurrencesOfString:(NSString *)target withString:(NSString *)replacement
Parameters
target

The string to replace.

replacement

The string with which to replace target.

Return Value

A new string in which all occurrences of target in the receiver are replaced by replacement.

Discussion

Invokes stringByReplacingOccurrencesOfString:withString:options:range:with 0 options and range of the whole string.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

stringByReplacingOccurrencesOfString:withString:options:range:

Returns a new string in which all occurrences of a target string in a specified range of the receiver are replaced by another given string.

- (NSString *)stringByReplacingOccurrencesOfString:(NSString *)target withString:(NSString *)replacement options:(NSStringCompareOptions)options range:(NSRange)searchRange
Parameters
target

The string to replace.

replacement

The string with which to replace target.

options

A mask of options to use when comparing target with the receiver. Pass 0 to specify no options.

searchRange

The range in the receiver in which to search for target.

Return Value

A new string in which all occurrences of target, matched using options, in searchRange of the receiver are replaced by replacement.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

stringByReplacingPercentEscapesUsingEncoding:

Returns a new string made by replacing in the receiver all percent escapes with the matching characters as determined by a given encoding.

- (NSString *)stringByReplacingPercentEscapesUsingEncoding:(NSStringEncoding)encoding
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.

Discussion

See CFURLCreateStringByReplacingPercentEscapes for more complex transformations.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSURL.h

stringByResolvingSymlinksInPath

Returns a new string made from the receiver by resolving all symbolic links and standardizing path.

- (NSString *)stringByResolvingSymlinksInPath
Return Value

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.

Discussion

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

stringByStandardizingPath

Returns a new string made by removing extraneous path components from the receiver.

- (NSString *)stringByStandardizingPath
Return Value

A new string made by removing extraneous path components from the receiver.

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.

This method can make the following changes in the provided string:

  • Expand an initial tilde expression using stringByExpandingTildeInPath.

  • 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).

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

stringByTrimmingCharactersInSet:

Returns a new string made by removing from both ends of the receiver characters contained in a given character set.

- (NSString *)stringByTrimmingCharactersInSet:(NSCharacterSet *)set
Parameters
set

A character set containing the characters to remove from the receiver. set must not be nil.

Return Value

A new string made by removing from both ends of the receiver characters contained in set. If the receiver is composed entirely of characters from set, the empty string is returned.

Discussion

Use whitespaceCharacterSet or whitespaceAndNewlineCharacterSet to remove whitespace around strings.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

stringsByAppendingPaths:

Returns an array of strings made by separately appending to the receiver each string in in a given array.

- (NSArray *)stringsByAppendingPaths:(NSArray *)paths
Parameters
paths

An array of NSString objects specifying paths to add to the receiver.

Return Value

An array of NSString objects made by separately appending each string in paths to the receiver, preceded if necessary by a path separator.

Discussion

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

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPathUtilities.h

substringFromIndex:

Returns a new string containing the characters of the receiver from the one at a given index to the end.

- (NSString *)substringFromIndex:(NSUInteger)anIndex
Parameters
anIndex

An index. The value must lie within the bounds of the receiver, or be equal to the length of the receiver.

Raises an NSRangeException if (anIndex - 1) lies beyond the end of the receiver.

Return Value

A new string containing the characters of the receiver from the one at anIndex to the end. If anIndex is equal to the length of the string, returns an empty string.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

substringToIndex:

Returns a new string containing the characters of the receiver up to, but not including, the one at a given index.

- (NSString *)substringToIndex:(NSUInteger)anIndex
Parameters
anIndex

An index. The value must lie within the bounds of the receiver, or be equal to the length of the receiver.

Raises an NSRangeException if (anIndex - 1) lies beyond the end of the receiver.

Return Value

A new string containing the characters of the receiver up to, but not including, the one at anIndex. If anIndex is equal to the length of the string, returns a copy of the receiver.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

substringWithRange:

Returns a string object containing the characters of the receiver that lie within a given range.

- (NSString *)substringWithRange:(NSRange)aRange
Parameters
aRange

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

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

uppercaseString

Returns a uppercased representation of the receiver.

- (NSString *)uppercaseString
Return Value

A string with each character from the receiver changed to its corresponding uppercase value.

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

uppercaseStringWithLocale:

Returns a version of the string with all letters converted to uppercase, taking into account the specified locale.

- (NSString *)uppercaseStringWithLocale:(NSLocale *)locale
Parameters
locale

The locale. Passing nil indicates the system locale. For strings presented to users, use currentLocale.

Return Value

An uppercase string using the locale. Input of @"ABcde" would result in a return of @"ABCDE".

Discussion

For the user preference locale setting, pass the result of the NSLocale method currentLocale.

Availability
  • Available in iOS 6.0 and later.
Declared In
NSString.h

UTF8String

Returns a null-terminated UTF8 representation of the receiver.

- (const char *)UTF8String
Return Value

A null-terminated UTF8 representation of the receiver.

Discussion

The returned 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 called this method.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

writeToFile:atomically:encoding:error:

Writes the contents of the receiver to a file at a given path using a given encoding.

- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile encoding:(NSStringEncoding)enc error:(NSError **)error
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 YES, the receiver is written to an auxiliary file, and then the auxiliary file is renamed to path. If NO, the receiver is written directly to path. The YES 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

YES if the file is written successfully, otherwise NO (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:

MACINTOSH;0
UTF-8;134217984
UTF-8;
;3071

The methods initWithContentsOfFile:usedEncoding:error:, initWithContentsOfURL:usedEncoding:error:, stringWithContentsOfFile:usedEncoding:error:, and stringWithContentsOfURL:usedEncoding:error: use this information to open the file using the right encoding.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

writeToURL:atomically:encoding:error:

Writes the contents of the receiver to the URL specified by url using the specified encoding.

- (BOOL)writeToURL:(NSURL *)url atomically:(BOOL)useAuxiliaryFile encoding:(NSStringEncoding)enc error:(NSError **)error
Parameters
url

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

useAuxiliaryFile

If YES, the receiver is written to an auxiliary file, and then the auxiliary file is renamed to url. If NO, the receiver is written directly to url. The YES 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

YES if the URL is written successfully, otherwise NO (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:

MACINTOSH;0
UTF-8;134217984
UTF-8;
;3071

The methods initWithContentsOfFile:usedEncoding:error:, initWithContentsOfURL:usedEncoding:error:, stringWithContentsOfFile:usedEncoding:error:, and stringWithContentsOfURL:usedEncoding:error: use this information to open the file using the right encoding.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

Constants

unichar

Type for Unicode characters.

typedef unsigned short unichar;
Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

NSMaximumStringLength

A constant to define the maximum number of characters in an NSString object. (Deprecated. This constant is not available in OS X v10.5 and later.)

#define NSMaximumStringLength (INT_MAX-1)
Constants
NSMaximumStringLength

Maximum number of characters in an NSString object.

Available in iOS 5.0 and later.

Declared in NSString.h.

Availability
  • Available in OS X v10.0.
  • Removed in OS X v10.5.
Declared In
NSString.h

NSStringCompareOptions

Type for string comparison options.

typedef NSUInteger NSStringCompareOptions;
Discussion

See “Search and Comparison Options” for possible values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

Search and Comparison Options

These values represent the options available to many of the string classes’ search and comparison methods.

enum {
   NSCaseInsensitiveSearch = 1,
   NSLiteralSearch = 2,
   NSBackwardsSearch = 4,
   NSAnchoredSearch = 8,
   NSNumericSearch = 64,
   NSDiacriticInsensitiveSearch = 128,
   NSWidthInsensitiveSearch = 256,
   NSForcedOrderingSearch = 512,
   NSRegularExpressionSearch = 1024
};
Constants
NSCaseInsensitiveSearch

A case-insensitive search.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSLiteralSearch

Exact character-by-character equivalence.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSBackwardsSearch

Search from end of source string.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSAnchoredSearch

Search is limited to start (or end, if NSBackwardsSearch) of source string.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSNumericSearch

Numbers within strings are compared using numeric value, that is, Name2.txt < Name7.txt < Name25.txt.

Numeric comparison only applies to the numerals in the string, not other characters that would have meaning in a true number such as a negative sign or a decimal point.

This option only applies to compare methods, not find.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSDiacriticInsensitiveSearch

Search ignores diacritic marks.

For example, ‘ö’ is equal to ‘o’.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSWidthInsensitiveSearch

Search ignores width differences in characters that have full-width and half-width forms, as occurs in East Asian character sets.

For example, with this option, the full-width Latin small letter 'a' (Unicode code point U+FF41) is equal to the basic Latin small letter 'a' (Unicode code point U+0061).

Available in iOS 2.0 and later.

Declared in NSString.h.

NSForcedOrderingSearch

Comparisons are forced to return either NSOrderedAscending or NSOrderedDescending if the strings are equivalent but not strictly equal.

This option gives stability when sorting. For example, “aaa” is greater than "AAA” if NSCaseInsensitiveSearch is specified.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSRegularExpressionSearch

The search string is treated as an ICU-compatible regular expression. If set, no other options can apply except NSCaseInsensitiveSearch and NSAnchoredSearch. You can use this option only with the rangeOfString:... methods and stringByReplacingOccurrencesOfString:withString:options:range:.

Available in iOS 3.2 and later.

Declared in NSString.h.

Discussion

See “Searching, Comparing, and Sorting Strings” for details on the effects of these options.

Declared In
NSString.h

NSStringEncodingConversionOptions

Type for encoding conversion options.

typedef NSUInteger NSStringEncodingConversionOptions;
Discussion

See “Encoding Conversion Options” for possible values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

Encoding Conversion Options

Options for converting string encodings.

enum {
   NSStringEncodingConversionAllowLossy = 1,
   NSStringEncodingConversionExternalRepresentation = 2
};
Constants
NSStringEncodingConversionAllowLossy

Allows lossy conversion.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSStringEncodingConversionExternalRepresentation

Specifies an external representation (with a byte-order mark, if necessary, to indicate endianness).

Available in iOS 2.0 and later.

Declared in NSString.h.

Special Considerations

These constants are available in OS X v10.4; they are, however, differently named:

typedef enum {
    NSAllowLossyEncodingConversion = 1,
    NSExternalRepresentationEncodingConversion = 2
} NSStringEncodingConversionOptions;

You can use them on OS X v10.4 if you define the symbols as extern constants.

Declared In
NSString.h

NSString Handling Exception Names

These constants define the names of exceptions raised if NSString cannot represent a string in a given encoding, or parse a string as a property list.

extern NSString *NSParseErrorException;
extern NSString *NSCharacterConversionException;
Constants
NSCharacterConversionException

NSString raises an NSCharacterConversionException if a string cannot be represented in a file-system or string encoding.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSParseErrorException

NSString raises an NSParseErrorException if a string cannot be parsed as a property list.

Available in iOS 2.0 and later.

Declared in NSString.h.

Declared In
NSString.h

NSStringEncoding

Type for string encoding.

typedef NSUInteger NSStringEncoding;
Discussion

See “String Encodings” for possible values.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

String Encodings

The following constants are provided by NSString as possible string encodings.

enum {
   NSASCIIStringEncoding = 1,
   NSNEXTSTEPStringEncoding = 2,
   NSJapaneseEUCStringEncoding = 3,
   NSUTF8StringEncoding = 4,
   NSISOLatin1StringEncoding = 5,
   NSSymbolStringEncoding = 6,
   NSNonLossyASCIIStringEncoding = 7,
   NSShiftJISStringEncoding = 8,
   NSISOLatin2StringEncoding = 9,
   NSUnicodeStringEncoding = 10,
   NSWindowsCP1251StringEncoding = 11,
   NSWindowsCP1252StringEncoding = 12,
   NSWindowsCP1253StringEncoding = 13,
   NSWindowsCP1254StringEncoding = 14,
   NSWindowsCP1250StringEncoding = 15,
   NSISO2022JPStringEncoding = 21,
   NSMacOSRomanStringEncoding = 30,
   NSUTF16StringEncoding = NSUnicodeStringEncoding,
   NSUTF16BigEndianStringEncoding = 0x90000100,
   NSUTF16LittleEndianStringEncoding = 0x94000100,
   NSUTF32StringEncoding = 0x8c000100,
   NSUTF32BigEndianStringEncoding = 0x98000100,
   NSUTF32LittleEndianStringEncoding = 0x9c000100,
   NSProprietaryStringEncoding = 65536
};
Constants
NSASCIIStringEncoding

Strict 7-bit ASCII encoding within 8-bit chars; ASCII values 0…127 only.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSNEXTSTEPStringEncoding

8-bit ASCII encoding with NEXTSTEP extensions.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSJapaneseEUCStringEncoding

8-bit EUC encoding for Japanese text.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSUTF8StringEncoding

An 8-bit representation of Unicode characters, suitable for transmission or storage by ASCII-based systems.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSISOLatin1StringEncoding

8-bit ISO Latin 1 encoding.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSSymbolStringEncoding

8-bit Adobe Symbol encoding vector.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSNonLossyASCIIStringEncoding

7-bit verbose ASCII to represent all Unicode characters.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSShiftJISStringEncoding

8-bit Shift-JIS encoding for Japanese text.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSISOLatin2StringEncoding

8-bit ISO Latin 2 encoding.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSUnicodeStringEncoding

The canonical Unicode encoding for string objects.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSWindowsCP1251StringEncoding

Microsoft Windows codepage 1251, encoding Cyrillic characters; equivalent to AdobeStandardCyrillic font encoding.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSWindowsCP1252StringEncoding

Microsoft Windows codepage 1252; equivalent to WinLatin1.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSWindowsCP1253StringEncoding

Microsoft Windows codepage 1253, encoding Greek characters.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSWindowsCP1254StringEncoding

Microsoft Windows codepage 1254, encoding Turkish characters.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSWindowsCP1250StringEncoding

Microsoft Windows codepage 1250; equivalent to WinLatin2.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSISO2022JPStringEncoding

ISO 2022 Japanese encoding for email.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSMacOSRomanStringEncoding

Classic Macintosh Roman encoding.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSUTF16StringEncoding

An alias for NSUnicodeStringEncoding.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSUTF16BigEndianStringEncoding

NSUTF16StringEncoding encoding with explicit endianness specified.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSUTF16LittleEndianStringEncoding

NSUTF16StringEncoding encoding with explicit endianness specified.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSUTF32StringEncoding

32-bit UTF encoding.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSUTF32BigEndianStringEncoding

NSUTF32StringEncoding encoding with explicit endianness specified.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSUTF32LittleEndianStringEncoding

NSUTF32StringEncoding encoding with explicit endianness specified.

Available in iOS 2.0 and later.

Declared in NSString.h.

NSProprietaryStringEncoding

Installation-specific encoding. (Deprecated. This encoding has been deprecated—there is no replacement.)

Proprietary encodings have not been used since OS X v10.0. You should specify a standard encoding instead.

Available in iOS 5.0 and later.

Declared in NSString.h.

Discussion

These values represent the various character encodings supported by the NSString classes. This is an incomplete list. Additional encodings are defined in String Programming Guide for Core Foundation (see CFStringEncodingExt.h); these encodings can be used with NSString by first passing the Core Foundation encoding to the CFStringConvertEncodingToNSStringEncoding function.

String Enumeration Options

Constants to specify kinds of substrings and styles of enumeration.

typedef NSUInteger NSStringEnumerationOptions;
enum {
NSStringEnumerationByLines = 0,
NSStringEnumerationByParagraphs = 1,
NSStringEnumerationByComposedCharacterSequences = 2,
NSStringEnumerationByWords = 3,
NSStringEnumerationBySentences = 4,
NSStringEnumerationReverse = 1UL << 8,
NSStringEnumerationSubstringNotRequired = 1UL << 9,
NSStringEnumerationLocalized = 1UL << 10
};
Constants
NSStringEnumerationByLines

Enumerates by lines. Equivalent to lineRangeForRange:.

Available in iOS 4.0 and later.

Declared in NSString.h.

NSStringEnumerationByParagraphs

Enumerates by paragraphs. Equivalent to paragraphRangeForRange:.

Available in iOS 4.0 and later.

Declared in NSString.h.

NSStringEnumerationByComposedCharacterSequences

Enumerates by composed character sequences. Equivalent to rangeOfComposedCharacterSequencesForRange:.

Available in iOS 4.0 and later.

Declared in NSString.h.

NSStringEnumerationByWords

Enumerates by words.

Available in iOS 4.0 and later.

Declared in NSString.h.

NSStringEnumerationBySentences

Enumerates by sentences.

Available in iOS 4.0 and later.

Declared in NSString.h.

NSStringEnumerationReverse

Causes enumeration to occur from the end of the specified range to the start.

Available in iOS 4.0 and later.

Declared in NSString.h.

NSStringEnumerationSubstringNotRequired

A way to indicate that the block does not need substring, in which case nil will be passed. This is simply a performance shortcut.

Available in iOS 4.0 and later.

Declared in NSString.h.

NSStringEnumerationLocalized

Causes the enumeration to occur using user's default locale. This does not make a difference in line, paragraph, or composed character sequence enumeration, but it may for words or sentences.

Available in iOS 4.0 and later.

Declared in NSString.h.

Discussion

These options are used with the enumerateSubstringsInRange:options:usingBlock: method. Pass in one NSStringEnumerationBy... option and combine with any of the remaining enumeration style constants using the C bitwise OR operator.