StructureSwift5.9.0

    String

    A Unicode string value that is a collection of characters.

    @frozen struct String

    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.

    Citizens in Swift

    Conformances

    Members

    Features

    Available in _RegexParser

    Members

    Available in RegexBuilder

    Conformances

    Members

    Available in Foundation

    Conformances

    • protocol CVarArg

      A type whose instances can be encoded, and appropriately passed, as elements of a C va_list.

    Members

    Extension in BSON

    Conformances

    Features

    Extension in ConsoleKit

    Members

    Extension in MultipartKit

    Conformances

    Members

    Extension in RoutingKit

    Members

    Extension in ArgumentParser

    Conformances

    Members

    Extension in SwiftASN1

    Members

    Extension in JSONDecoding

    Conformances

    Members

    Extension in JSONEncoding

    Conformances

    Members

    Extension in BSONTypes

    Members

    Extension in BSONDecoding

    Conformances

    • protocol BSONDecodable

      A type that can be decoded from a BSON variant value backed by some type of storage not particular to the decoded type.

    • protocol BSONStringDecodable

      A type that can be decoded from a BSON UTF-8 string. Javascript sources count as UTF-8 strings, from the perspective of this protocol. This protocol exists to allow types that also conform to LosslessStringConvertible to opt-in to automatic BSONDecodable conformance as well.

    Extension in BSONEncoding

    Conformances

    Members

    Extension in _NIOBase64

    Members

    Extension in NIOCore

    Members

    • init(buffer: ByteBuffer)

      Creates a String from a given ByteBuffer. The entire readable portion of the buffer will be read.

    Extension in SwiftSyntax

    Members

    Extension in SwiftSyntaxBuilder

    Conformances

    Members

    Extension in _SwiftSyntaxTestSupport

    Members

    Extension in SystemPackage

    Members

    Extension in HTMLStreaming

    Conformances

    Extension in JSONDecoding

    Conformances

    Members

    Extension in JSONEncoding

    Conformances

    Extension in Vapor

    Conformances

    Members

    Features

    AdditiveArithmeticAnyBidirectionalCollectionAnyCollectionAnyHashableAnyIndexAnyIteratorAnyKeyPathAnyRandomAccessCollectionAnySequenceArrayArraySliceBidirectionalCollectionBinaryFloatingPointBinaryIntegerBoolCVaListPointerCVarArgCaseIterableCharacterClosedRange
    Index
    CodingKeyCodingKeyRepresentableCodingUserInfoKeyCollectionCollectionDifference
    ChangeIndex
    CollectionOfOne
    Iterator
    CommandLineComparableContiguousArrayCustomDebugStringConvertibleCustomLeafReflectableCustomPlaygroundDisplayConvertibleCustomReflectableCustomStringConvertibleDecodableDecoderDecodingError
    Context
    DefaultIndicesDefaultStringInterpolationDictionary
    IndexIteratorKeys
    Iterator
    Values
    Iterator
    Double
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8Storage
    DropFirstSequenceDropWhileSequence
    Iterator
    DurationDurationProtocolEmptyCollection
    Iterator
    EncodableEncoderEncodingError
    Context
    EnumeratedSequence
    Iterator
    EquatableErrorExpressibleByArrayLiteralExpressibleByBooleanLiteralExpressibleByDictionaryLiteralExpressibleByExtendedGraphemeClusterLiteralExpressibleByFloatLiteralExpressibleByIntegerLiteralExpressibleByNilLiteralExpressibleByStringInterpolationExpressibleByStringLiteralExpressibleByUnicodeScalarLiteralFixedWidthIntegerFlattenSequence
    IndexIterator
    Float
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8Storage
    Float16
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8Storage
    Float80FloatingPointFloatingPointClassificationFloatingPointRoundingRuleFloatingPointSignHashableHasherIdentifiableIndexingIteratorInstantProtocolInt
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    Int16
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    Int32
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    Int64
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    Int8
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    IteratorProtocolIteratorSequenceJoinedSequence
    Iterator
    KeyPathKeyValuePairsKeyedDecodingContainerKeyedDecodingContainerProtocolKeyedEncodingContainerKeyedEncodingContainerProtocolLazyCollectionProtocolLazyDropWhileSequence
    Iterator
    LazyFilterSequence
    Iterator
    LazyMapSequence
    Iterator
    LazyPrefixWhileSequence
    IndexIterator
    LazySequenceLazySequenceProtocolLosslessStringConvertibleManagedBufferManagedBufferPointerMemoryLayoutMirror
    AncestorRepresentationDisplayStyle
    MirrorPathMutableCollectionNeverNumericObjectIdentifierOpaquePointerOptionSetOptionalPartialKeyPathPartialRangeFrom
    Iterator
    PartialRangeThroughPartialRangeUpToPrefixSequence
    Iterator
    RandomAccessCollectionRandomNumberGeneratorRangeRangeExpressionRangeReplaceableCollectionRawRepresentableReferenceWritableKeyPathRepeatedResultReversedCollection
    IndexIterator
    SIMDSIMD16SIMD2SIMD3SIMD32SIMD4SIMD64SIMD8SIMDMaskSIMDScalarSIMDStorageSendableSequenceSet
    IndexIterator
    SetAlgebraSignedIntegerSignedNumericSingleValueDecodingContainerSingleValueEncodingContainerSliceStaticBigIntStaticStringStrideThroughStrideThroughIteratorStrideToStrideToIteratorStrideableString
    IndexIteratorUTF16View
    Iterator
    UTF8ViewUnicodeScalarView
    Iterator
    StringInterpolationProtocolStringProtocolSubstring
    UTF16ViewUTF8ViewUnicodeScalarView
    SystemRandomNumberGeneratorTextOutputStreamTextOutputStreamableUInt
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    UInt16
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    UInt32
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    UInt64
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    UInt8
    SIMD16StorageSIMD2StorageSIMD32StorageSIMD4StorageSIMD64StorageSIMD8StorageWords
    UnboundedRange_UnfoldSequenceUnicode
    ASCII
    Parser
    CanonicalCombiningClassGeneralCategoryNumericTypeParseResultScalar
    PropertiesUTF16ViewUTF8View
    UTF16
    ForwardParserReverseParser
    UTF32
    Parser
    UTF8
    ForwardParserReverseParser
    UnicodeCodecUnicodeDecodingResultUnkeyedDecodingContainerUnkeyedEncodingContainerUnmanagedUnsafeBufferPointer
    Iterator
    UnsafeMutableBufferPointerUnsafeMutablePointerUnsafeMutableRawBufferPointerUnsafeMutableRawPointerUnsafePointerUnsafeRawBufferPointer
    Iterator
    UnsafeRawPointerUnsafeSendableUnsignedIntegerWritableKeyPathZip2Sequence
    Iterator
    _AppendKeyPath