stdlib/public/core/UnsafeBufferPointer.swift.gyb - third_party/swift - Git at Google

 //===--- UnsafeBufferPointer.swift.gyb ------------------------*- swift -*-===//
 //
 // 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
 //
 //===----------------------------------------------------------------------===//

 /// An iterator for the elements in the buffer referenced by an
 /// `UnsafeBufferPointer` or `UnsafeMutableBufferPointer` instance.
 @_fixed_layout
 public struct UnsafeBufferPointerIterator<Element>
   : IteratorProtocol, Sequence {

   /// Advances to the next element and returns it, or `nil` if no next element
   /// exists.
   ///
   /// Once `nil` has been returned, all subsequent calls return `nil`.
   @_inlineable
   public mutating func next() -> Element? {
     if _position == _end { return nil }

     let result = _position!.pointee
     _position! += 1
     return result
   }

   @_versioned
   internal var _position, _end: UnsafePointer<Element>?

   @_inlineable
   public init(_position: UnsafePointer<Element>?, _end: UnsafePointer<Element>?) {
       self._position = _position
       self._end = _end
   }
 }

 % for mutable in (True, False):
 %  Self = 'UnsafeMutableBufferPointer' if mutable else 'UnsafeBufferPointer'
 %  Mutable = 'Mutable' if mutable else ''
 /// A nonowning collection interface to a buffer of ${Mutable.lower()}
 /// elements stored contiguously in memory.
 ///
 /// You can use an `${Self}` instance in low level operations to eliminate
 /// uniqueness checks and, in release mode, bounds checks. Bounds checks are
 /// always performed in debug mode.
 ///
 /// ${Self} Semantics
 /// =================
 ///
 /// An `${Self}` instance is a view into memory and does not own the memory
 /// that it references. Copying a value of type `${Self}` does not copy the
 /// instances stored in the underlying memory. However, initializing another
 /// collection with an `${Self}` instance copies the instances out of the
 /// referenced memory and into the new collection.
 @_fixed_layout
 public struct Unsafe${Mutable}BufferPointer<Element>
   : ${Mutable}Collection, RandomAccessCollection {
   // FIXME: rdar://18157434 - until this is fixed, this has to be fixed layout
   // to avoid a hang in Foundation, which has the following setup:
   // struct A { struct B { let x: UnsafeMutableBufferPointer<...> } let b: B }

   public typealias Index = Int
   public typealias Iterator = UnsafeBufferPointerIterator<Element>

   /// The index of the first element in a nonempty buffer.
   ///
   /// The `startIndex` property of an `Unsafe${Mutable}BufferPointer` instance
   /// is always zero.
   @_inlineable
   public var startIndex: Int {
     return 0
   }

   /// The "past the end" position---that is, the position one greater than the
   /// last valid subscript argument.
   ///
   /// The `endIndex` property of an `Unsafe${Mutable}BufferPointer` instance is
   /// always identical to `count`.
   @_inlineable
   public var endIndex: Int {
     return count
   }

   @_inlineable
   public func index(after i: Int) -> Int {
     // NOTE: this is a manual specialization of index movement for a Strideable
     // index that is required for UnsafeBufferPointer performance. The
     // optimizer is not capable of creating partial specializations yet.
     // NOTE: Range checks are not performed here, because it is done later by
     // the subscript function.
     return i + 1
   }

   @_inlineable
   public func formIndex(after i: inout Int) {
     // NOTE: this is a manual specialization of index movement for a Strideable
     // index that is required for UnsafeBufferPointer performance. The
     // optimizer is not capable of creating partial specializations yet.
     // NOTE: Range checks are not performed here, because it is done later by
     // the subscript function.
     i += 1
   }

   @_inlineable
   public func index(before i: Int) -> Int {
     // NOTE: this is a manual specialization of index movement for a Strideable
     // index that is required for UnsafeBufferPointer performance. The
     // optimizer is not capable of creating partial specializations yet.
     // NOTE: Range checks are not performed here, because it is done later by
     // the subscript function.
     return i - 1
   }

   @_inlineable
   public func formIndex(before i: inout Int) {
     // NOTE: this is a manual specialization of index movement for a Strideable
     // index that is required for UnsafeBufferPointer performance. The
     // optimizer is not capable of creating partial specializations yet.
     // NOTE: Range checks are not performed here, because it is done later by
     // the subscript function.
     i -= 1
   }

   @_inlineable
   public func index(_ i: Int, offsetBy n: Int) -> Int {
     // NOTE: this is a manual specialization of index movement for a Strideable
     // index that is required for UnsafeBufferPointer performance. The
     // optimizer is not capable of creating partial specializations yet.
     // NOTE: Range checks are not performed here, because it is done later by
     // the subscript function.
     return i + n
   }

   @_inlineable
   public func index(
     _ i: Int, offsetBy n: Int, limitedBy limit: Int
   ) -> Int? {
     // NOTE: this is a manual specialization of index movement for a Strideable
     // index that is required for UnsafeBufferPointer performance. The
     // optimizer is not capable of creating partial specializations yet.
     // NOTE: Range checks are not performed here, because it is done later by
     // the subscript function.
     let l = limit - i
     if n > 0 ? l >= 0 && l < n : l <= 0 && n < l {
       return nil
     }
     return i + n
   }

   @_inlineable
   public func distance(from start: Int, to end: Int) -> Int {
     // NOTE: this is a manual specialization of index movement for a Strideable
     // index that is required for UnsafeBufferPointer performance. The
     // optimizer is not capable of creating partial specializations yet.
     // NOTE: Range checks are not performed here, because it is done later by
     // the subscript function.
     return end - start
   }

   @_inlineable
   public func _failEarlyRangeCheck(_ index: Int, bounds: Range<Int>) {
     // NOTE: This method is a no-op for performance reasons.
   }

   @_inlineable
   public func _failEarlyRangeCheck(_ range: Range<Int>, bounds: Range<Int>) {
     // NOTE: This method is a no-op for performance reasons.
   }

   public typealias Indices = CountableRange<Int>

   @_inlineable
   public var indices: Indices {
     return startIndex..<endIndex
   }

   /// Initializes the memory at `destination.baseAddress` with elements of `self`,
   /// stopping when either `self` or `destination` is exhausted.
   ///
   /// - Returns: an iterator over any remaining elements of `self` and the
   ///   number of elements initialized.
   @_inlineable // FIXME(sil-serialize-all)
   public func _copyContents(
     initializing destination: UnsafeMutableBufferPointer<Element>
   ) -> (Iterator, UnsafeMutableBufferPointer<Element>.Index) {
     guard !isEmpty && !destination.isEmpty else { return (makeIterator(), 0) }
     let s = self.baseAddress._unsafelyUnwrappedUnchecked
     let d = destination.baseAddress._unsafelyUnwrappedUnchecked
     let n = Swift.min(destination.count, self.count)
     d.initialize(from: s, count: n)
     return (Iterator(_position: s + n, _end: _end), n)
   }

   /// Accesses the element at the specified position.
   ///
 %if Mutable:
   /// The following example uses the buffer pointer's subscript to access and
   /// modify the elements of a mutable buffer pointing to the contiguous
   /// contents of an array:
   ///
   ///     var numbers = [1, 2, 3, 4, 5]
   ///     numbers.withUnsafeMutableBufferPointer { buffer in
   ///         for i in stride(from: buffer.startIndex, to: buffer.endIndex - 1, by: 2) {
   ///             let x = buffer[i]
   ///             buffer[i + 1] = buffer[i]
   ///             buffer[i] = x
   ///         }
   ///     }
   ///     print(numbers)
   ///     // Prints "[2, 1, 4, 3, 5]"
 %else:
   /// The following example uses the buffer pointer's subscript to access every
   /// other element of the buffer:
   ///
   ///     let numbers = [1, 2, 3, 4, 5]
   ///     let sum = numbers.withUnsafeBufferPointer { buffer -> Int in
   ///         var result = 0
   ///         for i in stride(from: buffer.startIndex, to: buffer.endIndex, by: 2) {
   ///             result += buffer[i]
   ///         }
   ///         return result
   ///     }
   ///     // 'sum' == 9
 %end
   ///
   /// - Note: Bounds checks for `i` are performed only in debug mode.
   ///
   /// - Parameter i: The position of the element to access. `i` must be in the
   ///   range `0..<count`.
   @_inlineable
   public subscript(i: Int) -> Element {
     get {
       _debugPrecondition(i >= 0)
       _debugPrecondition(i < endIndex)
       return _position![i]
     }
 %if Mutable:
     nonmutating set {
       _debugPrecondition(i >= 0)
       _debugPrecondition(i < endIndex)
       _position![i] = newValue
     }
 %end
   }

   @_inlineable
   public subscript(bounds: Range<Int>)
     -> Slice<Unsafe${Mutable}BufferPointer<Element>>
   {
     get {
       _debugPrecondition(bounds.lowerBound >= startIndex)
       _debugPrecondition(bounds.upperBound <= endIndex)
       return Slice(
         base: self, bounds: bounds)
     }
 %  if Mutable:
     set {
       _debugPrecondition(bounds.lowerBound >= startIndex)
       _debugPrecondition(bounds.upperBound <= endIndex)
       // FIXME: swift-3-indexing-model: tests.
       _writeBackMutableSlice(&self, bounds: bounds, slice: newValue)
     }
 %  end
   }

   /// Creates a new buffer pointer over the specified number of contiguous
   /// instances beginning at the given pointer.
   ///
   /// - Parameters:
   ///   - start: A pointer to the start of the buffer, or `nil`. If `start` is
   ///     `nil`, `count` must be zero. However, `count` may be zero even for a
   ///     non-`nil` `start`. The pointer passed as `start` must be aligned to
   ///     `MemoryLayout<Element>.alignment`.
   ///   - count: The number of instances in the buffer. `count` must not be
   ///     negative.
   @_inlineable
   public init(start: Unsafe${Mutable}Pointer<Element>?, count: Int) {
     _precondition(
       count >= 0, "Unsafe${Mutable}BufferPointer with negative count")
     _precondition(
       count == 0 || start != nil,
       "Unsafe${Mutable}BufferPointer has a nil start and nonzero count")
     _position = start
     _end = start.map { $0 + count }
   }

   /// Creates a buffer pointer starting at `start` and extending up to the last
   /// addressable pointer to `Element` in the memory space
   @_inlineable
   public init(_unboundedStartingAt start: Unsafe${Mutable}Pointer<Element>) {
     _position = start
     _end = type(of: start)._max
   }

   @_inlineable
   public init(_empty: ()) {
     _position = Unsafe${Mutable}Pointer._max
     _end = _position
   }

 %  if Mutable:

   /// Creates a mutable typed buffer pointer referencing the same memory as the
   /// given immutable buffer pointer.
   ///
   /// - Parameter other: The immutable buffer pointer to convert.
   @_inlineable
   public init(mutating other: UnsafeBufferPointer<Element>) {
     _position = UnsafeMutablePointer<Element>(mutating: other._position)
     _end = UnsafeMutablePointer<Element>(mutating: other._end)
   }

 %  else:

   /// Creates an immutable typed buffer pointer referencing the same memory as the
   /// given mutable buffer pointer.
   ///
   /// - Parameter other: The mutable buffer pointer to convert.
   @_inlineable
   public init(_ other: UnsafeMutableBufferPointer<Element>) {
     _position = UnsafePointer<Element>(other._position)
     _end = UnsafePointer<Element>(other._end)
   }

 %  end

 %  if not Mutable:

   /// Creates a buffer over the same memory as the given buffer slice.
   ///
   /// The new buffer represents the same region of memory as `slice`, but is
   /// indexed starting at zero instead of sharing indices with the original
   /// buffer. For example:
   ///
   ///     let buffer = returnsABuffer()
   ///     let n = 5
   ///     let slice = buffer[n...]
   ///     let rebased = UnsafeBufferPointer(rebasing: slice)
   ///
   /// After rebasing `slice` as the `rebased` buffer, the following are true:
   ///
   /// - `rebased.startIndex == 0`
   /// - `rebased[0] == slice[n]`
   /// - `rebased[0] == buffer[n]`
   /// - `rebased.count == slice.count`
   ///
   /// - Parameter slice: The buffer slice to rebase.
   @_inlineable
   public init(rebasing slice: Slice<UnsafeBufferPointer<Element>>) {
     self.init(start: slice.base.baseAddress! + slice.startIndex,
       count: slice.count)
   }

 %  end

   /// Creates a buffer over the same memory as the given buffer slice.
   ///
   /// The new buffer represents the same region of memory as `slice`, but is
   /// indexed starting at zero instead of sharing indices with the original
   /// buffer. For example:
   ///
   ///     let buffer = returnsABuffer()
   ///     let n = 5
   ///     let slice = buffer[n...]
   ///     let rebased = Unsafe${Mutable}BufferPointer(rebasing: slice)
   ///
   /// After rebasing `slice` as the `rebased` buffer, the following are true:
   ///
   /// - `rebased.startIndex == 0`
   /// - `rebased[0] == slice[n]`
   /// - `rebased[0] == buffer[n]`
   /// - `rebased.count == slice.count`
   ///
   /// - Parameter slice: The buffer slice to rebase.
   @_inlineable
   public init(
     rebasing slice:
     Slice<UnsafeMutableBufferPointer<Element>>
   ) {
     self.init(start: slice.base.baseAddress! + slice.startIndex,
       count: slice.count)
   }

   /// Returns an iterator over the elements of this buffer.
   ///
   /// - Returns: An iterator over the elements of this buffer.
   @_inlineable
   public func makeIterator() -> UnsafeBufferPointerIterator<Element> {
     return UnsafeBufferPointerIterator(_position: _position, _end: _end)
   }

   /// Deallocates the memory block previously allocated at this buffer pointer’s
   /// base address.
   ///
   /// This buffer pointer's `baseAddress` must be `nil` or a pointer to a memory
   /// block previously returned by a Swift allocation method. If `baseAddress` is
   /// `nil`, this function does nothing. Otherwise, the memory must not be initialized
   /// or `Pointee` must be a trivial type. This buffer pointer's `count` must
   /// be equal to the originally allocated size of the memory block.
   @_inlineable
   public func deallocate() {
     _position?.deallocate()
   }

 % if Mutable:

   /// Allocates uninitialized memory for the specified number of instances of
   /// type `Element`.
   ///
   /// The resulting buffer references a region of memory that is bound to
   /// `Element` and is `count * MemoryLayout<Element>.stride` bytes in size.
   ///
   /// The following example allocates a buffer that can store four `Int`
   /// instances and then initializes that memory with the elements of a range:
   ///
   ///     let buffer = UnsafeMutableBufferPointer<Int>.allocate(capacity: 4)
   ///     _ = buffer.initialize(from: 1...4)
   ///     print(buffer[2])
   ///     // Prints "3"
   ///
   /// When you allocate memory, always remember to deallocate once you're
   /// finished.
   ///
   ///     buffer.deallocate()
   ///
   /// - Parameter count: The amount of memory to allocate, counted in instances
   ///   of `Element`.
   @_inlineable
   public static func allocate(capacity count: Int)
     -> UnsafeMutableBufferPointer<Element> {
     let size = MemoryLayout<Element>.stride * count
     let raw  = Builtin.allocRaw(size._builtinWordValue, Builtin.alignof(Element.self))
     Builtin.bindMemory(raw, count._builtinWordValue, Element.self)
     return UnsafeMutableBufferPointer(
       start: UnsafeMutablePointer(raw), count: count)
   }

   /// Initializes every element in this buffer's memory to a copy of the given value.
   ///
   /// The destination memory must be uninitialized or the buffer's `Element`
   /// must be a trivial type. After a call to `initialize(repeating:)`, the
   /// entire region of memory referenced by this buffer is initialized.
   ///
   /// - Parameters:
   ///   - repeatedValue: The instance to initialize this buffer's memory with.
   @_inlineable
   public func initialize(repeating repeatedValue: Element) {
     guard let dstBase = _position else {
       return
     }

     dstBase.initialize(repeating: repeatedValue, count: _end! - dstBase)
   }

   /// Assigns every element in this buffer's memory to a copy of the given value.
   ///
   /// The buffer’s memory must be initialized or the buffer's `Element`
   /// must be a trivial type.
   ///
   /// - Parameters:
   ///   - repeatedValue: The instance to assign this buffer's memory to.
   ///
   /// Warning: All buffer elements must be initialized before calling this.
   /// Assigning to part of the buffer must be done using the `assign(repeating:count:)``
   /// method on the buffer’s `baseAddress`.
   @_inlineable
   public func assign(repeating repeatedValue: Element) {
     guard let dstBase = _position else {
       return
     }

     dstBase.assign(repeating: repeatedValue, count: _end! - dstBase)
   }

 % end

   /// Executes the given closure while temporarily binding the memory referenced
   /// by this buffer to the given type.
   ///
   /// Use this method when you have a buffer of memory bound to one type and
   /// you need to access that memory as a buffer of another type. Accessing
   /// memory as type `T` requires that the memory be bound to that type. A
   /// memory location may only be bound to one type at a time, so accessing
   /// the same memory as an unrelated type without first rebinding the memory
   /// is undefined.
   ///
   /// The entire region of memory referenced by this buffer must be initialized.
   ///
   /// Because this buffer's memory is no longer bound to its `Element` type
   /// while the `body` closure executes, do not access memory using the
   /// original buffer from within `body`. Instead, use the `body` closure's
   /// buffer argument to access the values in memory as instances of type
   /// `T`.
   ///
   /// After executing `body`, this method rebinds memory back to the original
   /// `Element` type.
   ///
   /// - Parameters:
   ///   - type: The type to temporarily bind the memory referenced by this
   ///     buffer. The type `T` must have the same stride and be layout compatible
   ///     with the pointer's `Element` type.
   ///   - body: A closure that takes a ${Mutable.lower()} typed buffer to the
   ///     same memory as this buffer, only bound to type `T`. The buffer argument
   ///     contains the same number of complete instances of `T` as the original
   ///     buffer’s `count`. The closure's buffer argument is valid only for the
   ///     duration of the closure's execution. If `body` has a return value, that
   ///     value is also used as the return value for the `withMemoryRebound(to:_:)`
   ///     method.
   /// - Returns: The return value, if any, of the `body` closure parameter.
   @_inlineable
   public func withMemoryRebound<T, Result>(
     to type: T.Type, _ body: (${Self}<T>) throws -> Result
   ) rethrows -> Result {
     if let base = _position {
       _debugPrecondition(MemoryLayout<Element>.stride == MemoryLayout<T>.stride)
       Builtin.bindMemory(base._rawValue, count._builtinWordValue, T.self)
       defer {
         Builtin.bindMemory(base._rawValue, count._builtinWordValue, Element.self)
       }

       return try body(${Self}<T>(
         start: Unsafe${Mutable}Pointer<T>(base._rawValue), count: count))
     }
     else {
       return try body(${Self}<T>(start: nil, count: 0))
     }
   }

   /// A pointer to the first element of the buffer.
   ///
   /// If the `baseAddress` of this buffer is `nil`, the count is zero. However,
   /// a buffer can have a `count` of zero even with a non-`nil` base address.
   @_inlineable
   public var baseAddress: Unsafe${Mutable}Pointer<Element>? {
     return _position
   }

   /// The number of elements in the buffer.
   ///
   /// If the `baseAddress` of this buffer is `nil`, the count is zero. However,
   /// a buffer can have a `count` of zero even with a non-`nil` base address.
   @_inlineable
   public var count: Int {
     guard let start = _position, let end = _end else {
       return 0
     }

     return end - start
   }

   @_versioned
   let _position, _end: Unsafe${Mutable}Pointer<Element>?
 }

 extension Unsafe${Mutable}BufferPointer : CustomDebugStringConvertible {
   /// A textual representation of the buffer, suitable for debugging.
   @_inlineable // FIXME(sil-serialize-all)
   public var debugDescription: String {
     return "Unsafe${Mutable}BufferPointer"
       + "(start: \(_position.map(String.init(describing:)) ?? "nil"), count: \(count))"
   }
 }
 %end


 extension UnsafeMutableBufferPointer {
   /// Initializes the buffer's memory with the given elements.
   ///
   /// When calling the `initialize(from:)` method on a buffer `b`, the memory
   /// referenced by `b` must be uninitialized or the `Element` type must be a
   /// trivial type. After the call, the memory referenced by this buffer up
   /// to, but not including, the returned index is initialized. The buffer
   /// must contain sufficient memory to accommodate
   /// `source.underestimatedCount`.
   ///
   /// The returned index is the position of the element in the buffer one past
   /// the last element written. If `source` contains no elements, the returned
   /// index is equal to the buffer's `startIndex`. If `source` contains an
   /// equal or greater number of elements than the buffer can hold, the
   /// returned index is equal to the buffer's `endIndex`.
   ///
   /// - Parameter source: A sequence of elements with which to initializer the
   ///   buffer.
   /// - Returns: An iterator to any elements of `source` that didn't fit in the
   ///   buffer, and an index to the point in the buffer one past the last
   ///   element written.
   @_inlineable
   public func initialize<S: Sequence>(from source: S) -> (S.Iterator, Index)
     where S.Element == Element {
     return source._copyContents(initializing: self)
   }
 }

 // ${'Local Variables'}:
 // eval: (read-only-mode 1)
 // End:
	//===--- UnsafeBufferPointer.swift.gyb ------------------------- swift --===//
	//
	// 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
	//
	//===----------------------------------------------------------------------===//

	/// An iterator for the elements in the buffer referenced by an
	/// `UnsafeBufferPointer` or `UnsafeMutableBufferPointer` instance.
	@_fixed_layout
	public struct UnsafeBufferPointerIterator<Element>
	: IteratorProtocol, Sequence {

	/// Advances to the next element and returns it, or `nil` if no next element
	/// exists.
	///
	/// Once `nil` has been returned, all subsequent calls return `nil`.
	@_inlineable
	public mutating func next() -> Element? {
	if _position == _end { return nil }

	let result = _position!.pointee
	_position! += 1
	return result
	}

	@_versioned
	internal var _position, _end: UnsafePointer<Element>?

	@_inlineable
	public init(_position: UnsafePointer<Element>?, _end: UnsafePointer<Element>?) {
	self._position = _position
	self._end = _end
	}
	}

	% for mutable in (True, False):
	% Self = 'UnsafeMutableBufferPointer' if mutable else 'UnsafeBufferPointer'
	% Mutable = 'Mutable' if mutable else ''
	/// A nonowning collection interface to a buffer of ${Mutable.lower()}
	/// elements stored contiguously in memory.
	///
	/// You can use an `${Self}` instance in low level operations to eliminate
	/// uniqueness checks and, in release mode, bounds checks. Bounds checks are
	/// always performed in debug mode.
	///
	/// ${Self} Semantics
	/// =================
	///
	/// An `${Self}` instance is a view into memory and does not own the memory
	/// that it references. Copying a value of type `${Self}` does not copy the
	/// instances stored in the underlying memory. However, initializing another
	/// collection with an `${Self}` instance copies the instances out of the
	/// referenced memory and into the new collection.
	@_fixed_layout
	public struct Unsafe${Mutable}BufferPointer<Element>
	: ${Mutable}Collection, RandomAccessCollection {
	// FIXME: rdar://18157434 - until this is fixed, this has to be fixed layout
	// to avoid a hang in Foundation, which has the following setup:
	// struct A { struct B { let x: UnsafeMutableBufferPointer<...> } let b: B }

	public typealias Index = Int
	public typealias Iterator = UnsafeBufferPointerIterator<Element>

	/// The index of the first element in a nonempty buffer.
	///
	/// The `startIndex` property of an `Unsafe${Mutable}BufferPointer` instance
	/// is always zero.
	@_inlineable
	public var startIndex: Int {
	return 0
	}

	/// The "past the end" position---that is, the position one greater than the
	/// last valid subscript argument.
	///
	/// The `endIndex` property of an `Unsafe${Mutable}BufferPointer` instance is
	/// always identical to `count`.
	@_inlineable
	public var endIndex: Int {
	return count
	}

	@_inlineable
	public func index(after i: Int) -> Int {
	// NOTE: this is a manual specialization of index movement for a Strideable
	// index that is required for UnsafeBufferPointer performance. The
	// optimizer is not capable of creating partial specializations yet.
	// NOTE: Range checks are not performed here, because it is done later by
	// the subscript function.
	return i + 1
	}

	@_inlineable
	public func formIndex(after i: inout Int) {
	// NOTE: this is a manual specialization of index movement for a Strideable
	// index that is required for UnsafeBufferPointer performance. The
	// optimizer is not capable of creating partial specializations yet.
	// NOTE: Range checks are not performed here, because it is done later by
	// the subscript function.
	i += 1
	}

	@_inlineable
	public func index(before i: Int) -> Int {
	// NOTE: this is a manual specialization of index movement for a Strideable
	// index that is required for UnsafeBufferPointer performance. The
	// optimizer is not capable of creating partial specializations yet.
	// NOTE: Range checks are not performed here, because it is done later by
	// the subscript function.
	return i - 1
	}

	@_inlineable
	public func formIndex(before i: inout Int) {
	// NOTE: this is a manual specialization of index movement for a Strideable
	// index that is required for UnsafeBufferPointer performance. The
	// optimizer is not capable of creating partial specializations yet.
	// NOTE: Range checks are not performed here, because it is done later by
	// the subscript function.
	i -= 1
	}

	@_inlineable
	public func index(_ i: Int, offsetBy n: Int) -> Int {
	// NOTE: this is a manual specialization of index movement for a Strideable
	// index that is required for UnsafeBufferPointer performance. The
	// optimizer is not capable of creating partial specializations yet.
	// NOTE: Range checks are not performed here, because it is done later by
	// the subscript function.
	return i + n
	}

	@_inlineable
	public func index(
	_ i: Int, offsetBy n: Int, limitedBy limit: Int
	) -> Int? {
	// NOTE: this is a manual specialization of index movement for a Strideable
	// index that is required for UnsafeBufferPointer performance. The
	// optimizer is not capable of creating partial specializations yet.
	// NOTE: Range checks are not performed here, because it is done later by
	// the subscript function.
	let l = limit - i
	if n > 0 ? l >= 0 && l < n : l <= 0 && n < l {
	return nil
	}
	return i + n
	}

	@_inlineable
	public func distance(from start: Int, to end: Int) -> Int {
	// NOTE: this is a manual specialization of index movement for a Strideable
	// index that is required for UnsafeBufferPointer performance. The
	// optimizer is not capable of creating partial specializations yet.
	// NOTE: Range checks are not performed here, because it is done later by
	// the subscript function.
	return end - start
	}

	@_inlineable
	public func _failEarlyRangeCheck(_ index: Int, bounds: Range<Int>) {
	// NOTE: This method is a no-op for performance reasons.
	}

	@_inlineable
	public func _failEarlyRangeCheck(_ range: Range<Int>, bounds: Range<Int>) {
	// NOTE: This method is a no-op for performance reasons.
	}

	public typealias Indices = CountableRange<Int>

	@_inlineable
	public var indices: Indices {
	return startIndex..<endIndex
	}

	/// Initializes the memory at `destination.baseAddress` with elements of `self`,
	/// stopping when either `self` or `destination` is exhausted.
	///
	/// - Returns: an iterator over any remaining elements of `self` and the
	/// number of elements initialized.
	@_inlineable // FIXME(sil-serialize-all)
	public func _copyContents(
	initializing destination: UnsafeMutableBufferPointer<Element>
	) -> (Iterator, UnsafeMutableBufferPointer<Element>.Index) {
	guard !isEmpty && !destination.isEmpty else { return (makeIterator(), 0) }
	let s = self.baseAddress._unsafelyUnwrappedUnchecked
	let d = destination.baseAddress._unsafelyUnwrappedUnchecked
	let n = Swift.min(destination.count, self.count)
	d.initialize(from: s, count: n)
	return (Iterator(_position: s + n, _end: _end), n)
	}

	/// Accesses the element at the specified position.
	///
	%if Mutable:
	/// The following example uses the buffer pointer's subscript to access and
	/// modify the elements of a mutable buffer pointing to the contiguous
	/// contents of an array:
	///
	/// var numbers = [1, 2, 3, 4, 5]
	/// numbers.withUnsafeMutableBufferPointer { buffer in
	/// for i in stride(from: buffer.startIndex, to: buffer.endIndex - 1, by: 2) {
	/// let x = buffer[i]
	/// buffer[i + 1] = buffer[i]
	/// buffer[i] = x
	/// }
	/// }
	/// print(numbers)
	/// // Prints "[2, 1, 4, 3, 5]"
	%else:
	/// The following example uses the buffer pointer's subscript to access every
	/// other element of the buffer:
	///
	/// let numbers = [1, 2, 3, 4, 5]
	/// let sum = numbers.withUnsafeBufferPointer { buffer -> Int in
	/// var result = 0
	/// for i in stride(from: buffer.startIndex, to: buffer.endIndex, by: 2) {
	/// result += buffer[i]
	/// }
	/// return result
	/// }
	/// // 'sum' == 9
	%end
	///
	/// - Note: Bounds checks for `i` are performed only in debug mode.
	///
	/// - Parameter i: The position of the element to access. `i` must be in the
	/// range `0..<count`.
	@_inlineable
	public subscript(i: Int) -> Element {
	get {
	_debugPrecondition(i >= 0)
	_debugPrecondition(i < endIndex)
	return _position![i]
	}
	%if Mutable:
	nonmutating set {
	_debugPrecondition(i >= 0)
	_debugPrecondition(i < endIndex)
	_position![i] = newValue
	}
	%end
	}

	@_inlineable
	public subscript(bounds: Range<Int>)
	-> Slice<Unsafe${Mutable}BufferPointer<Element>>
	{
	get {
	_debugPrecondition(bounds.lowerBound >= startIndex)
	_debugPrecondition(bounds.upperBound <= endIndex)
	return Slice(
	base: self, bounds: bounds)
	}
	% if Mutable:
	set {
	_debugPrecondition(bounds.lowerBound >= startIndex)
	_debugPrecondition(bounds.upperBound <= endIndex)
	// FIXME: swift-3-indexing-model: tests.
	_writeBackMutableSlice(&self, bounds: bounds, slice: newValue)
	}
	% end
	}

	/// Creates a new buffer pointer over the specified number of contiguous
	/// instances beginning at the given pointer.
	///
	/// - Parameters:
	/// - start: A pointer to the start of the buffer, or `nil`. If `start` is
	/// `nil`, `count` must be zero. However, `count` may be zero even for a
	/// non-`nil` `start`. The pointer passed as `start` must be aligned to
	/// `MemoryLayout<Element>.alignment`.
	/// - count: The number of instances in the buffer. `count` must not be
	/// negative.
	@_inlineable
	public init(start: Unsafe${Mutable}Pointer<Element>?, count: Int) {
	_precondition(
	count >= 0, "Unsafe${Mutable}BufferPointer with negative count")
	_precondition(
	count == 0 \|\| start != nil,
	"Unsafe${Mutable}BufferPointer has a nil start and nonzero count")
	_position = start
	_end = start.map { $0 + count }
	}

	/// Creates a buffer pointer starting at `start` and extending up to the last
	/// addressable pointer to `Element` in the memory space
	@_inlineable
	public init(_unboundedStartingAt start: Unsafe${Mutable}Pointer<Element>) {
	_position = start
	_end = type(of: start)._max
	}

	@_inlineable
	public init(_empty: ()) {
	_position = Unsafe${Mutable}Pointer._max
	_end = _position
	}

	% if Mutable:

	/// Creates a mutable typed buffer pointer referencing the same memory as the
	/// given immutable buffer pointer.
	///
	/// - Parameter other: The immutable buffer pointer to convert.
	@_inlineable
	public init(mutating other: UnsafeBufferPointer<Element>) {
	_position = UnsafeMutablePointer<Element>(mutating: other._position)
	_end = UnsafeMutablePointer<Element>(mutating: other._end)
	}

	% else:

	/// Creates an immutable typed buffer pointer referencing the same memory as the
	/// given mutable buffer pointer.
	///
	/// - Parameter other: The mutable buffer pointer to convert.
	@_inlineable
	public init(_ other: UnsafeMutableBufferPointer<Element>) {
	_position = UnsafePointer<Element>(other._position)
	_end = UnsafePointer<Element>(other._end)
	}

	% end

	% if not Mutable:

	/// Creates a buffer over the same memory as the given buffer slice.
	///
	/// The new buffer represents the same region of memory as `slice`, but is
	/// indexed starting at zero instead of sharing indices with the original
	/// buffer. For example:
	///
	/// let buffer = returnsABuffer()
	/// let n = 5
	/// let slice = buffer[n...]
	/// let rebased = UnsafeBufferPointer(rebasing: slice)
	///
	/// After rebasing `slice` as the `rebased` buffer, the following are true:
	///
	/// - `rebased.startIndex == 0`
	/// - `rebased[0] == slice[n]`
	/// - `rebased[0] == buffer[n]`
	/// - `rebased.count == slice.count`
	///
	/// - Parameter slice: The buffer slice to rebase.
	@_inlineable
	public init(rebasing slice: Slice<UnsafeBufferPointer<Element>>) {
	self.init(start: slice.base.baseAddress! + slice.startIndex,
	count: slice.count)
	}

	% end

	/// Creates a buffer over the same memory as the given buffer slice.
	///
	/// The new buffer represents the same region of memory as `slice`, but is
	/// indexed starting at zero instead of sharing indices with the original
	/// buffer. For example:
	///
	/// let buffer = returnsABuffer()
	/// let n = 5
	/// let slice = buffer[n...]
	/// let rebased = Unsafe${Mutable}BufferPointer(rebasing: slice)
	///
	/// After rebasing `slice` as the `rebased` buffer, the following are true:
	///
	/// - `rebased.startIndex == 0`
	/// - `rebased[0] == slice[n]`
	/// - `rebased[0] == buffer[n]`
	/// - `rebased.count == slice.count`
	///
	/// - Parameter slice: The buffer slice to rebase.
	@_inlineable
	public init(
	rebasing slice:
	Slice<UnsafeMutableBufferPointer<Element>>
	) {
	self.init(start: slice.base.baseAddress! + slice.startIndex,
	count: slice.count)
	}

	/// Returns an iterator over the elements of this buffer.
	///
	/// - Returns: An iterator over the elements of this buffer.
	@_inlineable
	public func makeIterator() -> UnsafeBufferPointerIterator<Element> {
	return UnsafeBufferPointerIterator(_position: _position, _end: _end)
	}

	/// Deallocates the memory block previously allocated at this buffer pointer’s
	/// base address.
	///
	/// This buffer pointer's `baseAddress` must be `nil` or a pointer to a memory
	/// block previously returned by a Swift allocation method. If `baseAddress` is
	/// `nil`, this function does nothing. Otherwise, the memory must not be initialized
	/// or `Pointee` must be a trivial type. This buffer pointer's `count` must
	/// be equal to the originally allocated size of the memory block.
	@_inlineable
	public func deallocate() {
	_position?.deallocate()
	}

	% if Mutable:

	/// Allocates uninitialized memory for the specified number of instances of
	/// type `Element`.
	///
	/// The resulting buffer references a region of memory that is bound to
	/// `Element` and is `count * MemoryLayout<Element>.stride` bytes in size.
	///
	/// The following example allocates a buffer that can store four `Int`
	/// instances and then initializes that memory with the elements of a range:
	///
	/// let buffer = UnsafeMutableBufferPointer<Int>.allocate(capacity: 4)
	/// _ = buffer.initialize(from: 1...4)
	/// print(buffer[2])
	/// // Prints "3"
	///
	/// When you allocate memory, always remember to deallocate once you're
	/// finished.
	///
	/// buffer.deallocate()
	///
	/// - Parameter count: The amount of memory to allocate, counted in instances
	/// of `Element`.
	@_inlineable
	public static func allocate(capacity count: Int)
	-> UnsafeMutableBufferPointer<Element> {
	let size = MemoryLayout<Element>.stride * count
	let raw = Builtin.allocRaw(size._builtinWordValue, Builtin.alignof(Element.self))
	Builtin.bindMemory(raw, count._builtinWordValue, Element.self)
	return UnsafeMutableBufferPointer(
	start: UnsafeMutablePointer(raw), count: count)
	}

	/// Initializes every element in this buffer's memory to a copy of the given value.
	///
	/// The destination memory must be uninitialized or the buffer's `Element`
	/// must be a trivial type. After a call to `initialize(repeating:)`, the
	/// entire region of memory referenced by this buffer is initialized.
	///
	/// - Parameters:
	/// - repeatedValue: The instance to initialize this buffer's memory with.
	@_inlineable
	public func initialize(repeating repeatedValue: Element) {
	guard let dstBase = _position else {
	return
	}

	dstBase.initialize(repeating: repeatedValue, count: _end! - dstBase)
	}

	/// Assigns every element in this buffer's memory to a copy of the given value.
	///
	/// The buffer’s memory must be initialized or the buffer's `Element`
	/// must be a trivial type.
	///
	/// - Parameters:
	/// - repeatedValue: The instance to assign this buffer's memory to.
	///
	/// Warning: All buffer elements must be initialized before calling this.
	/// Assigning to part of the buffer must be done using the `assign(repeating:count:)``
	/// method on the buffer’s `baseAddress`.
	@_inlineable
	public func assign(repeating repeatedValue: Element) {
	guard let dstBase = _position else {
	return
	}

	dstBase.assign(repeating: repeatedValue, count: _end! - dstBase)
	}

	% end

	/// Executes the given closure while temporarily binding the memory referenced
	/// by this buffer to the given type.
	///
	/// Use this method when you have a buffer of memory bound to one type and
	/// you need to access that memory as a buffer of another type. Accessing
	/// memory as type `T` requires that the memory be bound to that type. A
	/// memory location may only be bound to one type at a time, so accessing
	/// the same memory as an unrelated type without first rebinding the memory
	/// is undefined.
	///
	/// The entire region of memory referenced by this buffer must be initialized.
	///
	/// Because this buffer's memory is no longer bound to its `Element` type
	/// while the `body` closure executes, do not access memory using the
	/// original buffer from within `body`. Instead, use the `body` closure's
	/// buffer argument to access the values in memory as instances of type
	/// `T`.
	///
	/// After executing `body`, this method rebinds memory back to the original
	/// `Element` type.
	///
	/// - Parameters:
	/// - type: The type to temporarily bind the memory referenced by this
	/// buffer. The type `T` must have the same stride and be layout compatible
	/// with the pointer's `Element` type.
	/// - body: A closure that takes a ${Mutable.lower()} typed buffer to the
	/// same memory as this buffer, only bound to type `T`. The buffer argument
	/// contains the same number of complete instances of `T` as the original
	/// buffer’s `count`. The closure's buffer argument is valid only for the
	/// duration of the closure's execution. If `body` has a return value, that
	/// value is also used as the return value for the `withMemoryRebound(to:_:)`
	/// method.
	/// - Returns: The return value, if any, of the `body` closure parameter.
	@_inlineable
	public func withMemoryRebound<T, Result>(
	to type: T.Type, _ body: (${Self}<T>) throws -> Result
	) rethrows -> Result {
	if let base = _position {
	_debugPrecondition(MemoryLayout<Element>.stride == MemoryLayout<T>.stride)
	Builtin.bindMemory(base._rawValue, count._builtinWordValue, T.self)
	defer {
	Builtin.bindMemory(base._rawValue, count._builtinWordValue, Element.self)
	}

	return try body(${Self}<T>(
	start: Unsafe${Mutable}Pointer<T>(base._rawValue), count: count))
	}
	else {
	return try body(${Self}<T>(start: nil, count: 0))
	}
	}

	/// A pointer to the first element of the buffer.
	///
	/// If the `baseAddress` of this buffer is `nil`, the count is zero. However,
	/// a buffer can have a `count` of zero even with a non-`nil` base address.
	@_inlineable
	public var baseAddress: Unsafe${Mutable}Pointer<Element>? {
	return _position
	}

	/// The number of elements in the buffer.
	///
	/// If the `baseAddress` of this buffer is `nil`, the count is zero. However,
	/// a buffer can have a `count` of zero even with a non-`nil` base address.
	@_inlineable
	public var count: Int {
	guard let start = _position, let end = _end else {
	return 0
	}

	return end - start
	}

	@_versioned
	let _position, _end: Unsafe${Mutable}Pointer<Element>?
	}

	extension Unsafe${Mutable}BufferPointer : CustomDebugStringConvertible {
	/// A textual representation of the buffer, suitable for debugging.
	@_inlineable // FIXME(sil-serialize-all)
	public var debugDescription: String {
	return "Unsafe${Mutable}BufferPointer"
	+ "(start: \(_position.map(String.init(describing:)) ?? "nil"), count: \(count))"
	}
	}
	%end


	extension UnsafeMutableBufferPointer {
	/// Initializes the buffer's memory with the given elements.
	///
	/// When calling the `initialize(from:)` method on a buffer `b`, the memory
	/// referenced by `b` must be uninitialized or the `Element` type must be a
	/// trivial type. After the call, the memory referenced by this buffer up
	/// to, but not including, the returned index is initialized. The buffer
	/// must contain sufficient memory to accommodate
	/// `source.underestimatedCount`.
	///
	/// The returned index is the position of the element in the buffer one past
	/// the last element written. If `source` contains no elements, the returned
	/// index is equal to the buffer's `startIndex`. If `source` contains an
	/// equal or greater number of elements than the buffer can hold, the
	/// returned index is equal to the buffer's `endIndex`.
	///
	/// - Parameter source: A sequence of elements with which to initializer the
	/// buffer.
	/// - Returns: An iterator to any elements of `source` that didn't fit in the
	/// buffer, and an index to the point in the buffer one past the last
	/// element written.
	@_inlineable
	public func initialize<S: Sequence>(from source: S) -> (S.Iterator, Index)
	where S.Element == Element {
	return source._copyContents(initializing: self)
	}
	}

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