SE-0485: OutputSpan: delegate initialization of contiguous memory

[glessard (Guillaume Lessard)]

@xwu

---

  /// Create an OutputSpan with zero capacity
  @lifetime(immortal)
  public init()

I'm not seeing any APIs to resize the capacity. If so, is this initializer a useful operation?

If we have an Optional<OutputSpan<T>>, for example, we may need to materialize an empty OutputSpan<T> for the .none case. We end up needing this for many variants of non-owning types, and accordingly expect that when we propose initializers for Span and MutableSpan, empty initializers will be part of them as well.

Resizing is an operation performed by the type owning the memory; we've come across this issue with Kevin Perry's serialization API work (The future of serialization & deserialization APIs), and are working on a pattern to handle it.

@xwu

Should perhaps the APIs with more lenient preconditions be named something like appendUntilFilled(from:)? Should we offer such an API for not just iterators but also sequences?

I'm open to suggestions for the iterator-taking function; it may be that the append(from:) I suggested may be too close to "the good name." I would be opposed to a lenient form of the Sequence-taking function because this forces us to return an IteratorProtocol instance as part of a tuple, and if you have to handle an iterator it is simply nicer and more intentional to pass an inout iterator instance to the function; the provenance is clearer.

@xwu

On the topic of understanding preconditions being essential for correct use, the proposal doesn't specify whether the following APIs on OutputRawSpan have the "Sequence-like" preconditions or "Iterator-like" preconditions described above

I didn't include the note in the doc-comments, but the introductory paragraph above that block says: "Initializing an OutputRawSpan from a Sequence or other container type must use every element of the source." I'll update the doc-comments for clarity.

@lorentey

This variant of append needs to require Element to be copyable.

I rearranged code without a compiler, clearly. Fixed here.