doc number vs integer

Author: 1pkg

README.MD

@@ -1,3 +1,11 @@
+# VarInt: fast & memory efficient arbitrary bit length integers.
+
+## Introduction
+
+## Examples
+
+## Benchmarks
+
 ## Licence
 
 VarInt is licensed under the MIT License.  

bits.go

@@ -13,7 +13,7 @@ import (
 // b62digits const preallocated alphabet.
 const b62digits = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
 
-// Bits is immutable intermediate representation for single number inside VarInt.
+// Bits is immutable intermediate representation for single integer inside VarInt.
 // It's used as data transfer object for most of VarInt operations, and
 // provides a number of convenient methods to convert it back and forth
 // between other numerical presentations. Bits type somewhat resembles

support_test.go

@@ -115,13 +115,13 @@ func TestSortable(t *testing.T) {
 		sort.Sort(Sortable(vint))
 		for i, j := 0, 1; i < len-1; i, j = i+1, j+1 {
 			bi, bj := h.VarIntGet(i), h.VarIntGet(j)
-			// Numbers could be equal too.
+			// Integers could be equal too.
 			h.Equal(Compare(bi, bj) <= 0, true)
 		}
 		sort.Sort(sort.Reverse(Sortable(vint)))
 		for i, j := 0, 1; i < len-1; i, j = i+1, j+1 {
 			bi, bj := h.VarIntGet(i), h.VarIntGet(j)
-			// Numbers could be equal too.
+			// Integers could be equal too.
 			h.Equal(Compare(bi, bj) >= 0, true)
 		}
 	})

varinit.go

@@ -5,30 +5,30 @@ import math_bits "math/bits"
 // wsize const alias to system uint word size in bits.
 const wsize = math_bits.UintSize
 
-// VarInt defines the memory efficient unsigned numeric array type that provides
-// basic arithmetic and bitwise operations on variadic bit length numbers. The purpose
-// of VarInt to provide the memory optimal way to use unsigned custom bit len numbers.
-// It does so by storing all the numbers adjacent to each other inside
+// VarInt defines the memory efficient unsigned integer array type that provides
+// basic arithmetic and bitwise operations on arbitrary variadic bit length integers.
+// The purpose of VarInt to provide the memory optimal way to use unsigned custom bit len integers.
+// It does so by storing all the integers adjacent to each other inside
 // continuous numeric bytes slice. To function, it allocates the underlying
 // numeric bytes slice only once on creation and doesn't expect to allocate
 // any more new memory for any of its operations thereafter. To apply any
 // of its operations, some bits manipulations are required which implies
 // some computational overhead. Thus providing a tradeoff between CPU time and memeory.
 // Overhead grows lineraly proportionally to bit len and comparable with overhead
 // provided by big.Int type operations. Unlike big.Int however, VarInt uses exact number
-// of bits to store the numbers inside. Which makes VarInt extremely memory efficient. For example,
-// to store a slice of 100 number 100 bit each, big.Int requires 12400 bits while
+// of bits to store the integers inside. Which makes VarInt extremely memory efficient. For example,
+// to store a slice of 100 integers 100 bit each, big.Int requires 12400 bits while
 // VarInt needs exactly 10000 bits (excluding fixed internal overhead).
-// In the same way VarInt also provides the efficient way to store numbers smaller than 64 bits.
-// For example, to store a slice of 1000 number 2 bit each, []uin8 requires 8000 bits
+// In the same way VarInt also provides the efficient way to store integers smaller than 64 bits.
+// For example, to store a slice of 1000 integers 2 bit each, []uin8 requires 8000 bits
 // while VarInt needs exactly 2000 bits (excluding fixed internal overhead).
 // Note however, that VarInt is no way close to be optimized as well as big.Int, and
