ByteBuffer amazingly fails to document that it's a value type :)

[weissi]

The ByteBuffer docs fail to mention that it's a value type. We should fix that.

Given that BB also has a few tricks up its sleeve (reader/writerIndex, self-slicing are part of the struct) we should also add that you can perform some mutations without even suffering CoW :)

[natikgadzhi]

I'm happy to help, but let's make sure that my assumptions are correct:

1. Your goal is to have a general explanation that ByteBuffer itself is a struct, and as such, a value type.
2. ByteBuffer internally, it uses _Storage, which essentially is a pointer to the actual data the buffer represents in memory.
3. ByteBuffer is clever and does copy on write, but only for operations that are mutating the actual data.
4. I.e. moving reader/writer indices or slicing would not cause the buffer to have to copy and reallocate the underlying data. Reserving capacity and writing to the buffer, IF there are at least two buffers pointing to the same memory, will copy on write.

Any typical examples I should include?

[weissi]

I'm happy to help, but let's make sure that my assumptions are correct:

1. Your goal is to have a general explanation that ByteBuffer itself is a struct, and as such, a value type.

Not every struct has value semantics, so it should document that it does. This may be obvious/assumed by seasoned Swift programmers but I've had at least 3 people ask me if BB's a value type or not.

2. ByteBuffer internally, it uses _Storage, which essentially is a pointer to the actual data the buffer represents in memory.

Impl. detail, doesn't need docs

3. ByteBuffer is clever and does copy on write, but only for operations that are mutating the actual data.

Also technically an impl-detail but we should probably document that. Something like "ByteBuffer is a value type. The indices can always be modified without a copy of the underlying data. Any data modification may need to copy the contents using copy-on-write". Or similar

4. I.e. moving reader/writer indices or slicing would not cause the buffer to have to copy and reallocate the underlying data. Reserving capacity and writing to the buffer, IF there are at least two buffers pointing to the same memory, will copy on write.

Yes, that's also good to point out.

Any typical examples I should include?

Good idea! Yes, I think just something basic that shows it's a value type.

---

I think like good journalism, we should lead with the important bit "BB's a value type" and then descend into more details.