:orphan:

.. raw:: html

<style>

.repl,
.emph,
.look {
  color:rgb(47,175,187)
}
.emph {
  font-weight:bold
}

pre,
.pre {
  font-family: Monaco, monospace; font-size:90%
}

pre.literal-block {
  overflow: hidden;
}

span.look,
span.look1 {
  position: relative;
  border-bottom: .2em dotted rgb(255,165,165);
}

span.aside {
  font-family: sans-serif; white-space: normal;
}

span.look + span.aside,
span.look1 + span.aside {
  display: none;
}

span.look:hover,
span.look1:hover {
  background-color:greenyellow;
}

span.look:hover {
  color:rgb(23,87,94);
}

/* Main speech bubble*/
span.look:hover + span.aside,
span.look1:hover + span.aside {
  display: inline-block;
  position: relative;
  margin-top: -1000em;
  margin-bottom: -1000em;
  margin-right: -1000em;
  padding: 0.3em 1em 0.3em 1em;
  /*text-align: justify;*/
  max-width: 70%;
  /*width: 50%;*/
  left: 2em;
  background: gray;
  -moz-border-radius:10px;
  -webkit-border-radius:10px;
  border-radius:10px;
  color: #fff;
  z-index: 1;
}

/* Little triangle on the left */
span.look:hover + span.aside:after,
span.look1:hover + span.aside:after {
  content: "";
  position: absolute;
  bottom: 0.3em;
  left: -1.5em;
  border-style: solid;
  border-width: 0.6em 2em 0.6em 0;
  border-color: transparent gray;
  display: inline;
  width: 0;
  z-index: 2;
}

/*a:link {color:blue}*/
</style>

.. role:: repl .. default-role:: repl

.. |swift| replace:: (swift)

.. role:: look .. role:: look1 .. role:: aside .. role:: emph

=================== Swift String Design

.. Admonition:: This Document :class: note

contains interactive HTML commentary that does not currently appear in printed output. Hover your mouse over elements with a dotted pink underline to view the hidden commentary.
represents the intended design of Swift strings, not their current implementation state.
is being delivered in installments. Content still to come is outlined in Coming Installments_.

.. warning:: This document was used in planning Swift 1.0; it has not been kept up to date and does not describe the current or planned behavior of Swift.

.. contents:: :depth: 3

Introduction

Like all things Swift, our approach to strings begins with a deep respect for the lessons learned from many languages and libraries, especially Objective-C and Cocoa.

Goals

String should:

honor industry standards such as Unicode
when handling non-ASCII text, deliver "reasonably correct" results to users thinking only in terms of ASCII
when handling ASCII text, provide "expected behavior" to users thinking only in terms of ASCII
be hard to use incorrectly
be easy to use correctly
provide near-optimal efficiency for 99% of use cases
provide a foundation upon which proper locale-sensitive operations can be built

Non-Goals

String need not:

have behavior appropriate to all locales and contexts
be an appropriate type (or base type) for all text storage applications

Overview By Example

In this section, we'll walk through some basic examples of Swift string usage while discovering its essential properties.

`String` is a `First-Class Type`__

__ https://en.wikipedia.org/wiki/First-class_citizen

.. parsed-literal::

|swift| var s = "Yo" // s: :emph:String = "Yo"

Unlike, say, C's char*, the meaning of a Swift string is always unambiguous.

Strings are Efficient

The implementation of String takes advantage of state-of-the-art optimizations, including:

Storing short strings without heap allocation
Sharing allocated buffers among copies and slices
In-place modification of uniquely-owned buffers

As a result, copying_ and slicing__ strings, in particular, can be viewed by most programmers as being "almost free."

__ sliceable_

Strings are Mutable

.. sidebar:: Why Mention It?

The ability to change a string's value might not be worth noting except that some languages make all strings immutable, as a way of working around problems that Swift has defined away--by making strings pure values (see below).

.. parsed-literal:: |swift| extension String { func addEcho() { self += self } } |swift| :look1:s.addEcho()\ :aside:s is modified in place |swift| s // s: String = :emph:"YoYo"

.. _copying:

Strings are Value Types

Distinct string variables have independent values: when you pass someone a string they get a copy of the value, and when someone passes you a string you own it. Nobody can change a string value "behind your back."

.. parsed-literal:: |swift| class Cave { // Utter something in the cave func say(_ msg: String) -> String { :look1:msg.addEcho()\ :aside:Modifying a parameter is safe because the callee sees a copy of the argument self.lastSound = msg :look1:return self.lastSound\ :aside:Returning a stored value is safe because the caller sees a copy of the value }

        var lastSound: String   // a Cave remembers the last sound made
      }

Strings are Unicode-Aware

.. sidebar:: Deviations from Unicode

Any deviation from what Unicode specifies requires careful justification. So far, we have found two possible points of deviation for Swift String:

The Unicode Text Segmentation Specification_ says, "do not break between CR and LF__." However, breaking extended grapheme clusters between CR and LF may necessary if we wish String to "behave normally" for users of pure ASCII. This point is still open for discussion.

__ http://www.unicode.org/reports/tr29/#GB2
The Unicode Text Segmentation Specification_ says, "do not break between regional indicator symbols__." However, it also says "(Sequences of more than two RI characters should be separated by other characters, such as U+200B ZWSP)." Although the parenthesized note probably has less official weight than the other admonition, breaking pairs of RI characters seems like the right thing for us to do given that Cocoa already forms strings with several adjacent pairs of RI characters, and the Unicode spec can be read as outlawing such strings anyway.

__ http://www.unicode.org/reports/tr29/#GB8

.. _Unicode Text Segmentation Specification: http://www.unicode.org/reports/tr29

Swift applies Unicode algorithms wherever possible. For example, distinct sequences of code points are treated as equal if they represent the same character: [#canonical]_

Note that individual code points are still observable by explicit request:

.. parsed-literal:: |swift| n1.codePoints == n2.codePoints // r0 : Bool = false

.. _locale-agnostic:

Strings are Locale-Agnostic

Strings neither carry their own locale information, nor provide behaviors that depend on a global locale setting. Thus, for any pair of strings s1 and s2, "s1 == s2" yields the same result regardless of system state. Strings do provide a suitable foundation on which to build locale-aware interfaces.\ [#locales]_

Strings are Containers

.. sidebar:: String Indices

      ``String`` implements the ``Container`` protocol, but
      **cannot be indexed by integers**.  Instead,
      ``String.IndexType`` is a library type conforming to the
      ``BidirectionalIndex`` protocol.

      This might seem surprising at first, but code that indexes
      strings with arbitrary integers is seldom Unicode-correct in
      the first place, and Swift provides alternative interfaces
      that encourage Unicode-correct code.  For example, instead
      of ``s[0] == 'S'`` you'd write ``s.startsWith("S")``.

.. parsed-literal:: |swift| var s = "Strings are awesome" // s : String = "Strings are awesome" |swift| var r = s.find("awe") // r : Range<StringIndex> = <"...are a̲w̲e̲some"> |swift| s[r.start] // r0 : Character = :look:Character("a")\ :aside:String elements have type Character (see below)

.. |Character| replace:: Character .. _Character:

Strings are Composed of `Character`\ s

Character, the element type of String, represents a grapheme cluster, as specified by a default or tailored Unicode segmentation algorithm. This term is precisely defined__ by the Unicode specification, but it roughly means what the user thinks of when she hears "character"__. For example, the pair of code points "LATIN SMALL LETTER N, COMBINING TILDE" forms a single grapheme cluster, "ñ".

__ http://www.unicode.org/glossary/#grapheme_cluster __ http://useless-factor.blogspot.com/2007/08/unicode-implementers-guide-part-4.html

Access to lower-level elements is still possible by explicit request:

.. parsed-literal:: |swift| s.codePoints[s.codePoints.start] // r1 : CodePoint = CodePoint(83) /* S */ |swift| s.bytes[s.bytes.start] // r2 : UInt8 = UInt8(83)

Strings Support Flexible Segmentation

The Character\ s enumerated when simply looping over elements of a Swift string are extended grapheme clusters__ as determined by Unicode's Default Grapheme Cluster Boundary Specification__. [#char]_

__ http://www.unicode.org/glossary/#extended_grapheme_cluster __ http://www.unicode.org/reports/tr29/#Default_Grapheme_Cluster_Table

This segmentation offers naïve users of English, Chinese, French, and probably a few other languages what we think of as the "expected results." However, not every script_ can be segmented uniformly for all purposes. For example, searching and collation require different segmentations in order to handle Indic scripts correctly. To that end, strings support properties for more-specific segmentations:

.. Note:: The following example needs a more interesting string in order to demonstrate anything interesting. Hopefully Aki has some advice for us.

.. parsed-literal:: |swift| for c in s { print("Extended Grapheme Cluster: (c)") } Extended Grapheme Cluster: f Extended Grapheme Cluster: o Extended Grapheme Cluster: o |swift| for c in s.collationCharacters { print("Collation Grapheme Cluster: (c)") } Collation Grapheme Cluster: f Collation Grapheme Cluster: o Collation Grapheme Cluster: o |swift| for c in s.searchCharacters { print("Search Grapheme Cluster: (c)") } Search Grapheme Cluster: f Search Grapheme Cluster: o Search Grapheme Cluster: o

Also, each such segmentation provides a unique IndexType, allowing a string to be indexed directly with different indexing schemes

.. code-block:: swift-console

|swift| var i = s.searchCharacters.startIndex // r2 : UInt8 = UInt8(83)

.. _script: http://www.unicode.org/glossary/#script

.. _sliceable:

Strings are Sliceable

.. parsed-literal:: |swift| s[r.start...r.end] // r2 : String = "awe" |swift| s[\ :look1:r.start...\ ]\ :aside:postfix slice operator means "through the end" // r3 : String = "awesome" |swift| s[\ :look1:...r.start\ ]\ :aside:prefix slice operator means "from the beginning" // r4 : String = "Strings are " |swift| :look1:s[r]\ :aside:indexing with a range is the same as slicing // r5 : String = "awe" |swift| s[r] = "hand" |swift| s // s : String = "Strings are :look:handsome\ :aside:slice replacement can resize the string\ "

.. _extending:

Strings are Encoded as UTF-8

.. sidebar:: Encoding Conversion

Conversion to and from other encodings is out-of-scope for String itself, but could be provided, e.g., by an Encoding module.

.. parsed-literal:: |swift| for x in "bump"\ .bytes { print(x) } 98 117 109 112

Coming Installments

Reference Manual
Rationales
Cocoa Bridging Strategy
Comparisons with NSString
- High Level
- Member-by-member

Reference Manual

s.bytes
s.indices
s[i]
s[start...end]
s == t, s != t
s < t, s > t, s <= t, s >= t
s.hash()
s.startsWith(), s.endsWith()
s + t, s += t, s.append(t)
s.split(), s.split(n), s.split(sep, n)
s.strip(), s.stripStart(), s.stripEnd()
s.commonPrefix(t), s.mismatch(t)
s.toUpper(), s.toLower()
s.trim(predicate)
s.replace(old, new, count)
s.join(sequenceOfStrings)

.. Stuff from Python that we don't need to do

s.capitalize()
s.find(), s.rfind()
Stuff for monospace
- s * 20
- s.center()
- s.count() [no arguments]
- s.expandTabs(tabsize)
- s.leftJustify(width, fillchar)
- s.rightJustify(width, fillchar)
- s.count()
s.isAlphanumeric()
s.isAlphabetic()
s.isNumeric()
s.isDecimal()
s.isDigit()?
s.isLower()
s.isUpper()
s.isSpace()
s.isTitle()

Cocoa Bridging Strategy

Rationales

Why a Built-In String Type?

.. Admonition:: DaveZ Sez

In the "why a built-in string type" section, I think the main narrative is that two string types is bad, but that we have two string types in Objective-C for historically good reasons. To get one string type, we need to merge the high-level features of Objective-C with the performance of C, all while not having the respective bad the bad semantics of either (reference semantics and "anarchy" memory-management respectively). Furthermore, I'd write "value semantics" in place of "C++ semantics". I know that is what you meant, but we need to tread carefully in the final document.

NSString and NSMutableString\ --the string types provided by Cocoa--are full-featured classes with high-level functionality for writing fully-localized applications. They have served Apple programmers well; so, why does Swift have its own string type?

ObjCMessageSend
Error Prone Mutability Reference semantics don't line up with how people think about strings
2 is too many string types. two APIs duplication of effort documentation Complexity adds decisions for users etc.
ObjC needed to innovate because C strings suck O(N) length no localization no memory management no specified encoding
C strings had to stay around for performance reasons and interoperability

Want performance of C, sound semantics of C++ strings, and high-level goodness of ObjC.

The design of NSString is very different from the string designs of most modern programming languages, which all tend to be very similar to one another. Although existing NSString users are a critical constituency today, current trends indicate that most of our future target audience will not be NSString users. Absent compelling justification, it's important to make the Swift programming environment as familiar as possible for them.

How Would You Design It?

.. Admonition:: DaveZ Sez

In the "how would you design it" section, the main narrative is twofold: how does it "feel" and how efficient is it? The former is about feeling built in, which we can easily argue that both C strings or Cocoa strings fail at for their respective semantic (and often memory management related) reasons. Additionally, the "feel" should be modern, which is where the Cocoa framework and the Unicode standard body do better than C. Nevertheless, we can still do better than Objective-C and your strong work at helping people reason about grapheme clusters instead of code points (or worse, units) is wonderful and it feels right to developers. The second part of the narrative is about being efficient, which is where arguing for UTF8 is the non-obvious but "right" answer for the reasons we have discussed.

It'd be an independent value so you don't have to micromanage sharing and mutation
It'd be UTF-8 because:
- UTF-8 has been the clear winner__ among Unicode encodings since at least 2008; Swift should interoperate smoothly and efficiently with the rest of the world's systems
  
  __ http://www.artima.com/weblogs/viewpost.jsp?thread=230157
- UTF-8 is a fairly efficient storage format, especially for ASCII but also for the most common non-ASCII code points.
- This__ posting elaborates on some other nice qualities of UTF-8:
  1. All ASCII files are already UTF-8 files
  2. ASCII bytes always represent themselves in UTF-8 files. They never appear as part of other UTF-8 sequences
  3. ASCII code points are always represented as themselves in UTF-8 files. They cannot be hidden inside multibyte UTF-8 sequences
  4. UTF-8 is self-synchronizing
  5. CodePoint substring search is just byte string search
  6. Most programs that handle 8-bit files safely can handle UTF-8 safely
  7. UTF-8 sequences sort in code point order.
  8. UTF-8 has no "byte order."
  __ http://research.swtch.com/utf8
It would be efficient, taking advantage of state-of-the-art optimizations, including:
- Storing short strings without heap allocation
- Sharing allocated buffers among copies and slices
- In-place modification of uniquely-owned buffers

Comparisons with `NSString`

High-Level Comparison with `NSString`

.. Admonition:: DaveZ Sez

I think the main message of the API breadth subsection is that URLs, paths, etc would be modeled as formal types in Swift (i.e. not as extensions on String). Second, I'd speculate less on what Foundation could do (like extending String) and instead focus on the fact that NSString still exists as an escape hatch for those that feel that they need or want it. Furthermore, I'd move up the "element access" discussion above the "escape hatch" discussion (which should be last in the comparison with NSString discussion).

API Breadth


The ``NSString`` interface clearly shows the effects of 20 years of
evolution through accretion.  It is broad, with functionality
addressing encodings, paths, URLs, localization, and more.  By
contrast, the interface to Swift's ``String`` is much narrower.

.. _TBD:

Of course, there's a reason for every ``NSString`` method, and the
full breadth of ``NSString`` functionality must remain accessible to
the Cocoa/Swift programmer.  Fortunately, there are many ways to
address this need.  For example:

* The ``Foundation`` module can extend ``String`` with the methods of
  ``NSString``.  The extent to which we provide an identical-feeling
  interface and/or correct any ``NSString`` misfeatures is still TBD
  and wide open for discussion.

* We can create a new modular interface in pure Swift, including a
  ``Locale`` module that addresses localized string operations, an
  ``Encoding`` module that addresses character encoding schemes, a
  ``Regex`` module that provides regular expression functionality,
  etc.  Again, the specifics are TBD.

* When all else fails, users can convert their Swift ``String``\ s to
  ``NSString``\ s when they want to access ``NSString``-specific
  functionality:

  .. parsed-literal::

    **NString(mySwiftString)**\ .localizedStandardCompare(otherSwiftString)

For Swift version 1.0, we err on the side of keeping the string
interface small, coherent, and sufficient for implementing
higher-level functionality.

Element Access

NSString exposes UTF-16 code units__ as the primary element on which indexing, slicing, and iteration operate. Swift's UTF-8 code units are only available as a secondary interface.

__ http://www.unicode.org/glossary/#code_unit

NSString is indexable and sliceable using Int\ s, and so exposes a length attribute. Swift's String is indexable and sliceable using an abstract BidirectionalIndex type, and does not expose its length__.

__ length_

Sub-Strings


.. _range:

Creating substrings in Swift is very fast. Therefore, Cocoa APIs that
operate on a substring given as an ``NSRange`` are replaced with Swift
APIs that just operate on ``String``\ s. One can use range-based
subscripting to achieve the same effect. For example: ``[str doFoo:arg
withRange:subrange]`` becomes ``str[subrange].doFoo(arg)``.

``NSString`` Member-by-Member Comparison
----------------------------------------

:Notes:
  * The following are from public headers from public frameworks, which
    are AppKit and Foundation (verified).

  * Deprecated Cocoa APIs are not considered

  * A status of "*Remove*" below indicates a feature whose removal is
    anticipated.  Rationale is provided for these cases.

Indexing
~~~~~~~~

.. _length:

---------

.. sidebar:: Why doesn't ``String`` support ``.length``?

    In Swift, by convention, ``x.length`` is used to represent
    the number of elements in a container, and since ``String`` is a
    container of abstract |Character|_\ s, ``length`` would have to
    count those.

    This meaning of ``length`` is unimplementable in O(1).  It can be
    cached, although not in the memory block where the characters are
    stored, since we want a ``String`` to share storage with its
    slices.  Since the body of the ``String`` must already store the
    ``String``\ 's *byte length*, caching the ``length`` would
    increase the footprint of the top-level String object.  Finally,
    even if ``length`` were provided, doing things with ``String``
    that depend on a specific numeric ``length`` is error-prone.

:Cocoa:
  .. parsed-literal::

     \- (NSUInteger)\ **length**
     \- (unichar)\ **characterAtIndex:**\ (NSUInteger)index;

:Swift: *not directly provided*, but similar functionality is
  available:

  .. parsed-literal::

       for j in 0...\ **s.bytes.length** {
         doSomethingWith(**s.bytes[j]**)
       }

---------

:Cocoa:
  .. parsed-literal::
     \- (NSRange)\ **rangeOfComposedCharacterSequenceAtIndex:**\ (NSUInteger)index;
     \- (NSRange)\ **rangeOfComposedCharacterSequencesForRange:**\ (NSRange)range;

:Swift:
  .. parsed-literal::
    typealias IndexType = ...
    func **indices**\ () -> Range<IndexType>
    **subscript**\ (i: IndexType) -> Character

  .. Admonition:: Usage

     .. parsed-literal::

       for i in someString.indices() {
         doSomethingWith(\ **someString[i]**\ )
       }

       var (i, j) = **someString.indices().bounds**
       while (i != j) {
         doSomethingElseWith(\ **someString[i]**\ )
         ++i
       }


Slicing
~~~~~~~

:Cocoa:
  .. parsed-literal::
     \- (void)\ **getCharacters:**\ (unichar \*)\ **buffer range:**\ (NSRange)aRange;

:Swift:
  .. parsed-literal::
    typealias IndexType = ...
    **subscript**\ (r: Range<IndexType>) -> Character

Indexing
~~~~~~~~

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)\ **substringToIndex:**\ (NSUInteger)to;
     \- (NSString \*)\ **substringFromIndex:**\ (NSUInteger)from;
     \- (NSString \*)\ **substringWithRange:**\ (NSRange)range;

:Swift:
  .. parsed-literal::
    **subscript**\ (range : Range<IndexType>) -> String

  .. _slicing:

  .. Admonition:: Example

    .. parsed-literal::
        s[beginning...ending] // [s substringWithRange: NSMakeRange(beginning, ending)]
        s[beginning...]       // [s substringFromIndex: beginning]
        s[...ending]          // [s substringToIndex: ending]

    :Note: Swift may need additional interfaces to support
           ``index...`` and ``...index`` notations.  This part of the
           ``Container`` protocol design isn't worked out yet.

Comparison

:Cocoa: .. parsed-literal:: - (BOOL)\ isEqualToString:\ (NSString *)aString; - (NSComparisonResult)\ compare:\ (NSString *)string;

:Swift: .. parsed-literal:: func == (lhs: String, rhs: String) -> Bool func != (lhs: String, rhs: String) -> Bool func < (lhs: String, rhs: String) -> Bool func > (lhs: String, rhs: String) -> Bool func <= (lhs: String, rhs: String) -> Bool func >= (lhs: String, rhs: String) -> Bool

NSString comparison is "literal" by default. As the documentation says of isEqualToString,

"Ö" represented as the composed character sequence "O" and umlaut would not compare equal to "Ö" represented as one Unicode character.

By contrast, Swift string's primary comparison interface uses Unicode's default collation_ algorithm, and is thus always "Unicode-correct." Unlike comparisons that depend on locale, it is also stable across changes in system state. However, just like NSString\ 's isEqualToString and compare methods, it should not be expected to yield ideal (or even "proper") results in all contexts.

:Cocoa: .. parsed-literal:: - (NSComparisonResult)\ compare:\ (NSString *)string \ options:\ (NSStringCompareOptions)mask; - (NSComparisonResult)\ compare:\ (NSString *)string \ options:\ (NSStringCompareOptions)mask \ range:\ (NSRange)compareRange; - (NSComparisonResult)\ caseInsensitiveCompare:\ (NSString *)string;

:Swift: various compositions of primitive operations / TBD_

As noted above__, instead of passing sub-range arguments, we expect Swift users to compose slicing_ with whole-string operations.

__ range_
Other details of these interfaces are distinguished by an NSStringCompareOptions mask, of which caseInsensitiveCompare: is essentially a special case:

:NSCaseInsensitiveSearch: Whether a direct interface is needed at all in Swift, and if so, its form, are TBD_. However, we should consider following the lead of Python 3, wherein case conversion also normalizes letterforms__. Then one can combine String.toLower() with default comparison to get a case-insensitive comparison::
```
 { $0.toLower() == $1.toLower() }
```
__ http://stackoverflow.com/a/11573384/125349

:NSLiteralSearch: Though it is the default for NSString, this option is essentially only useful as a performance optimization when the string content is known to meet certain restrictions (i.e. is known to be pure ASCII). When such optimization is absolutely necessary, Swift standard library algorithms can be used directly on the String\ 's UTF8 code units. However, Swift will also perform these optimizations automatically (at the cost of a single test/branch) in many cases, because each String stores a bit indicating whether its content is known to be ASCII.

:NSBackwardsSearch: It's unclear from the docs how this option interacts with other NSString options, if at all, but basic cases can be handled in Swift by s1.endsWith(s2).

:NSAnchoredSearch: Not applicable to whole-string comparisons :NSNumericSearch: While it's legitimate to defer this functionality to Cocoa, it's (probably--see rdar://problem/14724804) locale-independent and easy enough to implement in Swift. TBD_ :NSDiacriticInsensitiveSearch: Ditto; TBD_ :NSWidthInsensitiveSearch: Ditto; TBD_ :NSForcedOrderingSearch: Ditto; TBD_. Also see rdar://problem/14724888 :NSRegularExpressionSearch: We can defer this functionality to Cocoa, or dispatch directly to ICU as an optimization. It's unlikely that we'll be building Swift its own regexp engine for 1.0.

:Cocoa: .. parsed-literal:: - (NSComparisonResult)\ localizedCompare:\ (NSString *)string; - (NSComparisonResult)\ localizedCaseInsensitiveCompare:\ (NSString *)string; - (NSComparisonResult)\ localizedStandardCompare:\ (NSString *)string; - (NSComparisonResult)\ compare:\ (NSString *)string \ options:\ (NSStringCompareOptions)mask \ range:\ (NSRange)compareRange \ locale:\ (id)locale;

:Swift: As these all depend on locale, they are TBD_

Searching


.. Sidebar:: Rationale

   Modern languages (Java, C#, Python, Ruby...) have standardized on
   variants of ``startsWith``/\ ``endsWith``.  There's no reason Swift
   should deviate from de-facto industry standards here.

:Cocoa:
  .. parsed-literal::
     \- (BOOL)\ **hasPrefix:**\ (NSString \*)aString;
     \- (BOOL)\ **hasSuffix:**\ (NSString \*)aString;

:Swift:
  .. parsed-literal::
     func **startsWith**\ (_ prefix: String)
     func **endsWith**\ (_ suffix: String)

----

:Cocoa:
  .. parsed-literal::
     \- (NSRange)\ **rangeOfString:**\ (NSString \*)aString;

:Swift:
  .. parsed-literal::
       func **find**\ (_ sought: String) -> Range<String.IndexType>

  .. Note:: Most other languages provide something like
            ``s1.indexOf(s2)``, which returns only the starting index of
            the first match.  This is far less useful than the range of
            the match, and is always available via
            ``s1.find(s2).bounds.0``

----

:Cocoa:
  .. parsed-literal::
     \- (NSRange)\ **rangeOfCharacterFromSet:**\ (NSCharacterSet \*)aSet;

.. sidebar:: Naming

   The Swift function is just an algorithm that comes from conformance
   to the ``Container`` protocol, which explains why it doesn't have a
   ``String``\ -specific name.

:Swift:
  .. parsed-literal::
       func **find**\ (_ match: (Character) -> Bool) -> Range<String.IndexType>

  .. Admonition:: Usage Example

     The ``NSString`` semantics can be achieved as follows:

     .. parsed-literal::

        someString.find( {someCharSet.contains($0)} )

-----

:Cocoa:
  .. parsed-literal::
     \- (NSRange)\ **rangeOfString:**\ (NSString \*)aString \ **options:**\ (NSStringCompareOptions)mask;
     \- (NSRange)\ **rangeOfString:**\ (NSString \*)aString \ **options:**\ (NSStringCompareOptions)mask \ **range:**\ (NSRange)searchRange;
     \- (NSRange)\ **rangeOfString:**\ (NSString \*)aString \ **options:**\ (NSStringCompareOptions)mask \ **range:**\ (NSRange)searchRange \ **locale:**\ (NSLocale \*)locale;

     \- (NSRange)\ **rangeOfCharacterFromSet:**\ (NSCharacterSet \*)aSet \ **options:**\ (NSStringCompareOptions)mask;
     \- (NSRange)\ **rangeOfCharacterFromSet:**\ (NSCharacterSet \*)aSet \ **options:**\ (NSStringCompareOptions)mask \ **range:**\ (NSRange)searchRange;

  These functions

:Swift: *various compositions of primitive operations* / TBD_

Building
~~~~~~~~

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)\ **stringByAppendingString:**\ (NSString \*)aString;

.. sidebar:: ``append``

   the ``append`` method is a consequence of ``String``\ 's
   conformance to ``TextOutputStream``.  See the *Swift
   formatting proposal* for details.

:Swift:
  .. parsed-literal::
        func **+** (lhs: String, rhs: String) -> String
        func [infix, assignment] **+=** (lhs: [inout] String, rhs: String)
        func **append**\ (_ suffix: String)


Dynamic Formatting

:Cocoa: .. parsed-literal:: - (NSString *)\ stringByAppendingFormat:\ (NSString *)format, ... NS_FORMAT_FUNCTION(1,2);

:Swift: Not directly provided\ --see the Swift formatting proposal

Extracting Numeric Values


:Cocoa:
  .. parsed-literal::
     \- (double)doubleValue;
     \- (float)floatValue;
     \- (int)intValue;
     \- (NSInteger)integerValue;
     \- (long long)longLongValue;
     \- (BOOL)boolValue;

:Swift: Not in ``String``\ --It is up to other types to provide their
   conversions to and from String.  See also this `rationale`__

   __ extending_

Splitting
~~~~~~~~~

:Cocoa:
  .. parsed-literal::
     \- (NSArray \*)\ **componentsSeparatedByString:**\ (NSString \*)separator;
     \- (NSArray \*)\ **componentsSeparatedByCharactersInSet:**\ (NSCharacterSet \*)separator;

:Swift:
  .. parsed-literal::
     func split(_ maxSplit: Int = Int.max()) -> [String]
     func split(_ separator: Character, maxSplit: Int = Int.max()) -> [String]

  The semantics of these functions were taken from Python, which seems
  to be a fairly good representative of what modern languages are
  currently doing.  The first overload splits on all whitespace
  characters; the second only on specific characters.  The universe of
  possible splitting functions is quite broad, so the particulars of
  this interface are **wide open for discussion**.  In Swift right
  now, these methods (on ``CodePoints``) are implemented in terms of a
  generic algorithm:

  .. parsed-literal::

    func **split**\ <Seq: Sliceable, IsSeparator: Predicate
        where IsSeparator.Arguments == Seq.Element
    >(_ seq: Seq, isSeparator: IsSeparator, maxSplit: Int = Int.max(),
      allowEmptySlices: Bool = false) -> [Seq]

Splitting
~~~~~~~~~

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)\ **commonPrefixWithString:**\ (NSString \*)aString \ **options:**\ (NSStringCompareOptions)mask;

:Swift:
  .. parsed-literal::
     func **commonPrefix**\ (_ other: String) -> String

Upper/Lowercase
~~~~~~~~~~~~~~~

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)\ **uppercaseString**;
     \- (NSString \*)\ **uppercaseStringWithLocale:**\ (NSLocale \*)locale;
     \- (NSString \*)\ **lowercaseString**;
     \- (NSString \*)\ **lowercaseStringWithLocale:**\ (NSLocale \*)locale;

