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 string for a space and then create a new string 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]
print(firstName)
// Prints "Marie"

Strings and their views share indices, so you can access the UTF-8 view of the name string using the same firstSpace index.

print(Array(name.utf8[..<firstSpace]))
// Prints "[77, 97, 114, 105, 101]"

Note that an index into one view may not have an exact corresponding position in another view. For example, the flag string declared above comprises a single character, but is composed of eight code units when encoded as UTF-8. The following code creates constants for the first and second positions in the flag.utf8 view. Accessing the utf8 view with these indices yields the first and second code UTF-8 units.

let firstCodeUnit = flag.startIndex
let secondCodeUnit = flag.utf8.index(after: firstCodeUnit)
// flag.utf8[firstCodeUnit] == 240
// flag.utf8[secondCodeUnit] == 159

When used to access the elements of the flag string itself, however, the secondCodeUnit index does not correspond to the position of a specific character. Instead of only accessing the specific UTF-8 code unit, that index is treated as the position of the character at the index’s encoded offset. In the case of secondCodeUnit, that character is still the flag itself.

// flag[firstCodeUnit] == "🇵🇷"
// flag[secondCodeUnit] == "🇵🇷"

If you need to validate that an index from one string’s view corresponds with an exact position in another view, use the index’s samePosition(in:) method or the init(_:within:) initializer.

if let exactIndex = secondCodeUnit.samePosition(in: flag) {
    print(flag[exactIndex])
} else {
    print("No exact match for this position.")
}
// Prints "No exact match for this position."

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.

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.

init(repeating: Character, count: Int)

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

init(repeating: Character, count: Int)

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

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.

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.

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.

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.

Appending Strings and Characters

func append(Character)

Appends the given character to the string.

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.

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.

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.

func reserveCapacity(String.CharacterView.IndexDistance)

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

Replacing Substrings

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

Replaces the specified subrange of elements with the given collection.

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

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

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.

func removeAll(keepingCapacity: Bool)

Replaces this string with the empty string.

func removeFirst()

Removes and returns the first element of the collection.

func removeFirst(Int)

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

func removeLast()

Removes and returns the last element of the collection.

func removeLast(Int)

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

func removeSubrange<R>(R)

Removes the elements in the specified subrange from the collection.

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.

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.

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

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

func dropFirst()

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

func dropFirst(Int)

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

func dropLast()

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

func dropLast(Int)

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

Changing Case

func lowercased()

Returns a lowercase version of the string.

func uppercased()

Returns an uppercase version of the string.

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.

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.

static func >(String, String)

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

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.

Comparing Characters

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

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

func elementsEqual<OtherSequence>(OtherSequence)

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

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.

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.

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.

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.

Finding Substrings

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.

Finding Characters

func contains(Character)

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

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

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

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

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

func index(of: Character)

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

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

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

func max()

Returns the maximum element in the sequence.

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

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

func min()

Returns the minimum element in the sequence.

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

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

Getting Substrings

func prefix(Int)

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

func prefix(through: String.Index)

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

func prefix(upTo: String.Index)

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

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

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

func suffix(Int)

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

func suffix(from: String.Index)

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

Splitting a String

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.

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.

Getting Characters and Bytes

subscript(String.Index)

Accesses the character at the given position.

var first: Character?

The first element of the collection.

var last: Character?

The last element of the collection.

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.

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.

init(Substring.CharacterView)

Creates a String having the given content.

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.

init(Substring.UnicodeScalarView)

Creates a String having the given content.

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.

init?(Substring.UTF16View)

Creates a String having the given content.

var utf8: String.UTF8View

A UTF-8 encoding of self.

init(String.UTF8View)

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

init?(Substring.UTF8View)

Creates a String having the given content.

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.

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

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

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

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

func reduce<Result>(into: Result, (inout Result, Character) -> ())

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

var lazy: LazyBidirectionalCollection<String>

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

var lazy: LazyCollection<String>

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

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.

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.

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.

func makeIterator()

Returns an iterator over the elements of the collection.

var underestimatedCount: Int

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

var underestimatedCount: Int

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

Sorting a String's Characters

func sorted()

Returns the elements of the sequence, sorted.

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

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

func reversed()

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

Getting C Strings

var utf8CString: ContiguousArray<CChar>

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

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.

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.

Creating a Range Expression

static func ..<(String)

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

static func ...(String)

Returns a partial range extending upward from a lower bound.

static func ...(String)

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

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

init<T>(stringInterpolationSegment: T)

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

init<T>(stringInterpolationSegment: T)

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

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.

protocol StringProtocol

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

struct String.Index

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

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.

See Also

Strings and Characters

struct Character

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