SwiftRadix
A lightweight library useful for translating integers to and from radix strings (binary, hex, octal or any base) using simple, clean functional syntax.
Summary
Common Usage
Unified library with several constructor methods, all of which in turn provide all of the functionality of the library inline.
| Option 1: Function | Option 2: Category method | Returns |
|---|---|---|
Radix(T, base:) |
.radix(base:) |
Radix<T>(base: n) where n is 2...36 |
Binary(T) |
.binary |
Radix<T>(base: 2) |
Octal(T) |
.octal |
Radix<T>(base: 8) |
Hex(T) |
.hex |
Radix<T>(base: 16) |
For the sake of simplifying this documentation, Hex() / .hex will be used for most examples below.
// convert to or from hex strings
255.hex.stringValue // "FF"
255.hex.stringValue(prefix: true) // "0xFF"
"FF".hex?.value // Optional(255)
"0xFF".hex?.value // Optional(255)
"ZZ".hex?.value // nil (not valid hex string, so init fails)
// work with arrays of any integer type, or hex strings and convert between them
[0, 255, 0, 255].hex.stringValue // "00 FF 00 FF"
[0, 255, 0, 255].hex.stringValues // ["00", "FF", "00", "FF"]
[0, 255, 0, 255].hex.stringValue(prefixes: true) // "0x00 0xFF 0x00 0xFF"
[0, 255, 0, 255].hex.stringValues(prefixes: true) // ["0x00", "0xFF", "0x00", "0xFF"]
[0, 255, 0, 255].hex.stringValueArrayLiteral // "[0x0, 0xFF, 0x0, 0xFF]"
[0, 255, 0, 255].hex.stringValueArrayLiteral(padTo: 2) // "[0x00, 0xFF, 0x00, 0xFF]"
[0, 65535, 4000].hex.stringValue // "0 FFFF FA0"
[0, 65535, 4000].hex.stringValue(padTo: 2) // "00 FFFF FA0"
[0, 65535, 4000].hex.stringValue(padToEvery: 2) // "00 FFFF 0FA0"
[0, 65535, 4000].hex.stringValue(padToEvery: 4) // "0000 FFFF 0FA0"
["00", "FF", "ZZ"].hex.values // [Optional(0), Optional(255), nil]
// test for equatability or perform math operations with great flexibility,
// without needing to extract the .value first, casting or converting
UInt8(123).hex == Int16(123) // true
"FF".hex == 255 // true
123.hex + 10.binary - 10 // 123Installation
Swift Package Manager (SPM)
-
Add SwiftRadix as a dependency using Swift Package Manager.
-
In an app project or framework, in Xcode:
- Select the menu: File → Swift Packages → Add Package Dependency...
- Enter this URL:
https://github.com/orchetect/SwiftRadix
-
In a Swift Package, add it to the Package.swift dependencies:
.package(url: "https://github.com/orchetect/SwiftRadix", from: "1.1.0")
-
Cocoapods
pod 'SwiftRadix'Documentation
Premise
At its core, a new generic type called Radix wraps any BinaryInteger value, as well as its associated base (radix).
Radix<T: BinaryInteger>
// constructors
Radix(0xFF, base: 16) // Radix<Int>(255)?
Radix(UInt8(0xFF), base: 16) // Radix<UInt8>(255)?
Radix<UInt8>(0xFF, base: 16) // Radix<UInt8>(255)?
Radix(0b1111, base: 2) // Radix<Int>(15)?
// category method to construct
0xFF.radix(base: 16) // Radix<Int>(255)?
0xFF.radix(base: 16, as: UInt8.self) // Radix<UInt8>(255)?However, for common bases (binary base-2, octal base-8, hex base-16) you may never need to construct Radix directly. Instead, there are convenient functional category methods on common types and collections to shortcut these.
255.binary // == Radix<Int>(0b11111111, base: 2)
"0b11111111".binary // == Radix<Int>(255, base: 2)?
255.octal // == Radix<Int>(0o377, base: 8)
"0o377".octal // == Radix<Int>(255, base: 8)?
255.hex // == Radix<Int>(0xFF, base: 16)
"0xFF".hex // == Radix<Int>(255, base: 16)?
255.radix(base: 5) // == Radix<Int>(255, base: 5)
"2010".radix(base: 5) // == Radix<Int>(255, base: 5)?You will see how powerful and elegant these can be when combined, further down the README.
Proxy Constructors
Two invocation styles, producing the same result.
// proxy constructor function
Hex(123) // Radix<Int>(123, base: 16)
// functional category property
123.hex // Radix<Int>(123, base: 16)Any BinaryInteger type can be used.
Int(123).hex // Radix<Int>(123)
Int8(123).hex // Radix<Int8>(123)
UInt8(123).hex // Radix<UInt8>(123)
Int16(123).hex // Radix<Int16>(123)
UInt16(123).hex // Radix<UInt16>(123)
Int32(123).hex // Radix<Int32>(123)
UInt32(123).hex // Radix<UInt32>(123)
Int64(123).hex // Radix<Int64>(123)
UInt64(123).hex // Radix<UInt64>(123)A valid hexadecimal string can be used, either containing the prefix 0x or without it.
This constructor returns an Optional, since if the string is not valid hexadecimal, the constructor will fail and nil will be returned.
If no integer type is specified, the type will defult to Int.
Hex("FF") // Radix<Int>(255)?
"FF".hex // Radix<Int>(255)?
"0xFF".hex // Radix<Int>(255)?
"ZZZZ".hex // nil ; not a valid hex stringTo specify an integer type other than Int, specify it using as:.
Hex("FF", as: UInt8.self) // Radix<UInt8>(255)?
"FF".hex(as: UInt8.self) // Radix<UInt8>(255)?
Hex("FFFFFF", as: UInt8.self) // nil -- 0xFFFFFF does not fit in UInt8, so init fails
"FFFFFF".hex(as: UInt8.self) // nil -- 0xFFFFFF does not fit in UInt8, so init failsGetting and Setting Values
Various methods become available:
let h = 255.hex // Radix<Int>(255)
h.value // Int(255)
h.stringValue // "FF"
h.stringValue(prefix: true) // "0xFF"
h.stringValue = "7F" // can also set the hex String and get value...
h.value // 127, type IntPadding to n number of leading zeros can be specified if you need uniform string formatting:
0xF.hex.stringValue // "F"
0xF.hex.stringValue(padTo: 2) // "0F"
0xF.hex.stringValue(padTo: 3) // "00F"
0xFFFF.hex.stringValue(padTo: 3) // "FFFF" - has no effect; it's > 3 placesIt is also possible to pad leading zeros to every n multiple of digit places.
0xF.hex.stringValue(padToEvery: 2) // "0F"
0xFF.hex.stringValue(padToEvery: 2) // "FF"
0xFFF.hex.stringValue(padToEvery: 2) // "0FFF"
0xFFFF.hex.stringValue(padToEvery: 2) // "FFFF"
0x1.hex.stringValue(padToEvery: 4) // "0001"
0x12345.hex.stringValue(padToEvery: 4) // "00012345"In addition to padding, strings can be split every n digit places, and also in combination with padding.
0xF.hex.stringValue(padTo: 8, splitEvery: 4) // "0000 000F"
0x123AB.hex.stringValue(padToEvery: 2, splitEvery: 2) // "01 23 AB"Equatability
Radix<T> can be tested for equatability directly using typical operators (==, !=, >, <) without needing to access the .value property. This makes for cleaner, more convenient syntax.
let h1 = 10.hex // Radix<Int>
let h2 = 20.hex // Radix<Int>
h1.value == h2.value // this works but it's easier to just do this...
h1 == h2 // falseThey can be compared with great flexibility -- even between different integer types directly without requiring casting or conversions.
let h1 = 10.hex // Radix<Int>
let h2 = 20.hex // Radix<Int>
h1 == h2 // false (comparing Radix<Int> with Radix<Int>)
h1 > 20 // true (comparing Radix<Int> with Int)
h1 != UInt8(20) // true (comparing Radix<Int> with UInt8)
// even though "FF".hex produces an Optional,
// the comparison still works safely without requiring the optional to be unwrapped first
"FF".hex == 255 // true
"FF".hex == 255.hex // true
"ZZ".hex == 255.hex // false - optional is nilAdditional Operators
Additional operators supported, allowing assignment and bitwise operations directly.
+=,-=,*=,/=,<<,>>,&
Bitwise Shifting
Traditional binary bit shift left/right is available directly on Radix.
0b0100.hex << 1 // 0b1000
0b0100.hex >> 1 // 0b0010Extensions on Array and Data
[BinaryInteger]
Any integer array can be converted to an equivalent [Radix<T>] Array:
let a = [1, 2].hex // [Radix<Int>(1), Radix<Int>(2)]
let arr: [UInt8] = [3, 4]
let b = arr.hex // [Radix<UInt8>(3), Radix<UInt8>(4)]
// and back again:
a.values // [1, 2] of type [Int]
b.values // [3, 4] of type [UInt8]It can also be flattened into a concatenated String or an array of Strings:
[0, 255, 0, 255].hex.stringValue // "00 FF 00 FF"
[0, 255, 0, 255].hex.stringValue(prefix: true) // "0x00 0xFF 0x00 0xFF"
[0, 255, 0, 255].hex.stringValues // ["00", "FF", "00", "FF"]
[0, 255, 0, 255].hex.stringValues(prefix: true) // ["0x00", "0xFF", "0x00", "0xFF"][String]
String arrays can also be translated into an array of Radix<T>? . The .values property produces an unwrapped array of [Optional<T>].
["00", "0xFF", "ZZ"].hex.values // [Optional(0), Optional(255), nil]It is also possible to easily generate a Swift source-compatible array literal.
let arr = [0, 2, 255]
arr.hex.stringValueArrayLiteral // "[0x0, 0x2, 0xFF]"
arr.binary.stringValueArrayLiteral // "[0b0, 0b10, 0b11111111]"Data
Useful when debugging binary data to the console, or presenting it in a human-readable format easily.
let d = Data([0x1, 0x2, 0x3, 0xFF])
d.hex.stringValue(padTo: 2) // "01 02 03 FF"Bits and Bytes Accessors
A numer of additional methods for reading and manipulating the underlying integer value.
Bit
.bit(Int)
[bit: Int] { get set }
- gets single bit value at specified position right-to-left
- subscript can also be used to get or set bit values
- radix-agnostic
var h = 0b1100.binary
h.bit(0) // 0b0.binary
h.bit(2) // 0b1.binary
h[bit: 0] // 0b0 (type T, which is Int in this case)
h[bit: 2] // 0b1 (type T, which is Int in this case)
h[bit: 2] = 0b0
h.value // == 0b1000Nibble
`.nibble(Int)
[nibble: Int] { get set }
- gets nibble (4-bit) value at specified position right-to-left
- subscript can also be used to get or set nibble values
- radix-agnostic
var h = 0x1234.hex
h.nibble(0) // 0x4.hex
h.nibble(3) // 0x1.hex
h[nibble: 0] // 0x4 (type T, which is Int in this case)
h[nibble: 3] // 0x1 (type T, which is Int in this case)
h[nibble: 3] = 0xF
h.value // == 0xF234Bytes
.bytes
- A convenience property to return the raw bytes of the value as
[UInt8]based on system endianness - radix-agnostic
let bytes = 0xFF00.hex.bytes
bytes // [0x00, 0xFF]Author
Coded by a bunch of
License
Licensed under the MIT license. See LICENSE for details.
This library was formerly known as SwiftHex.
Contributions
Contributions are welcome. Feel free to post an Issue to discuss.