iOS Developer Library — Pre-Release

Developer

Foundation Framework Reference NSString Class Reference

Options
Deployment Target:

On This Page
Language:

NSString

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.

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.

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

Interpreting UTF-16-encoded data

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

Distributed objects

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.

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.

  • Returns an empty string.

    Declaration

    Objective-C

    + (instancetype)string

    Return Value

    An empty string.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    See Also

    – init

  • init() - init Designated Initializer

    Returns an initialized NSString object that contains no characters.

    Declaration

    Swift

    init()

    Objective-C

    - (instancetype)init

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    + string

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

    Declaration

    Swift

    convenience init?(bytes bytes: UnsafePointer<Void>, length length: Int, encoding encoding: UInt)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    convenience init?(bytesNoCopy bytes: UnsafeMutablePointer<Void>, length length: Int, encoding encoding: UInt, freeWhenDone flag: Bool)

    Objective-C

    - (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 YEStrue, the receiver frees the memory when it no longer needs the data; if NOfalse it won’t.

    Return Value

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

    Special Considerations

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    convenience init(characters characters: UnsafePointer<unichar>, length length: Int)

    Objective-C

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

    Parameters

    characters

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

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    convenience init(charactersNoCopy characters: UnsafeMutablePointer<unichar>, length length: Int, freeWhenDone flag: Bool)

    Objective-C

    - (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 YEStrue, the receiver will free the memory when it no longer needs the characters; if NOfalse it won’t.

    Return Value

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

    Special Considerations

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    convenience init(string aString: String)

    Objective-C

    - (instancetype)initWithString:(NSString *)aString

    Parameters

    aString

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

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    convenience init?(CString nullTerminatedCString: UnsafePointer<Int8>, encoding encoding: UInt)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    convenience init?(UTF8String bytes: UnsafePointer<Int8>)

    Objective-C

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

    Parameters

    bytes

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

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

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

    ...

    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 system locale. The returned object may be different from the original receiver.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • 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 current locale.

    Declaration

    Swift

    convenience init(format format: String, arguments argList: CVaListPointer)

    Objective-C

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

    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 current locale. The returned object may be different from the original receiver.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

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

    locale

    An NSLocale object specifying the locale to use. To use the current locale, pass [NSLocalecurrentLocale]. To use the system locale, pass nil.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    convenience init(format format: String, locale locale: AnyObject?, arguments argList: CVaListPointer)

    Objective-C

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

    locale

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

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

    argList

    A list of arguments to substitute into format.

    Return Value

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

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    convenience init?(data data: NSData, encoding encoding: UInt)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

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

    ...

    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 system locale.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Returns a string created by using a given format string as a template into which the remaining argument values are substituted according to the current locale.

    Declaration

    Objective-C

    + (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 in the current locale.

    Discussion

    This method is equivalent to using initWithFormat:locale: and passing the current 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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

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

    Parameters

    chars

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

    length

    The number of characters to use from chars.

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    + (instancetype)stringWithString:(NSString *)aString

    Parameters

    aString

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

    Return Value

    A string created by copying the characters from aString.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

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

    Parameters

    bytes

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

    Return Value

    A string created by copying the data from bytes.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates a new string using a given C-string.

    Deprecation Statement

    Use stringWithCString:encoding: instead.

    Declaration

    Objective-C

    + (id)stringWithCString:(const char *)bytes

    Discussion

    cString should contain data in the default C string encoding. If the argument passed to stringWithCString: is not a zero-terminated C-string, the results are undefined.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

  • Initializes the receiver, a newly allocated NSString object, by converting the data in a given C-string from the default C-string encoding into the Unicode character encoding.

    Deprecation Statement

    Use initWithCString:encoding: instead.

    Declaration

    Objective-C

    - (id)initWithCString:(const char *)bytes

    Discussion

    cString must be a zero-terminated C string in the default C string encoding, and may not be NULL. Returns an initialized object, which might be different from the original receiver.

    To create an immutable string from an immutable C string buffer, do not attempt to use this method. Instead, use initWithCStringNoCopy:length:freeWhenDone:.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

  • Returns a string containing the characters in a given C-string.

    Deprecation Statement

    Use stringWithCString:encoding: instead.

    Declaration

    Objective-C

    + (id)stringWithCString:(const char *)bytes length:(NSUInteger)length

    Discussion

    cString must not be NULL. cString should contain characters in the default C-string encoding. This method converts length * sizeof(char) bytes from cString and doesn’t stop short at a NULL character.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

  • Initializes the receiver, a newly allocated NSString object, by converting the data in a given C-string from the default C-string encoding into the Unicode character encoding.

    Deprecation Statement

    Use initWithBytes:length:encoding: instead.

    Declaration

    Objective-C

    - (id)initWithCString:(const char *)bytes length:(NSUInteger)length

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

  • Initializes the receiver, a newly allocated NSString object, by converting the data in a given C-string from the default C-string encoding into the Unicode character encoding.

    Deprecation Statement

    Use initWithBytesNoCopy:length:encoding:freeWhenDone: instead.

    Declaration

    Objective-C

    - (id)initWithCStringNoCopy:(char *)bytes length:(NSUInteger)length freeWhenDone:(BOOL)freeBuffer

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    convenience init?(contentsOfFile path: String, encoding enc: UInt, error error: NSErrorPointer)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    convenience init?(contentsOfFile path: String, usedEncoding enc: UnsafeMutablePointer<UInt>, error error: NSErrorPointer)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a string created by reading data from the file named by a given path.

    Declaration

    Objective-C

    + (id)stringWithContentsOfFile:(NSString *)path

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

  • Initializes the receiver, a newly allocated NSString object, by reading data from the file named by path.

    Declaration

    Objective-C

    - (id)initWithContentsOfFile:(NSString *)path

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    convenience init?(contentsOfURL url: NSURL, encoding enc: UInt, error error: NSErrorPointer)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    convenience init?(contentsOfURL url: NSURL, usedEncoding enc: UnsafeMutablePointer<UInt>, error error: NSErrorPointer)

    Objective-C

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

    Discussion

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

    • NSURL *textFileURL = ;
    • NSStringEncoding encoding = 0;
    • NSError *error = nil;
    • NSString *string = [[NSString alloc] initWithContentsOfURL:textFileURL usedEncoding:&encoding error:&error];

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a string created by reading data from the file named by a given URL.

    Declaration

    Objective-C

    + (id)stringWithContentsOfURL:(NSURL *)url

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

  • Initializes the receiver, a newly allocated NSString object, by reading data from the location named by a given URL.

    Declaration

    Objective-C

    - (id)initWithContentsOfURL:(NSURL *)url

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

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

    Declaration

    Swift

    func writeToFile(_ path: String, atomically useAuxiliaryFile: Bool, encoding enc: UInt, error error: NSErrorPointer) -> Bool

    Objective-C

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

    enc

    The encoding to use for the output.

    error

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

    Return Value

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

    Discussion

    This method overwrites any existing file at path.

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Writes the contents of the receiver to the file specified by a given path.

    Deprecation Statement

    Use writeToFile:atomically:encoding:error: instead.

    Declaration

    Objective-C

    - (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile

    Return Value

    YEStrue if the file is written successfully, otherwise NOfalse.

    Discussion

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

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

    If path contains a tilde (~) character, you must expand it with stringByExpandingTildeInPath before invoking this method.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

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

    Declaration

    Swift

    func writeToURL(_ url: NSURL, atomically useAuxiliaryFile: Bool, encoding enc: UInt, error error: NSErrorPointer) -> Bool

    Objective-C

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

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

    enc

    The encoding to use for the output.

    error

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

    Return Value

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

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Writes the contents of the receiver to the location specified by a given URL.

    Deprecation Statement

    Use writeToURL:atomically:encoding:error: instead.

    Declaration

    Objective-C

    - (BOOL)writeToURL:(NSURL *)url atomically:(BOOL)atomically

    Return Value

    YEStrue if the location is written successfully, otherwise NOfalse.

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

  • length length Property

    The number of Unicode characters in the receiver. (read-only)

    Declaration

    Swift

    var length: Int { get }

    Objective-C

    @property(readonly) NSUInteger length

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func lengthOfBytesUsingEncoding(_ enc: UInt) -> Int

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func maximumLengthOfBytesUsingEncoding(_ enc: UInt) -> Int

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the character at a given array position.

    Declaration

    Swift

    func characterAtIndex(_ index: Int) -> unichar

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Copies all characters from the receiver into a given buffer.

    Deprecation Statement

    This method is unsafe because it could potentially cause buffer overruns. Use getCharacters:range: instead.

    Declaration

    Swift

    func getCharacters(_ buffer: UnsafeMutablePointer<unichar>)

    Objective-C

    - (void)getCharacters:(unichar *)buffer

    Parameters

    buffer

    Upon return, contains the characters from the receiver. buffer must be large enough to contain all characters in the string ([string length]*sizeof(unichar)).

    Discussion

    Invokes getCharacters:range: with buffer and the entire extent of the receiver as the range.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 4.0.

    See Also

    – length

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

    Declaration

    Swift

    func getCharacters(_ buffer: UnsafeMutablePointer<unichar>, range aRange: NSRange)

    Objective-C

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

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func getBytes(_ buffer: UnsafeMutablePointer<Void>, maxLength maxBufferCount: Int, usedLength usedBufferCount: UnsafeMutablePointer<Int>, encoding encoding: UInt, options options: NSStringEncodingConversionOptions, range range: NSRange, remainingRange leftover: NSRangePointer) -> Bool

    Objective-C

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

    YEStrue if some characters were converted, otherwise NOfalse.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func cStringUsingEncoding(_ encoding: UInt) -> UnsafePointer<Int8>

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func getCString(_ buffer: UnsafeMutablePointer<Int8>, maxLength maxBufferCount: Int, encoding encoding: UInt) -> Bool

    Objective-C

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

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

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • A null-terminated UTF8 representation of the string. (read-only)

    Declaration

    Swift

    var UTF8String: UnsafePointer<Int8> { get }

    Objective-C

    @property(readonly) const char *UTF8String

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • cString - cString (iOS 2.0)

    Returns a representation of the receiver as a C string in the default C-string encoding.

    Deprecation Statement

    Use cStringUsingEncoding: or UTF8String instead.

    Declaration

    Objective-C

    - (const char *)cString

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

  • Returns a representation of the receiver as a C string in the default C-string encoding, possibly losing information in converting to that encoding.

    Deprecation Statement

    Use cStringUsingEncoding: or dataUsingEncoding:allowLossyConversion: instead.

    Declaration

    Objective-C

    - (const char *)lossyCString

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

  • Returns the length in char-sized units of the receiver’s C-string representation in the default C-string encoding.

    Deprecation Statement

    Use lengthOfBytesUsingEncoding: or maximumLengthOfBytesUsingEncoding: instead.

    Declaration

    Objective-C

    - (NSUInteger)cStringLength

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

  • Invokes getCString:maxLength:range:remainingRange: with NSMaximumStringLength as the maximum length, the receiver’s entire extent as the range, and NULL for the remaining range.

    Deprecation Statement

    Use cStringUsingEncoding: or dataUsingEncoding:allowLossyConversion: instead.

    Declaration

    Objective-C

    - (void)getCString:(char *)bytes

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

  • Invokes getCString:maxLength:range:remainingRange: with maxLength as the maximum length in char-sized units, the receiver’s entire extent as the range, and NULL for the remaining range.

    Deprecation Statement

    Use getCString:maxLength:encoding: instead.

    Declaration

    Objective-C

    - (void)getCString:(char *)bytes maxLength:(NSUInteger)maxLength

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

  • Converts the receiver’s content to the default C-string encoding and stores them in a given buffer.

    Deprecation Statement

    Use getCString:maxLength:encoding: instead.

    Declaration

    Objective-C

    - (void)getCString:(char *)bytes maxLength:(NSUInteger)maxLength range:(NSRange)aRange remainingRange:(NSRangePointer)leftoverRange

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 2.0.

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

    Declaration

    Objective-C

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

    Parameters

    format

    A format string. See Formatting String Objects for more information. This value must not be 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:.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func stringByAppendingString(_ aString: String) -> String

    Objective-C

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

    Parameters

    aString

    The string to append to the receiver. This value must not be 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.”.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func stringByPaddingToLength(_ newLength: Int, withString padString: String, startingAtIndex padIndex: Int) -> String

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func componentsSeparatedByString(_ separator: String) -> [AnyObject]

    Objective-C

    - (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: { @"", @"Norman", @"Stanley", @"Fletcher" }

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func componentsSeparatedByCharactersInSet(_ separator: NSCharacterSet) -> [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func stringByTrimmingCharactersInSet(_ set: NSCharacterSet) -> String

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func substringFromIndex(_ anIndex: Int) -> String

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func substringWithRange(_ aRange: NSRange) -> String

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func substringToIndex(_ anIndex: Int) -> String

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func rangeOfCharacterFromSet(_ aSet: NSCharacterSet) -> NSRange

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func rangeOfCharacterFromSet(_ aSet: NSCharacterSet, options mask: NSStringCompareOptions) -> NSRange

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func rangeOfCharacterFromSet(_ aSet: NSCharacterSet, options mask: NSStringCompareOptions, range aRange: NSRange) -> NSRange

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func rangeOfString(_ aString: String) -> NSRange

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func rangeOfString(_ aString: String, options mask: NSStringCompareOptions) -> NSRange

    Objective-C

    - (NSRange)rangeOfString:(NSString *)aString options:(NSStringCompareOptions)mask

    Parameters

    aString

    The string to search for. This value must not be 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func rangeOfString(_ aString: String, options mask: NSStringCompareOptions, range aRange: NSRange) -> NSRange

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func rangeOfString(_ aString: String, options mask: NSStringCompareOptions, range aRange: NSRange, locale locale: NSLocale?) -> NSRange

    Objective-C

    - (NSRange)rangeOfString:(NSString *)aString options:(NSStringCompareOptions)mask range:(NSRange)aRange 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. To use the current locale, pass [NSLocalecurrentLocale]. To use the system locale, pass nil.

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

    Return Value

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

    Discussion

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

    Special Considerations

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Enumerates all the lines in a string.

    Declaration

    Swift

    func enumerateLinesUsingBlock(_ block: (String!, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func enumerateSubstringsInRange(_ range: NSRange, options opts: NSStringEnumerationOptions, usingBlock block: (String!, NSRange, NSRange, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func getLineStart(_ startIndex: UnsafeMutablePointer<Int>, end lineEndIndex: UnsafeMutablePointer<Int>, contentsEnd contentsEndIndex: UnsafeMutablePointer<Int>, forRange aRange: NSRange)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func lineRangeForRange(_ aRange: NSRange) -> NSRange

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func getParagraphStart(_ startIndex: UnsafeMutablePointer<Int>, end endIndex: UnsafeMutablePointer<Int>, contentsEnd contentsEndIndex: UnsafeMutablePointer<Int>, forRange aRange: NSRange)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func paragraphRangeForRange(_ aRange: NSRange) -> NSRange

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func rangeOfComposedCharacterSequenceAtIndex(_ anIndex: Int) -> NSRange

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func rangeOfComposedCharacterSequencesForRange(_ range: NSRange) -> NSRange

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func propertyList() -> AnyObject

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func propertyListFromStringsFileFormat() -> [NSObject : AnyObject]?

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func caseInsensitiveCompare(_ aString: String) -> NSComparisonResult

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func localizedCaseInsensitiveCompare(_ aString: String) -> NSComparisonResult

    Objective-C

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

    Discussion

    This method uses the current locale.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func compare(_ aString: String) -> NSComparisonResult

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func localizedCompare(_ aString: String) -> NSComparisonResult

    Objective-C

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

    This method uses the current locale.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func compare(_ aString: String, options mask: NSStringCompareOptions) -> NSComparisonResult

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func compare(_ aString: String, options mask: NSStringCompareOptions, range range: NSRange) -> NSComparisonResult

    Objective-C

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

    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, use compare:options:range:locale: instead and pass the current locale.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func compare(_ aString: String, options mask: NSStringCompareOptions, range range: NSRange, locale locale: AnyObject?) -> NSComparisonResult

    Objective-C

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

    locale

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

    Return Value

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

    Discussion

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

    Special Considerations

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Compares strings as sorted by the Finder.

    Declaration

    Swift

    func localizedStandardCompare(_ string: String) -> NSComparisonResult

    Objective-C

    - (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. This method uses the current locale.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func hasPrefix(_ aString: String) -> Bool

    Objective-C

    - (BOOL)hasPrefix:(NSString *)aString

    Parameters

    aString

    A string.

    Return Value

    YEStrue if aString matches the beginning characters of the receiver, otherwise NOfalse. Returns NOfalse if aString is empty.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func hasSuffix(_ aString: String) -> Bool

    Objective-C

    - (BOOL)hasSuffix:(NSString *)aString

    Parameters

    aString

    A string.

    Return Value

    YEStrue if aString matches the ending characters of the receiver, otherwise NOfalse. Returns NOfalse 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func isEqualToString(_ aString: String) -> Bool

    Objective-C

    - (BOOL)isEqualToString:(NSString *)aString

    Parameters

    aString

    The string with which to compare the receiver.

    Return Value

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

    Discussion

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

    Special Considerations

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • hash hash Property

    An unsigned integer that can be used as a hash table address. (read-only)

    Declaration

    Swift

    var hash: Int { get }

    Objective-C

    @property(readonly) NSUInteger hash

    Discussion

    If two string objects are equal (as determined by the isEqualToString: method), they must have the same hash value. This property fulfills this requirement.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a string with the given character folding options applied.

    Declaration

    Swift

    func stringByFoldingWithOptions(_ options: NSStringCompareOptions, locale locale: NSLocale?) -> String

    Objective-C

    - (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. To use the current locale, pass [NSLocalecurrentLocale]. To use the system locale, pass nil.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func commonPrefixWithString(_ aString: String, options mask: NSStringCompareOptions) -> String

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – hasPrefix:

  • A capitalized representation of the receiver. (read-only)

    Declaration

    Swift

    var capitalizedString: String { get }

    Objective-C

    @property(readonly, copy) NSString *capitalizedString

    Discussion

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

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func capitalizedStringWithLocale(_ locale: NSLocale?) -> String

    Objective-C

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

    Parameters

    locale

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

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • A lowercase representation of the string.

    Declaration

    Swift

    var lowercaseString: String { get }

    Objective-C

    @property(readonly, copy) NSString *lowercaseString

    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”

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func lowercaseStringWithLocale(_ locale: NSLocale?) -> String

    Objective-C

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

    Parameters

    locale

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

    Return Value

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

    Discussion

    .

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • An uppercase representation of the string. (read-only)

    Declaration

    Swift

    var uppercaseString: String { get }

    Objective-C

    @property(readonly, copy) NSString *uppercaseString

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func uppercaseStringWithLocale(_ locale: NSLocale?) -> String

    Objective-C

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

    Parameters

    locale

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

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • The floating-point value of the string as a double. (read-only)

    Declaration

    Swift

    var doubleValue: Double { get }

    Objective-C

    @property(readonly) double doubleValue

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The floating-point value of the string as a float. (read-only)

    Declaration

    Swift

    var floatValue: Float { get }

    Objective-C

    @property(readonly) float floatValue

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • intValue intValue Property

    The integer value of the string. (read-only)

    Declaration

    Swift

    var intValue: Int32 { get }

    Objective-C

    @property(readonly) int intValue

    Discussion

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

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

    Special Considerations

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The NSInteger value of the string. (read-only)

    Declaration

    Swift

    var integerValue: Int { get }

    Objective-C

    @property(readonly) NSInteger integerValue

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    doubleValue
    floatValue
    scanInt: (NSScanner)

  • The long long value of the string. (read-only)

    Declaration

    Swift

    var longLongValue: Int64 { get }

    Objective-C

    @property(readonly) long long longLongValue

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    doubleValue
    floatValue
    scanInt: (NSScanner)

  • boolValue boolValue Property

    The Boolean value of the string. (read-only)

    Declaration

    Swift

    var boolValue: Bool { get }

    Objective-C

    @property(readonly) BOOL boolValue

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    integerValue
    scanInt: (NSScanner)

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

    Declaration

    Swift

    class func availableStringEncodings() -> UnsafePointer<UInt>

    Objective-C

    + (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:

    • NSASCIIStringEncoding

    • NSUnicodeStringEncoding

    • NSISOLatin1StringEncoding

    • NSISOLatin2StringEncoding

    • NSSymbolStringEncoding

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    class func defaultCStringEncoding() -> UInt

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    class func localizedNameOfStringEncoding(_ encoding: UInt) -> String

    Objective-C

    + (NSString *)localizedNameOfStringEncoding:(NSStringEncoding)encoding

    Parameters

    encoding

    A string encoding.

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func canBeConvertedToEncoding(_ encoding: UInt) -> Bool

    Objective-C

    - (BOOL)canBeConvertedToEncoding:(NSStringEncoding)encoding

    Parameters

    encoding

    A string encoding.

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func dataUsingEncoding(_ encoding: UInt) -> NSData?

    Objective-C

    - (NSData *)dataUsingEncoding:(NSStringEncoding)encoding

    Parameters

    encoding

    A string encoding.

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func dataUsingEncoding(_ encoding: UInt, allowLossyConversion flag: Bool) -> NSData?

    Objective-C

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

    Parameters

    encoding

    A string encoding.

    flag

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

    Return Value

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

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • This NSString object. (read-only)

    Declaration

    Swift

    var description: String { get }

    Objective-C

    @property(readonly, copy) NSString *description

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The fastest encoding to which the receiver may be converted without loss of information. (read-only)

    Declaration

    Swift

    var fastestEncoding: UInt { get }

    Objective-C

    @property(readonly) NSStringEncoding fastestEncoding

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The smallest encoding to which the receiver can be converted without loss of information. (read-only)

    Declaration

    Swift

    var smallestEncoding: UInt { get }

    Objective-C

    @property(readonly) NSStringEncoding smallestEncoding

    Discussion

    This encoding may not be the fastest for accessing characters, but is space-efficient. This property may take some time to access.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    class func pathWithComponents(_ components: [AnyObject]) -> String

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The file-system path components of the receiver. (read-only)

    Declaration

    Swift

    var pathComponents: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *pathComponents

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func completePathIntoString(_ outputName: AutoreleasingUnsafeMutablePointer<NSString?>, caseSensitive flag: Bool, matchesIntoArray outputArray: AutoreleasingUnsafeMutablePointer<NSArray?>, filterTypes filterTypes: [AnyObject]?) -> Int

    Objective-C

    - (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 YEStrue, the method 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 these strings are included in outputArray. Pass nil if you don’t want to filter the output.

    Return Value

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

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • A file system-specific representation of the receiver. (read-only)

    Declaration

    Swift

    var fileSystemRepresentation: UnsafePointer<Int8> { get }

    Objective-C

    @property(readonly) const char *fileSystemRepresentation

    Discussion

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

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

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func getFileSystemRepresentation(_ buffer: UnsafeMutablePointer<Int8>, maxLength maxLength: Int) -> Bool

    Objective-C

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

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

    Discussion

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

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

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

    • 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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value that indicates whether the receiver represents an absolute path. (read-only)

    Declaration

    Swift

    var absolutePath: Bool { get }

    Objective-C

    @property(getter=isAbsolutePath, readonly) BOOL absolutePath

    Discussion

    YEStrue if the receiver (if interpreted as a path) represents an absolute path, otherwise NOfalse.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • The last path component of the receiver. (read-only)

    Declaration

    Swift

    var lastPathComponent: String { get }

    Objective-C

    @property(readonly, copy) NSString *lastPathComponent

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    pathComponents

  • The path extension, if any, of the string as interpreted as a path. (read-only)

    Declaration

    Swift

    var pathExtension: String { get }

    Objective-C

    @property(readonly, copy) NSString *pathExtension

    Discussion

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

    Receiver’s String Value

    String Returned

    /tmp/scratch.tiff

    tiff

    .scratch.tiff

    tiff

    /tmp/scratch

    “” (an empty string)

    /tmp/

    “” (an empty string)

    /tmp/scratch..tiff

    tiff

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var stringByAbbreviatingWithTildeInPath: String { get }

    Objective-C

    @property(readonly, copy) NSString *stringByAbbreviatingWithTildeInPath

    Discussion

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

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func stringByAppendingPathComponent(_ aString: String) -> String

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func stringByAppendingPathExtension(_ ext: String) -> String?

    Objective-C

    - (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. If the receiver is empty, or the resulting path would be too long, returns nil.

    Discussion

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

    Receiver’s String Value

    Resulting String

    /tmp/scratch.old

    /tmp/scratch.old.tiff

    /tmp/scratch.

    /tmp/scratch..tiff

    /tmp/

    /tmp.tiff

    scratch

    scratch.tiff

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

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

    Special Considerations

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • A new string made by deleting the last path component from the receiver, along with any final path separator. (read-only)

    Declaration

    Swift

    var stringByDeletingLastPathComponent: String { get }

    Objective-C

    @property(readonly, copy) NSString *stringByDeletingLastPathComponent

    Discussion

    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.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • A new string made by deleting the extension (if any, and only the last) from the receiver. (read-only)

    Declaration

    Swift

    var stringByDeletingPathExtension: String { get }

    Objective-C

    @property(readonly, copy) NSString *stringByDeletingPathExtension

    Discussion

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

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

    Receiver’s String Value

    Resulting String

    /tmp/scratch.tiff

    /tmp/scratch

    /tmp/

    /tmp

    scratch.bundle/

    scratch

    scratch..tiff

    scratch.

    .tiff

    .tiff

    /

    /

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • A new string made by expanding the initial component of the receiver to its full path value. (read-only)

    Declaration

    Swift

    var stringByExpandingTildeInPath: String { get }

    Objective-C

    @property(readonly, copy) NSString *stringByExpandingTildeInPath

    Discussion

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • A new string made from the receiver by resolving all symbolic links and standardizing path. (read-only)

    Declaration

    Swift

    var stringByResolvingSymlinksInPath: String { get }

    Objective-C

    @property(readonly, copy) NSString *stringByResolvingSymlinksInPath

    Discussion

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

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • A new string made by removing extraneous path components from the receiver. (read-only)

    Declaration

    Swift

    var stringByStandardizingPath: String { get }

    Objective-C

    @property(readonly, copy) NSString *stringByStandardizingPath

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func stringsByAppendingPaths(_ paths: [AnyObject]) -> [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func enumerateLinguisticTagsInRange(_ range: NSRange, scheme tagScheme: String, options opts: NSLinguisticTaggerOptions, orthography orthography: NSOrthography?, usingBlock block: (String!, NSRange, NSRange, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

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

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func linguisticTagsInRange(_ range: NSRange, scheme tagScheme: String, options opts: NSLinguisticTaggerOptions, orthography orthography: NSOrthography?, tokenRanges tokenRanges: AutoreleasingUnsafeMutablePointer<NSArray?>) -> [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 5.0 and later.

Data Types

  • Type for Unicode characters.

    Declaration

    Swift

    typealias unichar = UInt16

    Objective-C

    typedef unsigned short unichar;

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Type for string comparison options.

    Declaration

    Swift

    struct NSStringCompareOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var CaseInsensitiveSearch: NSStringCompareOptions { get } static var LiteralSearch: NSStringCompareOptions { get } static var BackwardsSearch: NSStringCompareOptions { get } static var AnchoredSearch: NSStringCompareOptions { get } static var NumericSearch: NSStringCompareOptions { get } static var DiacriticInsensitiveSearch: NSStringCompareOptions { get } static var WidthInsensitiveSearch: NSStringCompareOptions { get } static var ForcedOrderingSearch: NSStringCompareOptions { get } static var RegularExpressionSearch: NSStringCompareOptions { get } }

    Objective-C

    typedef NSUInteger NSStringCompareOptions;

    Discussion

    See Search and Comparison Options for possible values.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Type for encoding conversion options.

    Declaration

    Swift

    struct NSStringEncodingConversionOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var AllowLossy: NSStringEncodingConversionOptions { get } static var ExternalRepresentation: NSStringEncodingConversionOptions { get } }

    Objective-C

    typedef NSUInteger NSStringEncodingConversionOptions;

    Discussion

    See “Encoding Conversion Options” for possible values.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Type for string encoding.

    Declaration

    Objective-C

    typedef NSUInteger NSStringEncoding;

    Discussion

    See String Encodings for possible values.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • A constant to define the maximum number of characters in an NSString object.

    This constant is not available in OS X v10.5 and later.

    Declaration

    Objective-C

    #define NSMaximumStringLength (INT_MAX-1)

    Constants

    • NSMaximumStringLength

      NSMaximumStringLength

      Maximum number of characters in an NSString object.

      Available in iOS 5.0 and later.

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

    Declaration

    Swift

    static var CaseInsensitiveSearch: NSStringCompareOptions { get } static var LiteralSearch: NSStringCompareOptions { get } static var BackwardsSearch: NSStringCompareOptions { get } static var AnchoredSearch: NSStringCompareOptions { get } static var NumericSearch: NSStringCompareOptions { get } static var DiacriticInsensitiveSearch: NSStringCompareOptions { get } static var WidthInsensitiveSearch: NSStringCompareOptions { get } static var ForcedOrderingSearch: NSStringCompareOptions { get } static var RegularExpressionSearch: NSStringCompareOptions { get }

    Objective-C

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

    Constants

    • CaseInsensitiveSearch

      NSCaseInsensitiveSearch

      A case-insensitive search.

      Available in iOS 2.0 and later.

    • LiteralSearch

      NSLiteralSearch

      Exact character-by-character equivalence.

      Available in iOS 2.0 and later.

    • BackwardsSearch

      NSBackwardsSearch

      Search from end of source string.

      Available in iOS 2.0 and later.

    • AnchoredSearch

      NSAnchoredSearch

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

      Available in iOS 2.0 and later.

    • NumericSearch

      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.

    • DiacriticInsensitiveSearch

      NSDiacriticInsensitiveSearch

      Search ignores diacritic marks.

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

      Available in iOS 2.0 and later.

    • WidthInsensitiveSearch

      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.

    • ForcedOrderingSearch

      NSForcedOrderingSearch

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

      This option ensures reliable, reproducible results when sorting. For example, “aaa” is greater than "AAA” if NSCaseInsensitiveSearch is specified.

      Available in iOS 2.0 and later.

    • RegularExpressionSearch

      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.

    Discussion

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

  • Options for converting string encodings.

    Declaration

    Swift

    static var AllowLossy: NSStringEncodingConversionOptions { get } static var ExternalRepresentation: NSStringEncodingConversionOptions { get }

    Objective-C

    enum { NSStringEncodingConversionAllowLossy = 1, NSStringEncodingConversionExternalRepresentation = 2 };

    Constants

    • AllowLossy

      NSStringEncodingConversionAllowLossy

      Allows lossy conversion.

      Available in iOS 2.0 and later.

    • ExternalRepresentation

      NSStringEncodingConversionExternalRepresentation

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

      Available in iOS 2.0 and later.

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

    Declaration

    Swift

    let NSCharacterConversionException: String let NSParseErrorException: String

    Objective-C

    extern NSString *NSParseErrorException; extern NSString *NSCharacterConversionException;

    Constants

    • NSCharacterConversionException

      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.

    • NSParseErrorException

      NSParseErrorException

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

      Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var NSProprietaryStringEncoding: Int { get }

    Objective-C

    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

      NSASCIIStringEncoding

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

      Available in iOS 2.0 and later.

    • NSNEXTSTEPStringEncoding

      NSNEXTSTEPStringEncoding

      8-bit ASCII encoding with NEXTSTEP extensions.

      Available in iOS 2.0 and later.

    • NSJapaneseEUCStringEncoding

      NSJapaneseEUCStringEncoding

      8-bit EUC encoding for Japanese text.

      Available in iOS 2.0 and later.

    • NSUTF8StringEncoding

      NSUTF8StringEncoding

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

      Available in iOS 2.0 and later.

    • NSISOLatin1StringEncoding

      NSISOLatin1StringEncoding

      8-bit ISO Latin 1 encoding.

      Available in iOS 2.0 and later.

    • NSSymbolStringEncoding

      NSSymbolStringEncoding

      8-bit Adobe Symbol encoding vector.

      Available in iOS 2.0 and later.

    • NSNonLossyASCIIStringEncoding

      NSNonLossyASCIIStringEncoding

      7-bit verbose ASCII to represent all Unicode characters.

      Available in iOS 2.0 and later.

    • NSShiftJISStringEncoding

      NSShiftJISStringEncoding

      8-bit Shift-JIS encoding for Japanese text.

      Available in iOS 2.0 and later.

    • NSISOLatin2StringEncoding

      NSISOLatin2StringEncoding

      8-bit ISO Latin 2 encoding.

      Available in iOS 2.0 and later.

    • NSUnicodeStringEncoding

      NSUnicodeStringEncoding

      The canonical Unicode encoding for string objects.

      Available in iOS 2.0 and later.

    • NSWindowsCP1251StringEncoding

      NSWindowsCP1251StringEncoding

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

      Available in iOS 2.0 and later.

    • NSWindowsCP1252StringEncoding

      NSWindowsCP1252StringEncoding

      Microsoft Windows codepage 1252; equivalent to WinLatin1.

      Available in iOS 2.0 and later.

    • NSWindowsCP1253StringEncoding

      NSWindowsCP1253StringEncoding

      Microsoft Windows codepage 1253, encoding Greek characters.

      Available in iOS 2.0 and later.

    • NSWindowsCP1254StringEncoding

      NSWindowsCP1254StringEncoding

      Microsoft Windows codepage 1254, encoding Turkish characters.

      Available in iOS 2.0 and later.

    • NSWindowsCP1250StringEncoding

      NSWindowsCP1250StringEncoding

      Microsoft Windows codepage 1250; equivalent to WinLatin2.

      Available in iOS 2.0 and later.

    • NSISO2022JPStringEncoding

      NSISO2022JPStringEncoding

      ISO 2022 Japanese encoding for email.

      Available in iOS 2.0 and later.

    • NSMacOSRomanStringEncoding

      NSMacOSRomanStringEncoding

      Classic Macintosh Roman encoding.

      Available in iOS 2.0 and later.

    • NSUTF16StringEncoding

      NSUTF16StringEncoding

      An alias for NSUnicodeStringEncoding.

      Available in iOS 2.0 and later.

    • NSUTF16BigEndianStringEncoding

      NSUTF16BigEndianStringEncoding

      NSUTF16StringEncoding encoding with explicit endianness specified.

      Available in iOS 2.0 and later.

    • NSUTF16LittleEndianStringEncoding

      NSUTF16LittleEndianStringEncoding

      NSUTF16StringEncoding encoding with explicit endianness specified.

      Available in iOS 2.0 and later.

    • NSUTF32StringEncoding

      NSUTF32StringEncoding

      32-bit UTF encoding.

      Available in iOS 2.0 and later.

    • NSUTF32BigEndianStringEncoding

      NSUTF32BigEndianStringEncoding

      NSUTF32StringEncoding encoding with explicit endianness specified.

      Available in iOS 2.0 and later.

    • NSUTF32LittleEndianStringEncoding

      NSUTF32LittleEndianStringEncoding

      NSUTF32StringEncoding encoding with explicit endianness specified.

      Available in iOS 2.0 and later.

    • NSProprietaryStringEncoding

      NSProprietaryStringEncoding

      Installation-specific encoding.

      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.

    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.

  • Constants to specify kinds of substrings and styles of enumeration.

    Declaration

    Swift

    struct NSStringEnumerationOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var ByLines: NSStringEnumerationOptions { get } static var ByParagraphs: NSStringEnumerationOptions { get } static var ByComposedCharacterSequences: NSStringEnumerationOptions { get } static var ByWords: NSStringEnumerationOptions { get } static var BySentences: NSStringEnumerationOptions { get } static var Reverse: NSStringEnumerationOptions { get } static var SubstringNotRequired: NSStringEnumerationOptions { get } static var Localized: NSStringEnumerationOptions { get } }

    Objective-C

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

    Constants

    • ByLines

      NSStringEnumerationByLines

      Enumerates by lines. Equivalent to lineRangeForRange:.

      Available in iOS 4.0 and later.

    • ByParagraphs

      NSStringEnumerationByParagraphs

      Enumerates by paragraphs. Equivalent to paragraphRangeForRange:.

      Available in iOS 4.0 and later.

    • ByComposedCharacterSequences

      NSStringEnumerationByComposedCharacterSequences

      Enumerates by composed character sequences. Equivalent to rangeOfComposedCharacterSequencesForRange:.

      Available in iOS 4.0 and later.

    • ByWords

      NSStringEnumerationByWords

      Enumerates by words.

      Available in iOS 4.0 and later.

    • BySentences

      NSStringEnumerationBySentences

      Enumerates by sentences.

      Available in iOS 4.0 and later.

    • Reverse

      NSStringEnumerationReverse

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

      Available in iOS 4.0 and later.

    • SubstringNotRequired

      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.

    • Localized

      NSStringEnumerationLocalized

      Causes the enumeration to occur using the current 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.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.