Vendor dependencies

notes-service/vendor/bitvec/doc/macros/BitArr_type.md

@@ -0,0 +1,35 @@
+# Bit-Array Type Definition
+
+Because `BitArray<T, O, const BITS: usize>` is not expressible in stable Rust,
+this macro serves the purpose of creating a type definition that expands to a
+suitable `BitArray`. It creates the correct, rounded-up, `BitArray` to hold a
+requested number of bits in a requested set of ordering/storage parameters.
+
+The macro takes a minimum number of bits to store, and an optional set of
+bit-order and bit-store type names, and creates a `BitArray` that satisfies the
+request. As this macro is only usable in type position, it is named with
+`PascalCase` rather than `snake_case`.
+
+## Examples
+
+You must provide a bit-count; you may optionally provide a storage type, or a
+bit-ordering *and* a storage type, as subsequent arguments. When elided, the
+type parameters are set to the crate defaut type parameters of `Lsb0` and
+`usize`.
+
+```rust
+use bitvec::prelude::*;
+use core::cell::Cell;
+
+let a: BitArr!(for 100) = BitArray::ZERO;
+let b: BitArr!(for 100, in u32) = BitArray::<_>::ZERO;
+let c: BitArr!(for 100, in Cell<u16>, Msb0) = BitArray::<_, _>::ZERO;
+```
+
+The length expression must be `const`. It may be a literal, a named `const`
+item, or a `const` expression, as long as it evaluates to a `usize`. The type
+arguments have no restrictions, as long as they are in-scope at the invocation
+site and are implementors of [`BitOrder`] and [`BitStore`].
+
+[`BitOrder`]: crate::order::BitOrder
+[`BitStore`]: crate::store::BitStore

notes-service/vendor/bitvec/doc/macros/bitarr_value.md

@@ -0,0 +1,61 @@
+# Bit-Array Value Constructor
+
+This macro provides a bit-initializer syntax for [`BitArray`] values. It takes a
+superset of the [`vec!`] arguments, and is capable of producing bit-arrays in
+`const` contexts (for known type parameters).
+
+Like `vec!`, it can accept a sequence of comma-separated bit values, or a
+semicolon-separated pair of a bit value and a repetition counter. Bit values may
+be any integer or name of a `const` integer, but *should* only be `0` or `1`.
+
+## Argument Syntax
+
+It accepts zero, one, or three prefix arguments:
+
+- `const`: If the first argument to the macro is the keyword `const`, separated
+  from remaining arguments by a space, then the macro expands to a
+  `const`-expression that can be used in any appropriate context (initializing
+  a `static`, a `const`, or passed to a `const fn`). This only works when the
+  bit-ordering argument is either implicit, or one of the three tokens that
+  `bitvec` can recognize.
+- `$order ,`: When this is one of the three literal tokens `LocalBits`, `Lsb0`,
+  or `Msb0`, then the macro is able to compute the encoded bit-array contents at
+  compile time, including in `const` contexts. When it is anything else, the
+  encoding must take place at runtime. The name or path chosen must be in scope
+  at the macro invocation site.
+
+  When not provided, this defaults to `Lsb0`.
+- `$store ;`: This must be one of `uTYPE`, `Cell<uTYPE>`, `AtomicUTYPE`, or
+  `RadiumUTYPE` where `TYPE` is one of `8`, `16`, `32`, `64`, or `size`. The
+  macro recognizes this token textually, and does not have access to the type
+  system resolver, so it will not accept aliases or qualified paths.
+
+  When not provided, this defaults to `usize`.
+
+The `const` argument can be present or absent independently of the
+type-parameter pair. The pair must be either both absent or both present
+together.
+
+> Previous versions of `bitvec` supported `$order`-only arguments. This has been
+> removed for clarity of use and ease of implementation.
+
+## Examples
+
+```rust
+use bitvec::prelude::*;
+use core::{cell::Cell, mem};
+use radium::types::*;
+
+let a: BitArray = bitarr![0, 1, 0, 0, 1];
+
+let b: BitArray = bitarr![1; 5];
+assert_eq!(b.len(), mem::size_of::<usize>() * 8);
+
+let c = bitarr![u16, Lsb0; 0, 1, 0, 0, 1];
+let d = bitarr![Cell<u16>, Msb0; 1; 10];
+const E: BitArray<[u32; 1], LocalBits> = bitarr![u32, LocalBits; 1; 15];
+let f = bitarr![RadiumU32, Msb0; 1; 20];
+```
+
+[`BitArray`]: crate::array::BitArray
+[`vec!`]: macro@alloc::vec

notes-service/vendor/bitvec/doc/macros/bitbox.md

