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

//===--- CollectionAlgorithms.swift.gyb -----------------------------------===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2014 - 2015 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
//
//===----------------------------------------------------------------------===//

%{

# We know we will eventually get a SequenceType.Element type.  Define
# a shorthand that we can use today.
GElement = "Generator.Element"

}%

//===----------------------------------------------------------------------===//
// last
//===----------------------------------------------------------------------===//

extension CollectionType where Index : BidirectionalIndexType {
  final public var last: Generator.Element? {
    return isEmpty ? nil : self[endIndex.predecessor()]
  }
}

//===----------------------------------------------------------------------===//
// find()
//===----------------------------------------------------------------------===//

extension CollectionType where ${GElement} : Equatable {
  /// Returns the first index where `value` appears in `self` or `nil` if
  /// `value` is not found.
  ///
  /// - Complexity: O(`self.count()`).
  final public func indexOf(element: ${GElement}) -> Index? {
    if let result = _customIndexOfEquatableElement(element) {
      return result
    }

    for i in self.indices {
      if self[i] == element {
        return i
      }
    }
    return nil
  }
}

extension CollectionType {
  /// Returns the first index where `predicate` returns `true` for the
  /// corresponding value, or `nil` if such value is not found.
  ///
  /// - Complexity: O(`self.count()`).
  final public func indexOf(
    @noescape predicate: (${GElement}) -> Bool
  ) -> Index? {
    for i in self.indices {
      if predicate(self[i]) {
        return i
      }
    }
    return nil
  }
}

//===----------------------------------------------------------------------===//
// indices
//===----------------------------------------------------------------------===//

extension CollectionType {
  /// Return the range of valid index values.
  ///
  /// The result's `endIndex` is the same as that of `self`.  Because
  /// `Range` is half-open, iterating the values of the result produces
  /// all valid subscript arguments for `self`, omitting its `endIndex`.
  final public var indices: Range<Index> {
    return Range(start: startIndex, end: endIndex)
  }
}

//===----------------------------------------------------------------------===//
// MutableCollectionType
//===----------------------------------------------------------------------===//

//===----------------------------------------------------------------------===//
// partition()
//===----------------------------------------------------------------------===//

%{

partitionDocComment = """\
  /// Re-order the given `range` of elements in `self` and return
  /// a pivot index *p*.
  ///
  /// - Postcondition: for all *i* in `range.startIndex..<`\ *p*, and *j*
  ///   in *p*\ `..<range.endIndex`, `less(self[`\ *i*\ `],
  ///   self[`\ *j*\ `]) && !less(self[`\ *j*\ `], self[`\ *p*\ `])`.
  ///   Only returns `range.endIndex` when `self` is empty."""

orderingRequirementForPredicate = """\
  /// - Requires: `isOrderedBefore` is a
  ///   [strict weak ordering](http://en.wikipedia.org/wiki/Strict_weak_order#Strict_weak_orderings)
  ///   over the elements in `self`."""

orderingRequirementForComparable = """\
  /// - Requires: The less-than operator (`func <`) defined in
  ///   the `Comparable` conformance is a
  ///   [strict weak ordering](http://en.wikipedia.org/wiki/Strict_weak_order#Strict_weak_orderings)
  ///   over the elements in `self`."""

}%

extension MutableCollectionType
  where Index : RandomAccessIndexType, ${GElement} : Comparable {

${partitionDocComment}
  ///
${orderingRequirementForComparable}
  final public mutating func _prext_partition(range: Range<Index>) -> Index {
    return _partition(&self, range)
  }
}

extension MutableCollectionType where Index : RandomAccessIndexType {

${partitionDocComment}
  ///
${orderingRequirementForPredicate}
  final public mutating func _prext_partition(
    range: Range<Index>,
    var isOrderedBefore: (${GElement}, ${GElement}) -> Bool
  ) -> Index {
    return _partition(&self, range, &isOrderedBefore)
  }
}

//===----------------------------------------------------------------------===//
// sort()
//===----------------------------------------------------------------------===//

%{

sortDocCommentForPredicate = """\
  /// Return an `Array` containing the sorted elements of `source`
  /// according to `isOrderedBefore`."""

sortDocCommentForComparable = """\
  /// Return an `Array` containing the sorted elements of `source`."""

sortInPlaceDocCommentForPredicate = """\
  /// Sort `self` in-place according to `isOrderedBefore`."""

sortInPlaceDocCommentForComparable = """\
  /// Sort `self` in-place."""

sortIsUnstableForPredicate = """\
  /// The sorting algorithm is not stable (can change the relative order of
  /// elements for which `isOrderedBefore` does not establish an order)."""

sortIsUnstableForComparable = """\
  /// The sorting algorithm is not stable (can change the relative order of
  /// elements that compare equal)."""

}%

extension SequenceType where Self.Generator.Element : Comparable {
${sortDocCommentForComparable}
  ///
${sortIsUnstableForComparable}
  ///
${orderingRequirementForComparable}
  final public func _prext_sort() -> [Generator.Element] {
    var result = ContiguousArray(self)
    result._prext_sortInPlace()
    return Array(result)
  }
}

extension SequenceType {
${sortDocCommentForPredicate}
  ///
${sortIsUnstableForPredicate}
  ///
${orderingRequirementForPredicate}
  final public func _prext_sort(
    isOrderedBefore: (Generator.Element, Generator.Element) -> Bool
  ) -> [Generator.Element] {
    var result = ContiguousArray(self)
    result._prext_sortInPlace(isOrderedBefore)
    return Array(result)
  }
}

extension MutableCollectionType
  where
  Self.Index : RandomAccessIndexType,
  Self.Generator.Element : Comparable {

${sortInPlaceDocCommentForComparable}
  ///
${sortIsUnstableForComparable}
  ///
${orderingRequirementForComparable}
  final public mutating func _prext_sortInPlace() {
    let didSortUnsafeBuffer: Void? =
      _withUnsafeMutableBufferPointerIfSupported {
      (bufferPointer) -> () in
      bufferPointer._prext_sortInPlace()
      return ()
    }
    if didSortUnsafeBuffer == nil {
      _introSort(&self, self.indices)
    }
  }
}

extension MutableCollectionType where Self.Index : RandomAccessIndexType {
${sortInPlaceDocCommentForPredicate}
  ///
${sortIsUnstableForPredicate}
  ///
${orderingRequirementForPredicate}
  final public mutating func _prext_sortInPlace(
    isOrderedBefore: (Generator.Element, Generator.Element) -> Bool
  ) {
    let didSortUnsafeBuffer: Void? =
      _withUnsafeMutableBufferPointerIfSupported {
      (bufferPointer) -> () in
      bufferPointer._prext_sortInPlace(isOrderedBefore)
      return ()
    }
    if didSortUnsafeBuffer == nil {
      typealias IsOrderedBefore =
        (Generator.Element, Generator.Element) -> Bool
      _introSort(&self, self.indices, isOrderedBefore)
    }
  }
}