Equivalent to
```
for _ in 0..cnt {
self.put_u8(val);
}
```
but may work faster.
Name and signature is chosen to be consistent with `ptr::write_bytes`.
Include three specializations:
* `Vec<u8>`
* `&mut [u8]`
* `BytesMut`
`BytesMut` and `&mut [u8]` specializations use `ptr::write`, `Vec<u8>`
specialization uses `Vec::resize`.
Avoid allocation when `Take` or `Chain` is composed of `Bytes`
objects.
This works now for `Take`.
`Chain` it works if the requested bytes does not cross boundary
between `Chain` members.
Use case:
```
let bytes: Bytes = ...
let subbytes = bytes.slice(a..b); // where a == b
let slice = &subbytes[..];
let slice_bytes = bytes.slice_ref(slice);
```
Last line should not panic, because `slice` object is derived from
the original `Bytes` object.
Before this commit it panics, because `Bytes::slice` returns a fresh
`Bytes` object when `begin == end`.
"Promotable" `Bytes` object is constructed from disassembling a
boxed slice object, not a vec.
Thus we should reassemble data into a boxed slice, not into a vec.
Although, it does not create any problems in practice (`Box<[u8]>`
is allocated exactly the same way as `Vec<u8>`), technically it is
a violation of `Vec::from_raw_parts` spec which says that a pointer
"needs to have been previously allocated via `String`/`Vec<T>`".
If `shallow_clone` is called with `&mut self`, and `Bytes` contains
`Vec`, then expensive CAS can be avoided, because no other thread
have references to this `Bytes` object.
Bench `split_off_and_drop` difference:
Before the diff:
```
test split_off_and_drop ... bench: 91,858 ns/iter (+/- 17,401)
```
With the diff:
```
test split_off_and_drop ... bench: 81,162 ns/iter (+/- 17,603)
```
Slice operation should return inline when possible
It is cheaper than atomic increment/decrement.
Before this patch:
```
test slice_avg_le_inline_from_arc ... bench: 28,582 ns/iter (+/- 3,880)
test slice_empty ... bench: 8,797 ns/iter (+/- 1,325)
test slice_large_le_inline_from_arc ... bench: 27,684 ns/iter (+/- 5,920)
test slice_short_from_arc ... bench: 27,439 ns/iter (+/- 5,783)
```
After this patch:
```
test slice_avg_le_inline_from_arc ... bench: 18,872 ns/iter (+/- 2,937)
test slice_empty ... bench: 9,136 ns/iter (+/- 1,908)
test slice_large_le_inline_from_arc ... bench: 18,052 ns/iter (+/- 2,981)
test slice_short_from_arc ... bench: 18,200 ns/iter (+/- 2,534)
```
Return empty `Bytes` object
Bench for `slice_empty` difference is
```
55 ns/iter (+/- 1) # before this patch
17 ns/iter (+/- 5) # with this patch
```
Bench for `slice_not_empty` is
```
25,058 ns/iter (+/- 1,099) # before this patch
25,072 ns/iter (+/- 1,593) # with this patch
```
Round up to power of 2 is not necessary, because `reserve` already
doubles previous capacity in
```
new_cap = cmp::max(
cmp::max(v.capacity() << 1, new_cap),
original_capacity);
```
which makes `reserve` calls constant in average. Avoiding rounding
up prevents `reserve` from wasting space when caller knows exactly
what space they need.
Patch adds three tests which would fail before this test. The most
important is this:
```
#[test]
fn reserve_in_arc_unique_does_not_overallocate() {
let mut bytes = BytesMut::with_capacity(1000);
bytes.take();
// now bytes is Arc and refcount == 1
assert_eq!(1000, bytes.capacity());
bytes.reserve(2001);
assert_eq!(2001, bytes.capacity());
}
```
It asserts that when user requests more than double of current
capacity, exactly the requested amount of memory is allocated and
is not wasted to next power of two.
`extend_with_slice` is super-convenient operation on `Bytes`.
While `put_u8` would be expensive on `Bytes`, `extend_from_slice`
is OK, because it is batch, and it checks for kind only once.
Patch also adds `impl Extend for Bytes`.
cc #116
Before this commit `Bytes::split_{off,to}` always created a shallow copy if `self` is arc or vec.
However, in certain cases `split_off` or `split_to` is called with `len` or `0` parameter. E. g. if you are reading a frame from buffered stream, it is likely that buffer contains exactly the frame size bytes, so `split_to` will be called with `len` param.
Although, `split_off` and `split_to` functions are `O(1)`, shallow copy have downsides:
* shallow copy on vector does malloc and atomic cmpxchg
* after shallow copy, following operations (e. g. `drop`) on both `bytes` objects require atomics
* memory will be probably released to the system later
* `try_mut` will fail
* [into_vec](https://github.com/carllerche/bytes/issues/86) will copy
Standard `Debug` implementation for `[u8]` is comma separated list
of numbers. Since large amount of byte strings are in fact ASCII
strings or contain a lot of ASCII strings (e. g. HTTP), it is
convenient to print strings as ASCII when possible.