-// provides a diminishing returns as bit length grows above certain threshold. Currently,
+// provides diminishing returns as bit length grows above certain threshold. Currently,
 // in a conscious decision multiple operations implemented in favor of simplicity and
 // not computational complexity, this includes Mul that uses standard long multiplication
 // instead of fast multiplication algorithms like Karatsuba multiplication, and Div that
 // uses standard slow division instead of fast division algorithms. The main rationale behind
-// the choice is the fact that VarInt has the most efficiency when used for small and medium size numbers
+// the choice is the fact that VarInt has the most efficiency when used for small and medium size integers
 // in the range of 1 to 5000 bits, therefore asymptotic complexity should have less of impact.
 // VarInt carries a small fixed overhead internaly, it allocates 2 separate uint cells at the beginning
 // of the numeric bytes slice to store length and bit length somewhere. It also collocates extra Bits
@@ -41,7 +41,7 @@ const wsize = math_bits.UintSize
 type VarInt []uint
 
 // NewVarInt allocates and returns VarInt instance that is capable to
-// fit the provided len number of items each of the provided bit len in size.
+// fit the provided number of integers each of the provided bit len in width.
 // In case the provided bit len is not positive, invalid number and ErrorBitLengthIsNotPositive is returned.
 // In case the len is not positive, invalid number and ErrorLengthIsNotPositive is returned.
 // In case the provided bit len is larger than predefined threshold of 4096,
@@ -56,7 +56,7 @@ func NewVarInt(blen, len int) (VarInt, error) {
 	if len <= 0 {
 		return nil, ErrorLengthIsNotPositive
 	}
-	// Calculate capacity to fit all numbers with
+	// Calculate capacity to fit all integers with
 	// provided bit length and capacity.
 	cap := (blen*len+wsize-1)/wsize + 2
 	// Calculate number of whole words plus
@@ -85,7 +85,7 @@ func NewVarInt(blen, len int) (VarInt, error) {
 	}
 }
 
-// Get sets the provided bits to the number inside VarInt at the provided index.
+// Get sets the provided bits to the integer inside VarInt at the provided index.
 // It never allocates new Bits, the provided Bits are expected to be preallocated by the caller.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
@@ -143,7 +143,7 @@ func (vint VarInt) Get(i int, bits Bits) error {
 	return nil
 }
 
-// Set sets the provided bits into the number inside VarInt at the provided index.
+// Set sets the provided bits into the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
 // In case the provided index is greater than len of VarInt, ErrorIndexIsOutOfRange is returned.
@@ -207,7 +207,7 @@ func (vint VarInt) Set(i int, bits Bits) error {
 	return nil
 }
 
-// GetSet swaps the provided bits with the number inside VarInt at the provided index.
+// GetSet swaps the provided bits with the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
 // In case the provided index is greater than len of VarInt, ErrorIndexIsOutOfRange is returned.
@@ -277,7 +277,7 @@ func (vint VarInt) GetSet(i int, bits Bits) error {
 	return nil
 }
 
-// Add adds the provided bits to the number inside VarInt at the provided index.
+// Add adds the provided bits to the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
 // In case the provided index is greater than len of VarInt, ErrorIndexIsOutOfRange is returned.
@@ -373,12 +373,12 @@ func (vint VarInt) Add(i int, bits Bits) error {
 	return nil
 }
 
-// Sub subtracts the provided bits from the number inside VarInt at the provided index.
+// Sub subtracts the provided bits from the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
 // In case the provided index is greater than len of VarInt, ErrorIndexIsOutOfRange is returned.
 // In case the provided bits has different bit len, ErrorUnequalBitLengthCardinality is returned.
