Merge branch 'develop' into release-1.0.0

Author: tsolomko

.jazzy.yaml

@@ -9,3 +9,18 @@ readme: README.md
 github_url: https://github.com/tsolomko/BitByteData
 github_file_prefix: https://github.com/tsolomko/BitByteData/tree/develop
 theme: fullwidth
+
+custom_categories:
+    - name: Reading bytes
+      children:
+      - ByteReader
+    - name: Reading bits (and bytes)
+      children:
+      - BitReader
+      - LsbBitReader
+      - MsbBitReader
+    - name: Writing bits (and bytes)
+      children:
+      - BitWriter
+      - LsbBitWriter
+      - MsbBitWriter

Sources/BitReader.swift

@@ -5,31 +5,62 @@
 
 import Foundation
 
+/// A type that contains functions for reading `Data` bit-by-bit and byte-by-byte.
 public protocol BitReader: class {
 
+    /// True, if reader's BIT pointer is aligned with the BYTE border.
     var isAligned: Bool { get }
 
+    /// Creates an instance for reading `data`.
     init(data: Data)
 
-    func bits(count: Int) -> [UInt8]
+    /// Reads bit and returns it, advancing by one BIT position.
+    func bit() -> UInt8
 
-    // TODO: Rename?
-    func intFromBits(count: Int) -> Int
+    /// Reads `count` bits and returns them as an array of `UInt8`, advancing by `count` BIT positions.
+    func bits(count: Int) -> [UInt8]
 
-    func bit() -> Int
+    /// Reads `count` bits and returns them as a `Int` number, advancing by `count` BIT positions.
+    func int(fromBits count: Int) -> Int
 
+    /// Aligns reader's BIT pointer to the BYTE border, i.e. moves BIT pointer to the first BIT of the next BYTE.
     func align()
 
-    // TODO: Describe preconditions.
+    // MARK: ByteReader's methods.
 
+    /// Reads byte and returns it, advancing by one BYTE position.
     func byte() -> UInt8
 
+    /// Reads `count` bytes and returns them as an array of `UInt8`, advancing by `count` BYTE positions.
     func bytes(count: Int) -> [UInt8]
 
+    /// Reads 8 bytes and returns them as a `UInt64` number, advancing by 8 BYTE positions.
     func uint64() -> UInt64
 
+    /// Reads 4 bytes and returns them as a `UInt32` number, advancing by 4 BYTE positions.
     func uint32() -> UInt32
 
+    /// Reads 2 bytes and returns them as a `UInt16` number, advancing by 2 BYTE positions.
     func uint16() -> UInt16
 
 }
+
+extension BitReader {
+
+    /**
+     - Warning: Doesn't check if there is any data left.
+     */
+    public func bits(count: Int) -> [UInt8] {
+        guard count > 0
+            else { return [] }
+
+        var array = [UInt8]()
+        array.reserveCapacity(count)
+        for _ in 0..<count {
+            array.append(self.bit())
+        }
+
+        return array
+    }
+
+}

Sources/BitWriter.swift

@@ -5,25 +5,34 @@
 
 import Foundation
 
+/// A type that contains functions for writing `Data` bit-by-bit (and byte-by-byte).
 public protocol BitWriter {
 
+    /// Data which contains writer's output (the last byte in progress is not included).
     var data: Data { get }
 
-    init()
-
+    /// True, if writer's BIT pointer is aligned with the BYTE border.
     var isAligned: Bool { get }
 
+    /// Creates an instance for writing.
+    init()
+
+    /// Writes `bit`, advancing by one BIT position.
     func write(bit: UInt8)
 
+    /// Writes `bits`, advancing by `bits.count` BIT positions.
     func write(bits: [UInt8])
 
-    // TODO: Describe, what will happen if `bitsCount` is smaller than actual amount of `number`'s bits.
-    // TODO: Describe, that `number` is processed in the same order as `BitWriter`'s.
+    /// Writes `number`, using and advancing by `bitsCount` BIT positions.
     func write(number: Int, bitsCount: Int)
 
+    /// Writes `byte`, advancing by one BYTE position.
     func append(byte: UInt8)
 
-    // TODO: Describe, that it doesn't check if it actually needs to align.
+    /**
+     Aligns writer's BIT pointer to the BYTE border, i.e. moves BIT pointer to the first BIT of the next BYTE,
+     filling all skipped BIT positions with zeros.
+     */
     func align()
 
 }

Sources/ByteReader.swift

@@ -5,46 +5,88 @@
 
 import Foundation
 
