Vendor dependencies

notes-service/vendor/bitvec/doc/order/BitOrder.md

@@ -0,0 +1,92 @@
+# In-Element Bit Ordering
+
+This trait manages the translation of semantic bit indices into electrical
+positions within storage elements of a memory region.
+
+## Usage
+
+`bitvec` APIs operate on semantic index counters that exist in an abstract
+memory space independently of the real memory that underlies them. In order to
+affect real memory, `bitvec` must translate these indices into real values. The
+[`at`] function maps abstract index values into their corresponding real
+positions that can then be used to access memory.
+
+You will likely never call any of the trait functions yourself. They are used by
+`bitvec` internals to operate on memory regions; all you need to do is provide
+an implementation of this trait as a type parameter to `bitvec` data structures.
+
+## Safety
+
+`BitOrder` is unsafe to implement because its translation of index to position
+cannot be forcibly checked by `bitvec` itself, and an improper implementation
+will lead to memory unsafety errors and unexpected collisions. The trait has
+strict requirements for each function. If these are not upheld, then the
+implementation is considered undefined at the library level and its use may
+produce incorrect or undefined behavior during compilation.
+
+You are responsible for running [`verify_for_type`] or [`verify`] in your test
+suite if you implement `BitOrder`.
+
+## Implementation Rules
+
+Values of this type are never constructed or passed to `bitvec` functions. Your
+implementation does not need to be zero-sized, but it will never have access to
+an instance to view its state. It *may* refer to other global state, but per the
+rules of `at`, that state may not change while any `bitvec` data structures are
+alive.
+
+The only function you *need* to provide is `at`. Its requirements are listed in
+its trait documentation.
+
+You *may* also choose to provide implementations of `select` and `mask`. These
+have a default implementation that is correct, but may be unoptimized for your
+implementation. As such, you may replace them with a better version, but your
+implementation of these functions must be exactly equal to the default
+implementation for all possible inputs.
+
+This requirement is checked by the `verify_for_type` function.
+
+## Verification
+
+The `verify_for_type` function verifies that a `BitOrder` implementation is
+correct for a single `BitStore` implementor, and the `verify` function runs
+`verify_for_type` on all unsigned integers that implement `BitStore` on a
+target. If you run these functions in your test suite, they will provide
+detailed information if your implementation is incorrect.
+
+## Examples
+
+Implementations are not required to remain contiguous over a register, and may
+have any mapping they wish as long as it is total and bijective. This example
+swizzles the high and low halves of each byte.
+
+```rust
+use bitvec::{
+  order::BitOrder,
+  index::{BitIdx, BitPos},
+  mem::BitRegister,
+};
+
+pub struct HiLo;
+
+unsafe impl BitOrder for HiLo {
+  fn at<R>(index: BitIdx<R>) -> BitPos<R>
+  where R: BitRegister {
+    unsafe { BitPos::new_unchecked(index.into_inner() ^ 4) }
+  }
+}
+
+#[test]
+#[cfg(test)]
+fn prove_hilo() {
+  bitvec::order::verify::<HiLo>();
+}
+```
+
+Once a `BitOrder` implementation passes the test suite, it can be freely used as
+a type parameter in `bitvec` data structures. The translation takes place
+automatically, and you never need to look at this trait again.
+
+[`at`]: Self::at
+[`verify`]: crate::order::verify
+[`verify_for_type`]: crate::order::verify_for_type

notes-service/vendor/bitvec/doc/order/LocalBits.md

@@ -0,0 +1,23 @@
+# C-Compatible Bit Ordering
+
+This type alias attempts to match the bitfield ordering used by GCC on your
+target. The C standard permits ordering of single-bit bitfields in a structure
+to be implementation-defined, and GCC has been observed to use Lsb0-ordering on
+little-endian processors and Msb0-ordering on big-endian processors.
+
+This has two important caveats:
+
+- ordering of bits in an element is **completely** independent of the ordering
+  of constituent bytes in memory. These have nothing to do with each other in
+  any way. See [the user guide][0] for more information on memory
+  representation.
+- GCC wide bitfields on big-endian targets behave as `<T, Lsb0>` bit-slices
+  using the `_be` variants of `BitField` accessors. They do not match `Msb0`
+  bit-wise ordering.
+
+This type is provided solely as a convenience for narrow use cases that *may*
+match GCC’s `std::bitset<N>`. It makes no guarantee about what C compilers for
+your target actually do, and you will need to do your own investigation if you
+are exchanging a single buffer across FFI in this manner.
+
+[0]: https://bitvecto-rs.github.io/bitvec/memory-representation

notes-service/vendor/bitvec/doc/order/Lsb0.md

@@ -0,0 +1,13 @@
+# Least-Significant-First Bit Traversal
+
+This type orders the bits in an element with the least significant bit first and
+the most significant bit last, in contiguous order across the element.
+
+The guide has [a chapter][0] with more detailed information on the memory
+representation this produces.
+
+This is the default type parameter used throughout the crate. If you do not have
+a desired memory representation, you should continue to use it, as it provides
+the best codegen for bit manipulation.
+
+[0]: https://bitvecto-rs.github.io/bitvec/memory-representation

notes-service/vendor/bitvec/doc/order/Msb0.md

@@ -0,0 +1,13 @@
+# Most-Significant-First Bit Traversal
+
+This type orders the bits in an element with the most significant bit first and
+the least significant bit last, in contiguous order across the element.
+
+The guide has [a chapter][0] with more detailed information on the memory
+representation this produces.
+
+This type likely matches the ordering of bits you would expect to see in a
+debugger, but has worse codegen than `Lsb0`, and is not encouraged if you are
+not doing direct memory inspection.
+
+[0]: https://bitvecto-rs.github.io/bitvec/memory-representation

notes-service/vendor/bitvec/doc/order/verify.md

@@ -0,0 +1,23 @@
+# Complete `BitOrder` Verification
+
+This function checks some [`BitOrder`] implementation’s behavior on each of the
+[`BitRegister`] types present on the target, and reports any violation of the
+rules that it detects.
+
+## Type Parameters
+
+- `O`: The `BitOrder` implementation being tested.
+
+## Parameters
+
+- `verbose`: Controls whether the test should print diagnostic information to
+  standard output. If this is false, then the test only prints a message on
+  failure; if it is true, it emits a message for every test it executes.
+
+## Panics
+
+This panics when it detects a violation of the `BitOrder` rules. If it returns
+normally, then the implementation is correct.
+
+[`BitOrder`]: crate::order::BitOrder
+[`BitRegister`]: crate::mem::BitRegister

notes-service/vendor/bitvec/doc/order/verify_for_type.md

@@ -0,0 +1,29 @@
+# Single-Type `BitOrder` Verification
+
+This function checks some [`BitOrder`] implementation’s behavior on only one
+[`BitRegister`] type. It can be used when a program knows that it will only use
+a limited set of storage types and does not need to check against all of them.
+
+You should prefer to use [`verify`], as `bitvec` has no means of preventing the
+use of a `BitRegister` storage type that your `BitOrder` implementation does not
+satisfy.
+
+## Type Parameters
+
+- `O`: The `BitOrder` implementation being tested.
+- `R`: The `BitRegister` type for which `O` is being tested.
+
+## Parameters
+
+- `verbose`: Controls whether the test should print diagnostic information to
+  standard output. If this is false, then the test only prints a message on
+  failure; if it is true, then it emits a message for every test it executes.
+
+## Panics
+
+This panics when it detects a violation of the `BitOrder` rules. If it returns
+normally, then the implementation is correct for the given `R` type.
+
+[`BitOrder`]: crate::order::BitOrder
+[`BitRegister`]: crate::mem::BitRegister
+[`verify`]: crate::order::verify.