ShadowEncoder.Sink implemented

Author: dehesa

README.md

@@ -37,7 +37,7 @@ You can choose to add the library through SPM or Cocoapods:
     let package = Package(
         /* Your package name, supported platforms, and generated products go here */
         dependencies: [
-            .package(url: "https://github.com/dehesa/CodableCSV.git", .upToNextMinor(from: "0.5.1"))
+            .package(url: "https://github.com/dehesa/CodableCSV.git", .upToNextMinor(from: "0.5.2"))
         ],
         targets: [
             .target(name: /* Your target name here */, dependencies: ["CodableCSV"])
@@ -48,7 +48,7 @@ You can choose to add the library through SPM or Cocoapods:
 -   [Cocoapods](https://cocoapods.org).
 
     ```
-    pod 'CodableCSV', '~> 0.5.1'
+    pod 'CodableCSV', '~> 0.5.2'
     ```
 
 </p></details>
@@ -324,9 +324,9 @@ The decoding process can be tweaked by specifying configuration values at initia
 
 -   `dataStrategy` (default: `.base64`) specify the strategy to use when decoding data blobs.
 
--   `bufferingStrategy` (default: `.keepAll`) tells the decoder how to cache previously decoded CSV rows.
+-   `bufferingStrategy` (default: `.keepAll`) tells the decoder how to cache CSV rows.
 
-    Caching rows allow random access through `KeyedDecodingContainer`s.
+    Caching rows allow random access through `KeyedDecodingContainer`s. For more information check the `DecodingBuffer` strategy definition.
 
 The configuration values can be set during `CSVDecoder` initialization or at any point before the `decode` function is called.
 
@@ -335,7 +335,7 @@ let decoder = CSVDecoder {
     $0.encoding = .utf8
     $0.delimiters.field = "\t"
     $0.headerStrategy = .firstLine
-    $0.bufferingStrategy = .ordered
+    $0.bufferingStrategy = .keepAll
 }
 
 decoder.decimalStratey = .custom {

sources/Active/Reader/Reader.swift

@@ -84,7 +84,7 @@ extension CSVReader {
         if let l = self.headerLookup {
             lookup = l
         } else {
-            lookup = try self.makeHeaderLookup()
+            lookup = try self.headers.lookupDictionary(onCollision: Error.invalidHashableHeader)
             self.headerLookup = lookup
         }
 
@@ -132,21 +132,6 @@ extension CSVReader {
 // MARK: -
 
 extension CSVReader {
-    /// Creates the lookup dictionary from the headers row.
-    ///
-    /// Although it is officially allowed that two CSV headers have the same value, this method will throw an error if that is the case.
-    /// - throws: `CSVError<CSVReader>` exclusively.
-    internal func makeHeaderLookup() throws -> [Int:Int] {
-        var result: [Int:Int] = .init(minimumCapacity: self.headers.count)
-        for (index, header) in self.headers.enumerated() {
-            let hash = header.hashValue
-            guard case .none = result.updateValue(index, forKey: hash) else {
-                throw Error.invalidHashableHeader()
-            }
-        }
-        return result
-    }
-    
     /// Parses a CSV row.
     /// - parameter rowIndex: The current index location.
     /// - throws: `CSVError<CSVReader>` exclusively.

sources/Active/Reader/ReaderAPI.swift

@@ -118,7 +118,7 @@ extension CSVReader {
     /// - returns: Tuple with the CSV headers (empty if none) and all records within the CSV file.
     public static func parse<S>(input: S, configuration: Configuration = .init()) throws -> Output where S:StringProtocol {
         let reader = try CSVReader(input: input, configuration: configuration)
-        let lookup = try reader.makeHeaderLookup()
+        let lookup = try reader.headers.lookupDictionary(onCollision: Error.invalidHashableHeader)
 
         var result: [[String]] = .init()
         while let row = try reader.parseRow() {
@@ -135,7 +135,7 @@ extension CSVReader {
     /// - returns: Tuple with the CSV headers (empty if none) and all records within the CSV file.
     public static func parse(input: Data, configuration: Configuration = .init()) throws -> Output {
         let reader = try CSVReader(input: input, configuration: configuration)
-        let lookup = try reader.makeHeaderLookup()
+        let lookup = try reader.headers.lookupDictionary(onCollision: Error.invalidHashableHeader)
 
         var result: [[String]] = .init()
         while let row = try reader.parseRow() {
@@ -152,7 +152,7 @@ extension CSVReader {
     /// - returns: Tuple with the CSV headers (empty if none) and all records within the CSV file.
     public static func parse(input: URL, configuration: Configuration = .init()) throws -> Output {
         let reader = try CSVReader(input: input, configuration: configuration)
-        let lookup = try reader.makeHeaderLookup()
+        let lookup = try reader.headers.lookupDictionary(onCollision: Error.invalidHashableHeader)
 
         var result: [[String]] = .init()
         while let row = try reader.parseRow() {
@@ -220,4 +220,10 @@ fileprivate extension CSVReader.Error {
               help: "Make sure the URL is valid and you are allowed to access the file. Alternatively set the configuration's presample or load the file in a data blob and use the reader's data initializer.",
               userInfo: ["File URL": url])
     }
+    /// Error raised when a record is fetched, but there are header names which has the same hash value (i.e. they have the same name).
+    static func invalidHashableHeader() -> CSVError<CSVReader> {
+        .init(.invalidInput,
+              reason: "The header row contain two fields with the same value.",
+              help: "Request a row instead of a record.")
+    }
 }

sources/Active/Writer/Writer.swift

@@ -22,7 +22,7 @@ public final class CSVWriter {
     /// The field to write next.
     public private(set) var fieldIndex: Int
     /// The number of fields per row that are expected.
-    private var expectedFields: Int
+    private(set) internal var expectedFields: Int
 
     /// Designated initializer for the CSV writer.
     /// - parameter configuration: Recipe detailing how to parse the CSV data (i.e. encoding, delimiters, etc.).

sources/Codable/Decodable/Containers/KeyedDecodingContainer.swift

@@ -48,7 +48,7 @@ extension ShadowDecoder {
                 guard let numRows = self.decoder.source.numRows, numRows > 0 else { return [] }
                 return (0..<numRows).compactMap { Key(intValue: $0) }
             case .row:
-                let numFields = self.decoder.source.numFields
+                let numFields = self.decoder.source.numExpectedFields
                 guard numFields > 0 else { return [] }
 
                 let numberKeys = (0..<numFields).compactMap { Key(intValue: $0) }
@@ -65,7 +65,7 @@ extension ShadowDecoder {
                 return self.decoder.source.contains(rowIndex: index)
             case .row:
                 if let index = key.intValue {
-                    return index >= 0 && index < self.decoder.source.numFields
+                    return index >= 0 && index < self.decoder.source.numExpectedFields
                 } else {
                     return self.decoder.source.headers.contains(key.stringValue)
                 }
@@ -283,7 +283,7 @@ extension ShadowDecoder.KeyedContainer {
         case .file:
             guard let rowIndex = key.intValue else { throw DecodingError.invalidKey(forRow: key, codingPath: codingPath) }
             // Values are only allowed to be decoded directly from a nested container in "file level" if the CSV rows have a single column.
-            guard self.decoder.source.numFields == 1 else { throw DecodingError.invalidNestedRequired(codingPath: self.codingPath) }
+            guard self.decoder.source.numExpectedFields == 1 else { throw DecodingError.invalidNestedRequired(codingPath: self.codingPath) }
             index = (rowIndex, 0)
             codingPath.append(IndexKey(index.field))
         }

sources/Codable/Decodable/Containers/SingleValueDecodingContainer.swift

@@ -241,12 +241,12 @@ private extension ShadowDecoder.SingleValueContainer {
             return try transform(string) ?! DecodingError.invalid(type: T.self, string: string, codingPath: self.codingPath)
         case .row(let rowIndex):
             // Values are only allowed to be decoded directly from a single value container in "row level" if the CSV has single column rows.
-            guard source.numFields == 1 else { throw DecodingError.invalidNestedRequired(codingPath: self.codingPath) }
+            guard source.numExpectedFields == 1 else { throw DecodingError.invalidNestedRequired(codingPath: self.codingPath) }
             let string = try source.field(at: rowIndex, 0)
             return try transform(string) ?! DecodingError.invalid(type: T.self, string: string, codingPath: self.codingPath + [IndexKey(0)])
         case .file:
             // Values are only allowed to be decoded directly from a single value container in "file level" if the CSV file has a single row with a single column.
-            if source.isRowAtEnd(index: 1), source.numFields == 1 {
+            if source.isRowAtEnd(index: 1), source.numExpectedFields == 1 {
                 let string = try self.decoder.source.field(at: 0, 0)
                 return try transform(string) ?! DecodingError.invalid(type: T.self, string: string, codingPath: self.codingPath + [IndexKey(0), IndexKey(0)])
             } else {

sources/Codable/Decodable/Containers/UnkeyedDecodingContainer.swift

@@ -48,7 +48,7 @@ extension ShadowDecoder {
         var count: Int? {
             switch self.focus {
             case .file: return self.decoder.source.numRows
-            case .row: return self.decoder.source.numFields
+            case .row: return self.decoder.source.numExpectedFields
             }
         }
 
@@ -298,7 +298,7 @@ extension ShadowDecoder.UnkeyedContainer {
             index = (rowIndex, self.currentIndex)
         case .file:
             // Values are only allowed to be decoded directly from a nested container in "file level" if the CSV rows have a single column.
-            guard self.decoder.source.numFields == 1 else { throw DecodingError.invalidNestedRequired(codingPath: self.codingPath) }
+            guard self.decoder.source.numExpectedFields == 1 else { throw DecodingError.invalidNestedRequired(codingPath: self.codingPath) }
             index = (self.currentIndex, 0)
             codingPath.append(IndexKey(index.field))
         }

sources/Codable/Decodable/DecoderConfiguration.swift

@@ -12,7 +12,7 @@ extension CSVDecoder {
         /// The strategy to use when decoding binary data.
         public var dataStrategy: Strategy.DataDecoding
         /// The amount of CSV rows kept in memory after decoding to allow the random-order jumping exposed by keyed containers.
-        public var bufferingStrategy: Strategy.Buffering
+        public var bufferingStrategy: Strategy.DecodingBuffer
 
         /// Designated initializer setting the default values.
         public init() {

sources/Codable/Decodable/DecodingStrategy.swift

@@ -35,18 +35,26 @@ extension Strategy {
         case custom((_ decoder: Decoder) throws -> Data)
     }
 
-    /// Strategy indicating how many rows are cached for reuse by the decoder.
+    /// Indication of how many rows are cached for reuse by the decoder.
     ///
-    /// The `Decodable` protocol allows CSV rows to be decoded in random-order through the keyed containers. For example, a user can ask for a row at position 24 and then ask for the CSV row at index 1.
-    /// Since it is impossible to foresee how the user will decode the rows, this library allows the user to set the buffering mechanism.
+    /// CSV decoding is an inherently sequential operation; i.e. row 2 must be decoded after row 1. This due to the string encoding, the field/row delimiter usage, and by not setting the underlying row width.
+    /// On the other hand, the `Decodable` protocol allows CSV rows to be decoded in random-order through the keyed containers. For example, a user can ask for a row at position 24 and then ask for the CSV row at index 3.
     ///
-    /// Setting the buffering strategy lets you tweak the memory usage and whether an error will be thrown when previous rows are requested:
-    /// - `keepAll` will impose no restrictions and will make the decoder cache every decoded row. Setting this strategy will double the memory usage, but the user is free to request rows in any order.
-    /// - `ordered` discard decoded rows after usage, only keeping records when a jump forward have been requested through a keyed container.
-    public enum Buffering {
+    /// A buffer is used to marry the sequential needs of the CSV decoder and `Decodable`'s *random* nature. This buffer stores all decoded CSV rows (starts with none and gets filled as more rows are being decoded).
+    /// The `DecodingBuffer` strategy gives you the option to control the buffer's memory usage and whether rows are being discarded after being decoded.
+    public enum DecodingBuffer {
         /// All decoded CSV rows are cached.
+        /// Forward/Backwards decoding jumps are allowed. A row that has been previously decoded can be decoded again.
+        ///
+        /// Setting this strategy will double the memory usage, but the user is free to request rows in any order.
         case keepAll
-        /// Rows are only cached when there are holes between the decoded row indices.
-//        case ordered
+        /// Only CSV rows that have been decoded but not requested by the user are being kept in memory.
+        /// Forward/Backwards decoding jumps are allowed. However, previously requested rows cannot be requested again or an error will be thrown.
+        ///
+        /// This strategy will massively reduce the memory usage, but it will throw an error if a CSV row that was previously decoded is requested from a keyed container.
+        case unfulfilled
+        /// No rows are kept in memory (except for the CSV row being decoded at the moment)
+        /// Forward jumps are allowed, but the rows in-between the jump cannot be decoded.
+        case sequential
     }
 }

sources/Codable/Decodable/Shadow/Source.swift

@@ -9,10 +9,10 @@ extension ShadowDecoder {
         let configuration: CSVDecoder.Configuration
         /// Any contextual information set by the user for decoding.
         let userInfo: [CodingUserInfoKey:Any]
-        /// The header record with the field names.
+        /// The header row with the field names.
         let headers: [String]
         /// Lookup dictionary providing fast index discovery for header names.
-        private let headerLookup: [Int:Int]
+        private var headerLookup: [Int:Int]
 
         /// Creates the unique data source for a decoding process.
         /// - parameter reader: The instance actually reading the input bytes.
@@ -24,7 +24,7 @@ extension ShadowDecoder {
             self.configuration = configuration
             self.userInfo = userInfo
             self.headers = reader.headers
-            self.headerLookup = (self.headers.isEmpty) ? .init() : try! reader.makeHeaderLookup()
+            self.headerLookup = .init()
         }
     }
 }
@@ -77,8 +77,10 @@ extension ShadowDecoder.Source {
 }
 
 extension ShadowDecoder.Source {
-    /// Returns the number of fields that there is per record.
-    var numFields: Int {
+    /// Returns the number of fields that there is per row.
+    ///
+    /// If the number is not know at call time, a row is decoded to figure out how many fields there are.
+    var numExpectedFields: Int {
         let (numRows, numFields) = self.reader.count
         guard numRows <= 0 else { return numFields }
 
@@ -90,7 +92,7 @@ extension ShadowDecoder.Source {
     /// Boolean indicating whether the given field index is out of bounds (i.e. there are no more elements left to be decoded in the row).
     /// - parameter index: The field index being checked.
     func isFieldAtEnd(index: Int) -> Bool {
-        return index >= self.numFields
+        return index >= self.numExpectedFields
     }
 
     /// Returns the field index for the given coding key.
@@ -103,7 +105,11 @@ extension ShadowDecoder.Source {
         if let index = key.intValue { return index }
 
         let name = key.stringValue
-        guard !self.headerLookup.isEmpty else { throw DecodingError.emptyHeader(key: key, codingPath: codingPath) }
+        if self.headerLookup.isEmpty {
+            guard !self.headers.isEmpty else { throw DecodingError.emptyHeader(key: key, codingPath: codingPath) }
+            self.headerLookup = try self.headers.lookupDictionary(onCollision: { DecodingError.invalidHashableHeader(codingPath: codingPath) })
+        }
+        
         return try self.headerLookup[name.hashValue] ?! DecodingError.unmatchedHeader(forKey: key, codingPath: codingPath)
     }
 
@@ -134,6 +140,13 @@ extension ShadowDecoder.Source {
 }
 
 fileprivate extension DecodingError {
+    /// Error raised when a record is fetched, but there are header names which has the same hash value (i.e. they have the same name).
+    static func invalidHashableHeader(codingPath: [CodingKey]) -> DecodingError {
+        DecodingError.dataCorrupted(
+            Context(codingPath: codingPath,
+                    debugDescription: "The header row contain two fields with the same value.")
+        )
+    }
     /// The provided coding key couldn't be mapped into a concrete index since there is no CSV header.
     static func emptyHeader(key: CodingKey, codingPath: [CodingKey]) -> DecodingError {
         DecodingError.keyNotFound(key, .init(codingPath: codingPath,