From d25f21518c77c8b61a8f0451cbb69c46964d03d5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oscar=20Bystr=C3=B6m=20Ericsson?= <oscbyspro@protonmail.com>
Date: Mon, 8 Jul 2024 06:39:52 +0200
Subject: [PATCH] [README] Count<Layout> and BitCountable.

---
 README.md                          | 20 ++++++++++++++++++++
 Sources/CoreKit/BitCountable.swift |  2 +-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 0f8b42cc..13bea019 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@
   - [Upsize binary integer elements with DataInt\<U8\>](#corekit-upsize)
   - [Lightweight text decoding and encoding with TextInt](#corekit-text-int)
   - [Type-safe bit casts with BitCastable\<BitPattern\>](#corekit-bit-cast)
+  - [Bit counting with Count\<Layout\> and BitCountable](#corekit-bit-count)
   - [Generic logic gates with BitOperable](#corekit-bitwise-logic)
   - [More ones and zeros with Bit, Sign and Signum](#corekit-bit-sign-signum)
 * [DoubleIntKit](#doubleintkit)
@@ -394,6 +395,25 @@ via the init(raw:) bulk operation. Note that such type relationships are generic
 to all binary integers. Also, note that this method is both fully generic and fully recoverable.
 The init(load:) method is similar, but it returns the bit pattern that fits.
 
+<a name="corekit-bit-count"/>
+
+#### Bit counting with Count\<Layout\> and BitCountable
+
+> Please roll a **D20** arcana check.
+
+An arbitrary binary integer's bit pattern extends infinitely, yet its bit pattern has an end.
+Count\<IX\> is a pointer-bit model that can count the bits of any binary integer stored in memory.
+It does this by reinterpreting the last bit as logarithmically infinite.
+
+```
+min ..< msb: [0,  IX.max + 0]
+msb ... max: [∞ - IX.max,  ∞] ≤ log2(UXL.max + 1)
+```
+
+All binary integer types and all data integer types let you perform bit-counting operations; 
+the BitCountable protocol unifies them. Their common protocol requires methods like *size()* 
+and *ascending(\_:)* then derives methods like *entropy()* and *nonascending(\_:)* for them.
+
 <a name="corekit-bitwise-logic"/>
 
 #### Generic logic gates with BitOperable
diff --git a/Sources/CoreKit/BitCountable.swift b/Sources/CoreKit/BitCountable.swift
index 1bc85fb3..2ea9f4d9 100644
--- a/Sources/CoreKit/BitCountable.swift
+++ b/Sources/CoreKit/BitCountable.swift
@@ -61,7 +61,7 @@ public protocol BitCountable {
     ///
     /// - Invariant: `count(x) + noncount(x) == size()`
     ///
-    @inlinable func size() -> Count<IX>
+    @inlinable borrowing func size() -> Count<IX>
     
     /// The `bit` count in `self`.
     ///