.. sidebar:: Naming

   Other languages have overwhelmingly settled on ``upper()`` or
   ``toUpper()`` for this functionality

:Swift:
  .. parsed-literal::
     func **toUpper**\ () -> String
     func **toLower**\ () -> String

Capitalization
~~~~~~~~~~~~~~

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)\ **capitalizedString**;
     \- (NSString \*)\ **capitalizedStringWithLocale:**\ (NSLocale \*)locale;

:Swift:
  **TBD**

.. Note:: ``NSString`` capitalizes the first letter of each substring
          separated by spaces, tabs, or line terminators, which is in
          no sense "Unicode-correct."  In most other languages that
          support a ``capitalize`` method, it operates only on the
          first character of the string, and capitalization-by-word is
          named something like "``title``."  If Swift ``String``
          supports capitalization by word, it should be
          Unicode-correct, but how we sort this particular area out is
          still **TBD**.

---------

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)\ **stringByTrimmingCharactersInSet:**\ (NSCharacterSet \*)set;

:Swift:
  .. parsed-literal::
       trim **trim**\ (match: (Character) -> Bool) -> String

  .. Admonition:: Usage Example

     The ``NSString`` semantics can be achieved as follows:

     .. parsed-literal::

        someString.trim( {someCharSet.contains($0)} )

---------

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)\ **stringByPaddingToLength:**\ (NSUInteger)newLength \ **withString:**\ (NSString \*)padString \ **startingAtIndex:**\ (NSUInteger)padIndex;

:Swift:
  .. parsed-literal:: *Not provided*.  It's not clear whether this is
                      useful at all for non-ASCII strings, and

---------

:Cocoa:
  .. parsed-literal::
     \- (void)\ **getLineStart:**\ (NSUInteger \*)startPtr \ **end:**\ (NSUInteger \*)lineEndPtr \ **contentsEnd:**\ (NSUInteger \*)contentsEndPtr \ **forRange:**\ (NSRange)range;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSRange)\ **lineRangeForRange:**\ (NSRange)range;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (void)\ **getParagraphStart:**\ (NSUInteger \*)startPtr \ **end:**\ (NSUInteger \*)parEndPtr \ **contentsEnd:**\ (NSUInteger \*)contentsEndPtr \ **forRange:**\ (NSRange)range;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSRange)\ **paragraphRangeForRange:**\ (NSRange)range;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (void)\ **enumerateSubstringsInRange:**\ (NSRange)range \ **options:**\ (NSStringEnumerationOptions)opts \ **usingBlock:**\ (void (^)(NSString \*substring, NSRange substringRange, NSRange enclosingRange, BOOL \*stop))block;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (void)\ **enumerateLinesUsingBlock:**\ (void (^)(NSString \*line, BOOL \*stop))block;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)description;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSUInteger)hash;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSStringEncoding)fastestEncoding;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSStringEncoding)smallestEncoding;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSData \*)\ **dataUsingEncoding:**\ (NSStringEncoding)encoding \ **allowLossyConversion:**\ (BOOL)lossy;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSData \*)\ **dataUsingEncoding:**\ (NSStringEncoding)encoding;

