MutableSpanとMutableRawSpanの一括更新操作

MutableSpan と MutableRawSpan に、既存の要素を上書きする update 系のメソッド群を追加します。上書きされた古い値はデイニシャライズされます。先ほどのコピーは 1 回の呼び出しで書け、一括のメモリ操作が使われます（Element が BitwiseCopyable の場合は memcpy 相当になります）。

destination.updateAll(copying: source)

命名の体系

メソッド名は「対象（destination）をどう書き換えるか」を表すベース名と、「ソース（source）をどう扱うか」を表す引数ラベルの組み合わせで構成されます。

ベース名は次の 3 種類です。

• updateAll(...): span の全要素を上書きします。ソースの要素数は span と完全に一致している必要があります。
• updateSubrange(_:...): 指定したインデックス範囲の要素を上書きします。ソースの要素数は範囲の要素数と完全に一致している必要があります。
• updateElements(from:...): 指定したインデックスから順に上書きし、最後に更新した要素の次のインデックスを報告します。

ソースのラベルは次の 3 種類です。

• repeating:: すべての要素を同じ値にします。
• copying:: ソースから要素をコピーします。
• moving:: OutputSpan から要素をムーブします。ムーブ後のソースのメモリは未初期化になります。

この命名は、将来の range-replaceable なコンテナプロトコルで提案される removeAll / removeSubrange / replaceSubrange / insert / append などと揃えることを意図しています。

同じ値で埋める（repeating:）

var span = array.mutableSpan
span.updateAll(repeating: 0)
span.updateSubrange(2..<6, repeating: 1)
span.updateSubrange(..., repeating: 2)

updateSubrange は Range のほか、some RangeExpression（2... など）や UnboundedRange（...）も受け取れます。なお、新しい updateAll(repeating:) は既存の update(repeating:) と同じ意味ですが、既存のメソッドは非推奨にはなりません。

Span からコピーする（copying:）

var destination = array.mutableSpan

destination.updateAll(copying: source.span)
destination.updateSubrange(2..<6, copying: source.span.extracting(first: 4))

updateAll と updateSubrange では、ソースの要素数が span 全体または範囲の要素数と一致しない場合、実行時にトラップします。

要素数がわからないソースからコピーする（updateElements）

ソースから得られる要素数が事前にわからない場合は updateElements(from:copying:) を使います。ソースには SE-0516 の Iterable に適合する任意の型（Span、InlineArray、UniqueArray など）を渡せます。

var destination = array.mutableSpan
var index = 0
destination.updateElements(from: &index, copying: header)
destination.updateElements(from: &index, copying: payload)
destination.updateElements(from: &index, copying: checksum)
precondition(index == destination.count)

このオーバーロードは、イテレーションがエラーを throw しうる Iterable にも対応しています。index は inout で受け取り、正常終了時もエラーの throw 時も、最後に更新した要素の次のインデックスに更新されます。そのため、エラーが発生しても、どこまで書き換えられたかを呼び出し元が把握できます。

Iterable の Failure が Never の場合は、次のインデックスを戻り値として返す便利なオーバーロードも使えます。

var end = destination.updateElements(from: 0, copying: header)
end = destination.updateElements(from: end, copying: payload)

Iterable を受け取るオーバーロードはソースを最後まで全部コピーし、span の残りの領域に収まらない場合はトラップします。ソースが残りの領域より短いのはかまいません。

なお、ここでの from: は「どのインデックスから書き始めるか」を表します。UnsafeMutableBufferPointer の類似メソッドでは from: がコピー元を表すので、混同しないよう注意が必要です。

イテレータから途中までコピーする

3 つ目のオーバーロードは、BorrowingIteratorProtocol に適合するイテレータを inout で受け取ります。こちらは、イテレータが要素を出し尽くすか、span の末尾に達するか、どちらか早いほうで停止します。正常に返った時点で、イテレータは最後に渡した要素の次の位置を指しています。これを使うと、1 つのソースを複数の span に分けて書き込めます。

var iterator = source.makeBorrowingIterator()
var index = 0
first.updateElements(from: &index, copying: &iterator)
if index == first.count {
  var index2 = 0
  second.updateElements(from: &index2, copying: &iterator)
}

要素をムーブする（moving:）

updateAll(moving:) と updateSubrange(_:moving:) は、OutputSpan を inout で受け取り、その要素を span へムーブします。呼び出し後、ソースの OutputSpan は空になり、メモリは未初期化の状態に戻ります。

var destination = storage.mutableSpan
source.edit { output in
  assert(output.count == 2)
  destination.updateSubrange(2..<4, moving: &output)
}
assert(source.isEmpty)

ムーブには要素のコピーが不要なので、moving: 版は Element: ~Copyable の場合でも使えます。

MutableRawSpan の場合

MutableRawSpan にも同じ名前の操作が用意されます。ソースの型が Span の代わりに RawSpan、OutputSpan の代わりに OutputRawSpan になり、repeating: には UInt8 を、updateElements には要素型が UInt8 の Iterable / BorrowingIteratorProtocol を渡します。インデックスはバイトオフセット（Int）です。

var bytes = buffer.mutableBytes
bytes.updateAll(repeating: 0)
bytes.updateSubrange(0..<4, copying: magicNumber.bytes)

これらの API は新しい標準ライブラリを必要とします。ABI 安定なプラットフォームでは、updateElements は Iterable が、それ以外は Span が利用可能な OS バージョン以降で使えます。