swift-mirror/stdlib/public/core/UnavailableStringAPIs.swift.gyb

//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2014 - 2016 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
  /// The unavailable `String.count` API.
  ///
  /// The concept of "the number of characters 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`
  /// does not have a `count` property, since there is no universal
  /// answer to the question about the number of characters in a
  /// given string.
  ///
  /// Swift provides several different ways to access the character
  /// data stored inside strings.  To access the number of data units
  /// in each representation you can use the following APIs.
  ///
  /// - `String.utf8.count` property returns the number 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.count` property returns the number of UTF-16
  ///   code units in the 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.count` property returns the number of
  ///   Unicode scalars in the string.  Use this API when you are
  ///   performing low-level manipulation of character data.
  ///
  /// - `String.characters.count` property returns the number of
  ///   extended grapheme clusters.  Use this API to count the
  ///   number of user-perceived characters in the string.
  @available(
    *, unavailable,
    message: "there is no universally good answer, see the documentation comment for discussion")
  public var count: Int {
    Builtin.unreachable()
  }
}

% 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