:Swift:
  .. parsed-literal::
        **TBD**

- (BOOL)\ **canBeConvertedToEncoding:**\ (NSStringEncoding)encoding;


---------

:Cocoa:
  .. parsed-literal::
     \- (__strong const char \*)\ **cStringUsingEncoding:**\ (NSStringEncoding)encoding NS_RETURNS_INNER_POINTER;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (BOOL)\ **getCString:**\ (char \*)buffer \ **maxLength:**\ (NSUInteger)maxBufferCount \ **encoding:**\ (NSStringEncoding)encoding;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (BOOL)\ **getBytes:**\ (void \*)buffer \ **maxLength:**\ (NSUInteger)maxBufferCount \ **usedLength:**\ (NSUInteger \*)usedBufferCount \ **encoding:**\ (NSStringEncoding)encoding \ **options:**\ (NSStringEncodingConversionOptions)options \ **range:**\ (NSRange)range \ **remainingRange:**\ (NSRangePointer)leftover;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSUInteger)\ **maximumLengthOfBytesUsingEncoding:**\ (NSStringEncoding)enc;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSUInteger)\ **lengthOfBytesUsingEncoding:**\ (NSStringEncoding)enc;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)decomposedStringWithCanonicalMapping;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)precomposedStringWithCanonicalMapping;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)decomposedStringWithCompatibilityMapping;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)precomposedStringWithCompatibilityMapping;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)\ **stringByFoldingWithOptions:**\ (NSStringCompareOptions)options \ **locale:**\ (NSLocale \*)locale;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)\ **stringByReplacingOccurrencesOfString:**\ (NSString \*)target \ **withString:**\ (NSString \*)replacement \ **options:**\ (NSStringCompareOptions)options \ **range:**\ (NSRange)searchRange;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)\ **stringByReplacingOccurrencesOfString:**\ (NSString \*)target \ **withString:**\ (NSString \*)replacement;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (NSString \*)\ **stringByReplacingCharactersInRange:**\ (NSRange)range \ **withString:**\ (NSString \*)replacement;


