NSString

Inherits From

NSObject
NSString
NSMutableString
NSSimpleCString

NSObject
NSString
NSMutableString

Conforms To

Import Statement

Objective-C

@import Foundation;

Swift

import Foundation

Availability

Available in OS X v10.0 and later

The NSString class and its mutable subclass, NSMutableString, provide an extensive set of APIs for working with strings, including methods for comparing, searching, and modifying strings. NSString objects are used extensively throughout Foundation and other Cocoa frameworks, serving as the basis for all textual and linguistic functionality on the platform.

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

String Objects

An NSString object encodes a Unicode-compliant text string, represented as a sequence of UTF–16 code units. All lengths, character indexes, and ranges are expressed in terms of 16-bit platform-endian values, with index values starting at 0.

An NSString object can be initialized from or written to a C buffer, an NSData object, or the contents of an NSURL. It can also be encoded and decoded to and from ASCII, UTF–8, UTF–16, UTF–32, or any other string encoding represented by NSStringEncoding.

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 a sequence of UTF–16 code units. You can determine how many UTF-16 code units a string object contains with the length method and can retrieve a specific UTF-16 code unit 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. Unicode is a registered trademark of Unicode, Inc.

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 unichar values, the returned string is always native-endian, since the array always contains UTF–16 code units in native byte order.

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.

Creating and Initializing Strings

+ string

Returns an empty string.

Declaration

Objective-C

+ (instancetype)string

Return Value

An empty string.

Availability

Available in OS X v10.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.

Availability

Available in OS X v10.0 and later.

See Also

+ string


    
      
           init(bytes:length:encoding:)
      
      
           - initWithBytes:length:encoding:

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

Declaration

Swift

