- Notifications
You must be signed in to change notification settings - Fork11
Easily convert integers to binary/hex/octal strings and back again with clean functional syntax.
License
orchetect/SwiftRadix
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
A lightweight library useful for translating integers to and from radix strings (binary, hex, octal or any base) using simple, clean functional syntax.
Compatible with all Apple platforms and Linux.
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 is2...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 strings255.hex.stringValue // "FF"255.hex.stringValue(prefix:true) // "0xFF"255.hex.stringValue(prefix:true, uppercase:false) // "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 convertingUInt8(123).hex==Int16(123) // true"FF".hex==255 // true123.hex+10.binary-10 // 123
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.3.0")
pod'SwiftRadix'At its core, a new generic type calledRadix wraps anyBinaryInteger value, as well as its associated base (radix).
Radix<T: BinaryInteger>// constructorsRadix(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 construct0xFF.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 constructRadix 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.
Two invocation styles, producing the same result.
// proxy constructor functionHex(123) // Radix<Int>(123, base: 16)// functional category property123.hex // Radix<Int>(123, base: 16)
AnyBinaryInteger 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 prefix0x or without it.
This constructor returns anOptional, since if the string is not valid hexadecimal, the constructor will fail andnil will be returned.
If no integer type is specified, the type will default toInt.
Hex("FF") // Radix<Int>(255)?"FF".hex // Radix<Int>(255)?"0xFF".hex // Radix<Int>(255)?"ZZZZ".hex // nil ; not a valid hex string
To specify an integer type other thanInt, specify it usingas:.
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 fails
Various methods become available:
leth=255.hex // Radix<Int>(255)h.value // Int(255)h.stringValue // "FF"h.stringValue(prefix:true) // "0xFF"h.stringValue(prefix:true, uppercase:false) // "0xff"h.stringValue="7F" // can also set the hex String and get value...h.value // 127, type Int
Padding ton 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 places
It is also possible to pad leading zeros to everyn 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 everyn 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"
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.
leth1=10.hex // Radix<Int>leth2=20.hex // Radix<Int>h1.value== h2.value // this works but it's easier to just do this...h1== h2 // false
They can be compared with great flexibility -- even between different integer types directly without requiring casting or conversions.
leth1=10.hex // Radix<Int>leth2=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 nil
Additional operators supported, allowing assignment and bitwise operations directly.
+=,-=,*=,/=,<<,>>,&
Traditional binary bit shift left/right is available directly onRadix.
0b0100.hex <<1 // 0b10000b0100.hex >>1 // 0b0010
Any integer array can be converted to an equivalent[Radix<T>] Array:
leta=[1,2].hex // [Radix<Int>(1), Radix<Int>(2)]letarr:[UInt8]=[3,4]letb= 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 concatenatedString or an array ofStrings:
[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 arrays can also be translated into an array ofRadix<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.
letarr=[0,2,255]arr.hex.stringValueArrayLiteral // "[0x0, 0x2, 0xFF]"arr.binary.stringValueArrayLiteral // "[0b0, 0b10, 0b11111111]"
Useful when debugging binary data to the console, or presenting it in a human-readable format easily.
letd=Data([0x1,0x2,0x3,0xFF])d.hex.stringValue(padTo:2) // "01 02 03 FF"
A variety of additional methods for reading and manipulating the underlying integer value.
Method:.bit(Int)
Subscript:[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
varh=0b1100.binaryh.bit(0) // 0b0.binaryh.bit(2) // 0b1.binaryh[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]=0b0h.value // == 0b1000
Method:.nibble(Int)
Subscript:[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
varh=0x1234.hexh.nibble(0) // 0x4.hexh.nibble(3) // 0x1.hexh[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]=0xFh.value // == 0xF234
.bytes
- A convenience property to return the raw bytes of the value as
[UInt8]based on system endianness - radix-agnostic
letbytes=0xFF00.hex.bytesbytes // [0x00, 0xFF]
Coded by a bunch of 🐹 hamsters in a trench coat that calls itself@orchetect.
Licensed under the MIT license. SeeLICENSE for details.
Contributions are welcome. Feel free to post an Issue to discuss.
About
Easily convert integers to binary/hex/octal strings and back again with clean functional syntax.