custom-number
Custom numbers based on custom positional (numeral) systems.
Table of Contents
About
Why
There are times, where we need to iterate over an X amount of possible combinations of values over a specific number or a specific string etc.
(iterators, rainbow tables, numeral system converters)
For example, if you have an identifier that can contain values that are either 0-9 and a-z and A-Z and you would want to know each possible
combination.
Your base (or radix) is the amount of possible values a digit can have. In this example:
0-9 : 10
a-z : 26
A-Z : 26
That means that the base of the numeral system is 62. The possible values of a digit are:
0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
Now, if you wanted to find all the possible combinations of numbers, for 4 digits, for the above example you would want to iterate from:
0000 to ZZZZ
These are 916.132.832 different possible combinations.
How
A numeral is a symbol or group of symbols that represents a number. Numerals are not the
same as numbers just as words are not the same with the things they refer to. The symbols "11", "1011" and "B"
are different numerals, all representing the same number.
A numeral system (or system of numeration) is a framework where a set of numbers are
represented by numerals in a consistent manner. It can be seen as the context that allows the numeral "11" to be interpreted
as the binary numeral for three, the decimal numeral for eleven, or other numbers in different bases.
Ideally, such a system will:
-
Represent a useful set of numbers (e.g. all whole numbers, integers, or real numbers)
-
Give every number represented a unique representation (or at least a standard representation)
-
Reflect the algebraic and arithmetic structure of the numbers.
In mathematical numeral systems the base or radix is usually the number of unique digits, including zero, that a positional numeral system uses to represent numbers.
For example, for the decimal system the radix is 10, because it uses the 10 digits from 0 through 9.
When a number "hits" 9, the next number will not be another different symbol, but a "1" followed by a "0".
In binary, the radix is 2, since after it hits "1", instead of "2" or another written symbol, it jumps straight to "10", followed by "11" and "100".
The highest symbol of a positional numeral system usually has the value one less than the value of the base of that numeral system.
The standard positional numeral systems differ from one another only in the base they use.
The base is an integer that is greater than 1 (or less than negative 1), since a radix of zero would not have any digits, and a radix of 1 would only have the zero digit. Negative bases are rarely used.
In base-10 (decimal) positional notation, there are 10 decimal digits and the number
In base-16 (hexadecimal), there are 16 hexadecimal digits (0–9 and A–F) and the number
(where B represents the number eleven as a single symbol)
In general, in base-b, there are b digits and the number
(Note that represents a sequence of digits, not multiplication)
What
This library, customnumber provides the ability to create custom positional numeral systems in an efficient and performant way.
You can create custom numbers based on custom numeral systems and use them at will.
All you need is the possible values of a digit (e.g. 0123456789ABCDEF) and an initial number (e.g. 14FF)
To implement our HOW we utilize 2 standard library packages:
Each digit represented as a circular list that contains the all the possible numerals.
Each number is represented as a doubly linked list of circular lists.
When a digit rotates back to it's first digit as a result of an addition, then an arithmetic holding is generated
and because of the doubly linked list it rotates the next, in weight digit, once. The opposite thing happens when a subtraction is happening.
Getting Started
All you need is at least GO 1.13
Usage
Get the package
go get github.com/slysterous/custom-number
Then all you need to do is create a custom number
// create a slice of runes.
digitValues := []rune{'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'}
number := customnumber.NewNumber(digitValues, "128z")
// will make the number 1290.
number.Increment()
// will make the number 128y.
number.Decrement()
//will give you the string representation of the number.
strnumber:=number.String()
Make Utilities
ci run ci
fmt gofmt all files excluding vendor
lint perform linting
test run tests
Contributing
Refer to Contributing.
Report bugs using Github's issues
We use GitHub issues to track public bugs. Report a bug by opening a new issue;
License
This library is distributed under the MIT license found in the LICENSE
file.