Vendor dependencies

notes-service/vendor/bitvec/doc/vec/BitVec.md

@@ -0,0 +1,174 @@
+# Bit-Precision Dynamic Array
+
+This is an analogue to `Vec<bool>` that stores its data using a compaction
+scheme to ensure that each `bool` takes exactly one bit of memory. It is similar
+to the C++ type [`std::vector<bool>`], but uses `bitvec`’s type parameter system
+to provide more detailed control over the in-memory representation.
+
+This is *always* a heap allocation. If you know your sizes at compile-time, you
+may prefer to use [`BitArray`] instead, which is able to store its data as an
+immediate value rather than through an indirection.
+
+## Documentation Practices
+
+`BitVec` exactly replicates the API of the standard-library `Vec` type,
+including inherent methods, trait implementations, and relationships with the
+[`BitSlice`] slice analogue.
+
+Items that are either direct ports, or renamed variants, of standard-library
+APIs will have a `## Original` section that links to their standard-library
+documentation. Items that map to standard-library APIs but have a different API
+signature will also have an `## API Differences` section that describes what
+the difference is, why it exists, and how to transform your code to fit it. For
+example:
+
+## Original
+
+[`Vec<T>`](alloc::vec::Vec)
+
+## API Differences
+
+As with all `bitvec` data structures, this takes two type parameters `<T, O>`
+that govern the bit-vector’s storage representation in the underlying memory,
+and does *not* take a type parameter to govern what data type it stores (always
+`bool`)
+
+## Suggested Uses
+
+`BitVec` is able to act as a compacted `usize => bool` dictionary, and is useful
+for holding large collections of truthiness. For instance, you might replace a
+`Vec<Option<T>>` with a `(BitVec, Vec<MaybeUninit<T>>`) to cut down on the
+resident size of the discriminant.
+
+Through the [`BitField`] trait, `BitVec` is also able to act as a transport
+buffer for data that can be marshalled as integers. Serializing data to a
+narrower compacted form, or deserializing data *from* that form, can be easily
+accomplished by viewing subsets of a bit-vector and storing integers into, or
+loading integers out of, that subset. As an example, transporting four ten-bit
+integers can be done in five bytes instead of eight like so:
+
+```rust
+use bitvec::prelude::*;
+
+let mut bv = bitvec![u8, Msb0; 0; 40];
+bv[0 .. 10].store::<u16>(0x3A8);
+bv[10 .. 20].store::<u16>(0x2F9);
+bv[20 .. 30].store::<u16>(0x154);
+bv[30 .. 40].store::<u16>(0x06D);
+```
+
+If you wish to use bit-field memory representations as `struct` fields rather
+than a transport buffer, consider `BitArray` instead: that type keeps its data
+as an immediate, and is more likely to act like a C struct with bitfields.
+
+## Examples
+
+`BitVec` has exactly the same API as `Vec<bool>`, and even extends it with some
+of `Vec<T>`’s behaviors. As a brief tour:
+
+### Push and Pop
+
+```rust
+use bitvec::prelude::*;
+
+let mut bv: BitVec = BitVec::new();
+bv.push(false);
+bv.push(true);
+
+assert_eq!(bv.len(), 2);
+assert_eq!(bv[0], false);
+
+assert_eq!(bv.pop(), Some(true));
+assert_eq!(bv.len(), 1);
+```
+
+### Writing Into a Bit-Vector
+
+The only `Vec<bool>` API that `BitVec` does *not* implement is `IndexMut`,
+because that is not yet possible. Instead, [`.get_mut()`] can produce a proxy
+reference, or [`.set()`] can take an index and a value to write.
+
+```rust
+use bitvec::prelude::*;
+
+let mut bv: BitVec = BitVec::new();
+bv.push(false);
+
+*bv.get_mut(0).unwrap() = true;
+assert!(bv[0]);
+bv.set(0, false);
+assert!(!bv[0]);
+```
+
+### Macro Construction
+
+Like `Vec`, `BitVec` also has a macro constructor: [`bitvec!`] takes a sequence
+of bit expressions and encodes them at compile-time into a suitable buffer. At
+run-time, this buffer is copied into the heap as a `BitVec` with no extra cost
+beyond the allocation.
+
+```rust
+use bitvec::prelude::*;
+
+let bv = bitvec![0; 10];
+let bv = bitvec![0, 1, 0, 0, 1];
+let bv = bitvec![u16, Msb0; 1; 20];
+```
+
+### Borrowing as `BitSlice`
+
+`BitVec` lends its buffer as a `BitSlice`, so you can freely give permission to
+view or modify the contained data without affecting the allocation:
+
+```rust
+use bitvec::prelude::*;
+
+fn read_bitslice(bits: &BitSlice) {
+  // …
+}
+
+let bv = bitvec![0; 30];
+read_bitslice(&bv);
+let bs: &BitSlice = &bv;
+```
+
+## Other Notes
+
+The default type parameters are `<usize, Lsb0>`. This is the most performant
+pair when operating on memory, but likely does not match your needs if you are
+using `BitVec` to represent a transport buffer. See [the user guide][book] for
+more details on how the type parameters govern memory representation.
+
+Applications, or single-purpose libraries, built atop `bitvec` will likely want
+to create a `type` alias with specific type parameters for their usage. `bitvec`
+is fully generic over the ordering/storage types, but this generality is rarely
+useful for client crates to propagate. `<usize, Lsb0>` is fastest; `<u8, Msb0>`
+matches what most debugger views of memory will print, and the rest are
+documented in the guide.
+
+## Safety
+
+Unlike the other data structures in this crate, `BitVec` is uniquely able to
+hold uninitialized memory and produce pointers into it. As described in the
+[`BitAccess`] documentation, this crate is categorically unable to operate on
+uninitialized memory in any way. In particular, you may not allocate a buffer
+using [`::with_capacity()`], then use [`.as_mut_bitptr()`] to create a pointer
+used to write into the uninitialized buffer.
+
+You must always initialize the buffer contents of a `BitVec` before attempting
+to view its contents. You can accomplish this through safe APIs such as
+`.push()`, `.extend()`, or `.reserve()`. These are all guaranteed to safely
+initialize the memory elements underlying the `BitVec` buffer without incurring
+undefined behavior in their operation.
+
+[book]: https://bitvecto-rs.github.io/bitvec/type-parameters.html
+[`BitAccess`]: crate::access::BitAccess
+[`BitArray`]: crate::array::BitArray
+[`BitField`]: crate::field::BitField
+[`BitSlice`]: crate::slice::BitSlice
+[`bitvec!`]: macro@crate::bitvec
+[`std::vector<bool>`]: https://en.cppreference.com/w/cpp/container/vector_bool
+[`.as_mut_bitptr()`]: crate::slice::BitSlice::as_mut_bitptr
+[`.get_mut()`]: crate::slice::BitSlice::get_mut
+[`.set()`]: crate::slice::BitSlice::set
+[`::with_capacity()`]: Self::with_capacity

