BitByteData

一个 Swift 框架，包含用于读取和写入位和字节的类。支持的平台包括 Apple 平台、Linux 和 Windows。

可以使用 Swift Package Manager、CocoaPods 或 Carthage 将 BitByteData 集成到您的项目中。

要使用 SPM 进行安装，请将 BitByteData 添加到您的软件包依赖项中，并将其指定为目标的依赖项，例如：

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"]
        )
    ]
)

更多详细信息，您可以在 Swift Package Manager 的文档中找到。

将 pod 'BitByteData', '~> 2.0' 和 use_frameworks! 行添加到您的 Podfile。

要完成安装，请运行 pod install。

添加到您的 Cartfile github "tsolomko/BitByteData" ~> 2.0。

然后

1. 如果您使用 Xcode 12 或更高版本，您应该运行 carthage update --use-xcframeworks。之后，将 BitByteData.xcframework 文件从 Carthage/Build/ 目录拖放到 Xcode 中目标的“General”选项卡的“Frameworks, Libraries, and Embedded Content”部分。

2. 如果您使用 Xcode 11 或更早版本，您应该运行 carthage update。之后，将 BitByteData.framework 文件从 Carthage/Build/<platform>/ 目录拖放到 Xcode 中目标的“General”选项卡的“Embedded Binaries”部分。

2.0 版本更新中有许多重大更改。在本节中，您可以找到您需要对代码进行的修改列表，以使其能够使用 BitByteData 2.0 进行编译。有关更多信息，请参阅 2.0 发布说明 或 API 参考文档。

1. ByteReader 类已重命名为 LittleEndianByteReader。

   解决方案： 将代码中所有出现的 ByteReader 更改为 LittleEndianByteReader。

2. BitReader 协议有两个新的方法要求：signedInt(fromBits:representation:) 和 advance(by:)。

   解决方案： 如果您有自己的类型符合 BitReader 协议，则需要实现这两个方法。

3. BitWriter 协议有两个新的方法要求：write(unsignedNumber:bitsCount:) 和 write(signedNumber:bitsCount:representation:)。

   解决方案： 如果您有自己的类型符合 BitWriter 协议，则需要实现 write(unsignedNumber:bitsCount:) 函数（第二个函数具有默认实现）。

4. 如果读取器未对齐，则 LsbBitReader 和 MsbBitReader 类的 offset 属性的 setter 现在会崩溃。

   解决方案： 如果您直接设置此属性，请确保读取器已对齐，例如，通过检查 isAligned 属性。

5. 如果 bitsCount 参数超过当前平台上整数类型的位宽，则 BitWriter.write(number:bitsCount:) 函数的默认实现以及 LsbBitWriter 和 MsbBitWriter 类的 write(unsignedNumber:bitsCount:) 函数现在会崩溃。

   解决方案： 如果您直接使用这些函数，请确保 bitsCount 参数具有有效值。

此外，BitByteData 2.0 提供了新的功能，可以更正确地处理有符号整数。如果您之前使用过有符号整数，请考虑使用新的 BitReader.signedInt(fromBits:representation:) 和 BitWriter.write(signedNumber:bitsCount:representation:) 函数，而不是 int(fromBits:) 和 write(number:bitsCount:)。

要读取字节，请使用实现 ByteReader 协议的 LittleEndianByteReader 或 BigEndianByteReader 类。

对于读取位，也有两个类：LsbBitReader 和 MsbBitReader，它们为两种位编号方案（分别对应“LSB 0”和“MSB 0”）实现 BitReader 协议，但它们仅支持小端字节序。由于 BitReader 协议继承自 ByteReader，因此您也可以使用 LsbBitReader 和 MsbBitReader 类来读取字节（但这样做时它们必须对齐，请参阅文档以获取更多详细信息）。

写入位也为两种位编号方案实现：LsbBitWriter 和 MsbBitWriter 类。它们都符合 BitWriter 协议。

注意： 所有读取器和写入器都不是结构体，而是特意设计的类，以便更容易将它们作为引用传递给函数。这允许消除潜在的复制并避免在代码中编写额外的 inout 和与号。

BitByteData 的公共 API 的每个函数或类型都有文档记录。可以在其自己的 网站或通过稍微短一点的链接找到此文档：bitbytedata.tsolomko.me

无论您发现错误、有建议、想法、反馈或其他任何内容，请在 GitHub 上创建一个 issue。如果您有任何问题，可以在讨论页面上提问。

如果您想贡献代码，请在 GitHub 上创建一个 pull request。

注意： 如果您正在考虑开发 BitByteData，请注意 Xcode 项目 (BitByteData.xcodeproj) 是手动创建的，您不应使用 swift package generate-xcodeproj 命令。

BitByteData 开发的最重要目标之一是高速性能。为了帮助实现此目标，项目中每个函数都有基准测试，以及一个方便的命令行工具 benchmarks.py，它可以帮助运行、显示和比较基准测试及其结果。

如果您正在考虑为该项目做贡献，请确保

1. 每个新函数也添加了一个新的基准测试。
2. 对现有功能的其他更改不会引入性能回归，或者至少这些回归很小，并且这种性能权衡是必要且合理的。

最后，请注意，任何有意义的比较只能在相同硬件和软件上运行的基准测试之间进行。