diff --git a/README.md b/README.md index 2e88bc127..6d8e254dc 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,29 @@ 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 +--- + +> [!NOTE] +> The [count_digits()](https://docs.rs/count-digits/latest/count_digits/trait.CountDigits.html#tymethod.count_digits) +> and [count_digits_radix(10)](https://docs.rs/count-digits/latest/count_digits/trait.CountDigits.html#tymethod.count_digits_radix) +> functions do not include the negative sign in their counts. + +```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. +> [!NOTE] +> Negative numbers counted in base-10 are counted differently than +> negative numbers counted in other number bases. -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 +54,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 +87,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