Structure

String

A Unicode string value that is a collection of characters.

Overview

A string is a series of characters, such as "Swift", that forms a collection. Strings in Swift are Unicode correct and locale insensitive, and are designed to be efficient. The String type bridges with the Objective-C class NSString and offers interoperability with C functions that works with strings.

You can create new strings using string literals or string interpolations. A string literal is a series of characters enclosed in quotes.

let greeting = "Welcome!"

String interpolations are string literals that evaluate any included expressions and convert the results to string form. String interpolations give you an easy way to build a string from multiple pieces. Wrap each expression in a string interpolation in parentheses, prefixed by a backslash.

let name = "Rosa"
let personalizedGreeting = "Welcome, \(name)!"
// personalizedGreeting == "Welcome, Rosa!"

let price = 2
let number = 3
let cookiePrice = "\(number) cookies: $\(price * number)."
// cookiePrice == "3 cookies: $6."

Combine strings using the concatenation operator (+).

let longerGreeting = greeting + " We're glad you're here!"
// longerGreeting == "Welcome! We're glad you're here!"

Multiline string literals are enclosed in three double quotation marks ("""), with each delimiter on its own line. Indentation is stripped from each line of a multiline string literal to match the indentation of the closing delimiter.

let banner = """
          __,
         (          o   /) _/_
          `.  , , , ,  //  /
        (___)(_(_/_(_ //_ (__
                     /)
                    (/
        """

Modifying and Comparing Strings

Strings always have value semantics. Modifying a copy of a string leaves the original unaffected.

var otherGreeting = greeting
otherGreeting += " Have a nice time!"
// otherGreeting == "Welcome! Have a nice time!"

print(greeting)
// Prints "Welcome!"

Comparing strings for equality using the equal-to operator (==) or a relational operator (like < or >=) is always performed using Unicode canonical representation. As a result, different representations of a string compare as being equal.

let cafe1 = "Cafe\u{301}"
let cafe2 = "Café"
print(cafe1 == cafe2)
// Prints "true"

The Unicode code point "\u{301}" modifies the preceding character to include an accent, so "e\u{301}" has the same canonical representation as the single Unicode code point "é".

Basic string operations are not sensitive to locale settings, ensuring that string comparisons and other operations always have a single, stable result, allowing strings to be used as keys in Dictionary instances and for other purposes.

Accessing String Elements

A string is a collection of extended grapheme clusters, which approximate human-readable characters. Many individual characters, such as “é”, “김”, and “🇮🇳”, can be made up of multiple Unicode code points. These code points are combined by Unicode’s boundary algorithms into extended grapheme clusters, represented by the Swift Character type. Each element of a string is represented by a Character instance.

For example, to retrieve the first word of a longer string, you can search for a space and then create a substring from a prefix of the string up to that point:

let name = "Marie Curie"
let firstSpace = name.index(of: " ") ?? name.endIndex
let firstName = name[..<firstSpace]
// firstName == "Marie"

The firstName constant is an instance of the Substring type—a type that represents substrings of a string while sharing the original string’s storage. Substrings present the same interface as strings.

print("\(name)'s first name has \(firstName.count) letters.")
// Prints "Marie Curie's name has 5 letters."

Accessing a String’s Unicode Representation

If you need to access the contents of a string as encoded in different Unicode encodings, use one of the string’s unicodeScalars, utf16, or utf8 properties. Each property provides access to a view of the string as a series of code units, each encoded in a different Unicode encoding.

To demonstrate the different views available for every string, the following examples use this String instance:

let cafe = "Cafe\u{301} du 🌍"
print(cafe)
// Prints "Café du 🌍"

The cafe string is a collection of the nine characters that are visible when the string is displayed.

print(cafe.count)
// Prints "9"
print(Array(cafe))
// Prints "["C", "a", "f", "é", " ", "d", "u", " ", "🌍"]"

Unicode Scalar View

A string’s unicodeScalars property is a collection of Unicode scalar values, the 21-bit codes that are the basic unit of Unicode. Each scalar value is represented by a Unicode.Scalar instance and is equivalent to a UTF-32 code unit.

print(cafe.unicodeScalars.count)
// Prints "10"
print(Array(cafe.unicodeScalars))
// Prints "["C", "a", "f", "e", "\u{0301}", " ", "d", "u", " ", "\u{0001F30D}"]"
print(cafe.unicodeScalars.map { $0.value })
// Prints "[67, 97, 102, 101, 769, 32, 100, 117, 32, 127757]"

The unicodeScalars view’s elements comprise each Unicode scalar value in the cafe string. In particular, because cafe was declared using the decomposed form of the "é" character, unicodeScalars contains the code points for both the letter "e" (101) and the accent character "´" (769).

UTF-16 View

A string’s utf16 property is a collection of UTF-16 code units, the 16-bit encoding form of the string’s Unicode scalar values. Each code unit is stored as a UInt16 instance.

print(cafe.utf16.count)
// Prints "11"
print(Array(cafe.utf16))
// Prints "[67, 97, 102, 101, 769, 32, 100, 117, 32, 55356, 57101]"

The elements of the utf16 view are the code units for the string when encoded in UTF-16. These elements match those accessed through indexed NSString APIs.

let nscafe = cafe as NSString
print(nscafe.length)
// Prints "11"
print(nscafe.character(at: 3))
// Prints "101"

UTF-8 View

A string’s utf8 property is a collection of UTF-8 code units, the 8-bit encoding form of the string’s Unicode scalar values. Each code unit is stored as a UInt8 instance.

print(cafe.utf8.count)
// Prints "14"
print(Array(cafe.utf8))
// Prints "[67, 97, 102, 101, 204, 129, 32, 100, 117, 32, 240, 159, 140, 141]"

The elements of the utf8 view are the code units for the string when encoded in UTF-8. This representation matches the one used when String instances are passed to C APIs.

let cLength = strlen(cafe)
print(cLength)
// Prints "14"

Measuring the Length of a String

When you need to know the length of a string, you must first consider what you’ll use the length for. Are you measuring the number of characters that will be displayed on the screen, or are you measuring the amount of storage needed for the string in a particular encoding? A single string can have greatly differing lengths when measured by its different views.

For example, an ASCII character like the capital letter A is represented by a single element in each of its four views. The Unicode scalar value of A is 65, which is small enough to fit in a single code unit in both UTF-16 and UTF-8.

let capitalA = "A"
print(capitalA.count)
// Prints "1"
print(capitalA.unicodeScalars.count)
// Prints "1"
print(capitalA.utf16.count)
// Prints "1"
print(capitalA.utf8.count)
// Prints "1"

On the other hand, an emoji flag character is constructed from a pair of Unicode scalar values, like "\u{1F1F5}" and "\u{1F1F7}". Each of these scalar values, in turn, is too large to fit into a single UTF-16 or UTF-8 code unit. As a result, each view of the string "🇵🇷" reports a different length.

let flag = "🇵🇷"
print(flag.count)
// Prints "1"
print(flag.unicodeScalars.count)
// Prints "2"
print(flag.utf16.count)
// Prints "4"
print(flag.utf8.count)
// Prints "8"

To check whether a string is empty, use its isEmpty property instead of comparing the length of one of the views to 0. Unlike with isEmpty, calculating a view’s count property requires iterating through the elements of the string.

Accessing String View Elements

To find individual elements of a string, use the appropriate view for your task. For example, to retrieve the first word of a longer string, you can search the characters view for a space and then create a new string from a prefix of the characters view up to that point.

let name = "Marie Curie"
let firstSpace = name.index(of: " ") ?? name.endIndex
let firstName = name[..<firstSpace]
print(firstName)
// Prints "Marie"

You can convert an index into one of a string’s views to an index into another view.

let firstSpaceUTF8 = firstSpace.samePosition(in: name.utf8)
print(Array(name.utf8[..<firstSpaceUTF8]))
// Prints "[77, 97, 114, 105, 101]"

Performance Optimizations

Although strings in Swift have value semantics, strings use a copy-on-write strategy to store their data in a buffer. This buffer can then be shared by different copies of a string. A string’s data is only copied lazily, upon mutation, when more than one string instance is using the same buffer. Therefore, the first in any sequence of mutating operations may cost O(n) time and space.

When a string’s contiguous storage fills up, a new buffer must be allocated and data must be moved to the new storage. String buffers use an exponential growth strategy that makes appending to a string a constant time operation when averaged over many append operations.

Bridging Between String and NSString

Any String instance can be bridged to NSString using the type-cast operator (as), and any String instance that originates in Objective-C may use an NSString instance as its storage. Because any arbitrary subclass of NSString can become a String instance, there are no guarantees about representation or efficiency when a String instance is backed by NSString storage. Because NSString is immutable, it is just as though the storage was shared by a copy. The first in any sequence of mutating operations causes elements to be copied into unique, contiguous storage which may cost O(n) time and space, where n is the length of the string’s encoded representation (or more, if the underlying NSString has unusual performance characteristics).

For more information about the Unicode terms used in this discussion, see the Unicode.org glossary. In particular, this discussion mentions extended grapheme clusters, Unicode scalar values, and canonical equivalence.

Topics

Creating a String

In addition to creating a string from a single string literal, you can also create an empty string, a string containing an existing group of characters, or a string repeating the contents of another string.

init()

Creates an empty string.

init(Character)

Creates a string containing the given character.

init<S>(S)

Creates a new string containing the characters in the given sequence.

Beta
init<S>(S)

Creates a new instance of a collection containing the elements of a sequence.

init(repeating: String, count: Int)

Creates a new string representing the given string repeated the specified number of times.

init(Substring)

Creates a new string from the given substring.

Beta
init(repeating: Character, count: Int)

Creates a string representing the given character repeated the specified number of times.

Beta
init(repeating: Character, count: Int)

Creates a new collection containing the specified number of a single, repeated value.

Beta

Inspecting a String

var isEmpty: Bool

A Boolean value indicating whether the collection is empty.

var count: String.CharacterView.IndexDistance

The number of elements in the collection.

Beta

Creating a String from Unicode Data

init?(data: Data, encoding: String.Encoding)

Returns a String initialized by converting given data into Unicode characters using a given encoding.

init?(utf8String: UnsafePointer<CChar>)

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

init?(validatingUTF8: UnsafePointer<CChar>)

Creates a new string by copying and validating the null-terminated UTF-8 data referenced by the given pointer.

init(utf16CodeUnits: UnsafePointer<unichar>, count: Int)

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

init(utf16CodeUnitsNoCopy: UnsafePointer<unichar>, count: Int, freeWhenDone: Bool)

Returns an initialized String object that contains a given number of characters from a given array of UTF-16 Code Units

init<C, Encoding>(decoding: C, as: Encoding.Type)

Creates a string from the given Unicode code units in the specified encoding.

Beta

Creating a String Using Formats

init(format: String, CVarArg...)

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

init(format: String, arguments: [CVarArg])

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

init(format: String, locale: Locale?, CVarArg...)

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

init(format: String, locale: Locale?, arguments: [CVarArg])

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

static func localizedStringWithFormat(String, CVarArg...)

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

Converting a C String

init?<S>(bytes: S, encoding: String.Encoding)

Produces an initialized NSString object equivalent to the given bytes interpreted in the given encoding.

init?(bytesNoCopy: UnsafeMutableRawPointer, length: Int, encoding: String.Encoding, freeWhenDone: Bool)

Produces an initialized String object that contains a given number of bytes from a given buffer of bytes interpreted in a given encoding, and optionally frees the buffer. WARNING: this initializer is not memory-safe!

init(cString: UnsafePointer<CChar>)

Creates a new string by copying the null-terminated UTF-8 data referenced by the given pointer.

init(cString: UnsafePointer<UInt8>)

Creates a new string by copying the null-terminated UTF-8 data referenced by the given pointer.

init?(cString: UnsafePointer<CChar>, encoding: String.Encoding)

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

init<Encoding>(decodingCString: UnsafePointer<Encoding.CodeUnit>, as: Encoding.Type)

Creates a string from the null-terminated sequence of bytes at the given pointer.

Beta
static func decodeCString<Encoding>(UnsafePointer<Encoding.CodeUnit>?, as: Encoding.Type, repairingInvalidCodeUnits: Bool)

Creates a new string by copying the null-terminated data referenced by the given pointer using the specified encoding.

Converting Other Types to Strings

init<T>(T)

Creates an instance from the description of a given LosslessStringConvertible instance.

init<Subject>(describing: Subject)

Creates a string representing the given value.

init<Subject>(reflecting: Subject)

Creates a string with a detailed representation of the given value, suitable for debugging.

Creating a String from a File or URL

init(contentsOf: URL, encoding: String.Encoding)

Produces a string created by reading data from a given URL interpreted using a given encoding. Errors are written into the inout error argument.

init(contentsOf: URL, usedEncoding: inout String.Encoding)

Produces a string created by reading data from a given URL and returns by reference the encoding used to interpret the data. Errors are written into the inout error argument.

init(contentsOfFile: String, encoding: String.Encoding)

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

init(contentsOfFile: String, usedEncoding: inout String.Encoding)

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

Writing to a File or URL

func write(String)

Appends the given string to this string.

func write<Target>(to: inout Target)

Writes the string into the given output stream.

func write(to: URL, atomically: Bool, encoding: String.Encoding)

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

func write(toFile: String, atomically: Bool, encoding: String.Encoding)

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

Appending Strings and Characters

func append(Character)

Adds an element to the end of the collection.

func append(String)

Appends the given string to this string.

func append<S>(contentsOf: S)

Appends the characters in the given sequence to the string.

func append<S>(contentsOf: S)

Adds the elements of a sequence or collection to the end of this collection.

Beta
func appending(String)

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

func appendingFormat(String, CVarArg...)

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

func padding(toLength: Int, withPad: String, startingAt: Int)

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

func reserveCapacity(Int)

Reserves enough space in the string’s underlying storage to store the specified number of ASCII characters.

Inserting Characters

func insert(Character, at: String.Index)

Inserts a new character at the specified position.

func insert(Character, at: String.Index)

Inserts a new element into the collection at the specified position.

Beta
func insert<S>(contentsOf: S, at: String.Index)

Inserts a collection of characters at the specified position.

func insert<C>(contentsOf: C, at: String.Index)

Inserts the elements of a sequence into the collection at the specified position.

Beta
func reserveCapacity(String.CharacterView.IndexDistance)

Prepares the collection to store the specified number of elements, when doing so is appropriate for the underlying type.

Beta

Replacing Substrings

func replaceSubrange<C, R>(R, with: C)

Replaces the specified subrange of elements with the given collection.

Beta
func replaceSubrange<C>(Range<String.Index>, with: C)

Replaces the text within the specified bounds with the given characters.

func replacingCharacters(in: Range<String.Index>, with: String)

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

func replacingOccurrences(of: String, with: String, options: String.CompareOptions, range: Range<String.Index>?)

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

Removing Substrings

func remove(at: String.Index)

Removes and returns the character at the specified position.

func remove(at: String.Index)

Removes and returns the element at the specified position.

Beta
func removeAll(keepingCapacity: Bool)

Removes all elements from the collection.

func removeFirst()

Removes and returns the first element of the collection.

Beta
func removeFirst(Int)

Removes the specified number of elements from the beginning of the collection.

Beta
func removeLast()

Removes and returns the last element of the collection.

Beta
func removeLast(Int)

Removes the specified number of elements from the end of the collection.

Beta
func removeSubrange<R>(R)

Removes the elements in the specified subrange from the collection.

Beta
func removeSubrange(Range<String.Index>)

Removes the characters in the given range.

func removeSubrange(Range<String.Index>)

Removes the elements in the specified subrange from the collection.

Beta
func trimmingCharacters(in: CharacterSet)

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

func filter((Character) -> Bool)

Returns a new collection of the same type containing, in order, the elements of the original collection that satisfy the given predicate.

Beta
func drop(while: (Character) -> Bool)

Returns a subsequence by skipping elements while predicate returns true and returning the remaining elements.

Beta
func dropFirst()

Returns a subsequence containing all but the first element of the sequence.

Beta
func dropFirst(Int)

Returns a subsequence containing all but the given number of initial elements.

Beta
func dropLast()

Returns a subsequence containing all but the last element of the sequence.

Beta
func dropLast(Int)

Returns a subsequence containing all but the specified number of final elements.

Beta

Changing Case

var capitalized: String

A capitalized representation of the string.

func capitalized(with: Locale?)

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

var localizedCapitalized: String

A capitalized representation of the String that is produced using the current locale.

func lowercased()

Returns a lowercase version of the string.

func lowercased(with: Locale?)

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

var localizedLowercase: String

A lowercase version of the string that is produced using the current locale.

func uppercased()

Returns an uppercase version of the string.

func uppercased(with: Locale?)

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

var localizedUppercase: String

An uppercase version of the string that is produced using the current locale.

Comparing Strings

func compare(String, options: String.CompareOptions, range: Range<String.Index>?, locale: Locale?)

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

func caseInsensitiveCompare(String)

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

func localizedCompare(String)

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

func localizedCaseInsensitiveCompare(String)

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

func localizedStandardCompare(String)

Compares strings as sorted by the Finder.

Comparing Strings Using Operators

Comparing strings using the equal-to operator (==) or a relational operator (like < and >=) is always performed using the Unicode canonical representation, so that different representations of a string compare as being equal.

static func !=(String, String)

Returns a Boolean value indicating whether two values are not equal.

Beta
static func <=(String, String)

Returns a Boolean value indicating whether the value of the first argument is less than or equal to that of the second argument.

Beta
static func >(String, String)

Returns a Boolean value indicating whether the value of the first argument is greater than that of the second argument.

Beta
static func >=(String, String)

Returns a Boolean value indicating whether the value of the first argument is greater than or equal to that of the second argument.

Beta

Comparing Characters

func elementsEqual<OtherSequence>(OtherSequence, by: (Character, Character) -> Bool)

Returns a Boolean value indicating whether this sequence and another sequence contain equivalent elements, using the given predicate as the equivalence test.

Beta
func elementsEqual<OtherSequence>(OtherSequence)

Returns a Boolean value indicating whether this sequence and another sequence contain the same elements in the same order.

Beta
func starts<PossiblePrefix>(with: PossiblePrefix)

Returns a Boolean value indicating whether the initial elements of the sequence are the same as the elements in another sequence.

Beta
func starts<PossiblePrefix>(with: PossiblePrefix, by: (Character, Character) -> Bool)

Returns a Boolean value indicating whether the initial elements of the sequence are equivalent to the elements in another sequence, using the given predicate as the equivalence test.

Beta
func lexicographicallyPrecedes<OtherSequence>(OtherSequence)

Returns a Boolean value indicating whether the sequence precedes another sequence in a lexicographical (dictionary) ordering, using the less-than operator (<) to compare elements.

Beta
func lexicographicallyPrecedes<OtherSequence>(OtherSequence, by: (Character, Character) -> Bool)

Returns a Boolean value indicating whether the sequence precedes another sequence in a lexicographical (dictionary) ordering, using the given predicate to compare elements.

Beta

Finding Substrings

func contains(String)

Returns true iff other is non-empty and contained within self by case-sensitive, non-literal search.

func localizedStandardContains(String)

Returns true if self contains string, taking the current locale into account.

func localizedCaseInsensitiveContains(String)

Returns true iff other is non-empty and contained within self by case-insensitive, non-literal search, taking into account the current locale.

func range(of: String, options: String.CompareOptions, range: Range<String.Index>?, locale: 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.

func localizedStandardRange(of: String)

Finds and returns the range of the first occurrence of a given string, taking the current locale into account. Returns nil if the string was not found.

func rangeOfCharacter(from: CharacterSet, options: String.CompareOptions, range: Range<String.Index>?)

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.

func hasPrefix(String)

Returns a Boolean value indicating whether the string begins with the specified prefix.

func hasSuffix(String)

Returns a Boolean value indicating whether the string ends with the specified suffix.

func commonPrefix(with: String, options: String.CompareOptions)

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

Finding Characters

func contains(Character)

Returns a Boolean value indicating whether the sequence contains the given element.

Beta
func contains(where: (Character) -> Bool)

Returns a Boolean value indicating whether the sequence contains an element that satisfies the given predicate.

Beta
func first(where: (Character) -> Bool)

Returns the first element of the sequence that satisfies the given predicate.

Beta
func index(of: Character)

Returns the first index where the specified value appears in the collection.

Beta
func index(where: (Character) -> Bool)

Returns the first index in which an element of the collection satisfies the given predicate.

Beta
func max()

Returns the maximum element in the sequence.

Beta
func max(by: (Character, Character) -> Bool)

Returns the maximum element in the sequence, using the given predicate as the comparison between elements.

Beta
func min()

Returns the minimum element in the sequence.

Beta
func min(by: (Character, Character) -> Bool)

Returns the minimum element in the sequence, using the given predicate as the comparison between elements.

Beta

Getting Substrings

func substring(from: String.Index)

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

func substring(to: String.Index)

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

func substring(with: Range<String.Index>)

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

func prefix(Int)

Returns a subsequence, up to the specified maximum length, containing the initial elements of the collection.

Beta
func prefix(through: String.Index)

Returns a subsequence from the start of the collection through the specified position.

Beta
func prefix(upTo: String.Index)

Returns a subsequence from the start of the collection up to, but not including, the specified position.

Beta
func prefix(while: (Character) -> Bool)

Returns a subsequence containing the initial elements until predicate returns false and skipping the remaining elements.

Beta
func suffix(Int)

Returns a subsequence, up to the given maximum length, containing the final elements of the collection.

Beta
func suffix(from: String.Index)

Returns a subsequence from the specified position to the end of the collection.

Beta

Splitting a String

func components(separatedBy: String)

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

func components(separatedBy: CharacterSet)

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

func split(separator: Character, maxSplits: Int, omittingEmptySubsequences: Bool)

Returns the longest possible subsequences of the collection, in order, around elements equal to the given element.

Beta
func split(maxSplits: Int, omittingEmptySubsequences: Bool, whereSeparator: (Character) -> Bool)

Returns the longest possible subsequences of the collection, in order, that don’t contain elements satisfying the given predicate.

Beta

Getting Characters and Bytes

subscript(String.Index)

Accesses the character at the given position.

var first: Character?

The first element of the collection.

Beta
var last: Character?

The last element of the collection.

Beta

Determining Line and Paragraph Ranges

func paragraphRange(for: Range<String.Index>)

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

func lineRange(for: Range<String.Index>)

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

func getParagraphStart(UnsafeMutablePointer<String.Index>, end: UnsafeMutablePointer<String.Index>, contentsEnd: UnsafeMutablePointer<String.Index>, for: Range<String.Index>)

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

Determining Composed Character Sequences

func rangeOfComposedCharacterSequence(at: String.Index)

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

func rangeOfComposedCharacterSequences(for: Range<String.Index>)

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

Working with Encodings

static var availableStringEncodings: [String.Encoding]

Returns an Array of the encodings string objects support in the application’s environment.

static var defaultCStringEncoding: String.Encoding

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

static func localizedName(of: String.Encoding)

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

var smallestEncoding: String.Encoding

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

var fastestEncoding: String.Encoding

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

func canBeConverted(to: String.Encoding)

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

func lengthOfBytes(using: String.Encoding)

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

func maximumLengthOfBytes(using: String.Encoding)

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

func data(using: String.Encoding, allowLossyConversion: Bool)

Returns a Data containing a representation of the String encoded using a given encoding.

Working with String Views

var characters: String.CharacterView

A view of the string’s contents as a collection of characters.

init(String.CharacterView)

Creates a string from the given character view.

func withMutableCharacters<R>((inout String.CharacterView) -> R)

Applies the given closure to a mutable view of the string’s characters.

var unicodeScalars: String.UnicodeScalarView

The string’s value represented as a collection of Unicode scalar values.

init(String.UnicodeScalarView)

Creates a string corresponding to the given collection of Unicode scalars.

var utf16: String.UTF16View

A UTF-16 encoding of self.

init?(String.UTF16View)

Creates a string corresponding to the given sequence of UTF-16 code units.

var utf8: String.UTF8View

A UTF-8 encoding of self.

Transforming a String

func folding(options: String.CompareOptions, locale: Locale?)

Returns a string with the given character folding options applied.

Transforming a String's Characters

func map<T>((Character) -> T)

Returns an array containing the results of mapping the given closure over the sequence’s elements.

Beta
func map<T>((Character) -> T)

Returns an array containing the results of mapping the given closure over the sequence’s elements.

Beta
func reduce<Result>(Result, (Result, Character) -> Result)

Returns the result of combining the elements of the sequence using the given closure.

Beta
var lazy: LazyBidirectionalCollection<String>

A view onto this collection that provides lazy implementations of normally eager operations, such as map and filter.

Beta
var lazy: LazyCollection<String>

A view onto this collection that provides lazy implementations of normally eager operations, such as map and filter.

Beta
var lazy: LazySequence<String>

A sequence containing the same elements as this sequence, but on which some operations, such as map and filter, are implemented lazily.

Beta

Iterating over a String's Characters

func forEach((Character) -> Void)

Calls the given closure on each element in the sequence in the same order as a for-in loop.

Beta
func enumerated()

Returns a sequence of pairs (n, x), where n represents a consecutive integer starting at zero, and x represents an element of the sequence.

Beta
func makeIterator()

Returns an iterator over the elements of the collection.

Beta
var underestimatedCount: Int

Returns a value less than or equal to the number of elements in the sequence, nondestructively.

Beta
var underestimatedCount: Int

A value less than or equal to the number of elements in the collection.

Beta

Sorting a String's Characters

func sorted()

Returns the elements of the sequence, sorted.

Beta
func sorted(by: (Character, Character) -> Bool)

Returns the elements of the sequence, sorted using the given predicate as the comparison between elements.

Beta
func reversed()

Returns a view presenting the elements of the collection in reverse order.

Beta

Getting Strings with Mapping

var decomposedStringWithCanonicalMapping: String

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

var decomposedStringWithCompatibilityMapping: String

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

var precomposedStringWithCanonicalMapping: String

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

var precomposedStringWithCompatibilityMapping: String

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

Performing Linguistic Tagging and Analysis

Working with Property Lists

func propertyList()

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

func propertyListFromStringsFileFormat()

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

Getting C Strings

var utf8CString: ContiguousArray<CChar>

A contiguously stored null-terminated UTF-8 representation of the string.

func cString(using: String.Encoding)

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

func getCString(inout [CChar], maxLength: Int, encoding: String.Encoding)

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

func withCString<Result>((UnsafePointer<Int8>) -> Result)

Calls the given closure with a pointer to the contents of the string, represented as a null-terminated sequence of UTF-8 code units.

func withCString<Result, TargetEncoding>(encodedAs: TargetEncoding.Type, (UnsafePointer<TargetEncoding.CodeUnit>) -> Result)

Calls the given closure with a pointer to the contents of the string, represented as a null-terminated sequence of code units.

Beta

Working with Paths

func completePath(into: UnsafeMutablePointer<String>?, caseSensitive: Bool, matchesInto: UnsafeMutablePointer<[String]>?, filterTypes: [String]?)

Interprets the String 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 String. Returns the actual number of matching paths.

Working with URLs

func addingPercentEncoding(withAllowedCharacters: CharacterSet)

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

func addingPercentEscapes(using: String.Encoding)

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

func replacingPercentEscapes(using: String.Encoding)

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

var removingPercentEncoding: String?

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

Manipulating Indices

var startIndex: String.Index

The position of the first character in a nonempty string.

var endIndex: String.Index

A string’s “past the end” position—that is, the position one greater than the last valid subscript argument.

func index(after: String.Index)

Returns the position immediately after the given index.

func index(String.Index, offsetBy: String.IndexDistance)

Returns an index that is the specified distance from the given index.

func index(String.Index, offsetBy: String.IndexDistance, limitedBy: String.Index)

Returns an index that is the specified distance from the given index, unless that distance is beyond a given limiting index.

func distance(from: String.Index, to: String.Index)

Returns the distance between two indices.

var indices: DefaultBidirectionalIndices<String>

The indices that are valid for subscripting the collection, in ascending order.

Beta

Creating a Range Expression

static func ..<(String)

Returns a partial range up to, but not including, its upper bound.

Beta
static func ...(String)

Returns a partial range extending upward from a lower bound.

Beta
static func ...(String)

Returns a partial range up to, and including, its upper bound.

Beta

Encoding and Decoding

Describing a String

var debugDescription: String

A representation of the string that is suitable for debugging.

var customMirror: Mirror

A mirror that reflects the String instance.

var hash: Int

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

var hashValue: Int

The string’s hash value.

Infrequently Used Functionality

init(stringInterpolation: String...)

Creates a new string by concatenating the given interpolations.

init<T>(stringInterpolationSegment: T)

Creates a string containing the given value’s textual representation.

init<T>(stringInterpolationSegment: T)

Creates a string containing the given value’s textual representation.

Beta
init<T>(stringInterpolationSegment: T)

Creates a string containing the given expression’s textual representation.

Beta
init<T>(stringInterpolationSegment: T)

Creates a string containing the given value’s textual representation.

Beta
init(stringLiteral: String)

Creates an instance initialized to the given string value.

Reference Types

Use bridged reference types when you need reference semantics or Foundation-specific behavior.

class NSString

A static plain-text Unicode string object, for use instead of a String constant in cases that require reference semantics.

class NSMutableString

A dynamic plain-text Unicode string object, for use instead of a String variable in cases that require reference semantics.

Related String Types

struct Substring

A slice of a string.

Beta
protocol StringProtocol

A type that can represent a string as a collection of characters.

Beta
struct String.CharacterView

A view of a string’s contents as a collection of characters.

struct String.UnicodeScalarView

A view of a string’s contents as a collection of Unicode scalar values.

struct String.UTF16View

A view of a string’s contents as a collection of UTF-16 code units.

struct String.UTF8View

A view of a string’s contents as a collection of UTF-8 code units.

Type Aliases

typealias String.IndexDistance

A type that represents the number of steps between two String.Index values, where one value is reachable from the other.

typealias String.UTF16Index

The index type for subscripting a string’s utf16 view.

typealias String.UTF8Index

The index type for subscripting a string’s utf8 view.

typealias String.UnicodeScalarIndex

The index type for a string’s unicodeScalars view.

Initializers

init?(Slice<String.UTF8View>)

Creates a string corresponding to the given sequence of UTF-8 code units.

Beta
init(String.UTF8View)

Creates a string corresponding to the given sequence of UTF-8 code units.

Beta

Instance Properties

Structures

struct String.Index

A position of a character or code unit in a string.

Beta

See Also

Strings and Characters

struct Character

A single extended grapheme cluster that approximates a user-perceived character.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software