struct String

A Unicode string value that is a collection of characters.

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 scalar value "\u{301}" modifies the preceding character to include an accent, so "e\u{301}" has the same canonical representation as the single Unicode scalar value "é".

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 scalar values. These scalar values 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.firstIndex(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 first 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 scalar values 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.firstIndex(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.

Inheritance	`BidirectionalCollection, Codable, Collection, Comparable, CustomDebugStringConvertible, CustomPlaygroundQuickLookable, CustomReflectable, CustomStringConvertible, Equatable, ExpressibleByExtendedGraphemeClusterLiteral, ExpressibleByStringLiteral, ExpressibleByUnicodeScalarLiteral, Hashable, LosslessStringConvertible, MirrorPath, RangeReplaceableCollection, Sequence, StringProtocol, TextOutputStream, TextOutputStreamable` View Protocol Hierarchy →
Associated Types	`UTF8Index` `=` `String.UTF8View.Index` The index type for subscripting a string. `CharacterView` `IndexDistance` `=` `Int` A type that represents 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:)`. `SubSequence` `=` `Substring` A sequence that represents a contiguous subrange of the collection's elements. This associated type appears as a requirement in the `Sequence` protocol, but it is restated here with stricter constraints. In a collection, the subsequence should also conform to `Collection`. `UnicodeScalarIndex` `=` `String.UnicodeScalarView.Index` The index type for a string's `unicodeScalars` view. `UTF16Index` `=` `String.UTF16View.Index` The index type for subscripting a string.
Nested Types	`String.UTF8View, String.Index, String.UnicodeScalarView, String.UTF16View, String.UTF8View.Iterator, String.UnicodeScalarView.Iterator, String.UTF16View.Indices`
Import	`import` `Swift`

Initializers

init()

Creates an empty string.

Using this initializer is equivalent to initializing a string with an empty string literal.

let empty = ""
let alsoEmpty = 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 string's 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.UTF8View)

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

Declaration

init(_ utf8: String.UTF8View)

init(_: String.UTF16View)

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

Declaration

init(_ utf16: String.UTF16View)

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.firstIndex(of: " ") {
    let adjective = String(picnicGuest.unicodeScalars[..<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(_: Substring)

Creates a new string from the given substring.

substring: A substring to convert to a standalone String instance.

Complexity: O(n), where n is the length of substring.

Declaration

init(_ substring: Substring)

init(_: Substring.CharacterView)

Creates a String having the given content.

Complexity: O(N), where N is the length of the resulting String's UTF-16.

Declaration

init(_ content: Substring.CharacterView)

init(_: Substring.UnicodeScalarView)

Creates a String having the given content.

Complexity: O(N), where N is the length of the resulting String's UTF-16.

Declaration

init(_ content: Substring.UnicodeScalarView)

init(_: Unicode.Scalar)

Declaration

init(_ scalar: Unicode.Scalar)

init<S>(_: 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 collection operations on a string's characters. 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.lazy.filter { !vowels.contains($0) })
 
print(disemvoweled)
// Prints "Th rn n Spn stys mnly n th pln."

other: A string instance or another sequence of characters.

Declaration

init<S>(_ other: S)

init<S>(_: 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 collection operations on a string's characters. 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.lazy.filter { !vowels.contains($0) })
 
print(disemvoweled)
// Prints "Th rn n Spn stys mnly n th pln."

characters: A string instance or another sequence of characters.

Declaration

init<S>(_ characters: S)

init<T>(_: T)

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

Declaration

init<T>(_ value: T)

init(_:radix:uppercase:)

Creates a string representing the given value in base 10, or some other specified base.

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

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

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. The default is 10. 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>(_ value: T, radix: Int = default, 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(decoding:as:)

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

Parameters: codeUnits: A collection of code units encoded in the encoding specified in sourceEncoding. sourceEncoding: The encoding in which codeUnits should be interpreted.

Declaration

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

init(decodingCString:as:)

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

Parameters: nullTerminatedCodeUnits: A pointer to a sequence of contiguous code units in the encoding specified in sourceEncoding, ending just before the first zero code unit. sourceEncoding: The encoding in which the code units should be interpreted.

Declaration

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

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

Declaration

init<Subject>(describing instance: Subject)

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(from:)

Creates a new instance by decoding from the given decoder.

This initializer throws an error if reading from the decoder fails, or if the data read is corrupted or otherwise invalid.

decoder: The decoder to read data from.

Declaration

init(from decoder: Decoder)

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

Declaration

init<Subject>(reflecting subject: Subject)

init(repeating: Character, count: Int)

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

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

let zeroes = String(repeating: "0" as Character, count: 10)
print(zeroes)
// Prints "0000000000"

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

Declaration

init(repeating repeatedValue: Character, count: Int)

init(repeating: String, count: Int)

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

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

let s = String(repeating: "ab", count: 10)
print(s)
// Prints "abababababababababab"

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<T>(stringInterpolationSegment: T)

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.

Declaration

init<T>(stringInterpolationSegment expr: T)

init<T>(stringInterpolationSegment: T)

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.

Declaration

init<T>(stringInterpolationSegment expr: T)

init<T>(stringInterpolationSegment: T)

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.

Declaration

init<T>(stringInterpolationSegment expr: T)

init<T>(stringInterpolationSegment: T)

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

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

Declaration

init<T>(stringInterpolationSegment expr: T)

init(stringLiteral:)

Creates an instance initialized to the given string value.

Do not call this initializer directly. It is used by the compiler when you initialize a string using a string literal. For example:

let nextStop = "Clark & Lake"

This assignment to the nextStop constant calls this string literal initializer behind the scenes.

Declaration

init(stringLiteral value: String)

init(utf16CodeUnits:count:)

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

Declaration

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

init(utf16CodeUnitsNoCopy:count:freeWhenDone:)

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

Declaration

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

init?(_: Substring.UTF8View)

Creates a String having the given content.

If codeUnits is an ill-formed code unit sequence, the result is nil.

Complexity: O(N), where N is the length of the resulting String's UTF-16.

Declaration

init?(_ codeUnits: Substring.UTF8View)

init?(_: Substring.UTF16View)

Creates a String having the given content.

If codeUnits is an ill-formed code unit sequence, the result is nil.

Complexity: O(N), where N is the length of the resulting String's UTF-16.

Declaration

init?(_ codeUnits: Substring.UTF16View)

init?(bytes:encoding:)

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

Declaration

init?<S : Sequence where S.Iterator.Element == UInt8>(bytes: S, encoding: String.Encoding)

init?(bytesNoCopy:length:encoding:freeWhenDone:)

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

Declaration

init?(bytesNoCopy bytes: UnsafeMutablePointer<Swift.Void>, length: Int, encoding: String.Encoding, freeWhenDone flag: Bool)

init?(cString:encoding:)

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

Declaration

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

init?(data:encoding:)

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

Declaration

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

init?(utf8String:)

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

Declaration

init?(utf8String bytes: UnsafePointer<CChar>)

init?(validatingUTF8:)

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

This initializer does not try to repair ill-formed UTF-8 code unit sequences. If any are found, the result of the initializer is nil.

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

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

Declaration

init?(validatingUTF8 cString: UnsafePointer<CChar>)

Instance Variables

var capitalized: String

[Foundation] Produce a string with the first character from each word changed to the corresponding uppercase value.

Declaration

var capitalized: String { get }

var characters: String.CharacterView

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

Declaration

var characters: String.CharacterView { get set }

var count: Int

The number of characters in a string.

Declaration

var count: Int { get }

var customMirror: Mirror

A mirror that reflects the String instance.

Declaration

var customMirror: Mirror { get }

var customPlaygroundQuickLook: PlaygroundQuickLook

A custom playground Quick Look for the String instance.

Deprecated: String.customPlaygroundQuickLook will be removed in a future Swift version.

Declaration

var customPlaygroundQuickLook: PlaygroundQuickLook { get }

var debugDescription: String

A representation of the string that is suitable for debugging.

Declaration

var debugDescription: String { get }

var decomposedStringWithCanonicalMapping: String

[Foundation] Returns a string made by normalizing the String's contents using Form D.

Declaration

var decomposedStringWithCanonicalMapping: String { get }

var decomposedStringWithCompatibilityMapping: String

[Foundation] Returns a string made by normalizing the String's contents using Form KD.

Declaration

var decomposedStringWithCompatibilityMapping: String { get }

var description: String

The value of this string.

Using this property directly is discouraged. Instead, use simple assignment to create a new constant or variable equal to this string.

Declaration

var description: String { get }

var endIndex: String.Index

A string's "past the end" position---that is, the position one greater than the last valid subscript argument.

In an empty string, endIndex is equal to startIndex.

Declaration

var endIndex: String.Index { get }

var fastestEncoding: String.Encoding

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

Declaration

var fastestEncoding: String.Encoding { get }

var hash: Int

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

Declaration

var hash: Int { get }

var hashValue: Int

The string's hash value.

Hash values are not guaranteed to be equal across different executions of your program. Do not save hash values to use during a future execution.

Declaration

var hashValue: Int { get }

var isEmpty: Bool

A Boolean value indicating whether a string has no characters.

Declaration

var isEmpty: Bool { get }

var localizedCapitalized: String

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

Declaration

var localizedCapitalized: String { get }

var localizedLowercase: String

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

Declaration

var localizedLowercase: String { get }

var localizedUppercase: String

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

Declaration

var localizedUppercase: String { get }

var precomposedStringWithCanonicalMapping: String

[Foundation] Returns a string made by normalizing the String's contents using Form C.

Declaration

var precomposedStringWithCanonicalMapping: String { get }

var precomposedStringWithCompatibilityMapping: String

[Foundation] Returns a string made by normalizing the String's contents using Form KC.

Declaration

var precomposedStringWithCompatibilityMapping: String { get }

var removingPercentEncoding: String?

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

Declaration

var removingPercentEncoding: String? { get }

var smallestEncoding: String.Encoding

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

Declaration

var smallestEncoding: String.Encoding { get }

var startIndex: String.Index

The position of the first character in a nonempty string.

In an empty string, startIndex is equal to endIndex.

Declaration

var startIndex: String.Index { get }

var unicodeScalars: String.UnicodeScalarView

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

Declaration

var unicodeScalars: String.UnicodeScalarView { get set }

var utf8: String.UTF8View

A UTF-8 encoding of self.

Declaration

var utf8: String.UTF8View { get set }

var utf8CString: ContiguousArray<CChar>

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

To access the underlying memory, invoke withUnsafeBufferPointer on the array.

let s = "Hello!"
let bytes = s.utf8CString
print(bytes)
// Prints "[72, 101, 108, 108, 111, 33, 0]"
 
bytes.withUnsafeBufferPointer { ptr in
    print(strlen(ptr.baseAddress!))
}
// Prints "6"

Declaration

var utf8CString: ContiguousArray<CChar> { get }

var utf16: String.UTF16View

A UTF-16 encoding of self.

Declaration

var utf16: String.UTF16View { get set }

Subscripts

subscript(_: String.Index)

Accesses the character at the given position.

You can use the same indices for subscripting a string and its substring. For example, this code finds the first letter after the first space:

let str = "Greetings, friend! How are you?"
let firstSpace = str.firstIndex(of: " ") ?? str.endIndex
let substr = str[firstSpace...]
if let nextCapital = substr.firstIndex(where: { $0 >= "A" && $0 <= "Z" }) {
    print("Capital after a space: \(str[nextCapital])")
}
// Prints "Capital after a space: H"

i: A valid index of the string. i must be less than the string's end index.

Declaration

subscript(i: String.Index) -> Character { get }

subscript(_: Range<String.Index>)

Accesses a contiguous subrange of the collection's elements.

The accessed slice uses the same indices for the same elements as the original collection uses. Always use the slice's startIndex property instead of assuming that its indices start at a particular value.

This example demonstrates getting a slice of an array of strings, finding the index of one of the strings in the slice, and then using that index in the original array.

let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
let streetsSlice = streets[2 ..< streets.endIndex]
print(streetsSlice)
// Prints "["Channing", "Douglas", "Evarts"]"
 
let index = streetsSlice.firstIndex(of: "Evarts")    // 4
print(streets[index!])
// Prints "Evarts"

bounds: A range of the collection's indices. The bounds of the range must be valid indices of the collection.

Declaration

subscript(r: Range<String.Index>) -> Substring { get }

Static Methods

static func availableStringEncodings()

[Foundation] Returns an Array of the encodings string objects support in the application's environment.

Declaration

static func availableStringEncodings() -> [String.Encoding]

static func decodeCString(_:as:repairingInvalidCodeUnits:)

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

When you pass true as isRepairing, this method replaces ill-formed sequences with the Unicode replacement character ("\u{FFFD}"); otherwise, an ill-formed sequence causes this method to stop decoding and return nil.

The following example calls this method 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: [UInt8] = [67, 97, 102, 195, 169, 0]
validUTF8.withUnsafeBufferPointer { ptr in
    let s = String.decodeCString(ptr.baseAddress,
                                 as: UTF8.self,
                                 repairingInvalidCodeUnits: true)
    print(s)
}
// Prints "Optional((Café, false))"
 
let invalidUTF8: [UInt8] = [67, 97, 102, 195, 0]
invalidUTF8.withUnsafeBufferPointer { ptr in
    let s = String.decodeCString(ptr.baseAddress,
                                 as: UTF8.self,
                                 repairingInvalidCodeUnits: true)
    print(s)
}
// Prints "Optional((Caf�, true))"

Parameters: cString: A pointer to a null-terminated code sequence encoded in encoding. encoding: The Unicode encoding of the data referenced by cString. isRepairing: Pass true to create a new string, even when the data referenced by cString contains ill-formed sequences. Ill-formed sequences are replaced with the Unicode replacement character ("\u{FFFD}"). Pass false to interrupt the creation of the new string if an ill-formed sequence is detected. Returns: A tuple with the new string and a Boolean value that indicates whether any repairs were made. If isRepairing is false and an ill-formed sequence is detected, this method returns nil.

Declaration

static func decodeCString<Encoding>(_ cString: UnsafePointer<Encoding.CodeUnit>?, as encoding: Encoding.Type, repairingInvalidCodeUnits isRepairing: Bool = default) -> (result: String, repairsMade: Bool)? where Encoding : _UnicodeEncoding

static func defaultCStringEncoding()

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

Declaration

static func defaultCStringEncoding() -> String.Encoding

static func localizedName(of:)

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

Declaration

static func localizedName(of encoding: String.Encoding) -> String

static func localizedStringWithFormat(_:_:)

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

Declaration

static func localizedStringWithFormat(_ format: String, _ arguments: CVarArg...) -> String

Instance Methods

func addingPercentEncoding(withAllowedCharacters:)

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

Declaration

func addingPercentEncoding(withAllowedCharacters allowedCharacters: CharacterSet) -> String?

func addingPercentEscapes(using:)

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

Deprecated: Use addingPercentEncoding(withAllowedCharacters:) instead, which always uses the recommended UTF-8 encoding, and which encodes for a specific URL component or subcomponent since each URL component or subcomponent has different rules for what characters are valid..

Declaration

func addingPercentEscapes(using encoding: String.Encoding) -> String?

mutating func append(_: Character)

Appends the given character to the string.

The following example adds an emoji globe to the end of a string.

var globe = "Globe "
globe.append("🌍")
print(globe)
// Prints "Globe 🌍"

c: The character to append to the string.

Declaration

mutating func append(_ c: Character)

mutating func append(_: String)

Appends the given string to this string.

The following example builds a customized greeting by using the append(_:) method:

var greeting = "Hello, "
if let name = getUserName() {
    greeting.append(name)
} else {
    greeting.append("friend")
}
print(greeting)
// Prints "Hello, friend"

other: Another string.

Declaration

mutating func append(_ other: String)

mutating func append(contentsOf: String)

Declaration

mutating func append(contentsOf newElements: String)

mutating func append(contentsOf: Substring)

Declaration

mutating func append(contentsOf newElements: Substring)

mutating func append<S>(contentsOf: S)

Appends the characters in the given sequence to the string.

newElements: A sequence of characters.

Declaration

mutating func append<S>(contentsOf newElements: S)

func appending(_:)

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

Declaration

func appending(_ aString: String) -> String

func appendingFormat(_:_:)

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

Declaration

func appendingFormat(_ format: String, _ arguments: CVarArg...) -> String

func applyingTransform(_:reverse:)

[Foundation] Perform string transliteration.

Declaration

func applyingTransform(_ transform: StringTransform, reverse: Bool) -> String?

func cString(using:)

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

Declaration

func cString(using encoding: String.Encoding) -> [CChar]?

func canBeConverted(to:)

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

Declaration

func canBeConverted(to encoding: String.Encoding) -> Bool

func capitalized(with:)

[Foundation] Returns a capitalized representation of the String using the specified locale.

Declaration

func capitalized(with locale: Locale?) -> String

func caseInsensitiveCompare(_:)

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

Declaration

func caseInsensitiveCompare(_ aString: String) -> ComparisonResult

func commonPrefix(with:options:)

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

Declaration

func commonPrefix(with aString: String, options: CompareOptions = default) -> String

func compare(_:options:range:locale:)

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

Declaration

func compare(_ aString: String, options mask: CompareOptions = default, range: Range<Index>? = default, locale: Locale? = default) -> ComparisonResult

func completePath(into:caseSensitive:matchesInto:filterTypes:)

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

Declaration

func completePath(into outputName: UnsafeMutablePointer<String>? = default, caseSensitive: Bool, matchesInto outputArray: UnsafeMutablePointer<[String]>? = default, filterTypes: [String]? = default) -> Int

func components(separatedBy: CharacterSet)

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

Declaration

func components(separatedBy separator: CharacterSet) -> [String]

func components(separatedBy: String)

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

Declaration

func components(separatedBy separator: String) -> [String]

func contains(_:)

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

Equivalent to self.rangeOfString(other) != nil

Declaration

func contains(_ other: String) -> Bool

func data(using:allowLossyConversion:)

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

Declaration

func data(using encoding: String.Encoding, allowLossyConversion: Bool = default) -> Data?

func distance(from:to:)

Returns the distance between two indices.

Parameters: start: A valid index of the collection. end: Another valid index of the collection. If end is equal to start, the result is zero. Returns: The distance between start and end.

Complexity: O(n), where n is the resulting distance.

Declaration

func distance(from start: String.Index, to end: String.Index) -> String.IndexDistance

func encode(to:)

Encodes this value into the given encoder.

This function throws an error if any values are invalid for the given encoder's format.

encoder: The encoder to write data to.

Declaration

func encode(to encoder: Encoder) throws

func enumerateLines(_ body: (line: String,:)

[Foundation] Enumerates all the lines in a string.

Declaration

func enumerateLines(_ body: (line: String, stop: inout Bool) -> ())

func enumerateLinguisticTags(in:scheme:options:orthography:_:)

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

Declaration

func enumerateLinguisticTags(in range: Range<Index>, scheme tagScheme: String, options opts: NSLinguisticTagger.Options = default, orthography: NSOrthography? = default, _ body: (String, Range<Index>, Range<Index>, inout Bool) -> ())

func enumerateSubstrings(in:options:_ body: (substring: String?, substringRange: Range<Index>,:)

[Foundation] Enumerates the substrings of the specified type in the specified range of the string.

Declaration

func enumerateSubstrings(in range: Range<Index>, options opts: EnumerationOptions = default, _ body: (substring: String?, substringRange: Range<Index>, enclosingRange: Range<Index>, inout Bool) -> ())

func folding(_:locale:)

[Foundation] Returns a string with the given character folding options applied.

Declaration

func folding(_ options: CompareOptions = default, locale: Locale?) -> String

func getBytes(_:maxLength:usedLength:encoding:options:range:remaining:)

[Foundation] Writes the given range of characters into buffer in a given encoding, without any allocations. Does not NULL-terminate.

buffer: A buffer into which to store the bytes from the receiver. The returned bytes are not NUL-terminated.

maxBufferCount: The maximum number of bytes to write to buffer.

usedBufferCount: The number of bytes used from buffer. Pass nil if you do not need this value.

encoding: The encoding to use for the returned bytes.

options: A mask to specify options to use for converting the receiver's contents to encoding (if conversion is necessary).

range: The range of characters in the receiver to get.

leftover: The remaining range. Pass nil If you do not need this value.

Returns: true iff some characters were converted.

Note: Conversion stops when the buffer fills or when the conversion isn't possible due to the chosen encoding.

Note: will get a maximum of min(buffer.count, maxLength) bytes.

Declaration

func getBytes(_ buffer: inout [UInt8], maxLength maxBufferCount: Int, usedLength usedBufferCount: UnsafeMutablePointer<Int>, encoding: String.Encoding, options: EncodingConversionOptions = default, range: Range<Index>, remaining leftover: UnsafeMutablePointer<Range<Index>>) -> Bool

func getCString(_:maxLength:encoding:)

[Foundation] Converts the String's content to a given encoding and stores them in a buffer. Note: will store a maximum of min(buffer.count, maxLength) bytes.

Declaration

func getCString(_ buffer: inout [CChar], maxLength: Int, encoding: String.Encoding) -> Bool

func getLineStart(_:end:contentsEnd:for:)

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

Declaration

func getLineStart(_ start: UnsafeMutablePointer<Index>, end: UnsafeMutablePointer<Index>, contentsEnd: UnsafeMutablePointer<Index>, for range: Range<Index>)

func getParagraphStart(_:end:contentsEnd:for:)

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

Declaration

func getParagraphStart(_ start: UnsafeMutablePointer<Index>, end: UnsafeMutablePointer<Index>, contentsEnd: UnsafeMutablePointer<Index>, for range: Range<Index>)

func hasPrefix(_:)

Declaration

func hasPrefix(_ prefix: String) -> Bool

func hasSuffix(_:)

Declaration

func hasSuffix(_ suffix: String) -> Bool

func hash(into:)

Hashes the essential components of this value by feeding them into the given hasher.

hasher: The hasher to use when combining the components of this instance.

Declaration

func hash(into hasher: inout Hasher)

func index(_:offsetBy:)

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

The following example obtains an index advanced four positions from a string's starting index and then prints the character at that position.

let s = "Swift"
let i = s.index(s.startIndex, offsetBy: 4)
print(s[i])
// Prints "t"

The value passed as n must not offset i beyond the bounds of the collection.

Parameters: i: A valid index of the collection. n: The distance to offset i. Returns: An index offset by n from the index i. If n is positive, this is the same value as the result of n calls to index(after:). If n is negative, this is the same value as the result of -n calls to index(before:).

Complexity: O(n), where n is the absolute value of n.

Declaration

func index(_ i: String.Index, offsetBy n: String.IndexDistance) -> String.Index

func index(_:offsetBy:limitedBy:)

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

The following example obtains an index advanced four positions from a string's starting index and then prints the character at that position. The operation doesn't require going beyond the limiting s.endIndex value, so it succeeds.

let s = "Swift"
if let i = s.index(s.startIndex, offsetBy: 4, limitedBy: s.endIndex) {
    print(s[i])
}
// Prints "t"

The next example attempts to retrieve an index six positions from s.startIndex but fails, because that distance is beyond the index passed as limit.

let j = s.index(s.startIndex, offsetBy: 6, limitedBy: s.endIndex)
print(j)
// Prints "nil"

The value passed as n must not offset i beyond the bounds of the collection, unless the index passed as limit prevents offsetting beyond those bounds.

Parameters: i: A valid index of the collection. n: The distance to offset i. limit: A valid index of the collection to use as a limit. If n > 0, a limit that is less than i has no effect. Likewise, if n < 0, a limit that is greater than i has no effect. Returns: An index offset by n from the index i, unless that index would be beyond limit in the direction of movement. In that case, the method returns nil.

Complexity: O(n), where n is the absolute value of n.

Declaration

func index(_ i: String.Index, offsetBy n: String.IndexDistance, limitedBy limit: String.Index) -> String.Index?

func index(after:)

Returns the position immediately after the given index.

i: A valid index of the collection. i must be less than endIndex. Returns: The index value immediately after i.

Declaration

func index(after i: String.Index) -> String.Index

func index(before:)

Returns the position immediately before the given index.

i: A valid index of the collection. i must be greater than startIndex. Returns: The index value immediately before i.

Declaration

func index(before i: String.Index) -> String.Index

mutating func insert(_:at:)

Inserts a new character at the specified position.

Calling this method invalidates any existing indices for use with this string.

Parameters: newElement: The new character to insert into the string. i: A valid index of the string. If i is equal to the string's end index, this methods appends newElement to the string.

Complexity: O(n), where n is the length of the string.

Declaration

mutating func insert(_ newElement: Character, at i: String.Index)

mutating func insert(contentsOf:at:)

Inserts a collection of characters at the specified position.

Calling this method invalidates any existing indices for use with this string.

Parameters: newElements: A collection of Character elements to insert into the string. i: A valid index of the string. If i is equal to the string's end index, this methods appends the contents of newElements to the string.

Complexity: O(n), where n is the combined length of the string and newElements.

Declaration

mutating func insert<S>(contentsOf newElements: S, at i: String.Index)

func lengthOfBytes(using:)

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

Declaration

func lengthOfBytes(using encoding: String.Encoding) -> Int

func lineRange(for:)

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

Declaration

func lineRange(for aRange: Range<Index>) -> Range<Index>

func linguisticTags(in:scheme:options:orthography:tokenRanges:)

[Foundation] Returns an array of linguistic tags for the specified range and requested tags within the receiving string.

Declaration

func linguisticTags(in range: Range<Index>, scheme tagScheme: String, options opts: NSLinguisticTagger.Options = default, orthography: NSOrthography? = default, tokenRanges: UnsafeMutablePointer<[Range<Index>]>? = default) -> [String]

func localizedCaseInsensitiveCompare(_:)

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

Declaration

func localizedCaseInsensitiveCompare(_ aString: String) -> ComparisonResult

func localizedCaseInsensitiveContains(_:)

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

Locale-independent case-insensitive operation, and other needs, can be achieved by calling rangeOfString(_:options:, range:_locale:_).

Equivalent to

self.rangeOf(
  other, options: .CaseInsensitiveSearch,
  locale: Locale.current()) != nil

Declaration

func localizedCaseInsensitiveContains(_ other: String) -> Bool

func localizedCompare(_:)

[Foundation] Compares the string and a given string using a localized comparison.

Declaration

func localizedCompare(_ aString: String) -> ComparisonResult

func localizedStandardCompare(_:)

[Foundation] Compares strings as sorted by the Finder.

Declaration

func localizedStandardCompare(_ string: String) -> ComparisonResult

func localizedStandardContains(_:)

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

This is the most appropriate method for doing user-level string searches, similar to how searches are done generally in the system. The search is locale-aware, case and diacritic insensitive. The exact list of search options applied may change over time.

Declaration

func localizedStandardContains(_ string: String) -> Bool

func localizedStandardRange(of:)

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

Declaration

func localizedStandardRange(of string: String) -> Range<Index>?

func lowercased()

Returns a lowercase version of the string.

Here's an example of transforming a string to all lowercase letters.

let cafe = "BBQ Café 🍵"
print(cafe.lowercased())
// Prints "bbq café 🍵"

Returns: A lowercase copy of the string.

Complexity: O(n)

Declaration

func lowercased() -> String

func lowercased(with:)

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

Declaration

func lowercased(with locale: Locale?) -> String

func max(_:_:)

Declaration

func max<T>(_ x: T, _ y: T) -> T where T : Comparable

func maximumLengthOfBytes(using:)

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

Declaration

func maximumLengthOfBytes(using encoding: String.Encoding) -> Int

func min(_:_:)

Declaration

func min<T>(_ x: T, _ y: T) -> T where T : Comparable

func padding(toLength:withPad:startingAt:)

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

Declaration

func padding(toLength newLength: Int, withPad padString: String, startingAt padIndex: Int) -> String

func paragraphRange(for:)

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

Declaration

func paragraphRange(for aRange: Range<Index>) -> Range<Index>

func propertyList()

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

Declaration

func propertyList() -> AnyObject

func propertyListFromStringsFileFormat()

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

Declaration

func propertyListFromStringsFileFormat() -> [String : String]

func range(of:options:range:locale:)

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

Declaration

func range(of aString: String, options mask: CompareOptions = default, range searchRange: Range<Index>? = default, locale: Locale? = default) -> Range<Index>?

func rangeOfCharacter(from:options:range:)

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

Declaration

func rangeOfCharacter(from aSet: CharacterSet, options mask: CompareOptions = default, range aRange: Range<Index>? = default) -> Range<Index>?

func rangeOfComposedCharacterSequence(at:)

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

Declaration

func rangeOfComposedCharacterSequence(at anIndex: Index) -> Range<Index>

func rangeOfComposedCharacterSequences(for:)

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

Declaration

func rangeOfComposedCharacterSequences(for range: Range<Index>) -> Range<Index>

mutating func remove(at:)

Removes and returns the character at the specified position.

All the elements following i are moved to close the gap. This example removes the hyphen from the middle of a string.

var nonempty = "non-empty"
if let i = nonempty.firstIndex(of: "-") {
    nonempty.remove(at: i)
}
print(nonempty)
// Prints "nonempty"

Calling this method invalidates any existing indices for use with this string.

i: The position of the character to remove. i must be a valid index of the string that is not equal to the string's end index. Returns: The character that was removed.

Declaration

mutating func remove(at i: String.Index) -> Character

mutating func removeAll(keepingCapacity:)

Replaces this string with the empty string.

Calling this method invalidates any existing indices for use with this string.

keepCapacity: Pass true to prevent the release of the string's allocated storage. Retaining the storage can be a useful optimization when you're planning to grow the string again. The default value is false.

Declaration

mutating func removeAll(keepingCapacity keepCapacity: Bool = default)

mutating func removeSubrange(_:)

Removes the characters in the given range.

Calling this method invalidates any existing indices for use with this string.

bounds: The range of the elements to remove. The upper and lower bounds of bounds must be valid indices of the string and not equal to the string's end index.

bounds: The range of the elements to remove. The upper and lower bounds of bounds must be valid indices of the string.

Declaration

mutating func removeSubrange(_ bounds: Range<String.Index>)

mutating func replaceSubrange(_:with:)

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

Calling this method invalidates any existing indices for use with this string.

Parameters: bounds: The range of text to replace. The bounds of the range must be valid indices of the string. newElements: The new characters to add to the string.

Complexity: O(m), where m is the combined length of the string and newElements. If the call to replaceSubrange(_:with:) simply removes text at the end of the string, the complexity is O(n), where n is equal to bounds.count.

Declaration

mutating func replaceSubrange<C>(_ bounds: Range<String.Index>, with newElements: C)

func replacingCharacters(in:with:)

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

Declaration

func replacingCharacters(in range: Range<Index>, with replacement: String) -> String

func replacingOccurrences(of:with:options:range:)

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

Declaration

func replacingOccurrences(of target: String, with replacement: String, options: CompareOptions = default, range searchRange: Range<Index>? = default) -> String

func replacingPercentEscapes(using:)

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

Deprecated: Use removingPercentEncoding instead, which always uses the recommended UTF-8 encoding..

Declaration

func replacingPercentEscapes(using encoding: String.Encoding) -> String?

mutating func reserveCapacity(_:)

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

Because each character in a string can require more than a single ASCII character's worth of storage, additional allocation may be necessary when adding characters to a string after a call to reserveCapacity(_:).

n: The minimum number of ASCII character's worth of storage to allocate.

Complexity: O(n)

Declaration

mutating func reserveCapacity(_ n: Int)

func substring(from:)

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

Declaration

func substring(from index: Index) -> String

func substring(to:)

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

Declaration

func substring(to index: Index) -> String

func substring(with:)

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

Declaration

func substring(with aRange: Range<Index>) -> String

func trimmingCharacters(in:)

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

Declaration

func trimmingCharacters(in set: CharacterSet) -> String

func uppercased()

Returns an uppercase version of the string.

The following example transforms a string to uppercase letters:

let cafe = "Café 🍵"
print(cafe.uppercased())
// Prints "CAFÉ 🍵"

Returns: An uppercase copy of the string.

Complexity: O(n)

Declaration

func uppercased() -> String

func uppercased(with:)

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

Declaration

func uppercased(with locale: Locale?) -> String

func withCString(_:)

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

The pointer passed as an argument to body is valid only during the execution of withCString(_:). Do not store or return the pointer for later use.

body: A closure with a pointer parameter that points to a null-terminated sequence of UTF-8 code units. If body has a return value, that value is also used as the return value for the withCString(_:) method. The pointer argument is valid only for the duration of the method's execution. Returns: The return value, if any, of the body closure parameter.

Declaration

func withCString<Result>(_ body: (UnsafePointer<Int8>) throws -> Result) rethrows -> Result

func withCString(encodedAs:_:)

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

The pointer passed as an argument to body is valid only during the execution of withCString(encodedAs:_:). Do not store or return the pointer for later use.

Parameters: body: A closure with a pointer parameter that points to a null-terminated sequence of code units. If body has a return value, that value is also used as the return value for the withCString(encodedAs:_:) method. The pointer argument is valid only for the duration of the method's execution. targetEncoding: The encoding in which the code units should be interpreted. Returns: The return value, if any, of the body closure parameter.

Declaration

func withCString<Result, TargetEncoding>(encodedAs targetEncoding: TargetEncoding.Type, _ body: (UnsafePointer<TargetEncoding.CodeUnit>) throws -> Result) rethrows -> Result where TargetEncoding : _UnicodeEncoding

mutating func withMutableCharacters(_:)

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

Do not use the string that is the target of this method inside the closure passed to body, as it may not have its correct value. Instead, use the closure's CharacterView argument.

This example below uses the withMutableCharacters(_:) method to truncate the string str at the first space and to return the remainder of the string.

var str = "All this happened, more or less."
let afterSpace = str.withMutableCharacters {
    chars -> String.CharacterView in
    if let i = chars.firstIndex(of: " ") {
        let result = chars[chars.index(after: i)...]
        chars.removeSubrange(i...)
        return result
    }
    return String.CharacterView()
}
 
print(str)
// Prints "All"
print(String(afterSpace))
// Prints "this happened, more or less."

body: A closure that takes a character view as its argument. If body has a return value, that value is also used as the return value for the withMutableCharacters(_:) method. The CharacterView argument is valid only for the duration of the closure's execution. Returns: The return value, if any, of the body closure parameter.

Declaration

mutating func withMutableCharacters<R>(_ body: (inout String.CharacterView) -> R) -> R

mutating func write(_:)

Appends the given string to this string.

other: A string to append.

Declaration

mutating func write(_ other: String)

func write(to:)

Writes the string into the given output stream.

target: An output stream.

Declaration

func write<Target>(to target: inout Target)

func write(to:atomically:encoding:)

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

Declaration

func write(to url: URL, atomically useAuxiliaryFile: Bool, encoding enc: String.Encoding) throws

func write(toFile:atomically:encoding:)

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

Declaration

func write(toFile path: String, atomically useAuxiliaryFile: Bool, encoding enc: String.Encoding) throws

SwiftDoc.org

On this page

Display

Swift Version

Modifying and Comparing Strings

Accessing String Elements

Accessing a String's Unicode Representation

Unicode Scalar View

UTF-16 View

UTF-8 View

Measuring the Length of a String

Accessing String View Elements

Performance Optimizations

Bridging Between String and NSString

Initializers

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Instance Variables

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration