BitByteData
A Swift framework with classes for reading and writing bits and bytes. Supported platforms include Apple platforms, Linux, and Windows.
Installation
BitByteData can be integrated into your project using either Swift Package Manager, CocoaPods, or Carthage.
Swift Package Manager
To install using SPM, add BitByteData to you package dependencies and specify it as a dependency for your target, e.g.:
import PackageDescription
let package = Package(
name: "PackageName",
dependencies: [
.package(url: "https://github.com/tsolomko/BitByteData.git",
from: "2.0.0")
],
targets: [
.target(
name: "TargetName",
dependencies: ["BitByteData"]
)
]
)
More details you can find in Swift Package Manager’s Documentation.
CocoaPods
Add pod 'BitByteData', '~> 2.0'
and use_frameworks!
lines to your Podfile.
To complete installation, run pod install
.
Carthage
Add to your Cartfile github "tsolomko/BitByteData" ~> 2.0
.
Then:
If you use Xcode 12 or later you should run
carthage update --use-xcframeworks
. After that drag and drop theBitByteData.xcframework
file from theCarthage/Build/
directory into the “Frameworks, Libraries, and Embedded Content” section of your target’s “General” tab in Xcode.If you use Xcode 11 or earlier you should run
carthage update
. After that drag and drop theBitByteData.framework
file from from theCarthage/Build/<platform>/
directory into the “Embedded Binaries” section of your target’s “General” tab in Xcode.
Migration to 2.0
There is a number of breaking changes in the 2.0 update. In this section you can find a list of modifications you need to perform to your code to make it compile with BitByteData 2.0. For more information, please refer to either 2.0 Release Notes or API Reference Documentation.
ByteReader
class has been renamed toLittleEndianByteReader
.Solution: Change all occurrences in your code of
ByteReader
toLittleEndianByteReader
.BitReader
protocol has two new method requirements:signedInt(fromBits:representation:)
andadvance(by:)
.Solution: If you have your own type that conforms to the
BitReader
protocol you need to implement these two methods.BitWriter
protocol has two new method requirements:write(unsignedNumber:bitsCount:)
andwrite(signedNumber:bitsCount:representation:)
.Solution: If you have your own type that conforms to the
BitWriter
protocol you need to implement thewrite(unsignedNumber:bitsCount:)
function (the second function has a default implementation).The setter of the
offset
property of theLsbBitReader
andMsbBitReader
classes will now crash if the reader is not aligned.Solution: If you set this property directly, make sure that the reader is aligned, for example, by checking the
isAligned
property.The default implementation of the
BitWriter.write(number:bitsCount:)
function and thewrite(unsignedNumber:bitsCount:)
function of theLsbBitWriter
andMsbBitWriter
classes now crash if thebitsCount
argument exceeds the bit width of the integer type on the current platform.Solution: If you use these functions directly, make sure that the
bitsCount
argument has a valid value.
In addition, BitByteData 2.0 provides new functionality for working with signed integers more correctly. If you were
working with signed integers before, consider using the new BitReader.signedInt(fromBits:representation:)
and
BitWriter.write(signedNumber:bitsCount:representation:)
functions instead of int(fromBits:)
and
write(number:bitsCount:)
, respectively.
Usage
To read bytes use either LittleEndianByteReader
or BigEndianByteReader
class, which implement the ByteReader
protocol.
For reading bits there are also two classes: LsbBitReader
and MsbBitReader
, which implement the BitReader
protocol
for two bit-numbering schemes (“LSB 0” and “MSB 0” correspondingly), though they only support Little Endian byte order.
Since the BitReader
protocol inherits from ByteReader
, you can also use the LsbBitReader
and MsbBitReader
classes to read bytes (but they must be aligned when doing so, see documentation for more details).
Writing bits is implemented for two bit-numbering schemes as well: the LsbBitWriter
and MsbBitWriter
classes. Both
of them conform to the BitWriter
protocol.
Note: All readers and writers aren’t structs, but classes intentionally to make it easier to pass them as references
to functions. This allows to eliminate potential copying and avoid writing extra inout
s and ampersands all over the
code.
Documentation
Every function or type of BitByteData’s public API is documented. This documentation can be found at its own website or via a slightly shorter link: bitbytedata.tsolomko.me
Contributing
Whether you find a bug, have a suggestion, idea, feedback or something else, please create an issue on GitHub. If you have any questions, you can ask them on the Discussions page.
If you’d like to contribute, please create a pull request on GitHub.
Note: If you are considering working on BitByteData, please note that the Xcode project (BitByteData.xcodeproj)
was created manually and you shouldn’t use the swift package generate-xcodeproj
command.
Performance and benchmarks
One of the most important goals of BitByteData’s development is high speed performance. To help achieve this goal there
are benchmarks for every function in the project as well as a handy command-line tool, benchmarks.py
, which helps to
run, show, and compare benchmarks and their results.
If you are considering contributing to the project please make sure that:
- Every new function has also a new benchmark added.
- Other changes to existing functionality do not introduce performance regressions, or, at the very least, these regressions are small and such performance tradeoff is necessary and justifiable.
Finally, please note that any meaningful comparison can be made only between benchmarks run on the same hardware and software.