numeral

numerals based on custom positional (numeral) systems.

📝 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)

You might also need to have custom numerals and perform basic operations on them.

♟️ Numeral Positional Systems

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(decimal)", "1011(binary)" and "B(hexadecimal)" are different numerals, all representing the same number. The number is the idea, the numeral is anything that represents that idea.

A positional numeral system denotes usually the extension to any base of the Hindu–Arabic numeral system (or decimal system). In a more general sense, a positional system is a numeral system in which the contribution of a digit to the value of a number is the value of the digit multiplied by a factor determined by the position of the digit.

In modern positional systems, such as the decimal system, the position of the digit means that its value must be multiplied by some value: in 555, the three identical symbols represent five hundreds, five tens, and five units, respectively, due to their different positions in the digit string.

According to its position of occurrence in the number, each digit is weighted. Towards the left, the weights increase by a constant factor equivalent to the base or radix. With the help of the radix point ('.'), the positions corresponding to integral weights (1) are differentiated from the positions corresponding to fractional weights (<1).

Any integer value that is greater than or equal to two can be used as the base or radix.  The digit position 'n' has weight r ^n. The largest value of digit position is always 1 less than the base value. The value of a number is a weighted sum of its digits. For example:

Decimal (0–9 digits with radix 10) 2056 value breakdown

Hexadecimal(0–9 & A-F digits with radix 16) 171B value breakdown

The general form of value breakdown, where b is the base or radix of the numeral system

✨ The Package

This package, numeral provides the ability to create custom positional numeral systems in an efficient and performant way. You can create numerals 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:

• container/ring (circular list)
• container/list (doubly linked list)

Each digit represented as a circular list that contains the all the possible numeral.

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/numeral

Then all you need to do is create a numeral. For full reference on usage and available methods visit pkg.go.dev

// 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 := numeral.NewNumeral(digitValues, "128z")

number2, err := numeral.NewFromDecimal(digitValues, 150)


//will give you the string representation of the number.
strnumber:=number2.String()

//will give you the decimal integer representation of the number.
intnumber:=number.Decimal()

⛩️ 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.