notes-service/vendor/bitvec/doc/vec/iter.md

@@ -0,0 +1,14 @@
+# Bit-Vector Iteration
+
+This module provides iteration protocols for `BitVec`, including:
+
+- extension of existing bit-vectors with new data
+- collection of data into new bit-vectors
+- iteration over the contents of a bit-vector
+- draining and splicing iteration over parts of a bit-vector.
+
+`BitVec` implements `Extend` and `FromIterator` for both sources of individual
+bits and sources of `T` memory elements.
+
+The by-value `bool` iterator is defined in `boxed::iter`, rather than here. The
+`Drain` and `Splice` iterators remain here in their original location.

notes-service/vendor/bitvec/doc/vec/iter/Drain.md

@@ -0,0 +1,17 @@
+# Draining Iteration
+
+This structure iterates over a subset of a bit-vector, yielding each bit and
+removing it completely from the source.
+
+Each drain locks the bit-vector that created it until the drain is either
+destroyed or forgotten. If a drain is leaked rather than being allowed to drop
+normally, the source bit-vector is only guaranteed to have contents up to the
+original start of the drain. All further contents are unspecified.
+
+See [`BitVec::drain()`] for more details.
+
+## Original
+
+[`vec::Drain`](alloc::vec::Drain)
+
+[`BitVec::drain()`]: crate::vec::BitVec::drain

notes-service/vendor/bitvec/doc/vec/iter/Extend_BitRef.md

@@ -0,0 +1,10 @@
+# Bit-Vector Extension by Proxy References
+
+**DO NOT** use this. You *clearly* have a bit-slice. Use
+[`.extend_from_bitslice()`] instead!
+
+Iterating over a bit-slice requires loading from memory and constructing a proxy
+reference for each bit. This is needlessly slow; the specialized method is able
+to avoid this per-bit cost and possibly even use batched operations.
+
+[`.extend_from_bitslice()`]: crate::vec::BitVec::extend_from_bitslice

notes-service/vendor/bitvec/doc/vec/iter/Extend_bool.md

@@ -0,0 +1,21 @@
+# Bit-Vector Extension
+
+This extends a bit-vector from anything that produces individual bits.
+
+## Original
+
+[`impl<T> Extend<T> for Vec<T>`][orig]
+
+## Notes
+
+This `.extend()` call is the second-slowest possible way to append bits into a
+bit-vector, faster only than calling `iter.for_each(|bit| bv.push(bit))`.
+**DO NOT** use this if you have any other choice.
+
+If you are extending a bit-vector from the contents of a bit-slice, then you
+should use [`.extend_from_bitslice()`] instead. That method is specialized to
+perform upfront allocation and, where possible, use a batch copy rather than
+copying each bit individually from the source into the bit-vector.
+
+[orig]: https://doc.rust-lang.org/alloc/vec/struct.Vec.html#impl-Extend%3CT%3E
+[`.extend_from_bitslice()`]: crate::vec::BitVec::extend_from_bitslice

notes-service/vendor/bitvec/doc/vec/iter/FillStatus.md

@@ -0,0 +1,14 @@
+# Fill Status
+
+The standard library uses a `bool` flag to indicate whether a splicing operation
+exhausted the source or filled the target, which is not very clear about what is
+being signaled. This enum replaces it.
+
+## Variants
+
+- `FullSpan`: This marks that a drain span has been completely filled with
+  replacement bits, and any further replacement would require insertion rather
+  than overwriting dead storage.
+- `EmptyInput`: This marks that a replacement source has been run to completion,
+  but dead bits remain in a drain span, and the dead range will need to be
+  overwritten.

notes-service/vendor/bitvec/doc/vec/iter/FromIterator_BitRef.md

@@ -0,0 +1,10 @@
+# Bit-Vector Collection from Proxy References
+
+**DO NOT** use this. You *clearly* have a bit-slice. Use
+[`::from_bitslice()`] instead!
+
+Iterating over a bit-slice requires loading from memory and constructing a proxy
+reference for each bit. This is needlessly slow; the specialized method is able
+to avoid this per-bit cost and possibly even use batched operations.
+
+[`::from_bitslice()`]: crate::vec::BitVec::from_bitslice

notes-service/vendor/bitvec/doc/vec/iter/FromIterator_bool.md

@@ -0,0 +1,21 @@
+# Bit-Vector Collection
+
+This collects a bit-vector from anything that produces individual bits.
+
+## Original
+
+[`impl<T> FromIterator<T> for Vec<T>`][orig]
+
+## Notes
+
+This `.collect()` call is the second-slowest possible way to collect bits into a
+bit-vector, faster only than calling `iter.for_each(|bit| bv.push(bit))`.
+**DO NOT** use this if you have any other choice.
+
+If you are collecting a bit-vector from the contents of a bit-slice, then you
+should use [`::from_bitslice()`] instead. That method is specialized to
+perform upfront allocation and, where possible, use a batch copy rather than
+copying each bit individually from the source into the bit-vector.
+
+[orig]: https://doc.rust-lang.org/alloc/vec/struct.Vec.html#impl-FromIterator%3CT%3E
+[`::from_bitslice()`]: crate::vec::BitVec::extend_from_bitslice

notes-service/vendor/bitvec/doc/vec/iter/IntoIterator.md

@@ -0,0 +1,11 @@
+# Bit-Vector Iteration
+
+Bit-vectors have the advantage that iteration consumes the whole structure, so
+they can simply freeze the allocation into a bit-box, then use its iteration and
+destructor.
+
+## Original
+
+[`impl<T> IntoIterator for Vec<T>`][orig]
+
+[orig]: https://doc.rust-lang.org/alloc/vec/struct.Vec.html#impl-IntoIterator

notes-service/vendor/bitvec/doc/vec/iter/Splice.md

@@ -0,0 +1,17 @@
+# Splicing Iteration
+
+This adapts a [`Drain`] to overwrite the drained section with the contents of
+another iterator.
+
+When this splice is destroyed, the drained section of the source bit-vector is
+replaced with the contents of the replacement iterator. If the replacement is
+not the same length as the drained section, then the bit-vector is resized to
+fit.
+
+See [`BitVec::splice()`] for more information.
+
+## Original
+
+[`vec::Splice`](alloc::vec::Splice)
+
+[`BitVec::splice()`]: crate::vec::BitVec::splice