SwiftDoc.org

Creates an empty substring.

Declaration

Instantiates an instance of the conforming type from a string representation.

Declaration

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

• Parameter elements: The sequence of elements for the new collection.

Declaration

Creates a Substring having the given content.

Complexity: O(1)

Declaration

Creates a Substring having the given content.

Complexity: O(1)

Declaration

Creates a Substring having the given content.

Complexity: O(1)

Declaration

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

• Parameter elements: The sequence of elements for the new collection. elements must be finite.

Declaration

Creates a string from the null-terminated, UTF-8 encoded sequence of bytes at the given pointer.

• Parameter nullTerminatedUTF8: A pointer to a sequence of contiguous, UTF-8 encoded bytes ending just before the first zero byte.

Declaration

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

Declaration

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

Declaration

Creates an instance initialized to the given value.

• Parameter value: The value of the new instance.

Declaration

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

Here's an example of creating an array initialized with five strings containing the letter Z.

let fiveZs = Array(repeating: "Z", count: 5)
print(fiveZs)
// Prints "["Z", "Z", "Z", "Z", "Z"]"

Declaration

Creates a new instance from an interpolated string literal.

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

Creates an instance initialized to the given string value.

• Parameter value: The value of the new instance.

Declaration

Creates an instance initialized to the given value.

• Parameter value: The value of the new instance.

Declaration

Returns the underlying string from which this Substring was derived.

Declaration

The custom mirror for this instance.

If this type has value semantics, the mirror should be unaffected by subsequent mutations of the instance.

Declaration

A custom playground Quick Look for this instance.

If this type has value semantics, the PlaygroundQuickLook instance should be unaffected by subsequent mutations.

Declaration

A textual representation of this instance, suitable for debugging.

Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(reflecting:) initializer. This initializer works with any type, and uses the custom debugDescription property for types that conform to CustomDebugStringConvertible:

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

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

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

The conversion of p to a string in the assignment to s uses the Point type's debugDescription property.

Declaration

A textual representation of this instance.

Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:) initializer. This initializer works with any type, and uses the custom description property for types that conform to CustomStringConvertible:

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

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

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

The conversion of p to a string in the assignment to s uses the Point type's description property.

Declaration

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

When you need a range that includes the last element of a collection, use the half-open range operator (..<) with endIndex. The ..< operator creates a range that doesn't include the upper bound, so it's always safe to use with endIndex. For example:

let numbers = [10, 20, 30, 40, 50]
if let index = numbers.firstIndex(of: 30) {
    print(numbers[index ..< numbers.endIndex])
}
// Prints "[30, 40, 50]"

If the collection is empty, endIndex is equal to startIndex.

Declaration

Returns whether this string is capable of providing access to validly-encoded UTF-8 contents in contiguous memory in O(1) time.

Contiguous strings always operate in O(1) time for withUTF8 and always give a result for String.UTF8View.withContiguousStorageIfAvailable. Contiguous strings also benefit from fast-paths and better optimizations.

Declaration

The position of the first element in a nonempty collection.

If the collection is empty, startIndex is equal to endIndex.

Declaration

Declaration

Declaration

Declaration

Accesses the element at the specified position.

The following example accesses an element of an array through its subscript to print its value:

var streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
print(streets[1])
// Prints "Bryant"

You can subscript a collection with any valid index other than the collection's end index. The end index refers to the position one past the last element of a collection, so it doesn't correspond with an element.

• Parameter position: The position of the element to access. position must be a valid index of the collection that is not equal to the endIndex property.

Complexity: O(1)

Declaration

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"

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

Complexity: O(1)

Declaration

Adds an element to the end of the collection.

If the collection does not have sufficient capacity for another element, additional storage is allocated before appending newElement. The following example adds a new number to an array of integers:

var numbers = [1, 2, 3, 4, 5]
numbers.append(100)

print(numbers)
// Prints "[1, 2, 3, 4, 5, 100]"

• Parameter newElement: The element to append to the collection.

Complexity: O(1) on average, over many calls to append(_:) on the same collection.

Declaration

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

The collection being appended to allocates any additional necessary storage to hold the new elements.

The following example appends the elements of a Range<Int> instance to an array of integers:

var numbers = [1, 2, 3, 4, 5]
numbers.append(contentsOf: 10...15)
print(numbers)
// Prints "[1, 2, 3, 4, 5, 10, 11, 12, 13, 14, 15]"

• Parameter newElements: The elements to append to the collection.

Complexity: O(m), where m is the length of newElements.

Declaration

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