-// In case the subtraction result underflows the number, the regular unsigned semantic applies and
+// In case the subtraction result underflows the integer, the regular unsigned semantic applies and
 // extra ErrorSubtractionUnderflow warning is returned.
 func (vint VarInt) Sub(i int, bits Bits) error {
 	// Check explicitly for invalid number.
@@ -460,12 +460,12 @@ func (vint VarInt) Sub(i int, bits Bits) error {
 	return nil
 }
 
-// Mul multiplies the provided bits with the number inside VarInt at the provided index.
+// Mul multiplies the provided bits with the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
 // In case the provided index is greater than len of VarInt, ErrorIndexIsOutOfRange is returned.
 // In case the provided bits has different bit len, ErrorUnequalBitLengthCardinality is returned.
-// In case the multiplication result overflows the bit len, the number is trucated and
+// In case the multiplication result overflows the bit len, the integer is trucated and
 // extra ErrorMultiplicationOverflow warning is returned.
 func (vint VarInt) Mul(i int, bits Bits) error {
 	// Check explicitly for invalid number.
@@ -550,15 +550,15 @@ func (vint VarInt) Mul(i int, bits Bits) error {
 		}
 	}
 	// After multiplication is done set bits var
-	// back to i-th number and check for any error.
+	// back to i-th integer and check for any error.
 	_ = vint.Set(i, bvar)
 	if overflow {
 		return ErrorMultiplicationOverflow
 	}
 	return nil
 }
 
-// Div divides the provided bits with the number inside VarInt at the provided index.
+// Div divides the provided bits with the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
 // In case the provided index is greater than len of VarInt, ErrorIndexIsOutOfRange is returned.
@@ -622,7 +622,7 @@ func (vint VarInt) Div(i int, bits Bits) error {
 	return nil
 }
 
-// Mod applies modulo operation to the provided bits and the number inside VarInt at the provided index.
+// Mod applies modulo operation to the provided bits and the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
 // In case the provided index is greater than len of VarInt, ErrorIndexIsOutOfRange is returned.
@@ -637,12 +637,12 @@ func (vint VarInt) Mod(i int, bits Bits) error {
 		return err
 	}
 	// Get tmp bits variable with reminder inise,
-	// don't clear the previous and swap it with vint number.
+	// don't clear the previous and swap it with vint.
 	_ = vint.GetSet(i, bvar(vint, false))
 	return nil
 }
 
-// Not applies bitwise negation ^ operation to the number inside VarInt at the provided index.
+// Not applies bitwise negation ^ operation to the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
 // In case the provided index is greater than len of VarInt, ErrorIndexIsOutOfRange is returned.
@@ -700,7 +700,7 @@ func (vint VarInt) Not(i int) error {
 	return nil
 }
 
-// And applies bitwise and & operation to the provided bits and the number inside VarInt at the provided index.
+// And applies bitwise and & operation to the provided bits and the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
 // In case the provided index is greater than len of VarInt, ErrorIndexIsOutOfRange is returned.
@@ -764,7 +764,7 @@ func (vint VarInt) And(i int, bits Bits) error {
 	return nil
 }
 
-// Or applies bitwise and | operation to the provided bits and the number inside VarInt at the provided index.
+// Or applies bitwise and | operation to the provided bits and the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
 // In case the provided index is greater than len of VarInt, ErrorIndexIsOutOfRange is returned.
@@ -828,7 +828,7 @@ func (vint VarInt) Or(i int, bits Bits) error {
 	return nil
 }
 
-// Xor applies bitwise and ^ operation to the provided bits and the number inside VarInt at the provided index.
+// Xor applies bitwise and ^ operation to the provided bits and the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
 // In case the provided index is greater than len of VarInt, ErrorIndexIsOutOfRange is returned.
@@ -892,7 +892,7 @@ func (vint VarInt) Xor(i int, bits Bits) error {
 	return nil
 }
 
-// Rsh applies right shift >> operation to the number inside VarInt at the provided index.
+// Rsh applies right shift >> operation to the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative shift is provided, ErrorShiftIsNegative is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.
@@ -976,7 +976,7 @@ loop:
 	return nil
 }
 