---------

:Cocoa:
  .. parsed-literal::
     \- (__strong const char \*)UTF8String NS_RETURNS_INNER_POINTER;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \+ (NSStringEncoding)defaultCStringEncoding;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \+ (const NSStringEncoding \*)availableStringEncodings;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \+ (NSString \*)\ **localizedNameOfStringEncoding:**\ (NSStringEncoding)encoding;

Constructors
~~~~~~~~~~~~

:Cocoa:
  .. parsed-literal::
     \- (instancetype)init;

---------

:Cocoa:
  .. parsed-literal::
     \- (instancetype)\ **initWithString:**\ (NSString \*)aString;

---------

:Cocoa:
  .. parsed-literal::
    \+ (instancetype)string;

---------

:Cocoa:
  .. parsed-literal::
    \+ (instancetype)\ **stringWithString:**\ (NSString \*)string;

Not available (too error prone)

---------

:Cocoa:
  .. parsed-literal::
     \- (instancetype)\ **initWithCharactersNoCopy:**\ (unichar \*)characters \ **length:**\ (NSUInteger)length \ **freeWhenDone:**\ (BOOL)freeBuffer;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (instancetype)\ **initWithCharacters:**\ (const unichar \*)characters \ **length:**\ (NSUInteger)length;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (instancetype)\ **initWithUTF8String:**\ (const char \*)nullTerminatedCString;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (instancetype)\ **initWithFormat:**\ (NSString \*)format, ... NS_FORMAT_FUNCTION(1,2);

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (instancetype)\ **initWithFormat:**\ (NSString \*)format \ **arguments:**\ (va_list)argList NS_FORMAT_FUNCTION(1,0);

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (instancetype)\ **initWithFormat:**\ (NSString \*)format \ **locale:**\ (id)locale, ... NS_FORMAT_FUNCTION(1,3);

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (instancetype)\ **initWithFormat:**\ (NSString \*)format \ **locale:**\ (id)locale \ **arguments:**\ (va_list)argList NS_FORMAT_FUNCTION(1,0);

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (instancetype)\ **initWithData:**\ (NSData \*)data \ **encoding:**\ (NSStringEncoding)encoding;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (instancetype)\ **initWithBytes:**\ (const void \*)bytes \ **length:**\ (NSUInteger)len \ **encoding:**\ (NSStringEncoding)encoding;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (instancetype)\ **initWithBytesNoCopy:**\ (void \*)bytes \ **length:**\ (NSUInteger)len \ **encoding:**\ (NSStringEncoding)encoding \ **freeWhenDone:**\ (BOOL)freeBuffer;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \+ (instancetype)\ **stringWithCharacters:**\ (const unichar \*)characters \ **length:**\ (NSUInteger)length;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \+ (instancetype)\ **stringWithUTF8String:**\ (const char \*)nullTerminatedCString;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \+ (instancetype)\ **stringWithFormat:**\ (NSString \*)format, ... NS_FORMAT_FUNCTION(1,2);

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \+ (instancetype)\ **localizedStringWithFormat:**\ (NSString \*)format, ... NS_FORMAT_FUNCTION(1,2);

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \- (instancetype)\ **initWithCString:**\ (const char \*)nullTerminatedCString \ **encoding:**\ (NSStringEncoding)encoding;