convenience init?(bytes bytes: UnsafePointer<Void>, length len: 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.

Availability

Available in OS X v10.3 and later.

Declaration

Swift

convenience init?(bytesNoCopy bytes: UnsafeMutablePointer<Void>, length len: Int, encoding encoding: UInt, freeWhenDone freeBuffer: 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 releases the memory with `free()` 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.

Availability

Available in OS X v10.3 and later.

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 UTF–16 code units; the value must not be `NULL`. Important Raises an exception if `characters` is `NULL`, even if `length` is `0`.
`length`	The number of characters to use from `characters`.

Return Value

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

Availability

Available in OS X v10.0 and later.

Declaration

Swift

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

Objective-C

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

Parameters

`characters`	A C array of UTF–16 code units.
`length`	The number of characters to use from `characters`.
`flag`	If `YEStrue`, the receiver releases the memory with `free()` when it no longer needs the data; 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

Availability

Available in OS X v10.0 and later.

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.

Availability

Available in OS X v10.0 and later.

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

Only 8-bit encodings are supported, as encodings that have a greater width, such as UTF-16, may include a NULL byte in a single unit, which would result in the premature termination of the C string.

Availability

Available in OS X v10.4 and later.

Declaration

Swift

convenience init?(UTF8String nullTerminatedCString: 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.

Availability

Available in OS X v10.0 and later.

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`. Important Raises an `NSInvalidArgumentException` if `format` is `nil`.
`...`	A comma-separated list of arguments to substitute into `format`.

Return Value

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

Discussion

Invokes initWithFormat:locale:arguments: without applying any localization. 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. To create a localized string for the user’s current locale, use the class method localizedStringWithFormat:, or useinitWithFormat:locale: or initWithFormat:locale:arguments:, passing [NSLocale currentLocale] as the locale.

Availability

Available in OS X v10.0 and later.

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`. Important Raises an `NSInvalidArgumentException` if `format` is `nil`.
`argList`	A list of arguments to substitute into `format`.

Return Value

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

Discussion

Invokes initWithFormat:locale:arguments: without applying any localization.

Availability

Available in OS X v10.0 and later.

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`. Important Raises an `NSInvalidArgumentException` if `format` is `nil`.
`locale`	An `NSLocale` object specifying the locale to use. To use the current locale, pass `[NSLocale currentLocale]`. 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.

Availability

Available in OS X v10.0 and later.

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`. Important Raises an `NSInvalidArgumentException` if `format` is `nil`.
`locale`	An `NSLocale` object specifying the locale to use. To use the current locale (specified by user preferences), pass [`NSLocale` `currentLocale`]. 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 Objective-C code fragment illustrates how to create a string from myArgs, which is derived from a string object with the value “Cost:” and an int with the value 32:

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

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

See String Programming Guide for more information.

Availability

Available in OS X v10.0 and later.

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 UTF–16 code units using encoding. The returned object may be different from the original receiver. Returns nil if the initialization fails for some reason (for example if data does not represent valid data for encoding).

Availability

Available in OS X v10.0 and later.


    
      
           + stringWithFormat:

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`. Important Raises an `NSInvalidArgumentException` if `format` is `nil`.
`...`	A comma-separated list of arguments to substitute into `format`.

Return Value

A string created by using format as a template into which the remaining argument values are substituted without any localization.

Discussion

This method is similar to localizedStringWithFormat:, but without localization. This is useful, for example, if you want to produce non-localized formatting which needs to be written out to files and parsed back later.

Availability

Available in OS X v10.0 and later.

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.

Availability

Available in OS X v10.0 and later.

Declaration

Objective-C

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

Parameters

`chars`	A C array of UTF–16 code units; the value must not be `NULL`. Important Raises an exception if `chars` is `NULL`, even if `length` is `0`.
`length`	The number of characters to use from `chars`.

Return Value

A string containing length UTF–16 code units taken (starting with the first) from chars.

Availability

Available in OS X v10.0 and later.

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.

Availability

Available in OS X v10.0 and later.

Creating and Initializing a String from a File


    
      
           + stringWithContentsOfFile:encoding:error:

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 * _Nullable *)error

Parameters

`path`	A path to a file.
`enc`	The encoding of the file at `path`.
`error`	If an error occurs, upon returns contains an `NSError` object that describes the problem. If you are not interested in possible errors, pass in `NULL`.

Return Value

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

Availability

Available in OS X v10.4 and later.

Declaration

Swift

convenience init(contentsOfFile path: String, encoding enc: UInt) throws

Objective-C

- (instancetype)initWithContentsOfFile:(NSString *)path encoding:(NSStringEncoding)enc error:(NSError * _Nullable *)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.

Discussion

Availability

Available in OS X v10.4 and later.

Declaration

Objective-C

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

Parameters

`path`	A path to a file.
`enc`	Upon return, if the file is read successfully, contains the encoding used to interpret the file at `path`.
`error`	If an error occurs, upon returns contains an `NSError` object that describes the problem. If you are not interested in possible errors, you may pass in `NULL`.

Return Value

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

Discussion

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

Availability

Available in OS X v10.4 and later.

Declaration

Swift

convenience init(contentsOfFile path: String, usedEncoding enc: UnsafeMutablePointer<UInt>) throws

Objective-C

- (instancetype)initWithContentsOfFile:(NSString *)path usedEncoding:(NSStringEncoding *)enc error:(NSError * _Nullable *)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.

Discussion

Availability

Available in OS X v10.4 and later.

Creating and Initializing a String from an URL


    
      
           + stringWithContentsOfURL:encoding:error:

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 * _Nullable *)error

Parameters

`url`	The URL to read.
`enc`	The encoding of the data at `url`.
`error`	If an error occurs, upon returns contains an `NSError` object that describes the problem. If you are not interested in possible errors, you may pass in `NULL`.

Return Value

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

Availability

Available in OS X v10.4 and later.

Declaration

Swift

convenience init(contentsOfURL url: NSURL, encoding enc: UInt) throws

Objective-C

- (instancetype)initWithContentsOfURL:(NSURL *)url encoding:(NSStringEncoding)enc error:(NSError * _Nullable *)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.

Discussion

Availability

Available in OS X v10.4 and later.

Declaration

Objective-C

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

Parameters

`url`	The URL from which to read data.
`enc`	Upon return, if `url` is read successfully, contains the encoding used to interpret the data.
`error`	If an error occurs, upon returns contains an `NSError` object that describes the problem. If you are not interested in possible errors, you may pass in `NULL`.

Return Value

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

Discussion

This method attempts to determine the encoding at url.

Availability

Available in OS X v10.4 and later.

Declaration

Swift

convenience init(contentsOfURL url: NSURL, usedEncoding enc: UnsafeMutablePointer<UInt>) throws

Objective-C

- (instancetype)initWithContentsOfURL:(NSURL *)url usedEncoding:(NSStringEncoding *)enc error:(NSError * _Nullable *)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];

      

Availability

Available in OS X v10.4 and later.

Writing to a File or URL


    
      
           writeToFile(_:atomically:encoding:)
      
      
           - writeToFile:atomically:encoding:error:

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

Objective-C

- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile encoding:(NSStringEncoding)enc error:(NSError * _Nullable *)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.

Availability

Available in OS X v10.4 and later.


    
      
           writeToURL(_:atomically:encoding:)
      
      
           - writeToURL:atomically:encoding:error:

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

Objective-C

- (BOOL)writeToURL:(NSURL *)url atomically:(BOOL)useAuxiliaryFile encoding:(NSStringEncoding)enc error:(NSError * _Nullable *)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

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

Availability

Available in OS X v10.4 and later.

Getting a String’s Length

length length Property

The number of UTF–16 code units 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.

Availability

Available in OS X v10.0 and later.

See Also

– lengthOfBytesUsingEncoding:
sizeWithAttributes: (NSString Additions)
lengthOfBytesUsingEncoding(_:) - lengthOfBytesUsingEncoding:

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.

Availability

Available in OS X v10.4 and later.

See Also

– maximumLengthOfBytesUsingEncoding:
– length
maximumLengthOfBytesUsingEncoding(_:) - maximumLengthOfBytesUsingEncoding:

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.

Availability

Available in OS X v10.4 and later.

See Also

– lengthOfBytesUsingEncoding:
– length

Getting Characters and Bytes

characterAtIndex(_:) - characterAtIndex:

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.

Availability

Available in OS X v10.0 and later.

See Also

– getCharacters:range:


    
      
           getCharacters(_:range:)
      
      
           - getCharacters:range:

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

Declaration

Swift

func getCharacters(_ buffer: UnsafeMutablePointer<unichar>, range range: 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. Important Raises an `NSRangeException` if any part of `aRange` lies beyond the bounds of the receiver.

Discussion

This method does not add a NULL character.

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

Availability

Available in OS X v10.0 and later.


    
      
           getBytes(_:maxLength:usedLength:encoding:options:range:remainingRange:)
      
      
           - getBytes:maxLength:usedLength:encoding:options:range:remainingRange:

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.

Availability

Available in OS X v10.5 and later.

Getting C Strings

cStringUsingEncoding(_:) - cStringUsingEncoding:

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.

Availability

Available in OS X v10.4 and later.

See Also

– getCString:
– canBeConvertedToEncoding:
+ defaultCStringEncoding
– cStringLength
– UTF8String


    
      
           getCString(_:maxLength:encoding:)
      
      
           - getCString:maxLength:encoding:

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

Availability

Available in OS X v10.4 and later.

Identifying and Comparing Strings


    
      
           caseInsensitiveCompare(_:)
      
      
           - caseInsensitiveCompare:

Returns the result of invoking compare:options: with the case-insensitive option.

Declaration

Swift

func caseInsensitiveCompare(_ string: 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

This method adds the NSCaseInsensitiveSearch option automatically. If you are comparing strings to present to the end-user, you should typically use localizedCaseInsensitiveCompare: instead.

Availability

Available in OS X v10.0 and later.

Declaration

Swift

func localizedCaseInsensitiveCompare(_ string: 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.

Availability

Available in OS X v10.0 and later.

Declaration

Swift

func compare(_ string: 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.

Availability

Available in OS X v10.0 and later.

Declaration

Swift

func localizedCompare(_ string: 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.

Availability

Available in OS X v10.0 and later.

Declaration

Swift

func compare(_ string: 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.

Availability

Available in OS X v10.0 and later.

Declaration

Swift

func compare(_ string: String, options mask: NSStringCompareOptions, range compareRange: 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. Important Raises an `NSRangeException` if `range` exceeds the bounds of the receiver.

Return Value

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

Discussion

If you are comparing strings to present to the end-user, use compare:options:range:locale: instead and pass the current locale.

Availability

Available in OS X v10.0 and later.

Declaration

Swift

func compare(_ string: String, options mask: NSStringCompareOptions, range compareRange: 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. Important Raises an `NSRangeException` if `range` exceeds 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.

Availability

Available in OS X v10.0 and later.

Combining Strings


    
      
           - stringByAppendingFormat:

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`. Important Raises an `NSInvalidArgumentException` if `format` is `nil`.
`...`	A comma-separated list of arguments to substitute into `format`.

Return Value

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

Availability

Available in OS X v10.0 and later.

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

Availability

Available in OS X v10.0 and later.

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

      

Availability

Available in OS X v10.2 and later.

Dividing Strings

componentsSeparatedByString(_:) - componentsSeparatedByString:
Returns an array containing substrings from the receiver that have been divided by a given separator.

Declaration

Swift

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

Objective-C

- (NSArray<NSString *> *)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" }.
Availability

Available in OS X v10.0 and later.

See Also

componentsJoinedByString: (NSArray)
– pathComponents
componentsSeparatedByCharactersInSet(_:) - componentsSeparatedByCharactersInSet:

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

Declaration

Swift

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

Objective-C

- (NSArray<NSString *> *)componentsSeparatedByCharactersInSet:(NSCharacterSet *)separator

Parameters

separator

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

Return Value

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

Discussion

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

Availability

Available in OS X v10.5 and later.

See Also

– componentsSeparatedByString:
– stringByTrimmingCharactersInSet:
stringByTrimmingCharactersInSet(_:) - stringByTrimmingCharactersInSet:

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.

Availability

Available in OS X v10.2 and later.

See Also

– componentsSeparatedByCharactersInSet:


    
      
           substringFromIndex(_:)
      
      
           - substringFromIndex:

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

Declaration

Swift

func substringFromIndex(_ from: 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.

Availability

Available in OS X v10.0 and later.

Declaration

Swift

func substringWithRange(_ range: 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.

Availability

Available in OS X v10.0 and later.

Declaration

Swift

func substringToIndex(_ to: 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.

Availability

Available in OS X v10.0 and later.

Finding Characters and Substrings

containsString(_:) - containsString:

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

Declaration

Swift

func containsString(_ str: String) -> Bool

Objective-C

- (BOOL)containsString:(NSString *)str

Parameters

str

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

Return Value

YEStrue if the receiver contains str, otherwise NOfalse.

Discussion

Calling this method is equivalent to calling rangeOfString:options: with no options.

Availability

Available in OS X v10.10 and later.
localizedCaseInsensitiveContainsString(_:) - localizedCaseInsensitiveContainsString:

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

Declaration

Swift

func localizedCaseInsensitiveContainsString(_ str: String) -> Bool

Objective-C

- (BOOL)localizedCaseInsensitiveContainsString:(NSString *)str

Parameters

str

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

Return Value

YEStrue if the receiver contains str, otherwise NOfalse.

Discussion

Calling this method is equivalent to calling rangeOfString:options: with the NSCaseInsensitiveSearch option.

Availability

Available in OS X v10.10 and later.
localizedStandardContainsString(_:) - localizedStandardContainsString:

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

Declaration

Swift

func localizedStandardContainsString(_ str: String) -> Bool

Objective-C

- (BOOL)localizedStandardContainsString:(NSString *)str

Parameters

str

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

Return Value

YEStrue if the receiver contains str, otherwise NOfalse.

Availability

Available in OS X v10.11 and later.
localizedStandardRangeOfString(_:) - localizedStandardRangeOfString:

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

Declaration

Swift

func localizedStandardRangeOfString(_ str: String) -> NSRange

Objective-C

- (NSRange)localizedStandardRangeOfString:(NSString *)str

Parameters

str

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

Return Value

The range of the first occurrence of str in the receiver. Returns {NSNotFound, 0} if str is not found.

Availability

Available in OS X v10.11 and later.
rangeOfCharacterFromSet(_:) - rangeOfCharacterFromSet:

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

Declaration

Swift

func rangeOfCharacterFromSet(_ searchSet: 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.

Availability

Available in OS X v10.0 and later.


    
      
           rangeOfCharacterFromSet(_:options:)
      
      
           - rangeOfCharacterFromSet:options:

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

Declaration

Swift

func rangeOfCharacterFromSet(_ searchSet: 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.

Availability

Available in OS X v10.0 and later.


    
      
           rangeOfCharacterFromSet(_:options:range:)
      
      
           - rangeOfCharacterFromSet:options:range:

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

Declaration

Swift

func rangeOfCharacterFromSet(_ searchSet: NSCharacterSet, options mask: NSStringCompareOptions, range searchRange: 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

This method does not perform any Unicode normalization on the receiver, so canonically equivalent forms will not be matched. For example, searching the string “strüdel”—containing the decomposed characters “u” (U+0075 LATIN SMALL LETTER U) and “¨” (U+0308 COMBINING DIAERESIS)—with a character set containing the precomposed character “ü” (U+00FC LATIN SMALL LETTER U WITH DIAERESIS) would return the range {NSNotFound, 0}, because none of the characters in the set are found.

Special Considerations

Availability

Available in OS X v10.0 and later.

rangeOfString(_:) - rangeOfString:

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

Declaration

Swift

func rangeOfString(_ searchString: 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.

Availability

Available in OS X v10.0 and later.


    
      
           rangeOfString(_:options:)
      
      
           - rangeOfString:options:

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

Declaration

Swift

func rangeOfString(_ searchString: 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`. Important Raises an `NSInvalidArgumentException` if `aString` is `nil`.
`mask`	A mask specifying search options. The following options may be specified by combining them with the C bitwise `OR` operator: `NSCaseInsensitiveSearch`, `NSLiteralSearch`, `NSBackwardsSearch`, `NSAnchoredSearch`. See String Programming Guide for details on these options.

Return Value

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

Discussion

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

Availability

Available in OS X v10.0 and later.


    
      
           rangeOfString(_:options:range:)
      
      
           - rangeOfString:options:range:

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

Declaration

Swift

func rangeOfString(_ searchString: String, options mask: NSStringCompareOptions, range searchRange: 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`, `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

Availability

Available in OS X v10.0 and later.


    
      
           rangeOfString(_:options:range:locale:)
      
      
           - rangeOfString:options:range:locale:

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

Declaration

Swift

func rangeOfString(_ searchString: String, options mask: NSStringCompareOptions, range searchRange: 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`, `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 [`NSLocale` `currentLocale`]. 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

Discussion

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

Special Considerations

Availability

Available in OS X v10.5 and later.


    
      
           enumerateLinesUsingBlock(_:)
      
      
           - enumerateLinesUsingBlock:

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.

Availability

Available in OS X v10.6 and later.


    
      
           enumerateSubstringsInRange(_:options:usingBlock:)
      
      
           - enumerateSubstringsInRange:options:usingBlock:

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

Availability

Available in OS X v10.6 and later.

Replacing Substrings

stringByReplacingOccurrencesOfString(_:withString:) - stringByReplacingOccurrencesOfString:withString:

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

Declaration

Swift

func stringByReplacingOccurrencesOfString(_ target: String, withString replacement: String) -> String

Objective-C

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

Parameters

target

The string to replace.

replacement

The string with which to replace target.

Return Value

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

Discussion

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

Availability

Available in OS X v10.5 and later.

See Also

– stringByReplacingOccurrencesOfString:withString:options:range:
– stringByReplacingCharactersInRange:withString:
– stringByReplacingPercentEscapesUsingEncoding:


    
      
           stringByReplacingOccurrencesOfString(_:withString:options:range:)
      
      
           - stringByReplacingOccurrencesOfString:withString:options:range:

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

Declaration

Swift

func stringByReplacingOccurrencesOfString(_ target: String, withString replacement: String, options options: NSStringCompareOptions, range searchRange: NSRange) -> String

Objective-C

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

Parameters

`target`	The string to replace.
`replacement`	The string with which to replace `target`.
`options`	A mask of options to use when comparing `target` with the receiver. Pass `0` to specify no options.
`searchRange`	The range in the receiver in which to search for `target`.

Return Value

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

Availability

Available in OS X v10.5 and later.

Determining Line and Paragraph Ranges


    
      
           getLineStart(_:end:contentsEnd:forRange:)
      
      
           - getLineStart:end:contentsEnd:forRange:

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

Declaration

Swift

func getLineStart(_ startPtr: UnsafeMutablePointer<Int>, end lineEndPtr: UnsafeMutablePointer<Int>, contentsEnd contentsEndPtr: UnsafeMutablePointer<Int>, forRange range: 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+000A Unicode Character 'LINE FEED (LF)' (\n)
U+000D Unicode Character 'CARRIAGE RETURN (CR)' (\r)
U+0085 Unicode Character 'NEXT LINE (NEL)'
U+2028 Unicode Character 'LINE SEPARATOR'
U+2029 Unicode Character '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

Availability

Available in OS X v10.0 and later.

Declaration

Swift

func getParagraphStart(_ startPtr: UnsafeMutablePointer<Int>, end parEndPtr: UnsafeMutablePointer<Int>, contentsEnd contentsEndPtr: UnsafeMutablePointer<Int>, forRange range: 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.

Availability

Available in OS X v10.3 and later.

Determining Composed Character Sequences

rangeOfComposedCharacterSequenceAtIndex(_:) - rangeOfComposedCharacterSequenceAtIndex:

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

Declaration

Swift

func rangeOfComposedCharacterSequenceAtIndex(_ index: 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 decomposed base letter found at or before anIndex, and its length includes the decomposed base letter and all combining characters that follow.

Availability

Available in OS X v10.0 and later.

See Also

– rangeOfComposedCharacterSequencesForRange:
rangeOfComposedCharacterSequencesForRange(_:) - rangeOfComposedCharacterSequencesForRange:

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.

Availability

Available in OS X v10.5 and later.

See Also

– rangeOfComposedCharacterSequenceAtIndex:

Converting String Contents Into a Property List

propertyList() - propertyList

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

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.

Important

Raises an NSParseErrorException if the receiver cannot be parsed as a property list.

Availability

Available in OS X v10.0 and later.

See Also

– propertyListFromStringsFileFormat
+ stringWithContentsOfFile:
propertyListFromStringsFileFormat() - propertyListFromStringsFileFormat
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";
Availability

Available in OS X v10.0 and later.

See Also

– propertyList
+ stringWithContentsOfFile:

Drawing Strings


    
      
           drawAtPoint(_:withAttributes:)
      
      
           - drawAtPoint:withAttributes:

Draws the receiver with the font and other display characteristics of the given attributes, at the specified point in the current graphics context.

Declaration

Swift

func drawAtPoint(_ point: NSPoint, withAttributes attrs: [String : AnyObject]?)

Objective-C

- (void)drawAtPoint:(NSPoint)point withAttributes:(NSDictionary<NSString *,id> *)attrs

Parameters

`point`	The point in the current graphics context where you want to start drawing the string. The coordinate system of the graphics context is usually defined by the view in which you are drawing. In AppKit, the origin is normally in the lower-left corner of the drawing area, but the origin is in the upper-left corner if the focused view is flipped.
`attrs`	A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an `NSAttributedString` object, but in the case of `NSString` objects, the attributes apply to the entire string, rather than ranges within the string.

Discussion

The width (height for vertical layout) of the rendering area is unlimited, unlike drawInRect:withAttributes:, which uses a bounding rectangle. As a result, this method renders the text in a single line. However, if newline characters are present in the string, those characters are honored and cause subsequent text to be placed on the next line underneath the starting point.

There must be either a focused view or an active graphics context when you call this method.

Import Statement

Objective-C

@import AppKit;

Swift

import AppKit

Availability

Available in OS X v10.0 and later.


    
      
           drawInRect(_:withAttributes:)
      
      
           - drawInRect:withAttributes:

Draws the attributed string inside the specified bounding rectangle.

Declaration

Swift

func drawInRect(_ rect: NSRect, withAttributes attrs: [String : AnyObject]?)

Objective-C

- (void)drawInRect:(NSRect)rect withAttributes:(NSDictionary<NSString *,id> *)attrs

Parameters

`rect`	The bounding rectangle in which to draw the string. In AppKit, the origin of the bounding box is normally in the lower-left corner, but the origin is in the upper-left corner if the focused view is flipped.
`attrs`	The text attributes with which to draw the string. These are the same attributes that can be applied to an `NSAttributedString` object, but in the case of `NSString` objects, the attributes apply to the entire string, rather than ranges within the string.

Discussion

This method draws as much of the string as it can inside the specified rectangle, wrapping the string text as needed to make it fit. If the string is too long to fit inside the rectangle, the method renders as much as possible and clips the rest.

If newline characters are present in the string, those characters are honored and cause subsequent text to be placed on the next line underneath the starting point.

There must be either a focused view or an active graphics context when you call this method.

Import Statement

Objective-C

@import AppKit;

Swift

import AppKit

Availability

Available in OS X v10.0 and later.


    
      
           drawWithRect(_:options:attributes:context:)
      
      
           - drawWithRect:options:attributes:context:

Draws the attributed string in the specified bounding rectangle using the provided options.

Declaration

Swift

func drawWithRect(_ rect: NSRect, options options: NSStringDrawingOptions, attributes attributes: [String : AnyObject]?, context context: NSStringDrawingContext?)

Objective-C

- (void)drawWithRect:(NSRect)rect options:(NSStringDrawingOptions)options attributes:(NSDictionary<NSString *,id> *)attributes context:(NSStringDrawingContext *)context

Parameters

`rect`	The bounding rectangle in which to draw the string.
`options`	Additional drawing options to apply to the string during rendering. For a list of possible values, see `NSStringDrawingOptions`.
`attributes`	The text attributes with which to draw the string. These are the same attributes that can be applied to an `NSAttributedString` object, but in the case of `NSString` objects, the attributes apply to the entire string, rather than ranges within the string.
`context`	A context object with information about how to adjust the font tracking and scaling information. On return, the specified object contains information about the actual values used to render the string. This parameter may be `nil`.

Discussion

This method draws as much of the string as it can inside the specified rectangle, wrapping the string text as needed to make it fit. If the string is too big to fit completely inside the rectangle, the method scales the font or adjusts the letter spacing to make the string fit within the given bounds.

If newline characters are present in the string, those characters are honored and cause subsequent text to be placed on the next line underneath the starting point. To correctly draw and size multi-line text, pass NSStringDrawingUsesLineFragmentOrigin in the options parameter.

Special Considerations

This method uses the baseline origin by default.

If NSStringDrawingUsesLineFragmentOrigin is not specified, the rectangle’s height will be ignored and the operation considered to be single-line rendering.

Import Statement

Objective-C

@import AppKit;

Swift

import AppKit

Availability

Available in OS X v10.11 and later.


    
      
           boundingRectWithSize(_:options:attributes:context:)
      
      
           - boundingRectWithSize:options:attributes:context:

Calculates and returns the bounding rect for the receiver drawn using the given options and display characteristics, within the specified rectangle in the current graphics context.

Declaration

Swift

func boundingRectWithSize(_ size: NSSize, options options: NSStringDrawingOptions, attributes attributes: [String : AnyObject]?, context context: NSStringDrawingContext?) -> NSRect

Objective-C

- (NSRect)boundingRectWithSize:(NSSize)size options:(NSStringDrawingOptions)options attributes:(NSDictionary<NSString *,id> *)attributes context:(NSStringDrawingContext *)context

Parameters

`size`	The size of the rectangle to draw in.
`options`	String drawing options.
`attributes`	A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an `NSAttributedString` object, but in the case of `NSString` objects, the attributes apply to the entire string, rather than ranges within the string.
`context`	The string drawing context to use for the receiver, specifying minimum scale factor and tracking adjustments.

Return Value

The bounding rect for the receiver drawn using the given options and display characteristics. The rect origin returned from this method is the first glyph origin.

Discussion

To correctly draw and size multi-line text, pass NSStringDrawingUsesLineFragmentOrigin in the options parameter.

This method returns fractional sizes (in the size component of the returned CGRect); to use a returned size to size views, you must raise its value to the nearest higher integer using the ceil function.

This method returns the actual bounds of the glyphs in the string. Some of the glyphs (spaces, for example) are allowed to overlap the layout constraints specified by the size passed in, so in some cases the width value of the size component of the returned CGRect can exceed the width value of the size parameter.

Import Statement

Objective-C

@import AppKit;

Swift

import AppKit

Availability

Available in OS X v10.11 and later.

Declaration

Swift

func sizeWithAttributes(_ attrs: [String : AnyObject]?) -> NSSize

Objective-C

- (NSSize)sizeWithAttributes:(NSDictionary<NSString *,id> *)attrs

Parameters


  attrs

A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

Return Value

The bounding box size the receiver occupies when drawn with the specified attributes.

Discussion

This method returns fractional sizes; to use a returned size to size views, you must raise its value to the nearest higher integer using the ceil function.

Import Statement

Objective-C

@import AppKit;

Swift

import AppKit

Availability

Available in OS X v10.0 and later.

Folding Strings


    
      
           stringByFoldingWithOptions(_:locale:)
      
      
           - stringByFoldingWithOptions:locale:

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 [`NSLocale` `currentLocale`]. 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.

Availability

Available in OS X v10.5 and later.

Getting a Shared Prefix


    
      
           commonPrefixWithString(_:options:)
      
      
           - commonPrefixWithString:options:

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

Declaration

Swift

func commonPrefixWithString(_ str: 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”.

Availability

Available in OS X v10.0 and later.

Changing Case

capitalizedString capitalizedString Property

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.

Note

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

Availability

Available in OS X v10.0 and later.

See Also

– capitalizedStringWithLocale:
capitalizedStringWithLocale(_:) - capitalizedStringWithLocale:

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 ([NSLocale currentLocale]). 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.

Availability

Available in OS X v10.8 and later.

See Also

– capitalizedString
lowercaseString lowercaseString Property
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”
Note

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

Available in OS X v10.0 and later.

See Also

– lowercaseStringWithLocale:
uppercaseString
– uppercaseStringWithLocale:
lowercaseStringWithLocale(_:) - lowercaseStringWithLocale:

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 ([NSLocale currentLocale]). 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

.

Availability

Available in OS X v10.8 and later.

See Also

– lowercaseString
– uppercaseString
– uppercaseStringWithLocale:
uppercaseString uppercaseString Property

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.

Note

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

Availability

Available in OS X v10.0 and later.

See Also

lowercaseString
– lowercaseStringWithLocale:
– uppercaseStringWithLocale:
uppercaseStringWithLocale(_:) - uppercaseStringWithLocale:

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 ([NSLocale currentLocale]). 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".

Availability

Available in OS X v10.8 and later.

See Also

– uppercaseString
– lowercaseString
– lowercaseStringWithLocale:

Getting Strings with Mapping

decomposedStringWithCanonicalMapping decomposedStringWithCanonicalMapping Property

A string made by normalizing the string’s contents using the Unicode Normalization Form D. (read-only)

Declaration

Swift

var decomposedStringWithCanonicalMapping: String { get }

Objective-C

@property(readonly, copy) NSString *decomposedStringWithCanonicalMapping

Availability

Available in OS X v10.2 and later.

See Also

precomposedStringWithCanonicalMapping
decomposedStringWithCompatibilityMapping
decomposedStringWithCompatibilityMapping decomposedStringWithCompatibilityMapping Property

A string made by normalizing the receiver’s contents using the Unicode Normalization Form KD. (read-only)

Declaration

Swift

var decomposedStringWithCompatibilityMapping: String { get }

Objective-C

@property(readonly, copy) NSString *decomposedStringWithCompatibilityMapping

Availability

Available in OS X v10.2 and later.

See Also

precomposedStringWithCompatibilityMapping
decomposedStringWithCanonicalMapping
precomposedStringWithCanonicalMapping precomposedStringWithCanonicalMapping Property

A string made by normalizing the string’s contents using the Unicode Normalization Form C. (read-only)

Declaration

Swift

var precomposedStringWithCanonicalMapping: String { get }

Objective-C

@property(readonly, copy) NSString *precomposedStringWithCanonicalMapping

Availability

Available in OS X v10.2 and later.

See Also

precomposedStringWithCompatibilityMapping
decomposedStringWithCanonicalMapping
precomposedStringWithCompatibilityMapping precomposedStringWithCompatibilityMapping Property

A string made by normalizing the receiver’s contents using the Unicode Normalization Form KC. (read-only)

Declaration

Swift

var precomposedStringWithCompatibilityMapping: String { get }

Objective-C

@property(readonly, copy) NSString *precomposedStringWithCompatibilityMapping

Availability

Available in OS X v10.2 and later.

See Also

precomposedStringWithCanonicalMapping
decomposedStringWithCompatibilityMapping

Getting Numeric Values

doubleValue doubleValue Property

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.

Availability

Available in OS X v10.0 and later.

See Also

floatValue
longLongValue
integerValue
scanDouble: (NSScanner)
floatValue floatValue Property

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.

Availability

Available in OS X v10.0 and later.

See Also

doubleValue
longLongValue
integerValue
scanFloat: (NSScanner)
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.

Availability

Available in OS X v10.0 and later.

See Also

integerValue
doubleValue
floatValue
scanInt: (NSScanner)
integerValue integerValue Property

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.

Availability

Available in OS X v10.5 and later.

See Also

doubleValue
floatValue
scanInt: (NSScanner)
longLongValue longLongValue Property

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.

Availability

Available in OS X v10.5 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.

Availability

Available in OS X v10.5 and later.

See Also

integerValue
scanInt: (NSScanner)

Working with Encodings

availableStringEncodings() + availableStringEncodings
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:
See the NSStringEncoding type for a larger list and descriptions of many supported encodings. In addition to those encodings listed here, you can also use the encodings defined for CFString in Core Foundation; you just need to call the CFStringConvertEncodingToNSStringEncoding function to convert them to a usable format.
Availability

Available in OS X v10.0 and later.

See Also

+ localizedNameOfStringEncoding:
defaultCStringEncoding() + defaultCStringEncoding

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 NSStringEncoding for a full list of supported encodings.

Availability

Available in OS X v10.0 and later.


    
      
           stringEncodingForData(_:encodingOptions:convertedString:usedLossyConversion:)
      
      
           + stringEncodingForData:encodingOptions:convertedString:usedLossyConversion:

Returns the string encoding for the given data as detected by attempting to create a string according to the specified encoding options.

Declaration

Swift

class func stringEncodingForData(_ data: NSData, encodingOptions opts: [String : AnyObject]?, convertedString string: AutoreleasingUnsafeMutablePointer<NSString?>, usedLossyConversion usedLossyConversion: UnsafeMutablePointer<ObjCBool>) -> UInt

Objective-C

+ (NSStringEncoding)stringEncodingForData:(NSData *)data encodingOptions:(NSDictionary<NSString *,id> *)opts convertedString:(NSString * _Nullable *)string usedLossyConversion:(BOOL *)usedLossyConversion

Parameters

`data`	An `NSData` object containing bytes in an encoding to be determined.
`opts`	Options to use when attempting to determine the string encoding. See String Encoding Detection Options for a full list of supported options.
`string`	If a string encoding could be determined, upon return contains an `NSString` object constructed from data using the determined string encoding.
`usedLossyConversion`	If a string encoding could be determined, upon return contains a `BOOL` value corresponding to whether lossy conversion was used.

Return Value

An NSStringEncoding value, or 0 if a string encoding could not be determined.

Availability

Available in OS X v10.10 and later.

localizedNameOfStringEncoding(_:) + localizedNameOfStringEncoding:

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.

Availability

Available in OS X v10.0 and later.
canBeConvertedToEncoding(_:) - canBeConvertedToEncoding:

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.

Availability

Available in OS X v10.0 and later.

See Also

– dataUsingEncoding:allowLossyConversion:
dataUsingEncoding(_:) - dataUsingEncoding:

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

Availability

Available in OS X v10.0 and later.
dataUsingEncoding(_:allowLossyConversion:) - dataUsingEncoding:allowLossyConversion:

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

Declaration

Swift

func dataUsingEncoding(_ encoding: UInt, allowLossyConversion lossy: 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.

Availability

Available in OS X v10.0 and later.

See Also

+ availableStringEncodings
– canBeConvertedToEncoding:
description description Property

This NSString object. (read-only)

Declaration

Swift

var description: String { get }

Objective-C

@property(readonly, copy) NSString *description

Availability

Available in OS X v10.0 and later.
fastestEncoding fastestEncoding Property

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.

Availability

Available in OS X v10.0 and later.

See Also

smallestEncoding
– getCharacters:range:
smallestEncoding smallestEncoding Property

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.

Availability

Available in OS X v10.0 and later.

See Also

– fastestEncoding
– getCharacters:range:

Working with Paths


    
      
           pathWithComponents(_:)
      
      
           + pathWithComponents:

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: [String]) -> String

Objective-C

+ (NSString *)pathWithComponents:(NSArray<NSString *> *)components

Parameters


  components

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

Return Value

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

Discussion

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

Availability

Available in OS X v10.0 and later.

Declaration

Swift

var pathComponents: [String] { get }

Objective-C

@property(readonly, copy) NSArray <NSString *> *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.

Availability

Available in OS X v10.0 and later.

Declaration

Swift

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

Objective-C

- (NSUInteger)completePathIntoString:(NSString * _Nonnull *)outputName caseSensitive:(BOOL)flag matchesIntoArray:(NSArray<NSString *> * _Nonnull *)outputArray filterTypes:(NSArray<NSString *> *)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).

Availability

Available in OS X v10.0 and later.

fileSystemRepresentation fileSystemRepresentation Property

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.

Availability

Available in OS X v10.0 and later.


    
      
           getFileSystemRepresentation(_:maxLength:)
      
      
           - getFileSystemRepresentation:maxLength:

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

Declaration

Swift

func getFileSystemRepresentation(_ cname: UnsafeMutablePointer<Int8>, maxLength max: 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

      

Availability

Available in OS X v10.0 and later.

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

Availability

Available in OS X v10.0 and later.

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

Availability

Available in OS X v10.0 and later.

Declaration

Swift

func stringByAppendingPathComponent(_ str: 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).

Availability

Available in OS X v10.0 and later.

Declaration

Swift

func stringByAppendingPathExtension(_ str: 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.

Discussion

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


Receiver’s String Value	Resulting String
“`/tmp/scratch.old`”	“`/tmp/scratch.old.tiff`”
“`/tmp/scratch.`”	“`/tmp/scratch..tiff`”
“`/tmp/`”	“`/tmp.tiff`”
“`scratch`”	“`scratch.tiff`”

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

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

Special Considerations

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

Availability

Available in OS X v10.0 and later.

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

Availability

Available in OS X v10.0 and later.

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

Availability

Available in OS X v10.0 and later.

Working with URLs

stringByAddingPercentEncodingWithAllowedCharacters(_:) - stringByAddingPercentEncodingWithAllowedCharacters:

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

Declaration

Swift

func stringByAddingPercentEncodingWithAllowedCharacters(_ allowedCharacters: NSCharacterSet) -> String?

Objective-C

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

Parameters

allowedCharacters

The characters not replaced in the string.

Return Value

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

Discussion

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

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

Availability

Available in OS X v10.9 and later.

See Also

– stringByAddingPercentEscapesUsingEncoding:
– stringByReplacingPercentEscapesUsingEncoding:
– stringByRemovingPercentEncoding
stringByRemovingPercentEncoding - stringByRemovingPercentEncoding

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

Declaration

Swift

var stringByRemovingPercentEncoding: String? { get }

Objective-C

@property(readonly, copy) NSString *stringByRemovingPercentEncoding

Return Value

A new string with the percent encoded sequences removed, or nil if the receiver contains an invalid percent-encoding sequence.

Availability

Available in OS X v10.9 and later.

See Also

– stringByAddingPercentEncodingWithAllowedCharacters:
– stringByAddingPercentEscapesUsingEncoding:
– stringByReplacingPercentEscapesUsingEncoding:

Linguistic Tagging and Analysis


    
      
           enumerateLinguisticTagsInRange(_:scheme:options:orthography:usingBlock:)
      
      
           - enumerateLinguisticTagsInRange:scheme:options:orthography:usingBlock:

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

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

Availability

Available in OS X v10.7 and later.


    
      
           linguisticTagsInRange(_:scheme:options:orthography:tokenRanges:)
      
      
           - linguisticTagsInRange:scheme:options:orthography:tokenRanges:

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?>) -> [String]

Objective-C

- (NSArray<NSString *> *)linguisticTagsInRange:(NSRange)range scheme:(NSString *)tagScheme options:(NSLinguisticTaggerOptions)opts orthography:(NSOrthography *)orthography tokenRanges:(NSArray<NSValue *> * _Nullable *)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

Availability

Available in OS X v10.7 and later.

Deprecated

+ stringWithCString: (OS X v10.4)

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.

Availability

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

See Also

+ stringWithCString:encoding:
- initWithCString: (OS X v10.4)

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

Availability

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

See Also

– initWithCString:encoding:
+ stringWithCString:length: (OS X v10.4)

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.

Availability

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

See Also

+ stringWithCString:encoding:
- initWithCString:length: (OS X v10.4)

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.

Availability

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

See Also

– initWithCString:encoding:
- initWithCStringNoCopy:length:freeWhenDone: (OS X v10.4)

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.

Availability

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

See Also

– initWithCString:encoding:
+ stringWithContentsOfFile: (OS X v10.4)

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

Deprecation Statement

Use stringWithContentsOfFile:encoding:error: or stringWithContentsOfFile:usedEncoding:error: instead.

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 UTF–16 code units. 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.

Availability

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

See Also

+ stringWithContentsOfFile:encoding:error:
+ stringWithContentsOfFile:usedEncoding:error:
- initWithContentsOfFile: (OS X v10.4)

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

Deprecation Statement

Use initWithContentsOfFile:encoding:error: or initWithContentsOfFile:usedEncoding:error: instead.

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 UTF–16 code units; 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.

Availability

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

See Also

– initWithContentsOfFile:encoding:error:
– initWithContentsOfFile:usedEncoding:error:
+ stringWithContentsOfURL: (OS X v10.4)

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

Deprecation Statement

Use stringWithContentsOfURL:encoding:error: or stringWithContentsOfURL:usedEncoding:error: instead.

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 UTF–16 code units. 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.

Availability

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

See Also

+ stringWithContentsOfURL:encoding:error:
+ stringWithContentsOfURL:usedEncoding:error:
- initWithContentsOfURL: (OS X v10.4)

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

Deprecation Statement

Use initWithContentsOfURL:encoding:error: or initWithContentsOfURL:usedEncoding:error: instead.

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 UTF–16 code units; 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.

Availability

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

See Also

– initWithContentsOfURL:encoding:error:
– initWithContentsOfURL:usedEncoding:error:
- writeToFile:atomically: (OS X v10.4)

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.

Availability

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

See Also

– writeToFile:atomically:encoding:error:
- writeToURL:atomically: (OS X v10.4)

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.

Availability

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

See Also

– writeToURL:atomically:encoding:error:


    
      
           getCharacters(_:)
      
      
           - getCharacters:

(OS X v10.6)

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.

Availability

Available in OS X v10.0 and later.

Deprecated in OS X v10.6.

Declaration

Swift

func drawWithRect(_ rect: NSRect, options options: NSStringDrawingOptions, attributes attributes: [String : AnyObject]?)

Objective-C

- (void)drawWithRect:(NSRect)rect options:(NSStringDrawingOptions)options attributes:(NSDictionary<NSString *,id> *)attributes

Parameters

`rect`	The rectangle in which to draw the string.
`options`	String drawing options.
`attributes`	A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an `NSAttributedString` object, but in the case of `NSString` objects, the attributes apply to the entire string, rather than ranges within the string.

Discussion

This method works in single-line, baseline rendering configuration by default. That is, the rect argument's origin field specifies the rendering origin, and that point is interpreted as the baseline origin by default. If the string drawing option NSStringDrawingUsesLineFragmentOrigin is specified, origin is interpreted as the upper left corner of the line fragment rectangle, and the method behaves in multiline configuration.

The size field specifies the text container size. The width part of the size field specifies the maximum line fragment width if larger than 0.0. The height defines the maximum size that can be occupied with text if larger than 0.0 and NSStringDrawingUsesLineFragmentOrigin is specified. If NSStringDrawingUsesLineFragmentOrigin is not specified, height is ignored and considered to be single-line rendering (NSLineBreakByWordWrapping and NSLineBreakByCharWrapping are treated as NSLineBreakByClipping).

You should only invoke this method when there is a current graphics context.

Import Statement

Objective-C

@import AppKit;

Swift

import AppKit

Availability

Available in OS X v10.4 and later.

Deprecated in OS X v10.11.


    
      
           boundingRectWithSize(_:options:attributes:)
      
      
           - boundingRectWithSize:options:attributes:

(OS X v10.11)

Calculates and returns the bounding rect for the receiver drawn using the given options and display characteristics, within the specified rectangle in the current graphics context.

Declaration

Swift

func boundingRectWithSize(_ size: NSSize, options options: NSStringDrawingOptions, attributes attributes: [String : AnyObject]?) -> NSRect

Objective-C

- (NSRect)boundingRectWithSize:(NSSize)size options:(NSStringDrawingOptions)options attributes:(NSDictionary<NSString *,id> *)attributes

Parameters

`size`	The size of the rectangle to draw in.
`options`	String drawing options.
`attributes`	A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an `NSAttributedString` object, but in the case of `NSString` objects, the attributes apply to the entire string, rather than ranges within the string.

Return Value

The bounding rect for the receiver drawn using the given options and display characteristics. The rect origin returned from this method is the first glyph origin.

Special Considerations

This method works in single-line, baseline rendering configuration by default. If the string drawing option NSStringDrawingUsesLineFragmentOrigin is specified, the method behaves in multiline configuration.

Import Statement

Objective-C

@import AppKit;

Swift

import AppKit

Availability

Available in OS X v10.4 and later.

Deprecated in OS X v10.11.

Data Types

unichar unichar

Type for UTF-16 code units.

Declaration

Swift

typealias unichar = UInt16

Objective-C

typedef unsigned short unichar;

Import Statement

Objective-C

@import Foundation;

Swift

import Foundation

Availability

Available in OS X v10.0 and later.

Constants

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

Declaration

Swift

struct NSStringCompareOptions : OptionSetType { 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 enum NSStringCompareOptions : NSUInteger { NSCaseInsensitiveSearch = 1, NSLiteralSearch = 2, NSBackwardsSearch = 4, NSAnchoredSearch = 8, NSNumericSearch = 64, NSDiacriticInsensitiveSearch = 128, NSWidthInsensitiveSearch = 256, NSForcedOrderingSearch = 512, NSRegularExpressionSearch = 1024 } NSStringCompareOptions;

Constants
- CaseInsensitiveSearch
  
  NSCaseInsensitiveSearch
  
  A case-insensitive search.
  
  Available in OS X v10.0 and later.
- LiteralSearch
  
  NSLiteralSearch
  
  Exact character-by-character equivalence.
  
  Available in OS X v10.0 and later.
- BackwardsSearch
  
  NSBackwardsSearch
  
  Search from end of source string.
  
  Available in OS X v10.0 and later.
- AnchoredSearch
  
  NSAnchoredSearch
  
  Search is limited to start (or end, if NSBackwardsSearch) of source string.
  
  Available in OS X v10.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 OS X v10.3 and later.
- DiacriticInsensitiveSearch
  
  NSDiacriticInsensitiveSearch
  
  Search ignores diacritic marks.
  
  For example, ‘ö’ is equal to ‘o’.
  
  Available in OS X v10.5 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 OS X v10.5 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 OS X v10.5 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 OS X v10.7 and later.
Discussion

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

Import Statement

Objective-C

@import Foundation;

Swift

import Foundation

Availability

Available in OS X v10.5 and later.
NSStringEncodingConversionOptions
Options for converting string encodings.

Declaration

Swift

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

Objective-C

typedef enum NSStringEncodingConversionOptions : NSUInteger { NSStringEncodingConversionAllowLossy = 1, NSStringEncodingConversionExternalRepresentation = 2 } NSStringEncodingConversionOptions;

Constants
- AllowLossy
  
  NSStringEncodingConversionAllowLossy
  
  Allows lossy conversion.
  
  Available in OS X v10.5 and later.
- ExternalRepresentation
  
  NSStringEncodingConversionExternalRepresentation
  
  Specifies an external representation (with a byte-order mark, if necessary, to indicate endianness).
  
  Available in OS X v10.5 and later.
Import Statement

Objective-C

@import Foundation;

Swift

import Foundation

Availability

Available in OS X v10.5 and later.
NSStringEncoding
The following constants are provided by NSString as possible string encodings.

Declaration

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 }; typedef NSUInteger NSStringEncoding;

Constants
- NSASCIIStringEncoding
  
  NSASCIIStringEncoding
  
  Strict 7-bit ASCII encoding within 8-bit chars; ASCII values 0…127 only.
  
  Available in OS X v10.0 and later.
- NSNEXTSTEPStringEncoding
  
  NSNEXTSTEPStringEncoding
  
  8-bit ASCII encoding with NEXTSTEP extensions.
  
  Available in OS X v10.0 and later.
- NSJapaneseEUCStringEncoding
  
  NSJapaneseEUCStringEncoding
  
  8-bit EUC encoding for Japanese text.
  
  Available in OS X v10.0 and later.
- NSUTF8StringEncoding
  
  NSUTF8StringEncoding
  
  An 8-bit representation of Unicode characters, suitable for transmission or storage by ASCII-based systems.
  
  Available in OS X v10.0 and later.
- NSISOLatin1StringEncoding
  
  NSISOLatin1StringEncoding
  
  8-bit ISO Latin 1 encoding.
  
  Available in OS X v10.0 and later.
- NSSymbolStringEncoding
  
  NSSymbolStringEncoding
  
  8-bit Adobe Symbol encoding vector.
  
  Available in OS X v10.0 and later.
- NSNonLossyASCIIStringEncoding
  
  NSNonLossyASCIIStringEncoding
  
  7-bit verbose ASCII to represent all Unicode characters.
  
  Available in OS X v10.0 and later.
- NSShiftJISStringEncoding
  
  NSShiftJISStringEncoding
  
  8-bit Shift-JIS encoding for Japanese text.
  
  Available in OS X v10.0 and later.
- NSISOLatin2StringEncoding
  
  NSISOLatin2StringEncoding
  
  8-bit ISO Latin 2 encoding.
  
  Available in OS X v10.0 and later.
- NSUnicodeStringEncoding
  
  NSUnicodeStringEncoding
  
  The canonical Unicode encoding for string objects.
  
  Available in OS X v10.0 and later.
- NSWindowsCP1251StringEncoding
  
  NSWindowsCP1251StringEncoding
  
  Microsoft Windows codepage 1251, encoding Cyrillic characters; equivalent to AdobeStandardCyrillic font encoding.
  
  Available in OS X v10.0 and later.
- NSWindowsCP1252StringEncoding
  
  NSWindowsCP1252StringEncoding
  
  Microsoft Windows codepage 1252; equivalent to WinLatin1.
  
  Available in OS X v10.0 and later.
- NSWindowsCP1253StringEncoding
  
  NSWindowsCP1253StringEncoding
  
  Microsoft Windows codepage 1253, encoding Greek characters.
  
  Available in OS X v10.0 and later.
- NSWindowsCP1254StringEncoding
  
  NSWindowsCP1254StringEncoding
  
  Microsoft Windows codepage 1254, encoding Turkish characters.
  
  Available in OS X v10.0 and later.
- NSWindowsCP1250StringEncoding
  
  NSWindowsCP1250StringEncoding
  
  Microsoft Windows codepage 1250; equivalent to WinLatin2.
  
  Available in OS X v10.0 and later.
- NSISO2022JPStringEncoding
  
  NSISO2022JPStringEncoding
  
  ISO 2022 Japanese encoding for email.
  
  Available in OS X v10.0 and later.
- NSMacOSRomanStringEncoding
  
  NSMacOSRomanStringEncoding
  
  Classic Macintosh Roman encoding.
  
  Available in OS X v10.0 and later.
- NSUTF16StringEncoding
  
  NSUTF16StringEncoding
  
  An alias for NSUnicodeStringEncoding.
  
  Available in OS X v10.5 and later.
- NSUTF16BigEndianStringEncoding
  
  NSUTF16BigEndianStringEncoding
  
  NSUTF16StringEncoding encoding with explicit endianness specified.
  
  Available in OS X v10.5 and later.
- NSUTF16LittleEndianStringEncoding
  
  NSUTF16LittleEndianStringEncoding
  
  NSUTF16StringEncoding encoding with explicit endianness specified.
  
  Available in OS X v10.5 and later.
- NSUTF32StringEncoding
  
  NSUTF32StringEncoding
  
  32-bit UTF encoding.
  
  Available in OS X v10.5 and later.
- NSUTF32BigEndianStringEncoding
  
  NSUTF32BigEndianStringEncoding
  
  NSUTF32StringEncoding encoding with explicit endianness specified.
  
  Available in OS X v10.5 and later.
- NSUTF32LittleEndianStringEncoding
  
  NSUTF32LittleEndianStringEncoding
  
  NSUTF32StringEncoding encoding with explicit endianness specified.
  
  Available in OS X v10.5 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 OS X v10.7 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.

Import Statement

Objective-C

@import Foundation;

Availability

Available in OS X v10.0 and later.
NSStringEnumerationOptions
Constants to specify kinds of substrings and styles of enumeration.

Declaration

Swift

struct NSStringEnumerationOptions : OptionSetType { 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 enum NSStringEnumerationOptions : NSUInteger { NSStringEnumerationByLines = 0, NSStringEnumerationByParagraphs = 1, NSStringEnumerationByComposedCharacterSequences = 2, NSStringEnumerationByWords = 3, NSStringEnumerationBySentences = 4, NSStringEnumerationReverse = 1UL << 8, NSStringEnumerationSubstringNotRequired = 1UL << 9, NSStringEnumerationLocalized = 1UL << 10 } NSStringEnumerationOptions;

Constants
- ByLines
  
  NSStringEnumerationByLines
  
  Enumerates by lines. Equivalent to lineRangeForRange:.
  
  Available in OS X v10.6 and later.
- ByParagraphs
  
  NSStringEnumerationByParagraphs
  
  Enumerates by paragraphs. Equivalent to paragraphRangeForRange:.
  
  Available in OS X v10.6 and later.
- ByComposedCharacterSequences
  
  NSStringEnumerationByComposedCharacterSequences
  
  Enumerates by composed character sequences. Equivalent to rangeOfComposedCharacterSequencesForRange:.
  
  Available in OS X v10.6 and later.
- ByWords
  
  NSStringEnumerationByWords
  
  Enumerates by words.
  
  Available in OS X v10.6 and later.
- BySentences
  
  NSStringEnumerationBySentences
  
  Enumerates by sentences.
  
  Available in OS X v10.6 and later.
- Reverse
  
  NSStringEnumerationReverse
  
  Causes enumeration to occur from the end of the specified range to the start.
  
  Available in OS X v10.6 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 OS X v10.6 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 OS X v10.6 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 OS X v10.6 and later.
NSStringDrawingOptions
The following constants are provided as rendering options for a string when it is drawn.

Declaration

Swift

struct NSStringDrawingOptions : OptionSetType { init(rawValue rawValue: Int) static var UsesLineFragmentOrigin: NSStringDrawingOptions { get } static var UsesFontLeading: NSStringDrawingOptions { get } static var UsesDeviceMetrics: NSStringDrawingOptions { get } static var TruncatesLastVisibleLine: NSStringDrawingOptions { get } static var DisableScreenFontSubstitution: NSStringDrawingOptions { get } static var OneShot: NSStringDrawingOptions { get } }

Objective-C

typedef enum NSStringDrawingOptions : NSInteger { NSStringDrawingUsesLineFragmentOrigin = (1 << 0), NSStringDrawingUsesFontLeading = (1 << 1), NSStringDrawingDisableScreenFontSubstitution = (1 << 2), NSStringDrawingUsesDeviceMetrics = (1 << 3), NSStringDrawingOneShot = (1 << 4), NSStringDrawingTruncatesLastVisibleLine = (1 << 5) } NSStringDrawingOptions;

Constants
- UsesLineFragmentOrigin
  
  NSStringDrawingUsesLineFragmentOrigin
  
  The specified origin is the line fragment origin, not the baseline origin.
  
  Available in OS X v10.0 and later.
- UsesFontLeading
  
  NSStringDrawingUsesFontLeading
  
  Uses the font leading for calculating line heights.
  
  Available in OS X v10.0 and later.
- DisableScreenFontSubstitution
  
  NSStringDrawingDisableScreenFontSubstitution
  
  Disable screen font substitution (equivalent to [NSLayoutManager setUsesScreenFonts:NO]).
  
  Available in OS X v10.0 and later.
  
  Deprecated in OS X v10.11.
- UsesDeviceMetrics
  
  NSStringDrawingUsesDeviceMetrics
  
  Uses image glyph bounds instead of typographic bounds.
  
  Available in OS X v10.0 and later.
- OneShot
  
  NSStringDrawingOneShot
  
  Suppresses caching layout information.
  
  Available in OS X v10.0 and later.
  
  Deprecated in OS X v10.11.
- TruncatesLastVisibleLine
  
  NSStringDrawingTruncatesLastVisibleLine
  
  Truncates and adds the ellipsis character to the last visible line if the text doesn't fit into the bounds specified.
  
  This option is ignored if NSStringDrawingUsesLineFragmentOrigin is not also set. In addition, the line break mode must be either NSLineBreakByWordWrapping or NSLineBreakByCharWrapping for this option to take effect. The line break mode can be specified in a paragraph style passed in the attributes dictionary argument of the drawing methods.
  
  Available in OS X v10.5 and later.
Import Statement

Objective-C

@import AppKit;

Swift

import AppKit

Availability

Available in OS X v10.4 and later.
NSTextAlignment
Options for aligning text horizontally.

Declaration

Swift

enum NSTextAlignment : UInt { case Left case Right case Center case Justified case Natural }

Objective-C

typedef enum NSTextAlignment : NSUInteger { NSTextAlignmentLeft = 0, NSTextAlignmentCenter = 1, NSTextAlignmentRight = 2, NSTextAlignmentJustified = 3, NSTextAlignmentNatural = 4, } NSTextAlignment;

Constants
- Left
  
  NSTextAlignmentLeft
  
  Align text along the left edge.
  
  Available in OS X v10.11 and later.
- Center
  
  NSTextAlignmentCenter
  
  Align text equally along both sides of the center line.
  
  Available in OS X v10.11 and later.
- Right
  
  NSTextAlignmentRight
  
  Align text along the right edge.
  
  Available in OS X v10.11 and later.
- Justified
  
  NSTextAlignmentJustified
  
  Fully justify the text so that the last line in a paragraph is natural aligned.
  
  Available in OS X v10.11 and later.
- Natural
  
  NSTextAlignmentNatural
  
  Use the default alignment associated with the current localization of the app. The default alignment for left-to-right scripts is NSTextAlignmentLeft, and the default alignment for right-to-left scripts is NSTextAlignmentRight.
  
  Available in OS X v10.11 and later.
Import Statement

Objective-C

@import AppKit;

Swift

import AppKit

Availability

Available in OS X v10.0 and later.
NSWritingDirection
Constants for specifying the writing direction to use.

Declaration

Swift

enum NSWritingDirection : Int { case Natural case LeftToRight case RightToLeft }

Objective-C

typedef enum NSWritingDirection : NSInteger { NSWritingDirectionNatural = -1, NSWritingDirectionLeftToRight = 0, NSWritingDirectionRightToLeft = 1 } NSWritingDirection;

Constants
- Natural
  
  NSWritingDirectionNatural
  
  Use the Unicode Bidi algorithm rules P2 and P3 to determine which direction to use.
  
  Available in OS X v10.4 and later.
- LeftToRight
  
  NSWritingDirectionLeftToRight
  
  Use a left to right writing direction.
  
  Available in OS X v10.2 and later.
- RightToLeft
  
  NSWritingDirectionRightToLeft
  
  Use a right to left writing direction.
  
  Available in OS X v10.2 and later.
Import Statement

Objective-C

@import AppKit;

Swift

import AppKit

Availability

Available in OS X v10.2 and later.
NSString Handling Exception Names
These constants define the names of exceptions raised if NSString cannot represent a string in a given encoding, or parse a string as a property list.

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 OS X v10.0 and later.
- NSParseErrorException
  
  NSParseErrorException
  
  NSString raises an NSParseErrorException if a string cannot be parsed as a property list.
  
  Available in OS X v10.0 and later.
String Encoding Detection Options
The following constants are provided by NSString for use when detecting string encoding from a data object.

Declaration

Swift

let NSStringEncodingDetectionSuggestedEncodingsKey: String let NSStringEncodingDetectionDisallowedEncodingsKey: String let NSStringEncodingDetectionUseOnlySuggestedEncodingsKey: String let NSStringEncodingDetectionAllowLossyKey: String let NSStringEncodingDetectionFromWindowsKey: String let NSStringEncodingDetectionLossySubstitutionKey: String let NSStringEncodingDetectionLikelyLanguageKey: String

Objective-C

NSString * const NSStringEncodingDetectionSuggestedEncodingsKey; NSString * const NSStringEncodingDetectionDisallowedEncodingsKey; NSString * const NSStringEncodingDetectionUseOnlySuggestedEncodingsKey; NSString * const NSStringEncodingDetectionAllowLossyKey; NSString * const NSStringEncodingDetectionFromWindowsKey; NSString * const NSStringEncodingDetectionLossySubstitutionKey; NSString * const NSStringEncodingDetectionLikelyLanguageKey;

Constants
- NSStringEncodingDetectionSuggestedEncodingsKey
  
  NSStringEncodingDetectionSuggestedEncodingsKey
  
  Option specifying any suggested string encodings. Use this when you have prior knowledge about the likely or expected encoding. The corresponding value for this key is an NSArray of NSNumber objects that contain NSStringEncoding values. If this option is unspecified, all allowed encodings are evaluated with equal consideration.
  
  Available in OS X v10.10 and later.
- NSStringEncodingDetectionDisallowedEncodingsKey
  
  NSStringEncodingDetectionDisallowedEncodingsKey
  
  Option specifying any string encodings not to be considered. The corresponding value for this key is an NSArray of NSNumber objects that contain NSStringEncoding values. If this option is unspecified, no additional string encodings are removed from consideration.
  
  Available in OS X v10.10 and later.
- NSStringEncodingDetectionUseOnlySuggestedEncodingsKey
  
  NSStringEncodingDetectionUseOnlySuggestedEncodingsKey
  
  Option specifying whether to only consider suggested string encodings. Use this only if you specify a value for NSStringEncodingDetectionSuggestedEncodingsKey. The corresponding value for this key is an NSNumber object containing a Boolean value. By default, this value is @(NO).
  
  Available in OS X v10.10 and later.
- NSStringEncodingDetectionAllowLossyKey
  
  NSStringEncodingDetectionAllowLossyKey
  
  Option specifying whether to allow lossy string conversion. The corresponding value for this key is an NSNumber object containing a Boolean value. If @(NO), the a lossy string encoding may not be chosen. By default, this value is @(YES).
  
  Available in OS X v10.10 and later.
- NSStringEncodingDetectionFromWindowsKey
  
  NSStringEncodingDetectionFromWindowsKey
  
  Option specifying whether to consider string encodings corresponding to Windows codepage numbers. The corresponding value for this key is an NSNumber object containing a Boolean value. If @(YES), Windows string encodings are removed from consideration. By default, this value is @(NO).
  
  Available in OS X v10.10 and later.
- NSStringEncodingDetectionLossySubstitutionKey
  
  NSStringEncodingDetectionLossySubstitutionKey
  
  Option specifying the string used to substitute for any unsupported characters when converting to a lossy string encoding. If a @(NO) value is specified for NSStringEncodingDetectionAllowLossyKey, this option has no effect. The corresponding value for this key is an NSString object. By default, this value is U+FFFD.
  
  Available in OS X v10.10 and later.
- NSStringEncodingDetectionLikelyLanguageKey
  
  NSStringEncodingDetectionLikelyLanguageKey
  
  Option specifying the likely two-letter ISO 639-1 language code for the converted string. Use this when you have prior knowledge about the expected language of the converted string. The corresponding value for this key is an NSString object. If no value is specified, the language of the converted string is not considered.
  
  Available in OS X v10.10 and later.
Discussion

These constants are used as keys in the options passed to the stringEncodingForData:encodingOptions:convertedString:usedLossyConversion: method.
NSMaximumStringLength
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
  
  Maximum number of characters in an NSString object.
  
  Available in OS X v10.7 and later.
Availability

Available in OS X v10.0.

Removed in OS X v10.5.

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

`range`	A range of characters in the receiver.
`replacement`	The string with which to replace the characters in `range`.

`encoding`	A string encoding.
`flag`	If `YEStrue`, then allows characters to be removed or altered in conversion.

NSString

String Objects

Understanding Characters

Interpreting UTF-16-Encoded Data

Subclassing Notes

Methods to Override

Alternatives to Subclassing

Creating and Initializing Strings

Declaration

Return Value

Availability

See Also

Declaration

Return Value

Availability

See Also

Declaration

Parameters

Return Value

Availability

See Also

Declaration

Parameters

Return Value

Special Considerations

Availability

See Also

Declaration

Parameters

Return Value

Availability

See Also

Declaration

Parameters

Return Value

Special Considerations

Availability

See Also

Declaration

Parameters

Return Value

Availability

See Also

Declaration

Parameters

Return Value

Discussion

Special Considerations

Availability

See Also

Declaration

Parameters

Return Value

Availability

See Also

Declaration

Parameters

Return Value

Discussion

Availability

See Also

Declaration

Parameters

Return Value

Discussion

Availability

See Also

Declaration

Parameters

Discussion

Availability

See Also

Declaration

Parameters

Return Value

Discussion

Availability

See Also

Declaration

Parameters