-// Lsh applies left shift << operation to the number inside VarInt at the provided index.
+// Lsh applies left shift << operation to the integer inside VarInt at the provided index.
 // In case the operation is used on invalid nil VarInt, ErrorVarIntIsInvalid is returned.
 // In case negative shift is provided, ErrorShiftIsNegative is returned.
 // In case negative index is provided, ErrorIndexIsNegative is returned.

varint_test.go

@@ -511,7 +511,7 @@ func FuzzVarIntLsh(f *testing.F) {
 
 func BenchmarkVarIntOperations(b *testing.B) {
 	bench("Benchmark Arithmetic", b, func(b *testing.B) {
-		bench("Tiny Numbers", b, func(b *testing.B) {
+		bench("Tiny Integers", b, func(b *testing.B) {
 			const len, blen = 100000000, 4
 			bench("VarInt Operations", b, func(b *testing.B) {
 				vint, _ := NewVarInt(blen, len)
@@ -543,7 +543,7 @@ func BenchmarkVarIntOperations(b *testing.B) {
 				}
 			})
 		})
-		bench("Word 64 Bits Numbers", b, func(b *testing.B) {
+		bench("Word 64 Bits Integers", b, func(b *testing.B) {
 			const len, blen = 10000000, 64
 			bench("VarInt Operations", b, func(b *testing.B) {
 				vint, _ := NewVarInt(blen, len)
@@ -575,7 +575,7 @@ func BenchmarkVarIntOperations(b *testing.B) {
 				}
 			})
 		})
-		bench("Medium Large Numbers", b, func(b *testing.B) {
+		bench("Medium Large Integers", b, func(b *testing.B) {
 			const len, blen = 10000000, 100
 			bench("VarInt Operations", b, func(b *testing.B) {
 				vint, _ := NewVarInt(blen, len)
@@ -611,7 +611,7 @@ func BenchmarkVarIntOperations(b *testing.B) {
 				}
 			})
 		})
-		bench("Big Large Numbers", b, func(b *testing.B) {
+		bench("Big Large Integers", b, func(b *testing.B) {
 			const len, blen = 100000, 10000
 			bench("VarInt Operations", b, func(b *testing.B) {
 				vint, _ := NewVarInt(blen, len)
@@ -649,7 +649,7 @@ func BenchmarkVarIntOperations(b *testing.B) {
 		})
 	})
 	bench("Benchmark Binary Operations", b, func(b *testing.B) {
-		bench("Tiny Numbers", b, func(b *testing.B) {
+		bench("Tiny Integers", b, func(b *testing.B) {
 			const len, blen = 100000000, 4
 			bench("VarInt Operations", b, func(b *testing.B) {
 				vint, _ := NewVarInt(blen, len)
@@ -677,7 +677,7 @@ func BenchmarkVarIntOperations(b *testing.B) {
 				}
 			})
 		})
-		bench("Word 64 Bits Numbers", b, func(b *testing.B) {
+		bench("Word 64 Bits Integers", b, func(b *testing.B) {
 			const len, blen = 10000000, 64
 			bench("VarInt Operations", b, func(b *testing.B) {
 				vint, _ := NewVarInt(blen, len)
@@ -705,7 +705,7 @@ func BenchmarkVarIntOperations(b *testing.B) {
 				}
 			})
 		})
-		bench("Medium Large Numbers", b, func(b *testing.B) {
+		bench("Medium Large Integers", b, func(b *testing.B) {
 			const len, blen = 10000000, 100
 			bench("VarInt Operations", b, func(b *testing.B) {
 				vint, _ := NewVarInt(blen, len)
@@ -737,7 +737,7 @@ func BenchmarkVarIntOperations(b *testing.B) {
 				}
 			})
 		})
-		bench("Big Large Numbers", b, func(b *testing.B) {
+		bench("Big Large Integers", b, func(b *testing.B) {
 			const len, blen = 100000, 10000
 			bench("VarInt Operations", b, func(b *testing.B) {
 				vint, _ := NewVarInt(blen, len)