stdlib/public/core/Indices.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 http://swift.org/LICENSE.txt for license information
// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
//===----------------------------------------------------------------------===//

%{
from gyb_stdlib_support import (
    TRAVERSALS,
    collectionForTraversal,
    defaultIndicesForTraversal,
    documentationNameForTraversal
)
}%

% for Traversal in TRAVERSALS:
%   Self = defaultIndicesForTraversal(Traversal)
%   collection = documentationNameForTraversal(Traversal)

// FIXME(ABI)(compiler limitation): There should be just one default
// indices type that has conditional conformances to
// `BidirectionalCollection` and `RandomAccessCollection`.

/// A collection of indices for an arbitrary ${collection}.
public struct ${Self}<
  Elements : ${collectionForTraversal(Traversal).replace('Collection', 'Indexable')}
  // FIXME(ABI)(compiler limitation):
  // Elements : Collection
> : ${collectionForTraversal(Traversal)} {

  // FIXME(compiler limitation): this typealias should be inferred.
  public typealias Index = Elements.Index

  internal init(
    _elements: Elements,
    startIndex: Elements.Index,
    endIndex: Elements.Index
  ) {
    self._elements = _elements
    self._startIndex = startIndex
    self._endIndex = endIndex
  }

  public var startIndex: Elements.Index {
    return _startIndex
  }

  public var endIndex: Elements.Index {
    return _endIndex
  }

  public subscript(i: Index) -> Elements.Index {
    // FIXME: swift-3-indexing-model: range check.
    return i
  }

  // FIXME(compiler limitation): this typealias should be inferred.
  public typealias SubSequence = ${Self}<Elements>

  public subscript(bounds: Range<Index>) -> ${Self}<Elements> {
    // FIXME: swift-3-indexing-model: range check.
    return ${Self}(
      _elements: _elements,
      startIndex: bounds.lowerBound,
      endIndex: bounds.upperBound)
  }

  public func index(after i: Index) -> Index {
    // FIXME: swift-3-indexing-model: range check.
    return _elements.index(after: i)
  }

  public func formIndex(after i: inout Index) {
    // FIXME: swift-3-indexing-model: range check.
    _elements.formIndex(after: &i)
  }

%     if Traversal in ['Bidirectional', 'RandomAccess']:
  public func index(before i: Index) -> Index {
    // FIXME: swift-3-indexing-model: range check.
    return _elements.index(before: i)
  }

  public func formIndex(before i: inout Index) {
    // FIXME: swift-3-indexing-model: range check.
    _elements.formIndex(before: &i)
  }
%     end

  // FIXME(compiler limitation): this typealias should be inferred.
  public typealias Indices = ${Self}<Elements>

  public var indices: Indices {
    return self
  }

  internal var _elements: Elements
  internal var _startIndex: Elements.Index
  internal var _endIndex: Elements.Index
}

extension ${collectionForTraversal(Traversal)} where Indices == ${Self}<Self> {
  /// The indices that are valid for subscripting the collection, in ascending
  /// order.
  ///
  /// A collection's `indices` property can hold a strong reference to the
  /// collection itself, causing the collection to be non-uniquely referenced.
  /// If you mutate the collection while iterating over its indices, a strong
  /// reference can cause an unexpected copy of the collection. To avoid the
  /// unexpected copy, use the `index(after:)` method starting with
  /// `startIndex` to produce indices instead.
  ///
  ///     var c = MyFancyCollection([10, 20, 30, 40, 50])
  ///     var i = c.startIndex
  ///     while i != c.endIndex {
  ///         c[i] /= 5
  ///         i = c.index(after: i)
  ///     }
  ///     // c == MyFancyCollection([2, 4, 6, 8, 10])
  public var indices: ${Self}<Self> {
    return ${Self}(
      _elements: self,
      startIndex: self.startIndex,
      endIndex: self.endIndex)
  }
}

% end

// ${'Local Variables'}:
// eval: (read-only-mode 1)
// End: