What's new in Swift

@frozen public struct BorrowingIteratorAdapter<Iterator> : BorrowingIteratorProtocol where Iterator : IteratorProtocol {

    public typealias Element = Iterator.Element

    public init(iterator: Iterator)

    /// Returns a span over the next group of elements that are ready to by visited,
    /// up to the specifed maximum.
    ///
    /// If the underlying type stores its elements in one or more blocks of
    /// contiguous memory, then the returned span typically directly
    /// addresses one of those buffers. On the other hand, if the underlying type
    /// materializes its elements on demand, then the returned span addresses
    /// a temporary buffer managed by the iterator itself. Consequently, the returned
    /// span is tied to this particular invocation of `nextSpan`, and it cannot
    /// survive beyond the next invocation of this method.
    ///
    /// If the iterator has not yet reached the end of the underlying elements,
    /// then this method returns a non-empty span of at most `maximumCount`
    /// elements and updates the iterator's current position to the element
    /// following the last item in the returned span. The `maximumCount`
    /// argument allows callers to avoid getting more items than they are
    /// able to process in one go, simplifying usage, and
    /// avoiding materializing more elements than needed.
    ///
    /// If the iterator's current position is at the end of the container, then
    /// this method returns an empty span without updating the position.
    ///
    /// This method can be used to efficiently process the items of a container
    /// in bulk, by directly iterating over its piecewise contiguous pieces of
    /// storage:
    ///
    ///     var it = items.makeBorrowingIterator()
    ///     while true {
    ///       let span = it.nextSpan(maximumCount: .max)
    ///       if span.isEmpty { break }
    ///       // Process items in `span`
    ///     }
    ///
    /// The spans returned by this method are not guaranteed to be disjunct.
    /// Iterators that materialize elements on demand typically reuse the same
    /// buffer over and over again; and even some proper containers may link to a
    /// single storage chunk (or parts of a storage chunk) multiple times, for
    /// example to repeat their contents.
    public mutating func nextSpan(maximumCount: Int) -> Span<Iterator.Element>
}

public protocol BorrowingIteratorProtocol<Element> : ~Copyable, ~Escapable {

    associatedtype Element : ~Copyable

    /// Returns a span over the next group of elements that are ready to by visited,
    /// up to the specifed maximum.
    ///
    /// If the underlying type stores its elements in one or more blocks of
    /// contiguous memory, then the returned span typically directly
    /// addresses one of those buffers. On the other hand, if the underlying type
    /// materializes its elements on demand, then the returned span addresses
    /// a temporary buffer managed by the iterator itself. Consequently, the returned
    /// span is tied to this particular invocation of `nextSpan`, and it cannot
    /// survive beyond the next invocation of this method.
    ///
    /// If the iterator has not yet reached the end of the underlying elements,
    /// then this method returns a non-empty span of at most `maximumCount`
    /// elements and updates the iterator's current position to the element
    /// following the last item in the returned span. The `maximumCount`
    /// argument allows callers to avoid getting more items than they are
    /// able to process in one go, simplifying usage, and
    /// avoiding materializing more elements than needed.
    ///
    /// If the iterator's current position is at the end of the container, then
    /// this method returns an empty span without updating the position.
    ///
    /// This method can be used to efficiently process the items of a container
    /// in bulk, by directly iterating over its piecewise contiguous pieces of
    /// storage:
    ///
    ///     var it = items.makeBorrowingIterator()
    ///     while true {
    ///       let span = it.nextSpan(maximumCount: .max)
    ///       if span.isEmpty { break }
    ///       // Process items in `span`
    ///     }
    ///
    /// The spans returned by this method are not guaranteed to be disjunct.
    /// Iterators that materialize elements on demand typically reuse the same
    /// buffer over and over again; and even some proper containers may link to a
    /// single storage chunk (or parts of a storage chunk) multiple times, for
    /// example to repeat their contents.
    mutating func nextSpan(maximumCount: Int) -> Span<Self.Element>

    /// Advances the position of this iterator by the specified offset, or until
    /// the end of the underlying type's elements.
    ///
    /// - Parameter maximumOffset: The maximum number of elements
    ///   to offset the position of this iterator. `maximumOffset` must be
    ///   nonnegative.
    /// - Returns: The number of items that were skipped. If the returned count
    ///   is less than `maximumOffset`, then the underlying type did not have
    ///   enough elements left to skip the requested number of items.
    ///   In that case, the iterator's position is set to the end of the underlying type.
    mutating func skip(by maximumOffset: Int) -> Int
}

extension BorrowingIteratorProtocol where Self : ~Copyable, Self : ~Escapable, Self.Element : ~Copyable {

    /// Returns a span over the next group of elements that are ready to by visited,
    /// up to the specifed maximum.
    public mutating func nextSpan() -> Span<Self.Element>

    /// Advances the position of this iterator by the specified offset, or until
    /// the end of the underlying type's elements.
    ///
    /// - Parameter maximumOffset: The maximum number of elements
    ///   to offset the position of this iterator. `maximumOffset` must be
    ///   nonnegative.
    /// - Returns: The number of items that were skipped. If the returned count
    ///   is less than `maximumOffset`, then the underlying type did not have
    ///   enough elements left to skip the requested number of items.
    ///   In that case, the iterator's position is set to the end of the underlying type.
    public mutating func skip(by offset: Int) -> Int
}

public protocol BorrowingSequence<Element> : ~Copyable, ~Escapable {

    /// A type representing the sequence's elements.
    associatedtype Element : ~Copyable where Self.Element == Self.BorrowingIterator.Element

    /// A type that provides the sequence's iteration interface and
    /// encapsulates its iteration state.
    associatedtype BorrowingIterator : BorrowingIteratorProtocol, ~Copyable, ~Escapable

    /// Returns a borrowing iterator over the elements of this sequence.
    func makeBorrowingIterator() -> Self.BorrowingIterator

    /// A value less than or equal to the number of elements in the sequence,
    /// calculated nondestructively.
    var underestimatedCount: Int { get }
}

extension BorrowingSequence where Self : ~Copyable, Self : ~Escapable, Self.Element : ~Copyable {

    /// A value less than or equal to the number of elements in the sequence,
    /// calculated nondestructively.
    @inlinable public var underestimatedCount: Int { get }
}

extension Collection where Self : BorrowingSequence {

    @available(anyAppleOS 27.0, *)
    @inlinable public var underestimatedCount: Int { get }
}

extension CollectionOfOne : Equatable where Element : Equatable {
}

extension CollectionOfOne : Hashable where Element : Hashable {
}

extension Dictionary.Keys : Hashable {
}

extension EmptyCollection : Hashable {
}

extension MutableRawSpan : BorrowingSequence {

    /// Returns a borrowing iterator over the elements of this sequence.
    @available(anyAppleOS 27.0, *)
    @inlinable public func makeBorrowingIterator() -> SpanIterator<UInt8>

    /// A type that provides the sequence's iteration interface and
    /// encapsulates its iteration state.
    @available(anyAppleOS 27.0, *)
    public typealias BorrowingIterator = SpanIterator<UInt8>

    /// A type representing the sequence's elements.
    @available(anyAppleOS 27.0, *)
    public typealias Element = UInt8
}

extension MutableSpan : BorrowingSequence where Element : ~Copyable {

    /// Returns a borrowing iterator over the elements of this sequence.
    @available(anyAppleOS 27.0, *)
    @inlinable public func makeBorrowingIterator() -> SpanIterator<Element>

    /// A type that provides the sequence's iteration interface and
    /// encapsulates its iteration state.
    @available(anyAppleOS 27.0, *)
    public typealias BorrowingIterator = SpanIterator<Element>
}

extension RawSpan : BorrowingSequence {

    /// Returns a borrowing iterator over the elements of this sequence.
    @available(anyAppleOS 27.0, *)
    @inlinable public func makeBorrowingIterator() -> SpanIterator<UInt8>

    /// A type that provides the sequence's iteration interface and
    /// encapsulates its iteration state.
    @available(anyAppleOS 27.0, *)
    public typealias BorrowingIterator = SpanIterator<UInt8>

    /// A type representing the sequence's elements.
    @available(anyAppleOS 27.0, *)
    public typealias Element = UInt8
}

extension Sequence where Self : BorrowingSequence {

    @available(anyAppleOS 27.0, *)
    public func makeBorrowingIterator() -> BorrowingIteratorAdapter<Self.Iterator>
}

extension Span : BorrowingSequence where Element : ~Copyable {

    /// Returns a borrowing iterator over the elements of this sequence.
    @available(anyAppleOS 27.0, *)
    @inlinable public func makeBorrowingIterator() -> SpanIterator<Element>

    /// A type that provides the sequence's iteration interface and
    /// encapsulates its iteration state.
    @available(anyAppleOS 27.0, *)
    public typealias BorrowingIterator = SpanIterator<Element>
}

public struct SpanIterator<Element> : BorrowingIteratorProtocol, ~Copyable, ~Escapable where Element : ~Copyable {

    public init(_ elements: Span<Element>)

    /// Returns a span over the next group of elements that are ready to by visited,
    /// up to the specifed maximum.
    ///
    /// If the underlying type stores its elements in one or more blocks of
    /// contiguous memory, then the returned span typically directly
    /// addresses one of those buffers. On the other hand, if the underlying type
    /// materializes its elements on demand, then the returned span addresses
    /// a temporary buffer managed by the iterator itself. Consequently, the returned
    /// span is tied to this particular invocation of `nextSpan`, and it cannot
    /// survive beyond the next invocation of this method.
    ///
    /// If the iterator has not yet reached the end of the underlying elements,
    /// then this method returns a non-empty span of at most `maximumCount`
    /// elements and updates the iterator's current position to the element
    /// following the last item in the returned span. The `maximumCount`
    /// argument allows callers to avoid getting more items than they are
    /// able to process in one go, simplifying usage, and
    /// avoiding materializing more elements than needed.
    ///
    /// If the iterator's current position is at the end of the container, then
    /// this method returns an empty span without updating the position.
    ///
    /// This method can be used to efficiently process the items of a container
    /// in bulk, by directly iterating over its piecewise contiguous pieces of
    /// storage:
    ///
    ///     var it = items.makeBorrowingIterator()
    ///     while true {
    ///       let span = it.nextSpan(maximumCount: .max)
    ///       if span.isEmpty { break }
    ///       // Process items in `span`
    ///     }
    ///
    /// The spans returned by this method are not guaranteed to be disjunct.
    /// Iterators that materialize elements on demand typically reuse the same
    /// buffer over and over again; and even some proper containers may link to a
    /// single storage chunk (or parts of a storage chunk) multiple times, for
    /// example to repeat their contents.
    public mutating func nextSpan(maximumCount: Int) -> Span<Element>

    /// Advances the position of this iterator by the specified offset, or until
    /// the end of the underlying type's elements.
    ///
    /// - Parameter maximumOffset: The maximum number of elements
    ///   to offset the position of this iterator. `maximumOffset` must be
    ///   nonnegative.
    /// - Returns: The number of items that were skipped. If the returned count
    ///   is less than `maximumOffset`, then the underlying type did not have
    ///   enough elements left to skip the requested number of items.
    ///   In that case, the iterator's position is set to the end of the underlying type.
    public mutating func skip(by offset: Int) -> Int
}

extension UnownedTaskExecutor : Hashable {

    /// The hash value.
    ///
    /// Hash values are not guaranteed to be equal across different executions of
    /// your program. Do not save hash values to use during a future execution.
    ///
    /// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
    ///   conform to `Hashable`, implement the `hash(into:)` requirement instead.
    ///   The compiler provides an implementation for `hashValue` for you.
    public var hashValue: Int { get }
}