README
¶
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.
Documentation
¶
Overview ¶
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.
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.
Example
// 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")
// 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()
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Numeral ¶
type Numeral struct {
// contains filtered or unexported fields
}
Numeral represents a numeral that is consisted by its digits and digit values.
func Diff ¶
Diff returns the absolute difference between two numerals
Example ¶
package main
import (
"fmt"
"github.com/slysterous/numeral"
)
func main() {
testValues := []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'}
num, err := numeral.NewFromDecimal(testValues, 22)
if err != nil {
//handle the error
}
num2, err := numeral.NewFromDecimal(testValues, 12)
if err != nil {
//handle error
}
num3, err := numeral.Diff(testValues, *num2, *num)
if err != nil {
//handle error
}
fmt.Printf("decimal result should be 10, number: %d", num3.Decimal())
}
Output:
func NewFromDecimal ¶
NewFromDecimal creates a numeral from a decimal integer.
Example ¶
package main
import (
"fmt"
"github.com/slysterous/numeral"
)
func main() {
testValues := []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.NewFromDecimal(testValues, 100)
fmt.Printf("numeral: %v", number)
}
Output:
func NewNumeral ¶
NewNumeral initializes a numeral by providing the initial number in strings along with the possible values that each digit can have.
Example ¶
package main
import (
"fmt"
"github.com/slysterous/numeral"
)
func main() {
testValues := []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(testValues, "100")
fmt.Printf("numeral: %v", number)
}
Output:
func Sum ¶
Sum sums 2 numerals into a 3rd one. Values are needed to define the new system under which the number will be displayed. Every number can be from a different system.
Example ¶
package main
import (
"fmt"
"github.com/slysterous/numeral"
)
func main() {
testValues := []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'}
number1, err := numeral.NewNumeral(testValues, "100")
if err != nil {
//handle the error
}
number2, err := numeral.NewNumeral(testValues, "100")
if err != nil {
//handle the error
}
sum, err := numeral.Sum(testValues, *number1, *number2)
if err != nil {
//handle the error
}
fmt.Printf("sum is: %s", sum.String())
}
Output:
func (*Numeral) Add ¶
Add adds a number to the already existing number
Example ¶
package main
import (
"github.com/slysterous/numeral"
)
func main() {
testValues := []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, err := numeral.NewNumeral(testValues, "123z")
if err != nil {
//handle the error
}
num2, err := numeral.NewFromDecimal(testValues, 1)
if err != nil {
//handle error
}
err = number.Add(*num2)
if err != nil {
//handle error
}
}
Output:
func (*Numeral) Decimal ¶
Decimal converts a numeral to a decimal integer.
Example ¶
package main
import (
"fmt"
"github.com/slysterous/numeral"
)
func main() {
testValues := []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(testValues, "100")
dec := number.Decimal()
fmt.Printf("%d", dec)
}
Output: 1296
func (*Numeral) Decrement ¶
Decrement performs a -1 to the Numeral.
Example ¶
package main
import (
"fmt"
"github.com/slysterous/numeral"
)
func main() {
testValues := []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(testValues, "1230")
err := number.Decrement()
if err != nil {
// do whatever you need with the error
}
fmt.Printf(number.String())
}
Output: 122z
func (*Numeral) Increment ¶
Increment performs a +1 to the Numeral.
Example ¶
package main
import (
"fmt"
"github.com/slysterous/numeral"
)
func main() {
testValues := []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(testValues, "123z")
number.Increment()
fmt.Printf(number.String())
}
Output: 1240
func (Numeral) String ¶
String returns a string representation of Numeral.
Example ¶
package main
import (
"fmt"
"github.com/slysterous/numeral"
)
func main() {
testValues := []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, err := numeral.NewFromDecimal(testValues, 2021)
if err != nil {
//handle the err
}
fmt.Printf("numeral as a string representation: %s", number.String())
}
Output:
Source Files