go-hexadeca/README.md

383 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# go-hexadeca
Package **hexadeca** implements **hexadecimal** _encoding_ and _decoding_, for the Go programming language.
This is meant to be a better alternative to Go's built-in `"hex"` package.
Package **hexadeca** has functions for hexadecimal encoding and decoding with Go types:
* `byte` (i.e., `uint8`),
* `uint16`,
* `uint32`
* `uint64`
* `int64`
## Documention
Online documentation, which includes examples, can be found at: http://godoc.org/sourcecode.social/reiver/go-hexadeca
[![GoDoc](https://godoc.org/sourcecode.social/reiver/go-hexadeca?status.svg)](https://godoc.org/sourcecode.social/reiver/go-hexadeca)
## Symbols
Package **hexadeca** lets you pick the 16 symbols to hexadecimal encode to and hexadecimal decode from.
Package **hexadeca** has built-in support for the following symbols:
| Name | zero | one | two | three | four | five | six | seven | eight | nine | ten | eleven | twelve | thirteen | fourteen | fifteen |
|------------|-------|-------|-------|-------|-------|-------|-------|-------|-------|-------|-------|--------|--------|----------|----------|---------|
| Lower-Case | `'0'` | `'1'` | `'2'` | `'3'` | `'4'` | `'5'` | `'6'` | `'7'` | `'8'` | `'9'` | `'a'` | `'b'` | `'c'` | `'d'` | `'e'` | `'f'` |
| Upper-Case | `'0'` | `'1'` | `'2'` | `'3'` | `'4'` | `'5'` | `'6'` | `'7'` | `'8'` | `'9'` | `'A'` | `'B'` | `'C'` | `'D'` | `'E'` | `'F'` |
| Persian | `'۰'` | `'۱'` | `'۲'` | `'۳'` | `'۴'` | `'۵'` | `'۶'` | `'۷'` | `'۸'` | `'۹'` | `'ی'` | `'ک'` | `'ل'` | `'م'` | `'ن'` | `'س'` |
Lower-Case Samples:
* `c0de`
* `4b1d`
Upper-Case Samples:
* `C0DE`
* `4b1d`
Persian Samples:
* `نم۰ل`
* `م۱ک۴`
### Custom Symbols
Package **hexadeca** also lets you use your own custom symbols by using your own symbol function:
```go
func CustomSymbol(value byte) rune {
var table [16]rune = [16]rune{
'𝍠', // 0
'𝍡', // 1
'𝍢', // 2
'𝍣', // 3
'𝍤', // 4
'𝍥', // 5
'𝍦', // 6
'𝍧', // 7
'𝍨', // 8
'𝍩', // 9
'𝍪', // 10
'𝍫', // 11
'𝍬', // 12
'𝍭', // 13
'𝍮', // 14
'𝍯', // 15
}
var index int = int(value) % len(table)
var result rune = table[index]
return result
}
// ...
r1, r0 := hexadeca.EncodeRune(value, CustomSymbol)
```
Samples:
* `𝍬𝍠𝍭𝍮`
* `𝍤𝍫𝍡𝍭`
## hexadecimal encode `byte`
To hexadecimal encode a `byte` use any of these:
```go
import "sourcecode.social/reiver/go-hexadeca/enc/bytes"
// ...
// value==254 -> mostSignificant=='f', leastSignificant=='e'
mostSignificant, leastSignificant := hexadecabytes.EncodeByteUsingLowerCaseSymbols(value)
// ...
// value==254 -> mostSignificant=='F', leastSignificant=='E'
mostSignificant, leastSignificant := hexadecabytes.EncodeByteUsingUpperCaseSymbols(value)
```
Or:
```go
import "sourcecode.social/reiver/go-hexadeca/enc/runes"
// ...
// value==254 -> mostSignificant=='f', leastSignificant=='e'
mostSignificant, leastSignificant := hexadecarunes.EncodeByteUsingLowerCaseSymbols(value)
// ...
// value==254 -> mostSignificant=='F', leastSignificant=='E'
mostSignificant, leastSignificant := hexadecarunes.EncodeByteUsingUpperCaseSymbols(value)
```
Or:
```go
import (
"sourcecode.social/reiver/go-hexadeca/enc/bytes"
"sourcecode.social/reiver/go-hexadeca/symbols/byte"
)
// ...
// value==254 -> mostSignificant=='f', leastSignificant=='e'
mostSignificant, leastSignificant := hexadecabytes.EncodeByte(value, bytesymbols.LowerCase)
// ...
// value==254 -> mostSignificant=='F', leastSignificant=='E'
mostSignificant, leastSignificant := hexadecabytes.EncodeByte(value, bytesymbols.UpperCase)
```
Or:
```go
import (
"sourcecode.social/reiver/go-hexadeca/enc/runes"
"sourcecode.social/reiver/go-hexadeca/symbols/rune"
)
// ...
// value==254 -> mostSignificant=='f', leastSignificant=='e'
mostSignificant, leastSignificant := hexadecarunes.EncodeByte(value, runesymbols.LowerCase)
// ...
// value==254 -> mostSignificant=='F', leastSignificant=='E'
mostSignificant, leastSignificant := hexadecarunes.EncodeByte(value, runesymbols.UpperCase)
```
## hexadecimal encode `uint16`
To hexadecimal encode a `uint16` use any of these:
```go
import "sourcecode.social/reiver/go-hexadeca/enc/bytes"
// ...
r3, r2, r1, r0 := hexadecabytes.EncodeUint16UsingLowerCaseSymbols(value)
// ...
r3, r2, r1, r0 := hexadecabytes.EncodeUint16UsingUpperCaseSymbols(value)
```
Or:
```go
import "sourcecode.social/reiver/go-hexadeca/enc/runes"
// ...
r3, r2, r1, r0 := hexadecarunes.EncodeUint16UsingLowerCaseSymbols(value)
// ...
r3, r2, r1, r0 := hexadecarunes.EncodeUint16UsingUpperCaseSymbols(value)
```
Or:
```go
import (
"sourcecode.social/reiver/go-hexadeca/enc/bytes"
"sourcecode.social/reiver/go-hexadeca/symbols/byte"
)
// ...
r3, r2, r1, r0 := hexadecabytes.EncodeUint16(value, bytesymbols.LowerCase)
// ...
r3, r2, r1, r0 := hexadecabytes.EncodeUint16(value, bytesymbols.UpperCase)
```
Or:
```go
import (
"sourcecode.social/reiver/go-hexadeca/enc/bytes"
"sourcecode.social/reiver/go-hexadeca/symbols/rune"
)
// ...
r3, r2, r1, r0 := hexadecabytes.EncodeUint16(value, runesymbols.LowerCase)
// ...
r3, r2, r1, r0 := hexadecabytes.EncodeUint16(value, runesymbols.UpperCase)
```
## hexadecimal encode `uint32`
To hexadecimal encode a `uint32` use any of these:
```go
import "sourcecode.social/reiver/go-hexadeca/enc/bytes"
// ...
r7, r6, r5, r4, r3, r2, r1, r0 := hexadecabytes.EncodeUint32UsingLowerCaseSymbols(value)
// ...
r7, r6, r5, r4, r3, r2, r1, r0 := hexadecabytes.EncodeUint32UsingUpperCaseSymbols(value)
```
Or:
```go
import "sourcecode.social/reiver/go-hexadeca/enc/runes"
// ...
r7, r6, r5, r4, r3, r2, r1, r0 := hexadecarunes.EncodeUint32UsingLowerCaseSymbols(value)
// ...
r7, r6, r5, r4, r3, r2, r1, r0 := hexadecarunes.EncodeUint32UsingUpperCaseSymbols(value)
```
Or:
```go
import (
"sourcecode.social/reiver/go-hexadeca/enc/bytes"
"sourcecode.social/reiver/go-hexadeca/symbols/byte"
)
// ...
r7, r6, r5, r4, r3, r2, r1, r0 := hexadecabytes.EncodeUint32(value, bytesymbols.LowerCase)
// ...
r7, r6, r5, r4, r3, r2, r1, r0 := hexadecabytes.EncodeUint32(value, bytesymbols.UpperCase)
```
Or:
```go
import (
"sourcecode.social/reiver/go-hexadeca/enc/runes"
"sourcecode.social/reiver/go-hexadeca/symbols/rune"
)
// ...
r7, r6, r5, r4, r3, r2, r1, r0 := hexadecarunes.EncodeUint32(value, runesymbols.LowerCase)
// ...
r7, r6, r5, r4, r3, r2, r1, r0 := hexadecarunes.EncodeUint32(value, runesymbols.UpperCase)
```
## hexadecimal encode `uint64`
To hexadecimal encode a `uint64` use any of these:
```go
import "sourcecode.social/reiver/go-hexadeca"
// ...
// value==18364758544493064720 -> r15=='f', r14=='e', r13=='d', r12=='c', r11=='b', r10=='a', r9=='9', r8=='8', r7=='7', r6=='6', r5=='5', r4=='4', r3=='3', r2=='2', r1=='1', r0=='0'
r15, r14, r13, r12, r10, r9, r8, r7, r6, r5, r4, r3, r2, r1, r0 := hexadeca.EncodeUint64UsingLowerCaseSymbols(value)
// ...
// value==18364758544493064720 -> r15=='F', r14=='E', r13=='D', r12=='C', r11=='B', r10=='A', r9=='9', r8=='8', r7=='7', r6=='6', r5=='5', r4=='4', r3=='3', r2=='2', r1=='1', r0=='0'
r15, r14, r13, r12, r10, r9, r8, r7, r6, r5, r4, r3, r2, r1, r0 := hexadeca.EncodeUint64UsingUpperCaseSymbols(value)
```
Or:
```go
import (
"sourcecode.social/reiver/go-hexadeca"
"sourcecode.social/reiver/go-hexadeca/symbols/rune"
)
// ...
// value==18364758544493064720 -> r15=='f', r14=='e', r13=='d', r12=='c', r11=='b', r10=='a', r9=='9', r8=='8', r7=='7', r6=='6', r5=='5', r4=='4', r3=='3', r2=='2', r1=='1', r0=='0'
r15, r14, r13, r12, r10, r9, r8, r7, r6, r5, r4, r3, r2, r1, r0 := hexadeca.EncodeUint64(value, runesymbols.LowerCase)
// ...
// value==18364758544493064720 -> r15=='F', r14=='E', r13=='D', r12=='C', r11=='B', r10=='A', r9=='9', r8=='8', r7=='7', r6=='6', r5=='5', r4=='4', r3=='3', r2=='2', r1=='1', r0=='0'
r15, r14, r13, r12, r10, r9, r8, r7, r6, r5, r4, r3, r2, r1, r0 := hexadeca.EncodeUint64(value, runesymbols.UpperCase)
```
## hexadecimal encode `int64`
To hexadecimal encode a `int64` use any of these:
```go
import "sourcecode.social/reiver/go-hexadeca"
// ...
// value==18364758544493064720 -> r15=='f', r14=='e', r13=='d', r12=='c', r11=='b', r10=='a', r9=='9', r8=='8', r7=='7', r6=='6', r5=='5', r4=='4', r3=='3', r2=='2', r1=='1', r0=='0'
r15, r14, r13, r12, r10, r9, r8, r7, r6, r5, r4, r3, r2, r1, r0 := hexadeca.EncodeInt64UsingLowerCaseSymbols(value)
// ...
// value==18364758544493064720 -> r15=='F', r14=='E', r13=='D', r12=='C', r11=='B', r10=='A', r9=='9', r8=='8', r7=='7', r6=='6', r5=='5', r4=='4', r3=='3', r2=='2', r1=='1', r0=='0'
r15, r14, r13, r12, r10, r9, r8, r7, r6, r5, r4, r3, r2, r1, r0 := hexadeca.EncodeInt64UsingUpperCaseSymbols(value)
```
Or:
```go
import (
"sourcecode.social/reiver/go-hexadeca"
"sourcecode.social/reiver/go-hexadeca/symbols/rune"
)
// ...
// value==18364758544493064720 -> r15=='f', r14=='e', r13=='d', r12=='c', r11=='b', r10=='a', r9=='9', r8=='8', r7=='7', r6=='6', r5=='5', r4=='4', r3=='3', r2=='2', r1=='1', r0=='0'
r15, r14, r13, r12, r10, r9, r8, r7, r6, r5, r4, r3, r2, r1, r0 := hexadeca.EncodeInt64(value, runesymbols.LowerCase)
// ...
// value==18364758544493064720 -> r15=='F', r14=='E', r13=='D', r12=='C', r11=='B', r10=='A', r9=='9', r8=='8', r7=='7', r6=='6', r5=='5', r4=='4', r3=='3', r2=='2', r1=='1', r0=='0'
r15, r14, r13, r12, r10, r9, r8, r7, r6, r5, r4, r3, r2, r1, r0 := hexadeca.EncodeInt64(value, runesymbols.UpperCase)
```
## Import
To import package **hexadeca** use `import` code like the following:
```
import "sourcecode.social/reiver/go-hexadeca"
```
## Installation
To install package **hexadeca** do the following:
```
GOPROXY=direct go get https://sourcecode.social/reiver/go-hexadeca
```
## Author
Package **hexadeca** was written by [Charles Iliya Krempeaux](http://changelog.ca)