@@ -0,0 +1,10 @@
+# Boxed Bit-Slice Constructor
+
+This macro creates encoded `BitSlice` buffers at compile-time, and at run-time
+copies them directly into a new heap allocation.
+
+It forwards all of its arguments to [`bitvec!`], and calls
+[`BitVec::into_boxed_bitslice`] on the produced `BitVec`.
+
+[`BitVec::into_boxed_bitslice`]: crate::vec::BitVec::into_boxed_bitslice
+[`bitvec!`]: macro@crate::bitvec

notes-service/vendor/bitvec/doc/macros/bits.md

@@ -0,0 +1,102 @@
+# Bit-Slice Region Constructor
+
+This macro provides a bit-initializer syntax for [`BitSlice`] reference values.
+It takes a superset of the [`vec!`] arguments, and is capable of producing
+bit-slices in `const` contexts (for known type parameters).
+
+Like `vec!`, it can accept a sequence of comma-separated bit values, or a
+semicolon-separated pair of a bit value and a repetition counter. Bit values may
+be any integer or name of a `const` integer, but *should* only be `0` or `1`.
+
+## Argument Syntax
+
+It accepts two modifier prefixes, zero or two type parameters, and the bit
+expressions described above.
+
+The modifier prefixes are separated from the remaining arguments by clearspace.
+
+- `static`: If the first argument is the keyword `static`, then this produces a
+  `&'static BitSlice` reference bound into a (hidden, unnameable)
+  `static BitArray` item. If not, then it produces a stack temporary that the
+  Rust compiler automatically extends to have the lifetime of the returned
+  reference. Note that non-`static` invocations rely on the compiler’s escape
+  analysis, and you should typically not try to move them up the call stack.
+- `mut`: If the first argument is the keyword `mut`, then this produces a `&mut`
+  writable `BitSlice`.
+- `static mut`: These can be combined to create a `&'static mut BitSlice`. It is
+  always safe to use this reference, because the `static mut BitArray` it
+  creates is concealed and unreachable by any other codepath, and so the
+  produced reference is always the sole handle that can reach it.
+
+The next possible arguments are a pair of `BitOrder`/`BitStore` type parameters.
+
+- `$order ,`: When this is one of the three literal tokens `LocalBits`, `Lsb0`,
+  or `Msb0`, then the macro is able to compute the encoded bit-array contents at
+  compile time, including in `const` contexts. When it is anything else, the
+  encoding must take place at runtime. The name or path chosen must be in scope
+  at the macro invocation site.
+
+  When not provided, this defaults to `Lsb0`.
+- `$store ;`: This must be one of `uTYPE`, `Cell<uTYPE>`, `AtomicUTYPE`, or
+  `RadiumUTYPE` where `TYPE` is one of `8`, `16`, `32`, `64`, or `size`. The
+  macro recognizes this token textually, and does not have access to the type
+  system resolver, so it will not accept aliases or qualified paths.
+
+  When not provided, this defaults to `usize`.
+
+The `static`/`mut` modifiers may be individually present or absent independently
+of the type-parameter pair. The pair must be either both absent or both present
+together.
+
+> Previous versions of `bitvec` supported $order`-only arguments. This has been
+> removed for clarity of use and ease of implementation.
+
+## Safety
+
+Rust considers all `static mut` bindings to be `unsafe` to use. While `bits!`
+can prevent *some* of this unsafety by preventing direct access to the created
+`static mut` buffer, there are still ways to create multiple names referring to
+the same underlying buffer.
+
+```rust,ignore
+use bitvec::prelude::*;
+
+fn unsound() -> &'static mut BitSlice<usize, Lsb0> {
+  unsafe { bits![static mut 0; 64] }
+}
+
+let a = unsound();
+let b = unsound();
+```
+
+The two names `a` and `b` can be used to produce aliasing `&mut [usize]`
+references.
+
+**You must not invoke `bits![static mut …]` in a context where it can be used**
+**to create multiple escaping names**. This, and only this, argument combination
+of the macro produces a value that requires a call-site `unsafe` block to use.
+
+If you do not use this behavior to create multiple names over the same
+underlying buffer, then the macro’s expansion is safe to use, as `bitvec`’s
+existing alias-protection behavior suffices.
+
+## Examples
+
+```rust
+use bitvec::prelude::*;
+use core::cell::Cell;
+use radium::types::*;
+
+let a: &BitSlice = bits![0, 1, 0, 0, 1];
+
+let b: &BitSlice = bits![1; 5];
+assert_eq!(b.len(), 5);
+
+let c = bits![u16, Lsb0; 0, 1, 0, 0, 1];
+let d = bits![static Cell<u16>, Msb0; 1; 10];
+let e = unsafe { bits![static mut u32, LocalBits; 0; 15] };
+let f = bits![RadiumU32, Msb0; 1; 20];
+```
+
+[`BitSlice`]: crate::slice::BitSlice
+[`vec!`]: macro@alloc::vec

notes-service/vendor/bitvec/doc/macros/bitvec.md

@@ -0,0 +1,12 @@
+# Bit-Vector Constructor
+
+This macro creates encoded `BitSlice` buffers at compile-time, and at run-time
+copies them directly into a new heap allocation.
+
+It forwards all of its arguments to [`bits!`], and calls
+[`BitVec::from_bitslice`] on the produced `&BitSlice` expression. While you can
+use the `bits!` modifiers, there is no point, as the produced bit-slice is lost
+before the macro exits.
+
+[`BitVec::from_bitslice`]: crate::vec::BitVec::from_bitslice
+[`bits!`]: macro@crate::bits

notes-service/vendor/bitvec/doc/macros/encode_bits.md

@@ -0,0 +1,62 @@
+# Bit-Sequence Buffer Encoding
+
+This macro accepts a sequence of bit expressions from the public macros and
+creates encoded `[T; N]` arrays from them. The public macros can then use these
+encoded arrays as the basis of the requested data structure.
+
+This is a complex macro that uses recursion to modify and inspect its input
+tokens. It is divided into three major sections.
+
+## Entry Points
+
+The first section provides a series of entry points that the public macros
+invoke. Each arm matches the syntax provided by public macros, and detects a
+specific `BitStore` implementor name: `uN`, `Cell<uN>`, `AtomicUN`, or
+`RadiumUN`, for each `N` in `8`, `16`, `32`, `64`, and `size`.
+
+These arms then recurse, adding a token for the raw unsigned integer used as the
+basis of the encoding. The `usize` arms take an additional recursion that routes
+to the 32-bit or 64-bit encoding, depending on the target.
+
+## Zero Extension
+
+The next two arms handle extending the list of bit-expressions with 64 `0,`s.
+The first arm captures initial reëntry and appends the zero-comma tokens, then
+recurses to enter the chunking group. The second arm traps when recursion has
+chunked all user-provided tokens, and only the literal `0,` tokens appended by
+the first arm remain.
+
+The second arm dispatches the chunked bit-expressions into the element encoder,
+and is the exit point of the macro. Its output is an array of encoded memory
+elements, typed as the initially-requested `BitStore` name.
+
+The `0,` tokens remain matchable as text literals because they never depart
+this macro: recursion within the same macro does not change the types in the
+AST, while invoking a new macro causes already-known tokens to become opacified
+into `:tt` whose contents cannot be matched. This is the reason that the macro
+is recursive rather than dispatching.
+
+## Chunking
+
+The stream of user-provided bit-expressions, followed by the appended zero-comma
+tokens, is divided into chunks by the width of the storage type.
+
+Each width (8, 16, 32, 64) has an arm that munches from the token stream and
+grows an opaque token-list containing munched groups. In syntax, this is
+represented by the `[$([$($bit:tt,)+],)*];` cluster:
+
+- it is an array
+  - of zero or more arrays
+    - of one or more bit expressions
+    - each followed by a comma
+  - each followed by a comma
+- followed by a semicolon
+
+By placing this array ahead of the bit-expression stream, we can use the array
+as an append-only list (matched as `[$($elem:tt)*]`, emitted as
+`[$($elem)* [new]]`) grown by munching from the token stream of unknown length
+at the end of the argument set.
+
+On each recursion, the second arm in zero-extension attempts to trap the input.
+If it fails, then user-provided tokens remain; if it succeeds, then it discards
+any remaining macro-appended zeros and terminates.

notes-service/vendor/bitvec/doc/macros/internal.md

@@ -0,0 +1,6 @@
+# Internal Macro Implementations
+
+The contents of this module are required to be publicly reachable from external
+crates, because that is the context in which the public macros expand; however,
+the contents of this module are **not** public API and `bitvec` does not support
+any use of it other than within the public macros.

notes-service/vendor/bitvec/doc/macros/make_elem.md

@@ -0,0 +1,21 @@
+# Element Encoder Macro
+
+This macro is invoked by `__encode_bits!` with a set of bits that exactly fills
+some `BitStore` element type. It is responsible for encoding those bits into the
+raw memory bytes and assembling them into a whole integer.
+
+It works by inspecting the `$order` argument. If it is one of `LocalBits`,
+`Lsb0`, or `Msb0`, then it can do the construction in-place, and get solved
+during `const` evaluation. If it is any other ordering, then it emits runtime
+code to do the translation and defers to the optimizer for evaluation.
+
+It divides the input into clusters of eight bit expressions, then uses the
+`$order` argument to choose whether the bits are accumulated into a `u8` using
+`Lsb0`, `Msb0`, or `LocalBits` ordering. The accumulated byte array is then
+converted into an integer using the corresponding `uN::from_{b,l,n}e_bytes`
+function in `__ty_from_bytes!`.
+
+Once assembled, the raw integer is changed into the requested final type. This
+currently routes through a helper type that unifies `const fn` constructors for
+each of the raw integer fundamentals, cells, and atomics in order to avoid
+transmutes.