The collection being appended to allocates any additional necessary storage to hold the new elements.

The following example appends the elements of a Range<Int> instance to an array of integers:

var numbers = [1, 2, 3, 4, 5]
numbers.append(contentsOf: 10...15)
print(numbers)
// Prints "[1, 2, 3, 4, 5, 10, 11, 12, 13, 14, 15]"

• Parameter newElements: The elements to append to the collection.

Complexity: O(m), where m is the length of newElements.

Declaration

Applies the given difference to this collection.

• Parameter difference: The difference to be applied.

Complexity: O(n + c), where n is self.count and c is the number of changes contained by the parameter.

Declaration

Returns the distance between two indices.

Unless the collection conforms to the BidirectionalCollection protocol, start must be less than or equal to end.

Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(k), where k is the resulting distance.

Declaration

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

In this example, filter(_:) is used to include only names shorter than five characters.

let cast = ["Vivien", "Marlon", "Kim", "Karl"]
let shortNames = cast.filter { $0.count < 5 }
print(shortNames)
// Prints "["Kim", "Karl"]"

• Parameter isIncluded: A closure that takes an element of the sequence as its argument and returns a Boolean value indicating whether the element should be included in the returned collection.

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

Declaration

Declaration

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

The comparison is both case sensitive and Unicode safe. The case-sensitive comparison will only match strings whose corresponding characters have the same case.

let cafe = "Café du Monde"

// Case sensitive
print(cafe.hasPrefix("café"))
// Prints "false"

The Unicode-safe comparison matches Unicode extended grapheme clusters rather than the code points used to compose them. The example below uses two strings with different forms of the "é" character---the first uses the composed form and the second uses the decomposed form.

// Unicode safe
let composedCafe = "Café"
let decomposedCafe = "Cafe\u{0301}"

print(cafe.hasPrefix(composedCafe))
// Prints "true"
print(cafe.hasPrefix(decomposedCafe))
// Prints "true"

• Parameter prefix: A possible prefix to test against this string.

Declaration

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

The comparison is both case sensitive and Unicode safe. The case-sensitive comparison will only match strings whose corresponding characters have the same case.

let plans = "Let's meet at the café"

// Case sensitive
print(plans.hasSuffix("Café"))
// Prints "false"

The Unicode-safe comparison matches Unicode extended grapheme clusters rather than the code points used to compose them. The example below uses two strings with different forms of the "é" character---the first uses the composed form and the second uses the decomposed form.

// Unicode safe
let composedCafe = "café"
let decomposedCafe = "cafe\u{0301}"

print(plans.hasSuffix(composedCafe))
// Prints "true"
print(plans.hasSuffix(decomposedCafe))
// Prints "true"

• Parameter suffix: A possible suffix to test against this string.

Declaration

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

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

Declaration

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 distance must not offset i beyond the bounds of the collection.

Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(k), where k is the absolute value of distance.

Declaration

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 distance must not offset i beyond the bounds of the collection, unless the index passed as limit prevents offsetting beyond those bounds.

Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(k), where k is the absolute value of distance.

Declaration

Returns the position immediately after the given index.

The successor of an index must be well defined. For an index i into a collection c, calling c.index(after: i) returns the same index every time.

• Parameter i: A valid index of the collection. i must be less than endIndex.

Declaration

Returns the position immediately before the given index.

• Parameter i: A valid index of the collection. i must be greater than startIndex.

Declaration

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

The new element is inserted before the element currently at the specified index. If you pass the collection's endIndex property as the index parameter, the new element is appended to the collection.

var numbers = [1, 2, 3, 4, 5]
numbers.insert(100, at: 3)
numbers.insert(200, at: numbers.endIndex)

print(numbers)
// Prints "[1, 2, 3, 100, 4, 5, 200]"

Calling this method may invalidate any existing indices for use with this collection.

• Parameter newElement: The new element to insert into the collection.

• Parameter i: The position at which to insert the new element. index must be a valid index into the collection.

Complexity: O(n), where n is the length of the collection. If i == endIndex, this method is equivalent to append(_:).

Declaration

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

The new elements are inserted before the element currently at the specified index. If you pass the collection's endIndex property as the index parameter, the new elements are appended to the collection.

Here's an example of inserting a range of integers into an array of the same type:

var numbers = [1, 2, 3, 4, 5]
numbers.insert(contentsOf: 100...103, at: 3)
print(numbers)
// Prints "[1, 2, 3, 100, 101, 102, 103, 4, 5]"

Calling this method may invalidate any existing indices for use with this collection.