:Swift:
  .. parsed-literal::
        **TBD**

---------

:Cocoa:
  .. parsed-literal::
     \+ (instancetype)\ **stringWithCString:**\ (const char \*)cString \ **encoding:**\ (NSStringEncoding)enc;


Linguistic Analysis
~~~~~~~~~~~~~~~~~~~

:Cocoa:
  .. parsed-literal::
     \- (NSArray \*)\ **linguisticTagsInRange:**\ (NSRange)range \ **scheme:**\ (NSString \*)tagScheme \ **options:**\ (NSLinguisticTaggerOptions)opts \ **orthography:**\ (NSOrthography \*)orthography \ **tokenRanges:**\ (NSArray \*\*)tokenRanges;
     \- (void)\ **enumerateLinguisticTagsInRange:**\ (NSRange)range \ **scheme:**\ (NSString \*)tagScheme \ **options:**\ (NSLinguisticTaggerOptions)opts \ **orthography:**\ (NSOrthography \*)orthography \ **usingBlock:**\ (void (^)(NSString \*tag, NSRange tokenRange, NSRange sentenceRange, BOOL \*stop))block;

:Swift:
  .. parsed-literal::
        **TBD**

Unavailable on Swift Strings
----------------------------

URL Handling
~~~~~~~~~~~~

.. parsed-literal::

    \- (instancetype)\ **initWithContentsOfURL:**\ (NSURL \*)url \ **encoding:**\ (NSStringEncoding)enc \ **error:**\ (NSError \*\*)error;
    \+ (instancetype)\ **stringWithContentsOfURL:**\ (NSURL \*)url \ **encoding:**\ (NSStringEncoding)enc \ **error:**\ (NSError \*\*)error;
    \- (instancetype)\ **initWithContentsOfURL:**\ (NSURL \*)url \ **usedEncoding:**\ (NSStringEncoding \*)enc \ **error:**\ (NSError \*\*)error;
    \+ (instancetype)\ **stringWithContentsOfURL:**\ (NSURL \*)url \ **usedEncoding:**\ (NSStringEncoding \*)enc \ **error:**\ (NSError \*\*)error;
    \- (BOOL)\ **writeToURL:**\ (NSURL \*)url \ **atomically:**\ (BOOL)useAuxiliaryFile \ **encoding:**\ (NSStringEncoding)enc \ **error:**\ (NSError \*\*)error;
    \- (NSString \*)\ **stringByAddingPercentEncodingWithAllowedCharacters:**\ (NSCharacterSet \*)allowedCharacters;
    \- (NSString \*)stringByRemovingPercentEncoding;
    \- (NSString \*)\ **stringByAddingPercentEscapesUsingEncoding:**\ (NSStringEncoding)enc;
    \- (NSString \*)\ **stringByReplacingPercentEscapesUsingEncoding:**\ (NSStringEncoding)enc;

See: class File

.. parsed-literal::

    \- (instancetype)\ **initWithContentsOfFile:**\ (NSString \*)path \ **encoding:**\ (NSStringEncoding)enc \ **error:**\ (NSError \*\*)error;
    \+ (instancetype)\ **stringWithContentsOfFile:**\ (NSString \*)path \ **encoding:**\ (NSStringEncoding)enc \ **error:**\ (NSError \*\*)error;
    \- (instancetype)\ **initWithContentsOfFile:**\ (NSString \*)path \ **usedEncoding:**\ (NSStringEncoding \*)enc \ **error:**\ (NSError \*\*)error;
    \+ (instancetype)\ **stringWithContentsOfFile:**\ (NSString \*)path \ **usedEncoding:**\ (NSStringEncoding \*)enc \ **error:**\ (NSError \*\*)error;
    \- (BOOL)\ **writeToFile:**\ (NSString \*)path \ **atomically:**\ (BOOL)useAuxiliaryFile \ **encoding:**\ (NSStringEncoding)enc \ **error:**\ (NSError \*\*)error;

Path Handling
~~~~~~~~~~~~~

.. parsed-literal::

    \+ (NSString \*)\ **pathWithComponents:**\ (NSArray \*)components;
    \- (NSArray \*)pathComponents;
    \- (BOOL)isAbsolutePath;
    \- (NSString \*)lastPathComponent;
    \- (NSString \*)stringByDeletingLastPathComponent;
    \- (NSString \*)\ **stringByAppendingPathComponent:**\ (NSString \*)str;
    \- (NSString \*)pathExtension;
    \- (NSString \*)stringByDeletingPathExtension;
    \- (NSString \*)\ **stringByAppendingPathExtension:**\ (NSString \*)str;
    \- (NSString \*)stringByAbbreviatingWithTildeInPath;
    \- (NSString \*)stringByExpandingTildeInPath;
    \- (NSString \*)stringByStandardizingPath;
    \- (NSString \*)stringByResolvingSymlinksInPath;
    \- (NSArray \*)\ **stringsByAppendingPaths:**\ (NSArray \*)paths;
    \- (NSUInteger)\ **completePathIntoString:**\ (NSString \*\*)outputName \ **caseSensitive:**\ (BOOL)flag \ **matchesIntoArray:**\ (NSArray \*\*)outputArray \ **filterTypes:**\ (NSArray \*)filterTypes;
    \- (__strong const char \*)fileSystemRepresentation NS_RETURNS_INNER_POINTER;
    \- (BOOL)\ **getFileSystemRepresentation:**\ (char \*)cname \ **maxLength:**\ (NSUInteger)max;

