struct
String
Initializers
Creates an empty string.
Declaration
init
()
Creates a string containing the given character.
c
: The character to convert to a string.
Declaration
init
(
_
c
:
Character
)
[Foundation]
Declaration
init
(
_
cocoaString
:
NSString
)
Creates a string from the given character view.
Use this initializer to recover a string after performing a collection slicing operation on a character view.
let
poem
=
"'Twas brillig, and the slithy toves / "
+
"Did gyre and gimbal in the wabe: / "
+
"All mimsy were the borogoves / "
+
"And the mome raths outgrabe."
let
excerpt
=
String
(
poem
.
characters
.
prefix
(
22
)) +
"..."
(
excerpt
)
// Prints "'Twas brillig, and the..."
characters
: A character view to convert to a string.
Declaration
init
(
_
characters
:
String.CharacterView
)
Creates a string corresponding to the given collection of Unicode scalars.
You can use this initializer to create a new string from a slice of
another string's unicodeScalars
view.
let
picnicGuest
=
"Deserving porcupine"
if
let
i
=
picnicGuest
.
unicodeScalars
.
index
(
of
:
" "
) {
let
adjective
=
String
(
picnicGuest
.
unicodeScalars
.
prefix
(
upTo
:
i
))
(
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
)
Creates a string representing the given value in base 10.
The following example converts the maximal Int
value to a string and
prints its length:
Declaration
init
<
T
:
_SignedInteger
>
(
_
v
:
T
)
Creates a string representing the given value in base 10.
The following example converts the maximal UInt
value to a string and
prints its length:
Declaration
init
<
T
:
UnsignedInteger
>
(
_
v
:
T
)
Creates an instance from the description of a given
LosslessStringConvertible
instance.
Declaration
init
<
T
:
LosslessStringConvertible
>
(
_
value
:
T
)
Creates a new string containing the characters in the given sequence.
You can use this initializer to create a new string from the result of
one or more operations on a string's characters
view. For example:
characters
: A sequence of characters.
Declaration
Creates a string representing the given value in the specified base.
Numerals greater than 9 are represented as Roman letters. These letters
start with "A"
if uppercase
is true
; otherwise, with "a"
.
Parameters:
value: The value to convert to a string.
radix: The base to use for the string representation. radix
must be
at least 2 and at most 36.
uppercase: Pass true
to use uppercase letters to represent numerals
greater than 9, or false
to use lowercase letters. The default is
false
.
Declaration
init
<
T
:
_SignedInteger
>
(
_
value
:
T
,
radix
:
Int
,
uppercase
:
Bool
=
default
)
Creates a string representing the given value in the specified base.
Numerals greater than 9 are represented as Roman letters. These letters
start with "A"
if uppercase
is true
; otherwise, with "a"
.
Parameters:
value: The value to convert to a string.
radix: The base to use for the string representation. radix
must be
at least 2 and at most 36.
uppercase: Pass true
to use uppercase letters to represent numerals
greater than 9, or false
to use lowercase letters. The default is
false
.
Declaration
init
<
T
:
UnsignedInteger
>
(
_
value
:
T
,
radix
:
Int
,
uppercase
:
Bool
=
default
)
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
!)
(
s
)
}
// Prints "Café"
let
invalidUTF8
: [
CChar
] = [
67
,
97
,
102
, -
61
,
0
]
invalidUTF8
.
withUnsafeBufferPointer
{
ptr
in
let
s
=
String
(
cString
:
ptr
.
baseAddress
!)
(
s
)
}
// Prints "Caf�"
cString
: A pointer to a null-terminated UTF-8 code sequence.
Declaration
init
(
cString
:
UnsafePointer
<
CChar
>
)
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
>
)
[Foundation]
Declaration
init
(
contentsOf
url
:
URL
)
[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
)
[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
)
[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
)
[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
)
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 theTextOutputStreamable
protocol, the result is obtained by callinginstance.write(to: s)
on an empty strings
. - If
instance
conforms to theCustomStringConvertible
protocol, the result isinstance.description
. - If
instance
conforms to theCustomDebugStringConvertible
protocol, the result isinstance.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.
After adding CustomStringConvertible
conformance by implementing the
description
property, Point
provides its own custom representation.
extension
Point
:
CustomStringConvertible
{
var
description
:
String
{
return
"(\(
x
), \(
y
))"
}
}
(
String
(
describing
:
p
))
// Prints "(21, 30)"
See Also: String.init<Subject>(reflecting: Subject)
Declaration
init
<
Subject
>
(
describing
instance
:
Subject
)
Creates an instance initialized to the given extended grapheme cluster literal.
Don't call this initializer directly. It may be used by the compiler when you initialize a string using a string literal containing a single extended grapheme cluster.
Declaration
init
(
extendedGraphemeClusterLiteral
value
:
String
)
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 theCustomDebugStringConvertible
protocol, the result issubject.debugDescription
. - If
subject
conforms to theCustomStringConvertible
protocol, the result issubject.description
. - If
subject
conforms to theTextOutputStreamable
protocol, the result is obtained by callingsubject.write(to: s)
on an empty strings
. - 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.
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
))"
}
}
(
String
(
reflecting
:
p
))
// Prints "Point(x: 21, y: 30)"
See Also: String.init<Subject>(Subject)
Declaration
init
<
Subject
>
(
reflecting
subject
:
Subject
)
Creates a new string representing the given string repeated the specified number of times.
For example, use this initializer to create a string with ten "00"
strings in a row.
let
zeroes
=
String
(
repeating
:
"00"
,
count
:
10
)
(
zeroes
)
// Prints "00000000000000000000"
Parameters:
repeatedValue: The string to repeat.
count: The number of times to repeat repeatedValue
in the resulting
string.
Declaration
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."
(
message
)
// Prints "If one cookie costs 2 dollars, 3 cookies cost 6 dollars."
Declaration
init
(
stringInterpolation
strings
:
String
...)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
Bool
)
Creates a string containing the given value's textual representation.
Do not call this initializer directly. It is used by the compiler when interpreting string interpolations.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
Character
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
Float32
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
Float64
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
Int
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
Int8
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
Int16
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
Int32
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
Int64
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
String
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
UInt
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
UInt8
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
UInt16
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
UInt32
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
UInt64
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
(
stringInterpolationSegment
expr
:
UnicodeScalar
)
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.
See Also: ExpressibleByStringInterpolation
Declaration
init
<
T
>
(
stringInterpolationSegment
expr
:
T
)
Creates an instance initialized to the given string value.
Don't 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
)
Creates an instance initialized to the given Unicode scalar value.
Don't call this initializer directly. It may be used by the compiler when you initialize a string using a string literal that contains a single Unicode scalar value.
Declaration
init
(
unicodeScalarLiteral
value
:
String
)
[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
)
[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
)
Instantiates an instance of the conforming type from a string representation.
Declaration
init
?(
_
description
:
String
)
Creates a string corresponding to the given sequence of UTF-8 code units.
If utf8
is an ill-formed UTF-8 code sequence, the result is nil
.
You can use this initializer to create a new string from a slice of
another string's utf8
view.
let
picnicGuest
=
"Deserving porcupine"
if
let
i
=
picnicGuest
.
utf8
.
index
(
of
:
32
) {
let
adjective
=
String
(
picnicGuest
.
utf8
.
prefix
(
upTo
:
i
))
(
adjective
)
}
// Prints "Optional(Deserving)"
The adjective
constant is created by calling this initializer with a
slice of the picnicGuest.utf8
view.
utf8
: A UTF-8 code sequence.
Declaration
init
?(
_
utf8
:
String.UTF8View
)
Creates a string corresponding to the given sequence of UTF-16 code units.
If utf16
contains unpaired UTF-16 surrogates, the result is nil
.
You can use this initializer to create a new string from a slice of
another string's utf16
view.
let
picnicGuest
=
"Deserving porcupine"
if
let
i
=
picnicGuest
.
utf16
.
index
(
of
:
32
) {
let
adjective
=
String
(
picnicGuest
.
utf16
.
prefix
(
upTo
:
i
))
(
adjective
)
}
// Prints "Optional(Deserving)"
The adjective
constant is created by calling this initializer with a
slice of the picnicGuest.utf16
view.
utf16
: A UTF-16 code sequence.
Declaration
init
?(
_
utf16
:
String.UTF16View
)
[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
)
[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
)
[Foundation]
Returns a String
initialized by converting given data
into
Unicode characters using a given encoding
.
Declaration
init
?(
data
:
Data
,
encoding
:
String
.
Encoding
)
[Foundation] Produces a string created by copying the data from a given C array of UTF8-encoded bytes.
Declaration
init
?(
utf8String
bytes
:
UnsafePointer
<
CChar
>
)
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.
let
validUTF8
: [
CChar
] = [
67
,
97
,
102
, -
61
, -
87
,
0
]
validUTF8
.
withUnsafeBufferPointer
{
ptr
in
let
s
=
String
(
validatingUTF8
:
ptr
.
baseAddress
!)
(
s
)
}
// Prints "Optional(Café)"
let
invalidUTF8
: [
CChar
] = [
67
,
97
,
102
, -
61
,
0
]
invalidUTF8
.
withUnsafeBufferPointer
{
ptr
in
let
s
=
String
(
validatingUTF8
:
ptr
.
baseAddress
!)
(
s
)
}
// Prints "nil"
cString
: A pointer to a null-terminated UTF-8 code sequence.
Declaration
init
?(
validatingUTF8
cString
:
UnsafePointer
<
CChar
>
)
Instance Variables
[Foundation] Produce a string with the first character from each word changed to the corresponding uppercase value.
Declaration
var
capitalized
:
String
{
get
}
A view of the string's contents as a collection of characters.
Declaration
var
characters
:
String.CharacterView
{
get
set
}
A custom playground Quick Look for this instance.
If this type has value semantics, the PlaygroundQuickLook
instance
should be unaffected by subsequent mutations.
Declaration
var
customPlaygroundQuickLook
:
PlaygroundQuickLook
{
get
}
A representation of the string that is suitable for debugging.
Declaration
var
debugDescription
:
String
{
get
}
[Foundation]
Returns a string made by normalizing the String
's
contents using Form D.
Declaration
var
decomposedStringWithCanonicalMapping
:
String
{
get
}
[Foundation]
Returns a string made by normalizing the String
's
contents using Form KD.
Declaration
var
decomposedStringWithCompatibilityMapping
:
String
{
get
}
A textual representation of this instance.
Instead of accessing this property directly, convert an instance of any
type to a string by using the String(describing:)
initializer. For
example:
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
)
(
s
)
// Prints "(21, 30)"
The conversion of p
to a string in the assignment to s
uses the
Point
type's description
property.
Declaration
var
description
:
String
{
get
}
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
}
[Foundation]
Returns the fastest encoding to which the String
may be
converted without loss of information.
Declaration
var
fastestEncoding
:
String
.
Encoding
{
get
}
[Foundation] An unsigned integer that can be used as a hash table address.
Declaration
var
hash
:
Int
{
get
}
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
}
A Boolean value indicating whether a string has no characters.
Declaration
var
isEmpty
:
Bool
{
get
}
[Foundation]
A capitalized representation of the String
that is produced
using the current locale.
Declaration
var
localizedCapitalized
:
String
{
get
}
[Foundation] A lowercase version of the string that is produced using the current locale.
Declaration
var
localizedLowercase
:
String
{
get
}
[Foundation] An uppercase version of the string that is produced using the current locale.
Declaration
var
localizedUppercase
:
String
{
get
}
[Foundation]
Returns a string made by normalizing the String
's
contents using Form C.
Declaration
var
precomposedStringWithCanonicalMapping
:
String
{
get
}
[Foundation]
Returns a string made by normalizing the String
's
contents using Form KC.
Declaration
var
precomposedStringWithCompatibilityMapping
:
String
{
get
}
[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
}
[Foundation]
Returns the smallest encoding to which the String
can
be converted without loss of information.
Declaration
var
smallestEncoding
:
String
.
Encoding
{
get
}
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
}
The string's value represented as a collection of Unicode scalar values.
Declaration
var
unicodeScalars
:
String.UnicodeScalarView
{
get
set
}
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
(
bytes
)
// Prints "[72, 101, 108, 108, 111, 33, 0]"
bytes
.
withUnsafeBufferPointer
{
ptr
in
(
strlen
(
ptr
.
baseAddress
!))
}
// Prints "6"
Declaration
var
utf8CString
:
ContiguousArray
<
CChar
>
{
get
}
Subscripts
Accesses the character at the given position.
Indices for a subscripting a string are shared with the string's
characters
view. For example:
let
greeting
=
"Hello, friend!"
if
let
i
=
greeting
.
characters
.
index
(
where
: { $
0
>
=
"A"
&
&
$
0
<
=
"Z"
}) {
(
"First capital letter: \(
greeting
[
i
]
)"
)
}
// Prints "First capital letter: 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
}
Accesses the text in the given range.
Complexity: O(n) if the underlying string is bridged from Objective-C, where n is the length of the string; otherwise, O(1).
Declaration
subscript
(
bounds
:
ClosedRange
<
String
.
Index
>
) -
>
String
{
get
}
Static Methods
[Foundation] Returns an Array of the encodings string objects support in the application's environment.
Declaration
static
func
availableStringEncodings
() -
>
[
String
.
Encoding
]
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
)
(
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
)
(
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
.
See Also: UnicodeCodec
Declaration
static
func
decodeCString
<
Encoding
:
UnicodeCodec
>
(
_
cString
:
UnsafePointer
<
Encoding
.
CodeUnit
>
?,
as
encoding
:
Encoding
.
Type
,
repairingInvalidCodeUnits
isRepairing
:
Bool
=
default
) -
>
(
result
:
String
,
repairsMade
:
Bool
)?
[Foundation] Returns the C-string encoding assumed for any method accepting a C string as an argument.
Declaration
static
func
defaultCStringEncoding
() -
>
String
.
Encoding
[Foundation] Returns a human-readable string giving the name of a given encoding.
Declaration
static
func
localizedName
(
of
encoding
:
String
.
Encoding
) -
>
String
Instance Methods
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
.
Parameters: lhs: A value to compare. rhs: Another value to compare.
Declaration
[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
?
[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
?
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
(
"🌍"
)
(
globe
)
// Prints "Globe 🌍"
c
: The character to append to the string.
Declaration
mutating
func
append
(
_
c
:
Character
)
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"
)
}
(
greeting
)
// Prints "Hello, friend"
other
: Another string.
Declaration
mutating
func
append
(
_
other
:
String
)
[Foundation]
Returns a representation of the String
as a C string
using a given encoding.
Declaration
func
cString
(
using
encoding
:
String
.
Encoding
) -
>
[
CChar
]?
[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
[Foundation]
Returns a capitalized representation of the String
using the specified locale.
Declaration
func
capitalized
(
with
locale
:
Locale
?) -
>
String
[Foundation]
Returns the result of invoking compare:options:
with
NSCaseInsensitiveSearch
as the only option.
Declaration
func
caseInsensitiveCompare
(
_
aString
:
String
) -
>
ComparisonResult
[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
[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
]
[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
?
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
[Foundation] Performs linguistic analysis on the specified string by enumerating the specific range of the string, providing the Block with the located tags.
Declaration
[Foundation] Enumerates the substrings of the specified type in the specified range of the string.
Declaration
[Foundation] Returns a string with the given character folding options applied.
Declaration
func
folding
(
_
options
:
CompareOptions
=
default
,
locale
:
Locale
?) -
>
String
[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
[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
>
)
[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
>
)
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
(
cafe
.
hasPrefix
(
"café"
))
// Prints "false"
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.
// Unicode safe
let
composedCafe
=
"Café"
let
decomposedCafe
=
"Cafe\u{0301}"
(
cafe
.
hasPrefix
(
composedCafe
))
// Prints "true"
(
cafe
.
hasPrefix
(
decomposedCafe
))
// Prints "true"
prefix
: A possible prefix to test against this string.
Returns: true
if the string begins with prefix
, otherwise, false
.
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
(
plans
.
hasSuffix
(
"Café"
))
// Prints "false"
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.
// Unicode safe
let
composedCafe
=
"café"
let
decomposedCafe
=
"cafe\u{0301}"
(
plans
.
hasSuffix
(
composedCafe
))
// Prints "true"
(
plans
.
hasSuffix
(
decomposedCafe
))
// Prints "true"
suffix
: A possible suffix to test against this string.
Returns: true
if the string ends with suffix
, otherwise, false
.
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
)
(
s
[
i
])
// Prints "t"
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
func
index
(
_
i
:
String
.
Index
,
offsetBy
n
:
String
.
IndexDistance
) -
>
String
.
Index
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
) {
(
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
)
(
j
)
// Prints "nil"
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
func
index
(
_
i
:
String
.
Index
,
offsetBy
n
:
String
.
IndexDistance
,
limitedBy
limit
:
String
.
Index
) -
>
String
.
Index
?
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
Declaration
func
index
(
before
i
:
String
.
Index
) -
>
String
.
Index
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
)
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
:
Collection
where
S
.
Iterator
.
Element
==
Character
>
(
contentsOf
newElements
:
S
,
at
i
:
String
.
Index
)
[Foundation]
Returns the number of bytes required to store the
String
in a given encoding.
Declaration
func
lengthOfBytes
(
using
encoding
:
String
.
Encoding
) -
>
Int
[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
]
[Foundation] Compares the string and a given string using a case-insensitive, localized, comparison.
Declaration
func
localizedCaseInsensitiveCompare
(
_
aString
:
String
) -
>
ComparisonResult
[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
[Foundation] Compares the string and a given string using a localized comparison.
Declaration
func
localizedCompare
(
_
aString
:
String
) -
>
ComparisonResult
[Foundation] Compares strings as sorted by the Finder.
Declaration
func
localizedStandardCompare
(
_
string
:
String
) -
>
ComparisonResult
[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
Returns a lowercase version of the string.
Here's an example of transforming a string to all lowercase letters.
let
cafe
=
"Café 🍵"
(
cafe
.
lowercased
())
// Prints "café 🍵"
Returns: A lowercase copy of the string.
Complexity: O(n)
Declaration
func
lowercased
() -
>
String
[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
[Foundation]
Returns the maximum number of bytes needed to store the
String
in a given encoding.
Declaration
func
maximumLengthOfBytes
(
using
encoding
:
String
.
Encoding
) -
>
Int
[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
[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
[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
[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
>
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
.
characters
.
index
(
of
:
"-"
) {
nonempty
.
remove
(
at
:
i
)
}
(
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
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
)
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.
Declaration
mutating
func
removeSubrange
(
_
bounds
:
ClosedRange
<
String
.
Index
>
)
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.
Declaration
mutating
func
removeSubrange
(
_
bounds
:
Range
<
String
.
Index
>
)
Replaces the text within the specified bounds with the given string.
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
.
Declaration
mutating
func
replaceSubrange
(
_
bounds
:
ClosedRange
<
String
.
Index
>
,
with
newElements
:
String
)
Replaces the text within the specified bounds with the given string.
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
.
Declaration
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
where
C
:
Collection
,
C
.
Iterator
.
Element
==
Character
>
(
_
bounds
:
ClosedRange
<
String
.
Index
>
,
with
newElements
:
C
)
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
where
C
:
Collection
,
C
.
Iterator
.
Element
==
Character
>
(
_
bounds
:
Range
<
String
.
Index
>
,
with
newElements
:
C
)
[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
[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
?
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
)
[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
[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
[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
Returns an uppercase version of the string.
The following example transforms a string to uppercase letters:
let
cafe
=
"Café 🍵"
(
cafe
.
uppercased
())
// Prints "CAFÉ 🍵"
Returns: An uppercase copy of the string.
Complexity: O(n)
Declaration
func
uppercased
() -
>
String
[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
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.
Declaration
func
withCString
<
Result
>
(
_
body
: (
UnsafePointer
<
Int8
>
)
throws
-
>
Result
)
rethrows
-
>
Result
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 String.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
.
index
(
of
:
" "
) {
let
result
=
chars
.
suffix
(
from
:
chars
.
index
(
after
:
i
))
chars
.
removeSubrange
(
i
..
<
chars
.
endIndex
)
return
result
}
return
String.CharacterView
()
}
(
str
)
// Prints "All"
(
String
(
afterSpace
))
// Prints "this happened, more or less."
body
: A closure that takes a character view as its argument.
Returns: The return value of the body
closure, if any, is the return
value of this method.
Declaration
mutating
func
withMutableCharacters
<
R
>
(
_
body
: (
inout
String.CharacterView
) -
>
R
) -
>
R
Appends the given string to this string.
other
: A string to append.
Declaration
mutating
func
write
(
_
other
:
String
)
Writes the string into the given output stream.
target
: An output stream.
Declaration
func
write
<
Target
:
TextOutputStream
>
(
to
target
:
inout
Target
)
[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
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. TheString
type bridges with the Objective-C classNSString
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.
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.
Combine strings using the concatenation operator (
+
).Modifying and Comparing Strings
Strings always have value semantics. Modifying a copy of a string leaves the original unaffected.
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: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'sCharacter
type. Each element of thecharacters
view is represented by aCharacter
instance.Each visible character in the
cafe
string is a separate element of thecharacters
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 aUnicodeScalar
instance and is equivalent to a UTF-32 code unit.The
unicodeScalars
view's elements comprise each Unicode scalar value in thecafe
string. In particular, becausecafe
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 aUInt16
instance.The elements of the
utf16
view are the code units for the string when encoded in UTF-16.The elements of this collection match those accessed through indexed
NSString
APIs.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 aUInt8
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 whenString
instances are passed to C APIs.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 thecharacters
view up to that point.You can convert an index into one of a string's views to an index into another view.
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 toNSString
using the type-cast operator (as
), and anyString
instance that originates in Objective-C may use anNSString
instance as its storage. Because any arbitrary subclass ofNSString
can become aString
instance, there are no guarantees about representation or efficiency when aString
instance is backed byNSString
storage. BecauseNSString
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 underlyingNSString
has unusual performance characteristics).For more information about the Unicode terms used in this discussion, see the Unicode.org glossary. In particular, this discussion mentions extended grapheme clusters, Unicode scalar values, and canonical equivalence.
See Also:
String.CharacterView
,String.UnicodeScalarView
,String.UTF16View
,String.UTF8View