| //===----------------------------------------------------------------------===// |
| // |
| // This source file is part of the Swift.org open source project |
| // |
| // Copyright (c) 2014 - 2017 Apple Inc. and the Swift project authors |
| // Licensed under Apache License v2.0 with Runtime Library Exception |
| // |
| // See https://swift.org/LICENSE.txt for license information |
| // See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors |
| // |
| //===----------------------------------------------------------------------===// |
| |
| %{ |
| stringSubscriptComment = """ |
| /// Subscripting strings with integers is not available. |
| /// |
| /// The concept of "the `i`th character in a string" has |
| /// different interpretations in different libraries and system |
| /// components. The correct interpretation should be selected |
| /// according to the use case and the APIs involved, so `String` |
| /// cannot be subscripted with an integer. |
| /// |
| /// Swift provides several different ways to access the character |
| /// data stored inside strings. |
| /// |
| /// - `String.utf8` is a collection of UTF-8 code units in the |
| /// string. Use this API when converting the string to UTF-8. |
| /// Most POSIX APIs process strings in terms of UTF-8 code units. |
| /// |
| /// - `String.utf16` is a collection of UTF-16 code units in |
| /// string. Most Cocoa and Cocoa touch APIs process strings in |
| /// terms of UTF-16 code units. For example, instances of |
| /// `NSRange` used with `NSAttributedString` and |
| /// `NSRegularExpression` store substring offsets and lengths in |
| /// terms of UTF-16 code units. |
| /// |
| /// - `String.unicodeScalars` is a collection of Unicode scalars. |
| /// Use this API when you are performing low-level manipulation |
| /// of character data. |
| /// |
| /// - `String.characters` is a collection of extended grapheme |
| /// clusters, which are an approximation of user-perceived |
| /// characters. |
| /// |
| /// Note that when processing strings that contain human-readable |
| /// text, character-by-character processing should be avoided to |
| /// the largest extent possible. Use high-level locale-sensitive |
| /// Unicode algorithms instead, for example, |
| /// `String.localizedStandardCompare()`, |
| /// `String.localizedLowercaseString`, |
| /// `String.localizedStandardRangeOfString()` etc.""" |
| }% |
| |
| extension String { |
| ${stringSubscriptComment} |
| @available( |
| *, unavailable, |
| message: "cannot subscript String with an Int, see the documentation comment for discussion") |
| public subscript(i: Int) -> Character { |
| Builtin.unreachable() |
| } |
| |
| % for Range in 'Range', 'ClosedRange', 'CountableRange', 'CountableClosedRange': |
| ${stringSubscriptComment} |
| @available( |
| *, unavailable, |
| message: "cannot subscript String with a ${Range}<Int>, see the documentation comment for discussion") |
| public subscript(bounds: ${Range}<Int>) -> String { |
| Builtin.unreachable() |
| } |
| % end |
| } |
| |
| % for View in ['UTF8View', 'UTF16View', 'UnicodeScalarView', 'CharacterView']: |
| % Index = 'String.%s.Index' % View |
| % Distance = 'String.%s.IndexDistance' % View |
| extension ${Index} { |
| @available( |
| *, unavailable, |
| message: "To get the next index call 'index(after:)' on the ${View} instance that produced the index.") |
| public func successor() -> ${Index} { |
| Builtin.unreachable() |
| } |
| % if View != 'UTF8View': |
| @available( |
| *, unavailable, |
| message: "To get the previous index call 'index(before:)' on the ${View} instance that produced the index.") |
| public func predecessor() -> ${Index} { |
| Builtin.unreachable() |
| } |
| % end |
| @available( |
| *, unavailable, |
| message: "To advance an index by n steps call 'index(_:offsetBy:)' on the ${View} instance that produced the index.") |
| public func advancedBy(_ n: ${Distance}) -> ${Index} { |
| Builtin.unreachable() |
| } |
| @available( |
| *, unavailable, |
| message: "To advance an index by n steps stopping at a given limit call 'index(_:offsetBy:limitedBy:)' on ${View} instance that produced the index. Note that the Swift 3 API returns 'nil' when trying to advance past the limit; the Swift 2 API returned the limit.") |
| public func advancedBy(_ n: ${Distance}, limit: ${Index}) -> ${Index} { |
| Builtin.unreachable() |
| } |
| @available( |
| *, unavailable, |
| message: "To find the distance between two indices call 'distance(from:to:)' on the ${View} instance that produced the index.") |
| public func distanceTo(_ end: ${Index}) -> ${Distance} { |
| Builtin.unreachable() |
| } |
| } |
| % end |
| |