BitByteData 2.0.4

BitByteData 2.0.4

×

由Timofey Solomko维护。

BitByteData 2.0.4

  • 由
  • Timofey Solomko

BitByteData

Swift 5.2+ GitHub license Build Status

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

安装

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

Swift Package Manager

要使用 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 的文档。

CocoaPods

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

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

Carthage

将以下内容添加到您的Cartfile中：github "tsolomko/BitByteData" ~> 2.0。

之后

  1. 如果您使用的是Xcode 12或更新的版本，请运行carthage update --use-xcframeworks。然后，将Carthage/Build/目录中的BitByteData.xcframework文件拖放到Xcode目标“通用”标签中的“框架、库和嵌入式内容”部分。

  2. 如果您使用的是Xcode 11或更早的版本，请运行carthage update。然后，将Carthage/Build/目录中的BitByteData.framework文件拖放到Xcode目标“通用”标签中的“嵌入式二进制文件”部分。

迁移到2.0

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 属性的设置器在读取器未对齐时将导致崩溃。

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

  5. 现在，BitWriter.write(number:bitsCount:) 函数的默认实现以及 LsbBitWriter 和 MsbBitWriter 类的 write(unsignedNumber:bitsCount:) 函数将导致崩溃，如果 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 协议。尽管它们只支持小端字节序，但它们继承了 ByteReader 协议。因此，您也可以使用 LsbBitReader 和 MsbBitReader 类来读取字节（但在这样做时必须对齐，有关更多详细信息，请参阅文档）。

同样为两种位数编号方案实现了写入位的功能：LsbBitWriter 和 MsbBitWriter 类。这两个类都符合 BitWriter 协议。

注意：所有读取器和写入器旨在作为引用传递给函数以简化操作，因此故意不是结构体而是类。这允许消除潜在的复制，避免在代码中写入额外的 inout 和 & 和符号。

文档

BitByteData 的每个公共 API 函数或类型都有文档。此文档可在其自己的网站上找到，或通过简短的链接：bitbytedata.tsolomko.me。

贡献力量

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

如果您想贡献力量，请在GitHub上创建拉取请求。

注意：如果您考虑为BitByteData工作，请注意，Xcode项目（BitByteData.xcodeproj）是手动创建的，您不应使用swift package generate-xcodeproj命令。

性能和基准测试

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

如果您考虑为项目贡献力量，请确保：

  1. 每个新功能都添加了相应的基准测试。
  2. 对现有功能的其他更改不会引入性能下降，或者至少这些下降很小，这种性能权衡是必要的且可辩护的。

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