From 1063a59ec97e1a40e39badb229cdfa528dd95ccd Mon Sep 17 00:00:00 2001
From: Erik Nordin <nordzillacode@gmail.com>
Date: Thu, 25 Jan 2024 23:40:00 -0600
Subject: [PATCH] Update README.md

---
 README.md | 58 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 45 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 2e88bc127..6bc245576 100644
--- a/README.md
+++ b/README.md
@@ -8,9 +8,9 @@ the digits of integer types in various number bases.
 Compatible with all primitive integer types and all non-zero integer types.
 
 #### Examples
+
 ```rust
 use count_digits::CountDigits;
-use core::num::NonZeroIsize;
 
 assert_eq!(16, 0b1111000000001101.count_bits());
 assert_eq!(16, 0b1111000000001101.count_digits_radix(2_u32));
@@ -23,20 +23,37 @@ assert_eq!(05, 61453.count_digits_radix(10_u32));
 
 assert_eq!(04, 0xF00D.count_hex_digits());
 assert_eq!(04, 0xF00D.count_digits_radix(16_u32));
-
-assert_eq!(
-  0xF00D_isize.count_digits(),
-  NonZeroIsize::new(0xF00D).unwrap().count_digits(),
-);
 ```
 
-##### Note
+---
+
+<div class="warning">
+The
+<a href="trait.CountDigits.html#tymethod.count_digits" title="method count_digits::CountDigits::count_digits">
+   count_digits()
+</a>
+and
+<a href="trait.CountDigits.html#tymethod.count_digits_radix" title="method count_digits::CountDigits::count_digits_radix">
+   count_digits_radix(10)
+</a>
+functions do not include the negative sign in their counts.
+</div>
+
+```rust
+assert_eq!(5, 12345_i32.wrapping_neg().count_digits());
+assert_eq!(5, 12345_i32.wrapping_neg().count_digits_radix(10));
+````
+
+---
 
-Be mindful with negative signed integers in non-decimal number bases.
+<div class="warning">
+    Negative numbers counted in base-10 are counted differently than
+    negative numbers counted in other number bases.
+</div>
 
-Since negative decimal numbers are represented with a negative sign,
-the decimal digit count of a negative number will be equal to its
-positive counterpart.
+Since negative, base-10 numbers are represented with a negative sign,
+the digit count of a positive, base-10 number will be equal to the count
+of its negated value.
 
 ```rust
 assert_eq!(
@@ -45,8 +62,10 @@ assert_eq!(
 );
 ````
 
-However, a negative number using a different radix will not have the
-same count of digits as its positive counterpart.
+However, the digit counts of negative numbers represented in other bases reflect the
+[twos-complement representation](https://en.wikipedia.org/wiki/Two%27s_complement),
+and the digit count of a positive number will _not_ be the same as the count
+of its negated value.
 
 ```rust
 assert_ne!(
@@ -76,4 +95,17 @@ for radix in 2..=16 {
 }
 ````
 
+These counts are consistent with the representations of Rust's display format.
+```rust
+assert_eq!(1, format!("{:b}",  1_i8).chars().count());
+assert_eq!(1, format!("{:o}",  1_i8).chars().count());
+assert_eq!(1, format!("{  }",  1_i8).chars().count());
+assert_eq!(1, format!("{:x}",  1_i8).chars().count());
+
+assert_eq!(8, format!("{:b}", -1_i8).chars().count());
+assert_eq!(3, format!("{:o}", -1_i8).chars().count());
+assert_eq!(1, format!("{  }", -1_i8).strip_prefix('-').unwrap().chars().count());
+assert_eq!(2, format!("{:x}", -1_i8).chars().count());
+````
+
 License: MIT