+/// A type that contains functions for reading `Data` byte-by-byte.
 public class ByteReader {
 
+    /// Size of the `data` (in bytes).
     public let size: Int
+
+    /// Data which is being read.
     public let data: Data
+
+    /// Offset to the byte in `data` which will be read next.
     public var offset: Int
 
-    // TODO: Rename?
-    public var isAtTheEnd: Bool {
-        return self.data.endIndex == self.offset
+    /**
+     True, if `offset` points at any position after the last byte in `data`.
+
+     - Note: It generally means that all bytes have been read.
+     */
+
+    public var isFinished: Bool {
+        return self.data.endIndex <= self.offset
     }
 
+    /// Creates an instance for reading `data`.
     public init(data: Data) {
         self.size = data.count
         self.data = data
         self.offset = data.startIndex
     }
 
+    /**
+     Reads byte and returns it, advancing by one position.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     */
     public func byte() -> UInt8 {
         self.offset += 1
         return self.data[self.offset - 1]
     }
 
+    /**
+     Reads `count` bytes and returns them as an array of `UInt8`, advancing by `count` positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     */
     public func bytes(count: Int) -> [UInt8] {
         let result = self.data[self.offset..<self.offset + count].toArray(type: UInt8.self, count: count)
         self.offset += count
         return result
     }
 
+    /**
+     Reads 8 bytes and returns them as a `UInt64` number, advancing by 8 positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     */
     public func uint64() -> UInt64 {
         let result = self.data[self.offset..<self.offset + 8].to(type: UInt64.self)
         self.offset += 8
         return result
     }
 
+    /**
+     Reads 4 bytes and returns them as a `UInt32` number, advancing by 4 positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     */
     public func uint32() -> UInt32 {
         let result = self.data[self.offset..<self.offset + 4].to(type: UInt32.self)
         self.offset += 4
         return result
     }
 
+    /**
+     Reads 2 bytes and returns them as a `UInt16` number, advancing by 2 positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     */
     public func uint16() -> UInt16 {
         let result = self.data[self.offset..<self.offset + 2].to(type: UInt16.self)
         self.offset += 2

Sources/LsbBitReader.swift

@@ -5,38 +5,47 @@
 
 import Foundation
 
+/**
+ A type that contains functions for reading `Data` bit-by-bit and byte-by-byte,
+ assuming "LSB 0" bit numbering scheme.
+ */
 public final class LsbBitReader: ByteReader, BitReader {
 
     private var bitMask: UInt8 = 1
 
+    /// True, if reader's BIT pointer is aligned with the BYTE border.
     public var isAligned: Bool {
         return self.bitMask == 1
     }
 
-    public func bits(count: Int) -> [UInt8] {
-        guard count > 0 else {
-            return []
-        }
+    /**
+     Reads bit and returns it, advancing by one BIT position.
 
-        var array: [UInt8] = Array(repeating: 0, count: count)
-        for i in 0..<count {
-            array[i] = self.data[self.offset] & self.bitMask > 0 ? 1 : 0
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     */
+    public func bit() -> UInt8 {
+        let bit: UInt8 = self.data[self.offset] & self.bitMask > 0 ? 1 : 0
 
-            if self.bitMask == 128 {
-                self.offset += 1
-                self.bitMask = 1
-            } else {
-                self.bitMask <<= 1
-            }
+        if self.bitMask == 128 {
+            self.offset += 1
+            self.bitMask = 1
+        } else {
+            self.bitMask <<= 1
         }
 
-        return array
+        return bit
     }
 
-    public func intFromBits(count: Int) -> Int {
-        guard count > 0 else {
-            return 0
-        }
+    /**
+     Reads `count` bits and returns them as a `Int` number, advancing by `count` BIT positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     */
+    public func int(fromBits count: Int) -> Int {
+        guard count > 0
+            else { return 0 }
 
         var result = 0
         for i in 0..<count {
@@ -56,47 +65,78 @@ public final class LsbBitReader: ByteReader, BitReader {
         return result
     }
 
-    public func bit() -> Int {
-        let bit = self.data[self.offset] & self.bitMask > 0 ? 1 : 0
-
-        if self.bitMask == 128 {
-            self.offset += 1
-            self.bitMask = 1
-        } else {
-            self.bitMask <<= 1
-        }
-
-        return bit
-    }
+    /**
+     Aligns reader's BIT pointer to the BYTE border, i.e. moves BIT pointer to the first BIT of the next BYTE.
 
+     - Note: If reader is already aligned, then does nothing.
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` AFTER calling this method
+     to check if the end was reached.
+     */
     public func align() {
-        guard self.bitMask != 1 else {
-            return
-        }
+        guard self.bitMask != 1
+            else { return }
+
         self.bitMask = 1
         self.offset += 1
     }
 
+    // MARK: ByteReader's methods.
+
+    /**
+     Reads byte and returns it, advancing by one BYTE position.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     - Precondition: Reader MUST be aligned.
+     */
     public override func byte() -> UInt8 {
         precondition(isAligned, "BitReader is not aligned.")
         return super.byte()
     }
 
+    /**
+     Reads `count` bytes and returns them as an array of `UInt8`, advancing by `count` BYTE positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     - Precondition: Reader MUST be aligned.
+     */
     public override func bytes(count: Int) -> [UInt8] {
         precondition(isAligned, "BitReader is not aligned.")
         return super.bytes(count: count)
     }
 
+    /**
+     Reads 8 bytes and returns them as a `UInt64` number, advancing by 8 BYTE positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     - Precondition: Reader MUST be aligned.
+     */
     public override func uint64() -> UInt64 {
         precondition(isAligned, "BitReader is not aligned.")
         return super.uint64()
     }
 
+    /**
+     Reads 4 bytes and returns them as a `UInt32` number, advancing by 4 BYTE positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     - Precondition: Reader MUST be aligned.
+     */
     public override func uint32() -> UInt32 {
         precondition(isAligned, "BitReader is not aligned.")
         return super.uint32()
     }
 
+    /**
+     Reads 2 bytes and returns them as a `UInt16` number, advancing by 2 BYTE positions.
+
+     - Warning: Doesn't check if there is any data left. It is advisable to use `isFinished` BEFORE calling this method
+     to check if the end is reached.
+     - Precondition: Reader MUST be aligned.
+     */
     public override func uint16() -> UInt16 {
         precondition(isAligned, "BitReader is not aligned.")
         return super.uint16()