• Parameter newElements: The new elements to insert into the collection.

• Parameter i: The position at which to insert the new elements. index must be a valid index of the collection.

Complexity: O(n + m), where n is length of this collection and m is the length of newElements. If i == endIndex, this method is equivalent to append(contentsOf:).

Declaration

Declaration

If this string is not contiguous, make it so. If this mutates the substring, it will invalidate any pre-existing indices.

Complexity: O(n) if non-contiguous, O(1) if already contiguous

Declaration

Removes and returns the element at the specified position.

All the elements following the specified position are moved to close the gap. This example removes the middle element from an array of measurements.

var measurements = [1.2, 1.5, 2.9, 1.2, 1.6]
let removed = measurements.remove(at: 2)
print(measurements)
// Prints "[1.2, 1.5, 1.2, 1.6]"

Calling this method may invalidate any existing indices for use with this collection.

• Parameter position: The position of the element to remove. position must be a valid index of the collection that is not equal to the collection's end index.

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

Declaration

Removes all elements from the collection.

Calling this method may invalidate any existing indices for use with this collection.

• Parameter keepCapacity: Pass true to request that the collection avoid releasing its storage. Retaining the collection's storage can be a useful optimization when you're planning to grow the collection again. The default value is false.

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

Declaration

Removes all the elements that satisfy the given predicate.

Use this method to remove every element in a collection that meets particular criteria. The order of the remaining elements is preserved. This example removes all the vowels from a string:

var phrase = "The rain in Spain stays mainly in the plain."

let vowels: Set<Character> = ["a", "e", "i", "o", "u"]
phrase.removeAll(where: { vowels.contains($0) })
// phrase == "Th rn n Spn stys mnly n th pln."

• Parameter shouldBeRemoved: A closure that takes an element of the sequence as its argument and returns a Boolean value indicating whether the element should be removed from the collection.

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

Declaration

Removes and returns the first element of the collection.

The collection must not be empty.

var bugs = ["Aphid", "Bumblebee", "Cicada", "Damselfly", "Earwig"]
bugs.removeFirst()
print(bugs)
// Prints "["Bumblebee", "Cicada", "Damselfly", "Earwig"]"

Calling this method may invalidate any existing indices for use with this collection.

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

Declaration

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

var bugs = ["Aphid", "Bumblebee", "Cicada", "Damselfly", "Earwig"]
bugs.removeFirst(3)
print(bugs)
// Prints "["Damselfly", "Earwig"]"

Calling this method may invalidate any existing indices for use with this collection.

• Parameter k: The number of elements to remove from the collection. k must be greater than or equal to zero and must not exceed the number of elements in the collection.

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

Declaration

Removes the elements in the specified subrange from the collection.

All the elements following the specified position are moved to close the gap. This example removes three elements from the middle of an array of measurements.

var measurements = [1.2, 1.5, 2.9, 1.2, 1.5]
measurements.removeSubrange(1..<4)
print(measurements)
// Prints "[1.2, 1.5]"

Calling this method may invalidate any existing indices for use with this collection.

• Parameter bounds: The range of the collection to be removed. The bounds of the range must be valid indices of the collection.

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

Declaration

Removes the elements in the specified subrange from the collection.

All the elements following the specified position are moved to close the gap. This example removes three elements from the middle of an array of measurements.

var measurements = [1.2, 1.5, 2.9, 1.2, 1.5]
measurements.removeSubrange(1..<4)
print(measurements)
// Prints "[1.2, 1.5]"

Calling this method may invalidate any existing indices for use with this collection.

• Parameter bounds: The range of the collection to be removed. The bounds of the range must be valid indices of the collection.

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

Declaration

Replaces the specified subrange of elements with the given collection.

This method has the effect of removing the specified range of elements from the collection and inserting the new elements at the same location. The number of new elements need not match the number of elements being removed.

In this example, three elements in the middle of an array of integers are replaced by the five elements of a Repeated<Int> instance.

 var nums = [10, 20, 30, 40, 50]
 nums.replaceSubrange(1...3, with: repeatElement(1, count: 5))
 print(nums)
 // Prints "[10, 1, 1, 1, 1, 1, 50]"

If you pass a zero-length range as the subrange parameter, this method inserts the elements of newElements at subrange.startIndex. Calling the insert(contentsOf:at:) method instead is preferred.

Likewise, if you pass a zero-length collection as the newElements parameter, this method removes the elements in the given subrange without replacement. Calling the removeSubrange(_:) method instead is preferred.

