Display

Swift Version

String

struct String

A Unicode string value.

A string is a series of characters, such as "Swift". Strings in Swift are
Unicode correct, locale insensitive, and designed to be efficient. The
String type bridges with the Objective-C class NSString and offers
interoperability with C functions that works with strings.

You can create new strings using string literals or string interpolations.
A string literal is a series of characters enclosed in quotes.

let greeting = "Welcome!"

String interpolations are string literals that evaluate any included
expressions and convert the results to string form. String interpolations
are an easy way to build a string from multiple pieces. Wrap each
expression in a string interpolation in parentheses, prefixed by a
backslash.

Comparing strings for equality using the equal-to operator (==) or a
relational operator (like < and >=) is always performed using the
Unicode canonical representation. This means that different
representations of a string compare as being equal.

The Unicode code point "\u{301}" modifies the preceding character to
include an accent, so "e\u{301}" has the same canonical representation
as the single Unicode code point "é".

Basic string operations are not sensitive to locale settings. This ensures
that string comparisons and other operations always have a single, stable
result, allowing strings to be used as keys in Dictionary instances and
for other purposes.

Representing Strings: Views

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

To demonstrate the different views available for every string, the
following examples use this String instance:

let cafe = "Cafe\u{301} du 🌍"
print(cafe)
// Prints "Café du 🌍"

Character View

A string's characters property is a collection of extended grapheme
clusters, which approximate human-readable characters. Many individual
characters, such as "é", "김", and "🇮🇳", can be made up of multiple Unicode
code points. These code points are combined by Unicode's boundary
algorithms into extended grapheme clusters, represented by Swift's
Character type. Each element of the characters view is represented by
a Character instance.

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

Unicode Scalar View

A string's unicodeScalars property is a collection of Unicode scalar
values, the 21-bit codes that are the basic unit of Unicode. Each scalar
value is represented by a UnicodeScalar instance and is equivalent to a
UTF-32 code unit.

The unicodeScalars view's elements comprise each Unicode scalar value in
the cafe string. In particular, because cafe was declared using the
decomposed form of the "é" character, unicodeScalars contains the code
points for both the letter "e" (101) and the accent character "´"
(769).

UTF-16 View

A string's utf16 property is a collection of UTF-16 code units, the
16-bit encoding form of the string's Unicode scalar values. Each code unit
is stored as a UInt16 instance.

The elements of the utf8 view are the code units for the string when
encoded in UTF-8. This representation matches the one used when String
instances are passed to C APIs.

let cLength = strlen(cafe)
print(cLength)
// Prints "14"

Counting the Length of a String

When you need to know the length of a string, you must first consider what
you'll use the length for. Are you measuring the number of characters that
will be displayed on the screen, or are you measuring the amount of
storage needed for the string in a particular encoding? A single string
can have greatly differing lengths when measured by its different views.

For example, an ASCII character like the capital letter A is represented
by a single element in each of its four views. The Unicode scalar value of
A is 65, which is small enough to fit in a single code unit in both
UTF-16 and UTF-8.

On the other hand, an emoji flag character is constructed from a pair of
Unicode scalars values, like "\u{1F1F5}" and "\u{1F1F7}". Each of
these scalar values, in turn, is too large to fit into a single UTF-16 or
UTF-8 code unit. As a result, each view of the string "🇵🇷" reports a
different length.

Accessing String View Elements

To find individual elements of a string, use the appropriate view for your
task. For example, to retrieve the first word of a longer string, you can
search the characters view for a space and then create a new string from
a prefix of the characters view up to that point.

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

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

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

Declaration

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.

Declaration

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.

Declaration

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.

Declaration

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 (\(...)).

Declaration

[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

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.

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.

Declaration

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.

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

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

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

The Unicode-safe comparison matches Unicode scalar values 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.

The Unicode-safe comparison matches Unicode scalar values 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.

The value passed as n must not offset i beyond the endIndex or
before the startIndex of this 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:).

See Also:index(_:offsetBy:limitedBy:)Complexity: O(n), where n is the absolute value of n.

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.

The value passed as n must not offset i beyond the endIndex or
before the startIndex of this 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.

See Also:index(_:offsetBy:)Complexity: O(n), where n is the absolute value of n.

Declaration

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

[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

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

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

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

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

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

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.

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

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.

Declaration

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

The withCString(_:) method ensures that the sequence's lifetime extends
through the execution of f.

f: A closure that takes a pointer to the string's UTF-8 code
unit sequence as its sole argument. If the closure has a return value,
it is used as the return value of the withCString(_:) method.
Returns: The return value of the f closure, if any.