A Swift framework with classes for reading and writing bits and bytes.
BitByteData can be integrated into your project using 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: "1.4.0") ], targets: [ .target( name: "TargetName", dependencies: ["BitByteData"] ) ] )
More details you can find in Swift Package Manager's Documentation.
pod 'BitByteData', '~> 1.4' and
use_frameworks! to your Podfile.
To complete installation, run
Add to your Cartfile
github "tsolomko/BitByteData" ~> 1.4.
Finally, drag and drop
into the "Embedded Binaries" section on your targets' "General" tab in Xcode.
ByteReader class to read bytes.
For reading bits there are two classes:
MsbBitReader, which implement
for two bit-numbering schemes ("LSB 0" and "MSB 0" correspondingly).
MsbBitReader classes inherit from
ByteReader so you can also use them to read bytes
(but they must be aligned, see documentation for more details).
Writing bits is implemented in two classes
MsbBitWriter (again, for two bit-numbering schemes).
They both conform to
Note: All readers and writers aren't structs, but classes intentionally.
This is done to make it easier to pass them as arguments to functions and to eliminate unnecessary copying and
Every function or type of BitByteData's public API is documented. This documentation can be found at its own website.
Whether you find a bug, have a suggestion, idea or something else, please create an issue on GitHub.
If you'd like to contribute code, please create a pull request on GitHub.
Note: If you are considering working on BitByteData, please note that Xcode project (BitByteData.xcodeproj)
was created manually and you shouldn't use
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.
- Every other change to any existing function doesn't 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 system.
Help us keep the lights on
1.4.1 - Jun 8, 2019
- Reverted performance improvements of 1.4.0 update.
Comment: Those changes were grossly incompatible with Swift 5 and had to be reverted.
1.4.0 - Dec 12, 2018
- Significantly improved the performance of
Side note: I have published my plans for the next major update (2.0).
1.4.0-test - Dec 4, 2018
This is a test release for the upcoming 1.4.0 update. This update will include drastic changes to the internal implementation of all readers with the goal of significant improvements to the performance. Naturally, there should be NO other visible changes to the behavior of BitByteData. To ensure that this is, in fact, the case I would like to invite to test this release everyone who has the opportunity to do so. But keep in mind, that this is still a test release and it is not recommended to use it on a day-to-day basis (if everything goes well, the 1.4.0 update will go out some time next week).
Here are the instructions to install the test release:
For Cocoapods users
Replace the BitByteData dependency line in your Podfile with the following:
pod 'BitByteData', :git => 'https://github.com/tsolomko/BitByteData.git', :tag => '1.4.0-test'
Don't forget to revert the changes to your Podfile after the 1.4.0 update is released.
For Swift Package Manager users
Replace the BitByteData dependency line in your Package.swift manifest file with the following:
.package(url: "https://github.com/tsolomko/BitByteData", from: "1.4.0-test"),
Don't forget to revert the changes after the 1.4.0 update is released.
For Carthage users
Replace the BitByteData dependency line in your Cartfile with the following:
github "tsolomko/BitByteData" "1.4.0-test"
Don't forget to revert the changes to your Cartfile after the 1.4.0 update is released.
1.3.1 - Nov 8, 2018
- Improved performance of
ByteReader's functions and computed properties when BitByteData is compiled with Swift 4.2 compiler.
1.3.0 - Nov 1, 2018
- Updated to support Swift 4.2.
advance(by:)function to both
write(unsignedNumber:bitsCount:)function to both
MsbBitWriter(thanks to @cowgp for proposing and implementing this in PR #1).
Comment: There are plans to add both
write(unsignedNumber:bitsCount:) functions to corresponding protocols in the next major update.
Known potential issues:
For Cocoapods users. It seems like Xcode 10 changed how it sets build environment variables. Particularly, it no longer sets variables which have empty string values. This change breaks custom build scripts added to projects by Cocoapods. If you encounter problems with building/installing BitByteData with something about "unbound variable" in your Cocoapods verbose log, this means that you, most likely, have this issue. Thankfully, 1.6.0 version of Cocoapods is going to fix this problem, but at the time of this writing it hasn't been released yet. Meanwhile, I would like to recommend upgrading to the beta version of Cocoapods 1.6.0 if you have this problem. You can learn more about this issue here.
For Carthage users. You may notice that the size of "BitByteData.framework.zip" archive attached to this release (that is generated and used by Carthage) is significantly smaller than the one for 1.2.0 update. Upon investigation I discovered that dSym files inside it have become a lot smaller, but I am currently unable to determine what exactly has changed about them. If you encounter any problems which may be connected with this observation, please, let me know.