Calling this method may invalidate any existing indices for use with this collection.

Complexity: O(n + m), where n is length of this collection and m is the length of newElements. If the call to this method simply appends the contents of newElements to the collection, this method is equivalent to append(contentsOf:).

Declaration

Declaration

Replaces the specified subrange of elements with the given collection.

This method has the effect of removing the specified range of elements from the collection and inserting the new elements at the same location. The number of new elements need not match the number of elements being removed.

In this example, three elements in the middle of an array of integers are replaced by the five elements of a Repeated<Int> instance.

 var nums = [10, 20, 30, 40, 50]
 nums.replaceSubrange(1...3, with: repeatElement(1, count: 5))
 print(nums)
 // Prints "[10, 1, 1, 1, 1, 1, 50]"

If you pass a zero-length range as the subrange parameter, this method inserts the elements of newElements at subrange.startIndex. Calling the insert(contentsOf:at:) method instead is preferred.

Likewise, if you pass a zero-length collection as the newElements parameter, this method removes the elements in the given subrange without replacement. Calling the removeSubrange(_:) method instead is preferred.

Calling this method may invalidate any existing indices for use with this collection.

Complexity: O(n + m), where n is length of this collection and m is the length of newElements. If the call to this method simply appends the contents of newElements to the collection, the complexity is O(m).

Declaration

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

If you will be adding a known number of elements to a collection, use this method to avoid multiple reallocations. A type that conforms to RangeReplaceableCollection can choose how to respond when this method is called. Depending on the type, it may make sense to allocate more or less storage than requested or to take no action at all.

• Parameter n: The requested number of elements to store.

Declaration

Declaration

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.

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

Declaration

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.

Declaration

Runs body over the content of this substring in contiguous memory. If this substring is not contiguous, this will first make it contiguous, which will also speed up subsequent access. If this mutates the substring, it will invalidate any pre-existing indices.

Note that it is unsafe to escape the pointer provided to body. For example, strings of up to 15 UTF-8 code units in length may be represented in a small-string representation, and thus will be spilled into temporary stack space which is invalid after withUTF8 finishes execution.

Complexity: O(n) if non-contiguous, O(1) if already contiguous

Declaration

Appends the given string to the stream.

Declaration

Writes a textual representation of this instance into the given output stream.

Declaration

Declaration

Creates a new collection by concatenating the elements of a collection and a sequence.

The two arguments must have the same Element type. For example, you can concatenate the elements of an integer array and a Range<Int> instance.

let numbers = [1, 2, 3, 4]
let moreNumbers = numbers + 5...10
print(moreNumbers)
// Prints "[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"

The resulting collection has the type of the argument on the left-hand side. In the example above, moreNumbers has the same type as numbers, which is [Int].

Declaration

Creates a new collection by concatenating the elements of a sequence and a collection.

The two arguments must have the same Element type. For example, you can concatenate the elements of a Range<Int> instance and an integer array.

let numbers = [7, 8, 9, 10]
let moreNumbers = 1...6 + numbers
print(moreNumbers)
// Prints "[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"

The resulting collection has the type of argument on the right-hand side. In the example above, moreNumbers has the same type as numbers, which is [Int].

Declaration

Creates a new collection by concatenating the elements of two collections.

The two arguments must have the same Element type. For example, you can concatenate the elements of two integer arrays.

let lowerNumbers = [1, 2, 3, 4]
let higherNumbers: ContiguousArray = [5, 6, 7, 8, 9, 10]
let allNumbers = lowerNumbers + higherNumbers
print(allNumbers)
// Prints "[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"

The resulting collection has the type of the argument on the left-hand side. In the example above, moreNumbers has the same type as numbers, which is [Int].

Declaration

Appends the elements of a sequence to a range-replaceable collection.

Use this operator to append the elements of a sequence to the end of range-replaceable collection with same Element type. This example appends the elements of a Range<Int> instance to an array of integers.

var numbers = [1, 2, 3, 4, 5]
numbers += 10...15
print(numbers)
// Prints "[1, 2, 3, 4, 5, 10, 11, 12, 13, 14, 15]"

Complexity: O(m), where m is the length of the right-hand-side argument.

Declaration

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

This function is the only requirement of the Comparable protocol. The remainder of the relational operator functions are implemented by the standard library for any type that conforms to Comparable.

Declaration

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

Declaration

Returns a Boolean value indicating whether two values are equal.

Equality is the inverse of inequality. For any values a and b, a == b implies that a != b is false.

Declaration

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

Declaration

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

Declaration