Update documentation and rename shift functions

README.md

@@ -4,12 +4,12 @@
 
 ## A Magnifying Glass for Memory <!-- omit in toc -->
 
-[![Crate][crate_img]][crate]
-[![Documentation][docs_img]][docs]
+[![Crate][crate_img]][crate_link]
+[![MSRV][msrv_img]][crate_link]
 [![License][license_img]][license_file]
 
-[![Crate Downloads][downloads_img]][crate]
-[![Project Size][loc_img]][loc]
+[![Documentation][docs_img]][docs_link]
+[![Crate Downloads][downloads_img]][crate_link]
 
 </div>
 
@@ -36,7 +36,7 @@ Additionally, it allows a memory region to be divided into arbitrary regions of
 integer storage, like [binaries][erl_bit] in Erlang.
 
 If you need to view memory as bit-addressed instead of byte-addressed, then
-`bitvec` is the fastest, most complete, and Rust-idiomatic crate for you.
+`bitvec` is the most capable, complete, and Rust-idiomatic crate for you.
 
 ## Introduction
 
@@ -87,8 +87,6 @@ However, it does also have some small costs associated with its capabilities:
 
 ## Usage
 
-**Minimum Supported Rust Version**: 1.56.0
-
 `bitvec` strives to follow the sequence APIs in the standard library. However,
 as most of its functionality is a reïmplementation that does not require the
 standard library to actually have the symbols present, doing so may not require
@@ -392,15 +390,14 @@ these resources contain all of the information needed to understand what it
 does, how it works, and how it can be useful to you.
 
 <!-- Badges -->
-[crate]: https://crates.io/crates/bitvec "Crate listing"
-[crate_img]: https://img.shields.io/crates/v/bitvec.svg?logo=rust&style=for-the-badge "Crate badge"
-[docs]: https://docs.rs/bitvec/latest/bitvec "Crate documentation"
+[crate_link]: https://crates.io/crates/bitvec "Crate listing"
+[crate_img]: https://img.shields.io/crates/v/bitvec.svg?style=for-the-badge&color=f46623 "Crate badge"
+[docs_link]: https://docs.rs/bitvec/latest/bitvec "Crate documentation"
 [docs_img]: https://img.shields.io/docsrs/bitvec/latest.svg?style=for-the-badge "Documentation badge"
-[downloads_img]: https://img.shields.io/crates/dv/bitvec.svg?logo=rust&style=for-the-badge "Crate downloads"
+[downloads_img]: https://img.shields.io/crates/dv/bitvec.svg?style=for-the-badge "Crate downloads"
 [license_file]: https://github.com/bitvecto-rs/bitvec/blob/main/LICENSE.txt "Project license"
 [license_img]: https://img.shields.io/crates/l/bitvec.svg?style=for-the-badge "License badge"
-[loc]: https://github.com/bitvecto-rs/bitvec "Project repository"
-[loc_img]: https://img.shields.io/tokei/lines/github/bitvecto-rs/bitvec?category=code&style=for-the-badge "Project size"
+[msrv_img]: https://img.shields.io/badge/MSRV-1.56-f46623?style=for-the-badge&logo=rust "Minimum Supported Rust Version: 1.56"
 
 <!-- Documentation -->
 [`BitArray`]: https://docs.rs/bitvec/latest/bitvec/array/struct.BitArray.html
@@ -411,7 +408,6 @@ does, how it works, and how it can be useful to you.
 [`field`]: https://docs.rs/bitvec/latest/bitvec/field/index.html
 [`order`]: https://docs.rs/bitvec/latest/bitvec/order/index.html
 [`store`]: https://docs.rs/bitvec/latest/bitvec/store/index.html
-[layout]: https://bitvecto-rs.github.io/bitvec/memory-representation
 [prelude]: https://docs.rs/bitvec/latest/bitvec/prelude
 
 <!-- External References -->

book/memory-model.md

@@ -201,24 +201,24 @@ memory through them do not conflict with each other.
 ### Bit Slice Domains
 
 The in-memory domain of any bit slice can be generalized to one of two formats:
-either the slice touches zero element edges, or it touches at least one edge
-element. Consider three bytes of memory (any element will do, but the extra
-width on this page is unnecessary), with some bitslice regions drawn within
-them:
+either the slice touches zero edge-bits (`0` or `T::BITS - 1`), or it touches at
+edge-bit in at least one element. Consider three bytes of memory (any element
+will do, but the extra width on this page is unnecessary), with some bitslice
+regions drawn within them:
 
 ```text
-|00000000│11111111│22222222|
-|76543210│76543210│76543210│
+|00000000│11111111│22222222| Element
+|76543210│76543210│76543210│ Bit
 ├────────┼────────┼────────┤
-│        │        │        │ 1
-│        ╞════╡   │        │ 2
-│        │ ╞════╡ │        │ 3
-│        │   ╞════╡        │ 4
-│    ╞═══╪════╡   │        │ 5
-│    ╞═══╪════════╡        │ 6
-│        ╞════════╪═══╡    │ 7
-│    ╞═══╪════════╪═══╡    │ 8
-╞════════╪════════╪════════╡ 9
+┆        ┆        ┆        ┆ 1
+┆        ╞═════╡  ┆        ┆ 2
+┆        ┆ ╞════╡ ┆        ┆ 3
+┆        ┆  ╞═════╡        ┆ 4
+┆   ╞═════════╡   ┆        ┆ 5
+┆    ╞════════════╡        ┆ 6
+┆        ╞═════════════╡   ┆ 7
+┆     ╞═════════════════╡  ┆ 8
+╞══════════════════════════╡ 9
 ```
 
 There are nine example slices here, but they can be reduced into six specific

doc/mem/BitElement.md

@@ -8,10 +8,10 @@ syntax to turn an integer fundamental into the final type.
 This provides a `const fn BitElement::<_>::new(R) -> Self;` function,
 implemented only for the `BitStore` implementors that the crate provides, that
 the constructor macros can use to turn integers into final values without using
-[`mem::transmute`][0]. While `transmute` is acceptable in this case (the types
-are all `#[repr(transparent)]`), it is still better avoided where possible.
+[`mem::transmute`]. While `transmute` is acceptable in this case (the types are
+all `#[repr(transparent)]`), it is still better avoided where possible.
 
 As this is a macro assistant, it is publicly exposed, but is not public API. It
 has no purpose outside of the crate’s macros.
 
-[0]: core::mem::transmute.
+[`mem::transmute`]: core::mem::transmute.

src/domain.rs

@@ -352,6 +352,7 @@ Only `Domain<Const>` and `Domain<Mut>` are ever constructed, and they of course
 are only constructed from `&BitSlice` and `&mut BitSlice`, respectively.
 
 However, the Rust trait system does not have a way to express a closed set, so
+this has to be spelled out explicitly in the trait bounds.
 **/
 impl<'a, M, T, O> Domain<'a, M, T, O>
 where

src/field/io.rs

@@ -78,7 +78,7 @@ where
 	fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 		let bytes_read = self.as_bitslice().read(buf)?;
 		let bits = bytes_read * bits_of::<u8>();
-		self.shift_left(bits);
+		self.shift_start(bits);
 		self.truncate(self.len() - bits);
 		Ok(bytes_read)
 	}

src/index.rs

@@ -612,7 +612,7 @@ where R: BitRegister
 {
 	/// The position value of the most significant bit in an `R` element.
 	pub const MAX: Self = Self {
-		pos: R::MASK as u8,
+		pos: R::MASK,
 		_ty: PhantomData,
 	};
 	/// The position value of the least significant bit in an `R` element.
@@ -787,7 +787,7 @@ where R: BitRegister
 			sel.count_ones() == 1,
 			"Selections are required to have exactly one bit set: {:0>1$b}",
 			sel,
-			bits_of::<R>() as usize,
+			bits_of::<R>(),
 		);
 		Self { sel }
 	}
@@ -821,7 +821,7 @@ where R: BitRegister
 {
 	#[inline]
 	fn fmt(&self, fmt: &mut Formatter) -> fmt::Result {
-		write!(fmt, "{:0>1$b}", self.sel, bits_of::<R>() as usize)
+		write!(fmt, "{:0>1$b}", self.sel, bits_of::<R>())
 	}
 }
 
@@ -949,7 +949,7 @@ where R: BitRegister
 {
 	#[inline]
 	fn fmt(&self, fmt: &mut Formatter) -> fmt::Result {
-		write!(fmt, "{:0>1$b}", self.mask, bits_of::<R>() as usize)
+		write!(fmt, "{:0>1$b}", self.mask, bits_of::<R>())
 	}
 }
 

src/slice.rs

@@ -1471,7 +1471,7 @@ where
 	/// assert_eq!(bits, bits![0; 2]);
 	/// ```
 	#[inline]
-	pub fn shift_left(&mut self, by: usize) {
+	pub fn shift_start(&mut self, by: usize) {
 		if by == 0 {
 			return;
 		}
@@ -1493,6 +1493,14 @@ where
 		}
 	}
 
+	#[inline]
+	#[doc(hidden)]
+	#[allow(deprecated)]
+	#[deprecated(note = "Use `.shift_start()` instead", since = "1.1.0")]
+	pub fn shift_left(&mut self, by: usize) {
+		self.shift_start(by);
+	}
+
 	/// Shifts the contents of a bit-slice “right” (away from the zero-index),
 	/// clearing the “left” bits to `0`.
 	///
@@ -1529,7 +1537,7 @@ where
 	/// assert_eq!(bits, bits![0; 2]);
 	/// ```
 	#[inline]
-	pub fn shift_right(&mut self, by: usize) {
+	pub fn shift_end(&mut self, by: usize) {
 		if by == 0 {
 			return;
 		}
@@ -1550,6 +1558,14 @@ where
 			self.get_unchecked_mut(.. by).fill(false);
 		}
 	}
+
+	#[inline]
+	#[doc(hidden)]
+	#[allow(deprecated)]
+	#[deprecated(note = "Use `.shift_end() instead", since = "1.1.0")]
+	pub fn shift_right(&mut self, by: usize) {
+		self.shift_end(by);
+	}
 }
 
 /// Crate internals.

src/slice/specialization/lsb0.rs

@@ -168,7 +168,7 @@ where T: BitStore
 				let dead_bits =
 					bits_of::<T::Mem>() - elem.tail().into_inner() as usize;
 				if has_one(val, elem.mask().into_inner()) {
-					out -= val.leading_zeros() as usize - dead_bits as usize;
+					out -= val.leading_zeros() as usize - dead_bits;
 					return Some(out - 1);
 				}
 				None
@@ -259,7 +259,7 @@ where T: BitStore
 				let dead_bits =
 					bits_of::<T::Mem>() - elem.tail().into_inner() as usize;
 				if has_zero(val, elem.mask().into_inner()) {
-					out -= val.leading_ones() as usize - dead_bits as usize;
+					out -= val.leading_ones() as usize - dead_bits;
 					return Some(out - 1);
 				}
 				None

src/slice/specialization/msb0.rs

@@ -165,7 +165,7 @@ where T: BitStore
 				let dead_bits =
 					bits_of::<T::Mem>() - elem.tail().into_inner() as usize;
 				if has_one(val, elem.mask().into_inner()) {
-					out -= val.trailing_zeros() as usize - dead_bits as usize;
+					out -= val.trailing_zeros() as usize - dead_bits;
 					return Some(out);
 				}
 				None

src/slice/tests.rs

@@ -216,14 +216,14 @@ fn bit_counting() {
 #[test]
 fn shunting() {
 	let bits = bits![mut 0, 1, 0, 0, 1];
-	bits.shift_left(0);
-	bits.shift_right(0);
+	bits.shift_start(0);
+	bits.shift_end(0);
 	assert_eq!(bits, bits![0, 1, 0, 0, 1]);
 
 	let bits = bits![mut 1;5];
-	bits.shift_left(1);
-	bits.shift_right(2);
-	bits.shift_left(1);
+	bits.shift_start(1);
+	bits.shift_end(2);
+	bits.shift_start(1);
 	assert_eq!(bits, bits![0, 1, 1, 1, 0]);
 }
 

src/slice/traits.rs

@@ -381,7 +381,7 @@ where
 	#[inline]
 	fn fmt(&self, fmt: &mut Formatter) -> fmt::Result {
 		fmt.debug_list()
-			.entries(self.iter().by_vals().map(|b| if b { 1 } else { 0 }))
+			.entries(self.iter().by_vals().map(|b| b as u8))
 			.finish()
 	}
 }