# NSString A static, plain-text Unicode string object. ``` class NSString ``` ## Overview You can use this type in Swift when you need reference semantics or other Foundation-specific behavior. The [`NSString`](/documentation/Foundation/NSString) class and its mutable subclass, [`NSMutableString`](/documentation/Foundation/NSMutableString), provide an extensive set of APIs for working with strings, including methods for comparing, searching, and modifying strings. [`NSString`](/documentation/Foundation/NSString) objects are used throughout Foundation and other Cocoa frameworks, serving as the basis for all textual and linguistic functionality on the platform. [`NSString`](/documentation/Foundation/NSString) is *toll-free bridged* with its Core Foundation counterpart, . See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html#//apple_ref/doc/uid/TP40010810-CH2) for more information. ### String Objects An [`NSString`](/documentation/Foundation/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`](/documentation/Foundation/NSString) object can be initialized from or written to a C buffer, an [`NSData`](/documentation/Foundation/NSData) object, or the contents of an [`NSURL`](/documentation/Foundation/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`](/documentation/Foundation/NSStringEncoding). > Note: > An immutable string is a text string that is defined when it is created and subsequently cannot be changed. An immutable string is implemented as an array of UTF–16 code units (in other words, a text string). To create and manage an immutable string, use the ``doc://com.apple.foundation/documentation/Foundation/NSString`` class. To construct and manage a string that can be changed after it has been created, use ``doc://com.apple.foundation/documentation/Foundation/NSMutableString``. The objects you create using [`NSString`](/documentation/Foundation/NSString) and [`NSMutableString`](/documentation/Foundation/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`](/documentation/Foundation/NSString) or [`NSMutableString`](/documentation/Foundation/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`](/documentation/Foundation/NSString) and [`NSMutableString`](/documentation/Foundation/NSMutableString). The string classes adopt the [`NSCopying`](/documentation/Foundation/NSCopying) and [`NSMutableCopying`](/documentation/Foundation/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`](/documentation/Foundation/NSString/length) method and can retrieve a specific UTF-16 code unit with the [`character(at:)`](/documentation/Foundation/NSString/character(at:)) 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: . See also [Characters and Grapheme Clusters](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Strings/Articles/stringsClusters.html#//apple_ref/doc/uid/TP40008025) in [String Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Strings/introStrings.html#//apple_ref/doc/uid/10000035i). 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`](/documentation/Foundation/NSString) (and [`NSMutableString`](/documentation/Foundation/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`](/documentation/Foundation/NSString) and [`NSMutableString`](/documentation/Foundation/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`](/documentation/Foundation/NSString#Methods-to-Override)). Make sure your reasons for subclassing [`NSString`](/documentation/Foundation/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`](/documentation/Foundation/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`](/documentation/Foundation/NSString), a better alternative would be object composition (see [`Alternatives to Subclassing`](/documentation/Foundation/NSString#Alternatives-to-Subclassing)). Cocoa already provides an example of this with the [`NSAttributedString`](/documentation/Foundation/NSAttributedString) class. #### Methods to Override Any subclass of `NSString` *must* override the primitive instance methods [`length`](/documentation/Foundation/NSString/length) and [`character(at:)`](/documentation/Foundation/NSString/character(at:)). 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:)`](/documentation/Foundation/NSString/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 method of `super`. The `NSString` class adopts the [`NSCopying`](/documentation/Foundation/NSCopying), [`NSMutableCopying`](/documentation/Foundation/NSMutableCopying), and [`NSCoding`](/documentation/Foundation/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. ## Topics ### Creating and Initializing Strings [`string`](/documentation/Foundation/NSString/string) Returns an empty string. [`init()`](/documentation/Foundation/NSString/init()) Returns an initialized `NSString` object that contains no characters. [`init(bytes:length:encoding:)`](/documentation/Foundation/NSString/init(bytes:length:encoding:)) Returns an initialized `NSString` object containing a given number of bytes from a given buffer of bytes interpreted in a given encoding. [`init(bytesNoCopy:length:encoding:freeWhenDone:)`](/documentation/Foundation/NSString/init(bytesNoCopy:length:encoding:freeWhenDone:)) Returns an initialized `NSString` object that contains a given number of bytes from a given buffer of bytes interpreted in a given encoding, and optionally frees the buffer. [`init(characters:length:)`](/documentation/Foundation/NSString/init(characters:length:)) Returns an initialized `NSString` object that contains a given number of characters from a given C array of UTF-16 code units. [`init(charactersNoCopy:length:freeWhenDone:)`](/documentation/Foundation/NSString/init(charactersNoCopy:length:freeWhenDone:)) Returns an initialized `NSString` object that contains a given number of characters from a given C array of UTF-16 code units. [`init(string:)`](/documentation/Foundation/NSString/init(string:)-210xa) Returns an `NSString` object initialized by copying the characters from another given string. [`initWithFormat:`](/documentation/Foundation/NSString/initWithFormat:) Returns an `NSString` object initialized by using a given format string as a template into which the remaining argument values are substituted. [`init(format:arguments:)`](/documentation/Foundation/NSString/init(format:arguments:)) Returns an `NSString` object initialized by using a given format string as a template into which the remaining argument values are substituted without any localization. [`initWithFormat:locale:`](/documentation/Foundation/NSString/initWithFormat:locale:) Returns an `NSString` object initialized by using a given format string as a template into which the remaining argument values are substituted according to given locale. [`init(format:locale:arguments:)`](/documentation/Foundation/NSString/init(format:locale:arguments:)) Returns an `NSString` object initialized by using a given format string as a template into which the remaining argument values are substituted according to given locale information. This method is meant to be called from within a variadic function, where the argument list will be available. [`init(data:encoding:)`](/documentation/Foundation/NSString/init(data:encoding:)) Returns an `NSString` object initialized by converting given data into UTF-16 code units using a given encoding. [`stringWithFormat:`](/documentation/Foundation/NSString/stringWithFormat:) Returns a string created by using a given format string as a template into which the remaining argument values are substituted. [`localizedStringWithFormat:`](/documentation/Foundation/NSString/localizedStringWithFormat:) Returns a string created by using a given format string as a template into which the remaining argument values are substituted according to the current locale. [`localizedUserNotificationString(forKey:arguments:)`](/documentation/Foundation/NSString/localizedUserNotificationString(forKey:arguments:)) Returns a localized string intended for display in a notification alert. [`localizedStringWithFormat(_:_:)`](/documentation/Foundation/NSString/localizedStringWithFormat(_:_:)) [`stringWithCharacters:length:`](/documentation/Foundation/NSString/stringWithCharacters:length:) Returns a string containing a given number of characters taken from a given C array of UTF-16 code units. [`stringWithString:`](/documentation/Foundation/NSString/stringWithString:) Returns a string created by copying the characters from another given string. [`unichar`](/documentation/Foundation/unichar) Type for UTF-16 code units. ### Creating and Initializing a String from a File [`stringWithContentsOfFile:encoding:error:`](/documentation/Foundation/NSString/stringWithContentsOfFile:encoding:error:) Returns a string created by reading data from the file at a given path interpreted using a given encoding. [`init(contentsOfFile:encoding:)`](/documentation/Foundation/NSString/init(contentsOfFile:encoding:)) Returns an `NSString` object initialized by reading data from the file at a given path using a given encoding. [`stringWithContentsOfFile:usedEncoding:error:`](/documentation/Foundation/NSString/stringWithContentsOfFile:usedEncoding:error:) Returns a string created by reading data from the file at a given path and returns by reference the encoding used to interpret the file. [`init(contentsOfFile:usedEncoding:)`](/documentation/Foundation/NSString/init(contentsOfFile:usedEncoding:)) Returns an `NSString` object initialized by reading data from the file at a given path and returns by reference the encoding used to interpret the characters. ### Creating and Initializing a String from an URL ### Getting a String’s Length [`length`](/documentation/Foundation/NSString/length) The number of UTF-16 code units in the receiver. [`lengthOfBytes(using:)`](/documentation/Foundation/NSString/lengthOfBytes(using:)) Returns the number of bytes required to store the receiver in a given encoding. [`maximumLengthOfBytes(using:)`](/documentation/Foundation/NSString/maximumLengthOfBytes(using:)) Returns the maximum number of bytes needed to store the receiver in a given encoding. ### Getting Characters and Bytes [`character(at:)`](/documentation/Foundation/NSString/character(at:)) Returns the character at a given UTF-16 code unit index. [`getCharacters(_:range:)`](/documentation/Foundation/NSString/getCharacters(_:range:)) Copies characters from a given range in the receiver into a given buffer. [`getBytes(_:maxLength:usedLength:encoding:options:range:remaining:)`](/documentation/Foundation/NSString/getBytes(_:maxLength:usedLength:encoding:options:range:remaining:)) Gets a given range of characters as bytes in a specified encoding. ### Getting C Strings [`cString(using:)`](/documentation/Foundation/NSString/cString(using:)) Returns a representation of the string as a C string using a given encoding. [`getCString(_:maxLength:encoding:)`](/documentation/Foundation/NSString/getCString(_:maxLength:encoding:)) Converts the string to a given encoding and stores it in a buffer. [`utf8String`](/documentation/Foundation/NSString/utf8String) A null-terminated UTF8 representation of the string. ### Identifying and Comparing Strings [`caseInsensitiveCompare(_:)`](/documentation/Foundation/NSString/caseInsensitiveCompare(_:)) Returns the result of invoking [`compare(_:options:)`](/documentation/Foundation/NSString/compare(_:options:)) with `NSCaseInsensitiveSearch` as the only option. [`localizedCaseInsensitiveCompare(_:)`](/documentation/Foundation/NSString/localizedCaseInsensitiveCompare(_:)) Compares the string with a given string using a case-insensitive, localized, comparison. [`compare(_:)`](/documentation/Foundation/NSString/compare(_:)) Returns the result of invoking [`compare(_:options:range:)`](/documentation/Foundation/NSString/compare(_:options:range:)) with no options and the receiver’s full extent as the range. [`localizedCompare(_:)`](/documentation/Foundation/NSString/localizedCompare(_:)) Compares the string and a given string using a localized comparison. [`compare(_:options:)`](/documentation/Foundation/NSString/compare(_:options:)) Compares the string with the specified string using the given options. [`compare(_:options:range:)`](/documentation/Foundation/NSString/compare(_:options:range:)) Returns the result of invoking [`compare(_:options:range:locale:)`](/documentation/Foundation/NSString/compare(_:options:range:locale:)) with a `nil` locale. [`compare(_:options:range:locale:)`](/documentation/Foundation/NSString/compare(_:options:range:locale:)) Compares the string using the specified options and returns the lexical ordering for the range. [`localizedStandardCompare(_:)`](/documentation/Foundation/NSString/localizedStandardCompare(_:)) Compares strings as sorted by the Finder. [`hasPrefix(_:)`](/documentation/Foundation/NSString/hasPrefix(_:)) Returns a Boolean value that indicates whether a given string matches the beginning characters of the receiver. [`hasSuffix(_:)`](/documentation/Foundation/NSString/hasSuffix(_:)) Returns a Boolean value that indicates whether a given string matches the ending characters of the receiver. [`isEqual(to:)`](/documentation/Foundation/NSString/isEqual(to:)) Returns a Boolean value that indicates whether a given string is equal to the receiver using a literal Unicode-based comparison. [`hash`](/documentation/Foundation/NSString/hash) An unsigned integer that can be used as a hash table address. [`NSString.CompareOptions`](/documentation/Foundation/NSString/CompareOptions) These values represent the options available to many of the string classes’ search and comparison methods. [`NSString.EncodingConversionOptions`](/documentation/Foundation/NSString/EncodingConversionOptions) Options for converting string encodings. ### Combining Strings [`appendingFormat(_:_:)`](/documentation/Foundation/NSString/appendingFormat(_:_:)) [`stringByAppendingFormat:`](/documentation/Foundation/NSString/stringByAppendingFormat:) Returns a string made by appending to the receiver a string constructed from a given format string and the following arguments. [`appending(_:)`](/documentation/Foundation/NSString/appending(_:)) Returns a new string made by appending a given string to the receiver. [`padding(toLength:withPad:startingAt:)`](/documentation/Foundation/NSString/padding(toLength:withPad:startingAt:)) Returns a new string formed from the receiver by either removing characters from the end, or by appending as many occurrences as necessary of a given pad string. ### Changing Case [`lowercased`](/documentation/Foundation/NSString/lowercased) A lowercase representation of the string. [`localizedLowercase`](/documentation/Foundation/NSString/localizedLowercase) Returns a version of the string with all letters converted to lowercase, taking into account the current locale. [`lowercased(with:)`](/documentation/Foundation/NSString/lowercased(with:)) Returns a version of the string with all letters converted to lowercase, taking into account the specified locale. [`uppercased`](/documentation/Foundation/NSString/uppercased) An uppercase representation of the string. [`localizedUppercase`](/documentation/Foundation/NSString/localizedUppercase) Returns a version of the string with all letters converted to uppercase, taking into account the current locale. [`uppercased(with:)`](/documentation/Foundation/NSString/uppercased(with:)) Returns a version of the string with all letters converted to uppercase, taking into account the specified locale. [`capitalized`](/documentation/Foundation/NSString/capitalized) A capitalized representation of the string. [`localizedCapitalized`](/documentation/Foundation/NSString/localizedCapitalized) Returns a capitalized representation of the receiver using the current locale. [`capitalized(with:)`](/documentation/Foundation/NSString/capitalized(with:)) Returns a capitalized representation of the receiver using the specified locale. ### Dividing Strings [`components(separatedBy:)`](/documentation/Foundation/NSString/components(separatedBy:)-238fy) Returns an array containing substrings from the receiver that have been divided by a given separator. [`components(separatedBy:)`](/documentation/Foundation/NSString/components(separatedBy:)-27x9g) Returns an array containing substrings from the receiver that have been divided by characters in a given set. [`trimmingCharacters(in:)`](/documentation/Foundation/NSString/trimmingCharacters(in:)) Returns a new string made by removing from both ends of the receiver characters contained in a given character set. [`substring(from:)`](/documentation/Foundation/NSString/substring(from:)) Returns a new string containing the characters of the receiver from the one at a given index to the end. [`substring(with:)`](/documentation/Foundation/NSString/substring(with:)) Returns a string object containing the characters of the receiver that lie within a given range. [`substring(to:)`](/documentation/Foundation/NSString/substring(to:)) Returns a new string containing the characters of the receiver up to, but not including, the one at a given index. ### Normalizing Strings [`decomposedStringWithCanonicalMapping`](/documentation/Foundation/NSString/decomposedStringWithCanonicalMapping) A string made by normalizing the string’s contents using the Unicode Normalization Form D. [`decomposedStringWithCompatibilityMapping`](/documentation/Foundation/NSString/decomposedStringWithCompatibilityMapping) A string made by normalizing the receiver’s contents using the Unicode Normalization Form KD. [`precomposedStringWithCanonicalMapping`](/documentation/Foundation/NSString/precomposedStringWithCanonicalMapping) A string made by normalizing the string’s contents using the Unicode Normalization Form C. [`precomposedStringWithCompatibilityMapping`](/documentation/Foundation/NSString/precomposedStringWithCompatibilityMapping) A string made by normalizing the receiver’s contents using the Unicode Normalization Form KC. ### Folding Strings [`folding(options:locale:)`](/documentation/Foundation/NSString/folding(options:locale:)) Creates a string suitable for comparison by removing the specified character distinctions from a string. ### Transforming Strings [`applyingTransform(_:reverse:)`](/documentation/Foundation/NSString/applyingTransform(_:reverse:)) Returns a new string by applying a specified transform to the string. [`StringTransform`](/documentation/Foundation/StringTransform) Constants representing an ICU string transform. ### Finding Characters and Substrings [`contains(_:)`](/documentation/Foundation/NSString/contains(_:)) Returns a Boolean value indicating whether the string contains a given string by performing a case-sensitive, locale-unaware search. [`localizedCaseInsensitiveContains(_:)`](/documentation/Foundation/NSString/localizedCaseInsensitiveContains(_:)) Returns a Boolean value indicating whether the string contains a given string by performing a case-insensitive, locale-aware search. [`localizedStandardContains(_:)`](/documentation/Foundation/NSString/localizedStandardContains(_:)) Returns a Boolean value indicating whether the string contains a given string by performing a case and diacritic insensitive, locale-aware search. [`rangeOfCharacter(from:)`](/documentation/Foundation/NSString/rangeOfCharacter(from:)) Finds and returns the range in the string of the first character from a given character set. [`rangeOfCharacter(from:options:)`](/documentation/Foundation/NSString/rangeOfCharacter(from:options:)) Finds and returns the range in the string of the first character, using given options, from a given character set. [`rangeOfCharacter(from:options:range:)`](/documentation/Foundation/NSString/rangeOfCharacter(from:options:range:)) Finds and returns the range in the string of the first character from a given character set found in a given range with given options. [`range(of:)`](/documentation/Foundation/NSString/range(of:)) Finds and returns the range of the first occurrence of a given string within the string. [`range(of:options:)`](/documentation/Foundation/NSString/range(of:options:)) Finds and returns the range of the first occurrence of a given string within the string, subject to given options. [`range(of:options:range:)`](/documentation/Foundation/NSString/range(of:options:range:)) Finds and returns the range of the first occurrence of a given string, within the given range of the string, subject to given options. [`range(of:options:range:locale:)`](/documentation/Foundation/NSString/range(of:options:range:locale:)) Finds and returns the range of the first occurrence of a given string within a given range of the string, subject to given options, using the specified locale, if any. [`localizedStandardRange(of:)`](/documentation/Foundation/NSString/localizedStandardRange(of:)) Finds and returns the range of the first occurrence of a given string within the string by performing a case and diacritic insensitive, locale-aware search. [`enumerateLines(_:)`](/documentation/Foundation/NSString/enumerateLines(_:)) Enumerates all the lines in the string. [`enumerateSubstrings(in:options:using:)`](/documentation/Foundation/NSString/enumerateSubstrings(in:options:using:)) Enumerates the substrings of the specified type in the specified range of the string. ### Replacing Substrings [`replacingOccurrences(of:with:)`](/documentation/Foundation/NSString/replacingOccurrences(of:with:)) Returns a new string in which all occurrences of a target string in the receiver are replaced by another given string. [`replacingOccurrences(of:with:options:range:)`](/documentation/Foundation/NSString/replacingOccurrences(of:with: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. [`replacingCharacters(in:with:)`](/documentation/Foundation/NSString/replacingCharacters(in:with:)) Returns a new string in which the characters in a specified range of the receiver are replaced by a given string. ### Getting a Shared Prefix [`commonPrefix(with:options:)`](/documentation/Foundation/NSString/commonPrefix(with: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. ### Performing Linguistic Analysis [`enumerateLinguisticTags(in:scheme:options:orthography:using:)`](/documentation/Foundation/NSString/enumerateLinguisticTags(in:scheme:options:orthography:using:)) Performs linguistic analysis on the specified string by enumerating the specific range of the string, providing the Block with the located tags. [`linguisticTags(in:scheme:options:orthography:tokenRanges:)`](/documentation/Foundation/NSString/linguisticTags(in:scheme:options:orthography:tokenRanges:)) Returns an array of linguistic tags for the specified range and requested tags within the receiving string. [`NSString.EnumerationOptions`](/documentation/Foundation/NSString/EnumerationOptions) Constants to specify kinds of substrings and styles of enumeration. ### Determining Line and Paragraph Ranges [`getLineStart(_:end:contentsEnd:for:)`](/documentation/Foundation/NSString/getLineStart(_:end:contentsEnd:for:)) Returns by reference the beginning of the first line and the end of the last line touched by the given range. [`lineRange(for:)`](/documentation/Foundation/NSString/lineRange(for:)) Returns the range of characters representing the line or lines containing a given range. [`getParagraphStart(_:end:contentsEnd:for:)`](/documentation/Foundation/NSString/getParagraphStart(_:end:contentsEnd:for:)) Returns by reference the beginning of the first paragraph and the end of the last paragraph touched by the given range. [`paragraphRange(for:)`](/documentation/Foundation/NSString/paragraphRange(for:)) Returns the range of characters representing the paragraph or paragraphs containing a given range. ### Determining Composed Character Sequences [`rangeOfComposedCharacterSequence(at:)`](/documentation/Foundation/NSString/rangeOfComposedCharacterSequence(at:)) Returns the range in the receiver of the composed character sequence located at a given index. [`rangeOfComposedCharacterSequences(for:)`](/documentation/Foundation/NSString/rangeOfComposedCharacterSequences(for:)) Returns the range in the string of the composed character sequences for a given range. ### Writing to a File or URL [`write(toFile:atomically:encoding:)`](/documentation/Foundation/NSString/write(toFile:atomically:encoding:)) Writes the contents of the receiver to a file at a given path using a given encoding. [`write(to:atomically:encoding:)`](/documentation/Foundation/NSString/write(to:atomically:encoding:)) Writes the contents of the receiver to the URL specified by `url` using the specified encoding. ### Converting String Contents Into a Property List [`propertyList()`](/documentation/Foundation/NSString/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. [`propertyListFromStringsFileFormat()`](/documentation/Foundation/NSString/propertyListFromStringsFileFormat()) Returns a dictionary object initialized with the keys and values found in the receiver. ### Sizing and Drawing Strings [`draw(at:withAttributes:)`](/documentation/Foundation/NSString/draw(at:withAttributes:)) Draws the receiver with the font and other display characteristics of the given attributes, at the specified point in the current graphics context. [`draw(in:withAttributes:)`](/documentation/Foundation/NSString/draw(in:withAttributes:)) Draws the attributed string inside the specified bounding rectangle. [`draw(with:options:attributes:context:)`](/documentation/Foundation/NSString/draw(with:options:attributes:context:)) Draws the attributed string in the specified bounding rectangle using the provided options. [`boundingRect(with:options:attributes:context:)`](/documentation/Foundation/NSString/boundingRect(with: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. [`size(withAttributes:)`](/documentation/Foundation/NSString/size(withAttributes:)) Returns the bounding box size the receiver occupies when drawn with the given attributes. [`variantFittingPresentationWidth(_:)`](/documentation/Foundation/NSString/variantFittingPresentationWidth(_:)) Returns a string variation suitable for the specified presentation width. ### Getting Numeric Values [`doubleValue`](/documentation/Foundation/NSString/doubleValue) The floating-point value of the string as a `double`. [`floatValue`](/documentation/Foundation/NSString/floatValue) The floating-point value of the string as a `float`. [`intValue`](/documentation/Foundation/NSString/intValue) The integer value of the string. [`integerValue`](/documentation/Foundation/NSString/integerValue) The `NSInteger` value of the string. [`longLongValue`](/documentation/Foundation/NSString/longLongValue) The `long long` value of the string. [`boolValue`](/documentation/Foundation/NSString/boolValue) The Boolean value of the string. ### Working with Encodings [`availableStringEncodings`](/documentation/Foundation/NSString/availableStringEncodings) Returns a zero-terminated list of the encodings string objects support in the application’s environment. [`defaultCStringEncoding`](/documentation/Foundation/NSString/defaultCStringEncoding) Returns the C-string encoding assumed for any method accepting a C string as an argument. [`stringEncoding(for:encodingOptions:convertedString:usedLossyConversion:)`](/documentation/Foundation/NSString/stringEncoding(for: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. [`localizedName(of:)`](/documentation/Foundation/NSString/localizedName(of:)) Returns a human-readable string giving the name of a given encoding. [`canBeConverted(to:)`](/documentation/Foundation/NSString/canBeConverted(to:)) Returns a Boolean value that indicates whether the receiver can be converted to a given encoding without loss of information. [`data(using:)`](/documentation/Foundation/NSString/data(using:)) Returns an `NSData` object containing a representation of the receiver encoded using a given encoding. [`data(using:allowLossyConversion:)`](/documentation/Foundation/NSString/data(using:allowLossyConversion:)) Returns an `NSData` object containing a representation of the receiver encoded using a given encoding. [`description`](/documentation/Foundation/NSString/description) [`fastestEncoding`](/documentation/Foundation/NSString/fastestEncoding) The fastest encoding to which the receiver may be converted without loss of information. [`smallestEncoding`](/documentation/Foundation/NSString/smallestEncoding) The smallest encoding to which the receiver can be converted without loss of information. [`NSStringEncoding`](/documentation/Foundation/NSStringEncoding) The following constants are provided by `NSString` as possible string encodings. [`StringEncodingDetectionOptionsKey`](/documentation/Foundation/StringEncodingDetectionOptionsKey) [NSString Handling Exception Names](/documentation/Foundation/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. ### Working with Paths [`path(withComponents:)`](/documentation/Foundation/NSString/path(withComponents:)) Returns a string built from the strings in a given array by concatenating them with a path separator between each pair. [`pathComponents`](/documentation/Foundation/NSString/pathComponents) The file-system path components of the receiver. [`completePath(into:caseSensitive:matchesInto:filterTypes:)`](/documentation/Foundation/NSString/completePath(into:caseSensitive:matchesInto:filterTypes:)) Interprets the receiver as a path in the file system and attempts to perform filename completion, returning a numeric value that indicates whether a match was possible, and by reference the longest path that matches the receiver. [`fileSystemRepresentation`](/documentation/Foundation/NSString/fileSystemRepresentation) A file system-specific representation of the receiver. [`getFileSystemRepresentation(_:maxLength:)`](/documentation/Foundation/NSString/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. [`isAbsolutePath`](/documentation/Foundation/NSString/isAbsolutePath) A Boolean value that indicates whether the receiver represents an absolute path. [`lastPathComponent`](/documentation/Foundation/NSString/lastPathComponent) The last path component of the receiver. [`pathExtension`](/documentation/Foundation/NSString/pathExtension) The path extension, if any, of the string as interpreted as a path. [`abbreviatingWithTildeInPath`](/documentation/Foundation/NSString/abbreviatingWithTildeInPath) A new string that replaces the current home directory portion of the current path with a tilde (`~`) character. [`appendingPathComponent(_:)`](/documentation/Foundation/NSString/appendingPathComponent(_:)) Returns a new string made by appending to the receiver a given string. [`appendingPathExtension(_:)`](/documentation/Foundation/NSString/appendingPathExtension(_:)) Returns a new string made by appending to the receiver an extension separator followed by a given extension. [`deletingLastPathComponent`](/documentation/Foundation/NSString/deletingLastPathComponent) A new string made by deleting the last path component from the receiver, along with any final path separator. [`deletingPathExtension`](/documentation/Foundation/NSString/deletingPathExtension) A new string made by deleting the extension (if any, and only the last) from the receiver. [`expandingTildeInPath`](/documentation/Foundation/NSString/expandingTildeInPath) A new string made by expanding the initial component of the receiver to its full path value. [`resolvingSymlinksInPath`](/documentation/Foundation/NSString/resolvingSymlinksInPath) A new string made from the receiver by resolving all symbolic links and standardizing path. [`standardizingPath`](/documentation/Foundation/NSString/standardizingPath) A new string made by removing extraneous path components from the receiver. [`strings(byAppendingPaths:)`](/documentation/Foundation/NSString/strings(byAppendingPaths:)) Returns an array of strings made by separately appending to the receiver each string in a given array. ### Working with URL Strings [`addingPercentEncoding(withAllowedCharacters:)`](/documentation/Foundation/NSString/addingPercentEncoding(withAllowedCharacters:)) Returns a new string made from the receiver by replacing all characters not in the specified set with percent-encoded characters. [`removingPercentEncoding`](/documentation/Foundation/NSString/removingPercentEncoding) Returns a new string made from the receiver by replacing all percent encoded sequences with the matching UTF-8 characters. ### Deprecated [`string(withCString:)`](/documentation/Foundation/NSString/string(withCString:)) Creates a new string using a given C-string. [`init(CString:)`](/documentation/Foundation/NSString/init(CString:)-vkuo) 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. [`string(withCString:length:)`](/documentation/Foundation/NSString/string(withCString:length:)) Returns a string containing the characters in a given C-string. [`init(CString:length:)`](/documentation/Foundation/NSString/init(CString:length:)-5ure3) 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. [`init(CStringNoCopy:length:freeWhenDone:)`](/documentation/Foundation/NSString/init(CStringNoCopy:length:freeWhenDone:)-86dm2) 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. [`string(withContentsOfFile:)`](/documentation/Foundation/NSString/string(withContentsOfFile:)) Returns a string created by reading data from the file named by a given path. [`init(contentsOfFile:)`](/documentation/Foundation/NSString/init(contentsOfFile:)) Initializes the receiver, a newly allocated `NSString` object, by reading data from the file named by `path`. [`string(withContentsOf:)`](/documentation/Foundation/NSString/string(withContentsOf:)) Returns a string created by reading data from the file named by a given URL. [`init(contentsOfURL:)`](/documentation/Foundation/NSString/init(contentsOfURL:)) Initializes the receiver, a newly allocated `NSString` object, by reading data from the location named by a given URL. [`write(toFile:atomically:)`](/documentation/Foundation/NSString/write(toFile:atomically:)) Writes the contents of the receiver to the file specified by a given path. [`write(to:atomically:)`](/documentation/Foundation/NSString/write(to:atomically:)) Writes the contents of the receiver to the location specified by a given URL. [`getCharacters(_:)`](/documentation/Foundation/NSString/getCharacters(_:)) Copies all characters from the receiver into a given buffer. [`cString()`](/documentation/Foundation/NSString/cString()) Returns a representation of the receiver as a C string in the default C-string encoding. [`lossyCString()`](/documentation/Foundation/NSString/lossyCString()) Returns a representation of the receiver as a C string in the default C-string encoding, possibly losing information in converting to that encoding. [`cStringLength()`](/documentation/Foundation/NSString/cStringLength()) Returns the length in char-sized units of the receiver’s C-string representation in the default C-string encoding. [`getCString(_:)`](/documentation/Foundation/NSString/getCString(_:)) Invokes [`getCString(_:maxLength:range:remaining:)`](/documentation/Foundation/NSString/getCString(_:maxLength:range:remaining:)) with `NSMaximumStringLength` as the maximum length, the receiver’s entire extent as the range, and `NULL` for the remaining range. [`getCString(_:maxLength:)`](/documentation/Foundation/NSString/getCString(_:maxLength:)) Invokes [`getCString(_:maxLength:range:remaining:)`](/documentation/Foundation/NSString/getCString(_:maxLength:range:remaining:)) with `maxLength` as the maximum length in char-sized units, the receiver’s entire extent as the range, and `NULL` for the remaining range. [`getCString(_:maxLength:range:remaining:)`](/documentation/Foundation/NSString/getCString(_:maxLength:range:remaining:)) Converts the receiver’s content to the default C-string encoding and stores them in a given buffer. [`addingPercentEscapes(using:)`](/documentation/Foundation/NSString/addingPercentEscapes(using:)) Returns a representation of the receiver using a given encoding to determine the percent escapes necessary to convert the receiver into a legal URL string. [`replacingPercentEscapes(using:)`](/documentation/Foundation/NSString/replacingPercentEscapes(using:)) Returns a new string made by replacing in the receiver all percent escapes with the matching characters as determined by a given encoding. [`sizeWithFont:`](/documentation/Foundation/NSString/sizeWithFont:) Returns the size of the string if it were to be rendered with the specified font on a single line. [`sizeWithFont:forWidth:lineBreakMode:`](/documentation/Foundation/NSString/sizeWithFont:forWidth:lineBreakMode:) Returns the size of the string if it were to be rendered with the specified font and line attributes on a single line. [`sizeWithFont:minFontSize:actualFontSize:forWidth:lineBreakMode:`](/documentation/Foundation/NSString/sizeWithFont:minFontSize:actualFontSize:forWidth:lineBreakMode:) Returns the size of the string if it were rendered with the specified constraints, including a variable font size, on a single line. [`sizeWithFont:constrainedToSize:`](/documentation/Foundation/NSString/sizeWithFont:constrainedToSize:) Returns the size of the string if it were rendered and constrained to the specified size. [`sizeWithFont:constrainedToSize:lineBreakMode:`](/documentation/Foundation/NSString/sizeWithFont:constrainedToSize:lineBreakMode:) Returns the size of the string if it were rendered with the specified constraints. [`drawAtPoint:withFont:`](/documentation/Foundation/NSString/drawAtPoint:withFont:) Draws the string in a single line at the specified point in the current graphics context using the specified font. [`drawAtPoint:forWidth:withFont:lineBreakMode:`](/documentation/Foundation/NSString/drawAtPoint:forWidth:withFont:lineBreakMode:) Draws the string in a single line at the specified point in the current graphics context using the specified font and attributes. [`drawAtPoint:forWidth:withFont:fontSize:lineBreakMode:baselineAdjustment:`](/documentation/Foundation/NSString/drawAtPoint:forWidth:withFont:fontSize:lineBreakMode:baselineAdjustment:) Draws the string in a single line at the specified point in the current graphics context using the specified font and attributes. [`drawAtPoint:forWidth:withFont:minFontSize:actualFontSize:lineBreakMode:baselineAdjustment:`](/documentation/Foundation/NSString/drawAtPoint:forWidth:withFont:minFontSize:actualFontSize:lineBreakMode:baselineAdjustment:) Draws the string in a single line with the specified font and attributes, adjusting the font attributes as needed to render as much of the text as possible. [`drawInRect:withFont:`](/documentation/Foundation/NSString/drawInRect:withFont:) Draws the string in the current graphics context using the specified bounding rectangle and font. [`drawInRect:withFont:lineBreakMode:`](/documentation/Foundation/NSString/drawInRect:withFont:lineBreakMode:) Draws the string in the current graphics context using the specified bounding rectangle, font, and attributes. [`drawInRect:withFont:lineBreakMode:alignment:`](/documentation/Foundation/NSString/drawInRect:withFont:lineBreakMode:alignment:) Draws the string in the current graphics context using the specified bounding rectangle, font and attributes. [`draw(with:options:attributes:)`](/documentation/Foundation/NSString/draw(with:options:attributes:)) Draws the receiver with the specified options and other display characteristics of the given attributes, within the specified rectangle in the current graphics context. [`boundingRect(with:options:attributes:)`](/documentation/Foundation/NSString/boundingRect(with:options:attributes:)) 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. [`NSMaximumStringLength`](/documentation/Foundation/NSMaximumStringLength) Maximum number of characters in an `NSString` object. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)