stdlib/public/core/UnavailableStringAPIs.swift.gyb

//===----------------------------------------------------------------------===//
//
// 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