struct String

A Unicode string value.

A string is a series of characters, such as "Swift". Strings in Swift are Unicode correct, locale insensitive, and 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 are 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)!"

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

Combine strings using the concatenation operator (+).

let longerGreeting = greeting + " We're glad you're here!"
print(longerGreeting)
// Prints "Welcome! We're glad you're here!"

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!"
print(otherGreeting)
// Prints "Welcome! Have a nice time!"

print(greeting)
// Prints "Welcome!"

Comparing strings for equality using the equal-to operator (==) or a relational operator (like < and >=) is always performed using the Unicode canonical representation. This means that 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. This ensures 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.

Representing Strings: Views

A string is not itself a collection. Instead, it has properties that present its contents as meaningful collections. Each of these collections is a particular type of view of the string's visible and data representation.

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

Character View

A string's characters property 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 Swift's Character type. Each element of the characters view is represented by a Character instance.

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

Each visible character in the cafe string is a separate element of the characters view.

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

The elements of this collection 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"

Counting 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.characters.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 scalars 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.characters.count)
// Prints "1"
print(flag.unicodeScalars.count)
// Prints "2"
print(flag.utf16.count)
// Prints "4"
print(flag.utf8.count)
// Prints "8"

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.characters.index(of: " ")!
let firstName = String(name.characters.prefix(upTo: 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.prefix(upTo: 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.

See Also: String.CharacterView, String.UnicodeScalarView, String.UTF16View, String.UTF8View

Inheritance	`Comparable, CustomDebugStringConvertible, CustomPlaygroundQuickLookable, CustomReflectable, CustomStringConvertible, Equatable, ExpressibleByExtendedGraphemeClusterLiteral, ExpressibleByStringInterpolation, ExpressibleByStringLiteral, ExpressibleByUnicodeScalarLiteral, Hashable, LosslessStringConvertible, MirrorPath, TextOutputStream, TextOutputStreamable` View Protocol Hierarchy →
Associated Types	`UTF16Index = String.UTF16View.Index` The index type for subscripting a string's `utf16` view. `UTF8Index = String.UTF8View.Index` The index type for subscripting a string's `utf8` view. `Index = String.CharacterView.Index` The index type for subscripting a string. `IndexDistance = String.CharacterView.IndexDistance` A type used to represent the number of steps between two `String.Index` values, where one value is reachable from the other. In Swift, reachability refers to the ability to produce one value from the other through zero or more applications of `index(after:)`. `UnicodeScalarIndex = String.UnicodeScalarView.Index` The index type for a string's `unicodeScalars` view.
Nested Types	`String.UTF16View, String.UTF8View, String.CharacterView, String.UnicodeScalarView, String.UTF16View.Index, String.UTF16View.Indices, String.UTF8View.Index, String.CharacterView.Index, String.UnicodeScalarView.Index, String.UnicodeScalarView.Iterator`
Import	`import Swift`

Initializers

init()

Creates an empty string.

Declaration

init()

init(_: Character)

Creates a string containing the given character.

c: The character to convert to a string.

Declaration

init(_ c: Character)

init(_: NSString)

[Foundation]

Declaration

init(_ cocoaString: NSString)

init(_: String.CharacterView)

Creates a string from the given character view.

Use this initializer to recover a string after performing a collection slicing operation on a character view.

let poem = "'Twas brillig, and the slithy toves / " +
           "Did gyre and gimbal in the wabe: / " +
           "All mimsy were the borogoves / " +
           "And the mome raths outgrabe."
let excerpt = String(poem.characters.prefix(22)) + "..."
print(excerpt)
// Prints "'Twas brillig, and the..."

characters: A character view to convert to a string.

Declaration

init(_ characters: String.CharacterView)

init(_: String.UnicodeScalarView)

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

You can use this initializer to create a new string from a slice of another string's unicodeScalars view.

let picnicGuest = "Deserving porcupine"
if let i = picnicGuest.unicodeScalars.index(of: " ") {
    let adjective = String(picnicGuest.unicodeScalars.prefix(upTo: i))
    print(adjective)
}
// Prints "Deserving"

The adjective constant is created by calling this initializer with a slice of the picnicGuest.unicodeScalars view.

unicodeScalars: A collection of Unicode scalar values.

Declaration

init(_ unicodeScalars: String.UnicodeScalarView)

init<T : _SignedInteger>(_: T)

Creates a string representing the given value in base 10.

The following example converts the maximal Int value to a string and prints its length:

let max = String(Int.max)
print("\(max) has \(max.utf16.count) digits.")
// Prints "9223372036854775807 has 19 digits."

Declaration

init<T : _SignedInteger>(_ v: T)

init<T : UnsignedInteger>(_: T)

Creates a string representing the given value in base 10.

The following example converts the maximal UInt value to a string and prints its length:

let max = String(UInt.max)
print("\(max) has \(max.utf16.count) digits.")
// Prints "18446744073709551615 has 20 digits."

Declaration

init<T : UnsignedInteger>(_ v: T)

init<T : LosslessStringConvertible>(_: T)

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

Declaration

init<T : LosslessStringConvertible>(_ value: T)

init<S : Sequence where S.Iterator.Element == Character>(_: S)

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

You can use this initializer to create a new string from the result of one or more operations on a string's characters view. For example:

let str = "The rain in Spain stays mainly in the plain."

let vowels: Set<Character> = ["a", "e", "i", "o", "u"]
let disemvoweled = String(str.characters.lazy.filter { !vowels.contains($0) })

print(disemvoweled)
// Prints "Th rn n Spn stys mnly n th pln."

characters: A sequence of characters.

Declaration

init<S : Sequence where S.Iterator.Element == Character>(_ characters: S)

init<T : _SignedInteger>(_: T, radix: Int, uppercase: Bool)

Creates a string representing the given value in the specified base.

Numerals greater than 9 are represented as Roman letters. These letters start with "A" if uppercase is true; otherwise, with "a".

let v = 999_999
print(String(v, radix: 2))
// Prints "11110100001000111111"

print(String(v, radix: 16))
// Prints "f423f"
print(String(v, radix: 16, uppercase: true))
// Prints "F423F"

Parameters: value: The value to convert to a string. radix: The base to use for the string representation. radix must be at least 2 and at most 36. uppercase: Pass true to use uppercase letters to represent numerals greater than 9, or false to use lowercase letters. The default is false.

Declaration

init<T : _SignedInteger>(_ value: T, radix: Int, uppercase: Bool = default)

init<T : UnsignedInteger>(_: T, radix: Int, uppercase: Bool)

Creates a string representing the given value in the specified base.

Numerals greater than 9 are represented as Roman letters. These letters start with "A" if uppercase is true; otherwise, with "a".

let v: UInt = 999_999
print(String(v, radix: 2))
// Prints "11110100001000111111"

print(String(v, radix: 16))
// Prints "f423f"
print(String(v, radix: 16, uppercase: true))
// Prints "F423F"

Declaration

init<T : UnsignedInteger>(_ value: T, radix: Int, uppercase: Bool = default)

init(cString: UnsafePointer<CChar>)

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

If cString contains ill-formed UTF-8 code unit sequences, this initializer replaces them with the Unicode replacement character ("\u{FFFD}").

The following example calls this initializer with pointers to the contents of two different CChar arrays---the first with well-formed UTF-8 code unit sequences and the second with an ill-formed sequence at the end.

let validUTF8: [CChar] = [67, 97, 102, -61, -87, 0]
validUTF8.withUnsafeBufferPointer { ptr in
    let s = String(cString: ptr.baseAddress!)
    print(s)
}
// Prints "Café"

let invalidUTF8: [CChar] = [67, 97, 102, -61, 0]
invalidUTF8.withUnsafeBufferPointer { ptr in
    let s = String(cString: ptr.baseAddress!)
    print(s)
}
// Prints "Caf�"

cString: A pointer to a null-terminated UTF-8 code sequence.

Declaration

init(cString: UnsafePointer<CChar>)

init(cString: UnsafePointer<UInt8>)

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

This is identical to init(cString: UnsafePointer<CChar> but operates on an unsigned sequence of bytes.

Declaration

init(cString: UnsafePointer<UInt8>)

init(contentsOf:)

[Foundation]

Declaration

init(contentsOf url: URL)

init(contentsOf:encoding:)

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

Declaration

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

init(contentsOf:usedEncoding:)

[Foundation] 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.

Declaration

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

init(contentsOfFile:)

[Foundation]

Declaration

init(contentsOfFile path: String)

init(contentsOfFile:encoding:)

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

Declaration

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

init(contentsOfFile:usedEncoding:)

[Foundation] 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.

Declaration

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

init(describing:)

Creates a string representing the given value.

Use this initializer to convert an instance of any type to its preferred representation as a String instance. The initializer creates the string representation of instance in one of the following ways, depending on its protocol conformance:

If instance conforms to the TextOutputStreamable protocol, the result is obtained by calling instance.write(to: s) on an empty string s.
If instance conforms to the CustomStringConvertible protocol, the result is instance.description.
If instance conforms to the CustomDebugStringConvertible protocol, the result is instance.debugDescription.
An unspecified result is supplied automatically by the Swift standard library.

For example, this custom Point struct uses the default representation supplied by the standard library.

struct Point {
    let x: Int, y: Int
}

let p = Point(x: 21, y: 30)
print(String(describing: p))
// Prints "Point(x: 21, y: 30)"

After adding CustomStringConvertible conformance by implementing the description property, Point provides its own custom representation.

extension Point: CustomStringConvertible {
    var description: String {
        return "(\(x), \(y))"
    }
}

print(String(describing: p))
// Prints "(21, 30)"

See Also: String.init<Subject>(reflecting: Subject)

Declaration

init<Subject>(describing instance: Subject)

init(extendedGraphemeClusterLiteral:)

Creates an instance initialized to the given extended grapheme cluster literal.

Don't call this initializer directly. It may be used by the compiler when you initialize a string using a string literal containing a single extended grapheme cluster.

Declaration

init(extendedGraphemeClusterLiteral value: String)

init(format:_:)

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

Declaration

init(format: String, _ arguments: CVarArg...)

init(format:arguments:)

[Foundation] 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.

Declaration

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

init(format:locale:_:)

[Foundation] 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.

Declaration

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

init(format:locale:arguments:)

[Foundation] 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.

Declaration

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

init(reflecting:)

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

Use this initializer to convert an instance of any type to its custom debugging representation. The initializer creates the string representation of instance in one of the following ways, depending on its protocol conformance:

If subject conforms to the CustomDebugStringConvertible protocol, the result is subject.debugDescription.
If subject conforms to the CustomStringConvertible protocol, the result is subject.description.
If subject conforms to the TextOutputStreamable protocol, the result is obtained by calling subject.write(to: s) on an empty string s.
An unspecified result is supplied automatically by the Swift standard library.

For example, this custom Point struct uses the default representation supplied by the standard library.

struct Point {
    let x: Int, y: Int
}

let p = Point(x: 21, y: 30)
print(String(reflecting: p))
// Prints "p: Point = {
//           x = 21
//           y = 30
//         }"

After adding CustomDebugStringConvertible conformance by implementing the debugDescription property, Point provides its own custom debugging representation.

extension Point: CustomDebugStringConvertible {
    var debugDescription: String {
        return "Point(x: \(x), y: \(y))"
    }
}

print(String(reflecting: p))
// Prints "Point(x: 21, y: 30)"

See Also: String.init<Subject>(Subject)

Declaration

init<Subject>(reflecting subject: Subject)

init(repeating:count:)

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

For example, use this initializer to create a string with ten "00" strings in a row.

let zeroes = String(repeating: "00", count: 10)
print(zeroes)
// Prints "00000000000000000000"

Parameters: repeatedValue: The string to repeat. count: The number of times to repeat repeatedValue in the resulting string.

Declaration

init(repeating repeatedValue: String, count: Int)

init(stringInterpolation:)

Creates a new string by concatenating the given interpolations.

Do not call this initializer directly. It is used by the compiler when you create a string using string interpolation. Instead, use string interpolation to create a new string by including values, literals, variables, or expressions enclosed in parentheses, prefixed by a backslash (\(...)).

let price = 2
let number = 3
let message = "If one cookie costs \(price) dollars, " +
              "\(number) cookies cost \(price * number) dollars."
print(message)
// Prints "If one cookie costs 2 dollars, 3 cookies cost 6 dollars."

Declaration

init(stringInterpolation strings: String...)

init(stringInterpolationSegment: Bool)

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

Do not call this initializer directly. It is used by the compiler when interpreting string interpolations.