Property Lists
~~~~~~~~~~~~~~

Property lists are a feature of Cocoa.

.. parsed-literal::

    \- (id)propertyList;
    \- (NSDictionary \*)propertyListFromStringsFileFormat;
    Not applicable. Swift does not provide GUI support.

    \- (NSSize)\ **sizeWithAttributes:**\ (NSDictionary \*)attrs;
    \- (void)\ **drawAtPoint:**\ (NSPoint)point \ **withAttributes:**\ (NSDictionary \*)attrs;
    \- (void)\ **drawInRect:**\ (NSRect)rect \ **withAttributes:**\ (NSDictionary \*)attrs;
    \- (void)\ **drawWithRect:**\ (NSRect)rect \ **options:**\ (NSStringDrawingOptions)options \ **attributes:**\ (NSDictionary \*)attributes;
    \- (NSRect)\ **boundingRectWithSize:**\ (NSSize)size \ **options:**\ (NSStringDrawingOptions)options \ **attributes:**\ (NSDictionary \*)attributes;
    \- (NSArray \*)\ **writableTypesForPasteboard:**\ (NSPasteboard \*)pasteboard;
    \- (NSPasteboardWritingOptions)\ **writingOptionsForType:**\ (NSString \*)type \ **pasteboard:**\ (NSPasteboard \*)pasteboard;
    \- (id)\ **pasteboardPropertyListForType:**\ (NSString \*)type;
    \+ (NSArray \*)\ **readableTypesForPasteboard:**\ (NSPasteboard \*)pasteboard;
    \+ (NSPasteboardReadingOptions)\ **readingOptionsForType:**\ (NSString \*)type \ **pasteboard:**\ (NSPasteboard \*)pasteboard;
    \- (id)\ **initWithPasteboardPropertyList:**\ (id)propertyList \ **ofType:**\ (NSString \*)type;

Deprecated APIs
~~~~~~~~~~~~~~~

Already deprecated in Cocoa.

.. parsed-literal::

    \- (const char \*)cString;
    \- (const char \*)lossyCString;
    \- (NSUInteger)cStringLength;
    \- (void)\ **getCString:**\ (char \*)bytes;
    \- (void)\ **getCString:**\ (char \*)bytes \ **maxLength:**\ (NSUInteger)maxLength;
    \- (void)\ **getCString:**\ (char \*)bytes \ **maxLength:**\ (NSUInteger)maxLength \ **range:**\ (NSRange)aRange \ **remainingRange:**\ (NSRangePointer)leftoverRange;
    \- (BOOL)\ **writeToFile:**\ (NSString \*)path \ **atomically:**\ (BOOL)useAuxiliaryFile;
    \- (BOOL)\ **writeToURL:**\ (NSURL \*)url \ **atomically:**\ (BOOL)atomically;
    \- (id)\ **initWithContentsOfFile:**\ (NSString \*)path;
    \- (id)\ **initWithContentsOfURL:**\ (NSURL \*)url;
    \+ (id)\ **stringWithContentsOfFile:**\ (NSString \*)path;
    \+ (id)\ **stringWithContentsOfURL:**\ (NSURL \*)url;
    \- (id)\ **initWithCStringNoCopy:**\ (char \*)bytes \ **length:**\ (NSUInteger)length \ **freeWhenDone:**\ (BOOL)freeBuffer;
    \- (id)\ **initWithCString:**\ (const char \*)bytes \ **length:**\ (NSUInteger)length;
    \- (id)\ **initWithCString:**\ (const char \*)bytes;
    \+ (id)\ **stringWithCString:**\ (const char \*)bytes \ **length:**\ (NSUInteger)length;
    \+ (id)\ **stringWithCString:**\ (const char \*)bytes;
    \- (void)\ **getCharacters:**\ (unichar \*)buffer;


--------------

Why YAGNI
---------

* Retroactive Modeling
* Derivation
* ...

.. [#agnostic] Unicode specifies default ("un-tailored")
   locale-independent collation_ and segmentation_ algorithms that
   make reasonable sense in most contexts.  Using these algorithms
   allows strings to be naturally compared and combined, generating
   the expected results when the content is ASCII

.. [#canonical] Technically, ``==`` checks for `Unicode canonical
                equivalence`__

                __ http://www.unicode.org/reports/tr15/tr15-18.html#Introduction

.. [#locales] We have some specific ideas for locale-sensitive
              interfaces, but details are still TBD and wide open for
              discussion.

.. [#re_sort] Collections that automatically re-sort based on locale
   changes are out of scope for the core Swift language

.. [#char] The type currently called ``Char`` in Swift represents a
   Unicode code point.  This document refers to it as ``CodePoint``,
   in anticipation of renaming.


.. _segmentation: http://www.unicode.org/reports/tr29/#GB1

.. _collation: http://www.unicode.org/reports/tr10/


.. [#code_points] When the user writes a string literal, she
   specifies a particular sequence of code points.  We guarantee that
   those code points are stored without change in the resulting
   ``String``.  The user can explicitly request normalization, and
   Swift can use a bit to remember whether a given string buffer has
   been normalized, thus speeding up comparison operations.

.. [#elements] Since ``String`` is locale-agnostic_, its elements are
   determined using Unicode's default, "un-tailored" segmentation_
   algorithm.

Swift String Design

=================== Swift String Design

Introduction

Goals

Non-Goals

Overview By Example

String is a First-Class Type__

Strings are Efficient

Strings are Mutable

Strings are Value Types

Strings are Unicode-Aware

Strings are Locale-Agnostic

Strings are Containers

Strings are Composed of Character\ s

Strings Support Flexible Segmentation

Strings are Sliceable

Strings are Encoded as UTF-8

Coming Installments

Reference Manual

Cocoa Bridging Strategy

Rationales

Why a Built-In String Type?

How Would You Design It?

Comparisons with NSString

High-Level Comparison with NSString

`String` is a `First-Class Type`__

Strings are Composed of `Character`\ s

Comparisons with `NSString`

High-Level Comparison with `NSString`