ShadowEncoder.Sink complete encoding functionality

Author: dehesa

README.md

@@ -360,7 +360,7 @@ decoder.decimalStratey = .custom {
 <ul>
 <details><summary>Basic adoption.</summary><p>
 
-`Codable` is just a type alias for `Decodable` and `Encodable`. When a custom type conforms to `Codable`, the type is stating that it has the ability to decode itself from and encode itself to a external representation. Which representation depends on the decoder or encoder chosen. Foundation provides support for [JSON and Property Lists](https://developer.apple.com/documentation/foundation/archives_and_serialization), but the community provide many other formats, such as: [YAML](https://github.com/jpsim/Yams), [XML](https://github.com/MaxDesiatov/XMLCoder), [BSON](https://github.com/OpenKitten/BSON), and CSV (through this library).
+When a custom type conforms to `Codable`, the type is stating that it has the ability to decode itself from and encode itself to a external representation. Which representation depends on the decoder or encoder chosen. Foundation provides support for [JSON and Property Lists](https://developer.apple.com/documentation/foundation/archives_and_serialization), but the community provide many other formats, such as: [YAML](https://github.com/jpsim/Yams), [XML](https://github.com/MaxDesiatov/XMLCoder), [BSON](https://github.com/OpenKitten/BSON), and CSV (through this library).
 
 Lets see a regular CSV encoding/decoding usage through `Codable`'s interface. Let's suppose we have a list of students formatted in a CSV file:
 
@@ -393,7 +393,7 @@ let students = try decoder.decode([Student], from: data)
 The inverse process (from Swift to CSV) is very similar (and simple).
 
 ```swift
-let encoder = CSVEncoder { $0.headerStraty = .firstLine }
+let encoder = CSVEncoder { $0.headers = ["name", "age", "hasPet"] }
 let newData = try encoder.encode(students)
 ```
 

sources/Active/Writer/Writer.swift

@@ -22,6 +22,8 @@ public final class CSVWriter {
     /// The field to write next.
     public private(set) var fieldIndex: Int
     /// The number of fields per row that are expected.
+    ///
+    /// It is zero, if no expectectations have been set.
     private(set) internal var expectedFields: Int
 
     /// Designated initializer for the CSV writer.
@@ -118,22 +120,24 @@ extension CSVWriter {
     /// It is perfectly fine to call this method when only some fields (but not all) have been writen. This function will complete the row writing row delimiters.
     /// - throws: `CSVError<CSVWriter>` exclusively.
     public func endRow() throws {
+        // 1. Has any field being writen for the current row? If not, write a complete emtpy row.
         guard self.fieldIndex > 0 else {
             return try self.writeEmptyRow()
         }
-        
+        // 2. If the number of fields per row is known, write the missing fields (if any).
         if self.expectedFields > 0 {
-            try stride(from: self.fieldIndex, to: self.expectedFields, by: 1).forEach { [f = self.settings.delimiters.field] _ in
-                try self.lowlevelWrite(delimiter: f)
+            while self.fieldIndex < self.expectedFields {
+                try self.lowlevelWrite(delimiter: self.settings.delimiters.field)
                 try self.lowlevelWrite(field: "")
             }
+        // 3. If the number of fields per row is unknown, store the number of written fields for this row as that number.
         } else {
             self.expectedFields = self.fieldIndex
         }
-        
+        // 4. Write the row delimiter.
         try self.lowlevelWrite(delimiter: self.settings.delimiters.row)
-        self.rowIndex += 1
-        self.fieldIndex = 0
+        // 5. Increment the row index and reset the field index.
+        (self.rowIndex, self.fieldIndex) = (self.rowIndex + 1, 0)
     }
 }
 

sources/Codable/Encodable/Containers/UnkeyedEncodingContainer.swift

@@ -79,7 +79,7 @@ extension ShadowEncoder.UnkeyedContainer {
             return Self(unsafeEncoder: encoder, rowIndex: rowIndex)
         case .row:
             let error = CSVEncoder.Error.invalidContainerRequest(codingPath: codingPath)
-            return ShadowEncoder.InvalidContainer<IndexKey>(error: error, encoder: self.encoder)
+            return ShadowEncoder.InvalidContainer<InvalidKey>(error: error, encoder: self.encoder)
         }
     }
 

sources/Codable/Encodable/Encoder.swift

@@ -38,7 +38,7 @@ extension CSVEncoder {
         let writer = try CSVWriter(configuration: self.configuration.writerConfiguration)
         let sink = try ShadowEncoder.Sink(writer: writer, configuration: self.configuration, userInfo: self.userInfo)
         try value.encode(to: ShadowEncoder(sink: sink, codingPath: []))
-        try writer.endFile()
+        try sink.completeEncoding()
         return try writer.data()
     }
 
@@ -59,6 +59,6 @@ extension CSVEncoder {
         let writer = try CSVWriter(fileURL: fileURL, append: append, configuration: self.configuration.writerConfiguration)
         let sink = try ShadowEncoder.Sink(writer: writer, configuration: self.configuration, userInfo: self.userInfo)
         try value.encode(to: ShadowEncoder(sink: sink, codingPath: []))
-        try writer.endFile()
+        try sink.completeEncoding()
     }
 }

sources/Codable/Encodable/EncodingStrategy.swift

@@ -49,9 +49,9 @@ extension Strategy {
         ///
         /// Foward encoding jumps are allowed and the user may jump backward to continue encoding.
         case unfulfilled
-        /// No rows are kept in memory and written is performed sequentially.
+        /// No rows are kept in memory and writes are performed sequentially.
         ///
-        /// If a keyed container is used to encode rows and a jump forward is performed all the in-between rows are filled with empty fields.
+        /// If a keyed container is used to encode rows and a jump forward is requested all the in-between rows are filled with empty fields.
         case sequential
     }
 }
@@ -63,6 +63,8 @@ extension CSVEncoder: Failable {
         case invalidConfiguration = 1
         /// The encoding coding path is invalid.
         case invalidPath = 2
+        /// An error occurred on the encoder buffer.
+        case bufferFailure = 4
     }
 
     public static var errorDomain: String { "Writer" }
@@ -71,6 +73,7 @@ extension CSVEncoder: Failable {
         switch failure {
         case .invalidConfiguration: return "Invalid configuration"
         case .invalidPath: return "Invalid coding path"
+        case .bufferFailure: return "Invalid buffer state"
         }
     }
 }

sources/Codable/Encodable/Shadow/ShadowEncoder.swift

@@ -38,7 +38,7 @@ extension ShadowEncoder {
         do { // It is weird that this function (as it's defined in the `Encoder` protocol) doesn't throw. Instead there is just a warning in the function documentation.
             return try UnkeyedContainer(encoder: self)
         } catch let error {
-            return InvalidContainer<IndexKey>(error: error, encoder: self)
+            return InvalidContainer<InvalidKey>(error: error, encoder: self)
         }
     }
 
@@ -50,7 +50,7 @@ extension ShadowEncoder {
         do { // It is weird that this function (as it's defined in the `Encoder` protocol) doesn't throw. Instead there is just a warning in the function documentation.
             return try SingleValueContainer(encoder: self)
         } catch let error {
-            return InvalidContainer<IndexKey>(error: error, encoder: self)
+            return InvalidContainer<InvalidKey>(error: error, encoder: self)
         }
     }
 }

sources/Codable/Encodable/Shadow/Sink.swift

@@ -45,9 +45,9 @@ extension ShadowEncoder.Sink {
         if rowIndex < self.writer.rowIndex {
             return self.writer.expectedFields
         } else if rowIndex == self.writer.rowIndex {
-            return max(self.writer.fieldIndex, self.buffer.fieldCount(forRowIndex: rowIndex))
+            return max(self.writer.fieldIndex, self.buffer.fieldCount(for: rowIndex))
         } else {
-            return self.buffer.fieldCount(forRowIndex: rowIndex)
+            return self.buffer.fieldCount(for: rowIndex)
         }
     }
 
@@ -70,29 +70,68 @@ extension ShadowEncoder.Sink {
 
     /// Encodes the given field in the given position.
     func field(value: String, at rowIndex: Int, _ fieldIndex: Int) throws {
-        // 1. Check the given row index is matching the row to be written by the writer.
+        #warning("How to deal with intended field gaps?")
+        // When the next row is writen, check the previous row.
+        // Although, what happens when there are several empty rows?
+        
+        // 1. Is the requested row the same position as the writer's row?
         guard self.writer.rowIndex == rowIndex else {
-            // 1.1. If not, the row must not have been written already (otherwise an error is thrown).
+            // 1.1. If not, the row must not have been written yet (otherwise an error is thrown).
             guard self.writer.rowIndex > rowIndex else { throw CSVEncoder.Error.writingSurpassed(rowIndex: rowIndex, fieldIndex: fieldIndex, value: value) }
             // 1.2. If the row hasn't been writen yet, store it in the buffer.
             return self.buffer.store(value: value, at: rowIndex, fieldIndex)
         }
-        
-        // 2. Check the field index is matching the field to be written by the writer.
+        // 2. Is the requested field the same as the writer's field?
         guard self.writer.fieldIndex == fieldIndex else {
-            // 2.1 If not, the field must not have been written already (otherwise an error is thrown).
+            // 2.1 If not, the field must not have been written yet (otherwise an error is thrown).
             guard self.writer.fieldIndex > fieldIndex else { throw CSVEncoder.Error.writingSurpassed(rowIndex: rowIndex, fieldIndex: fieldIndex, value: value) }
             // 2.2 If the field hasn't been writen yet, store it in the buffer.
             return self.buffer.store(value: value, at: rowIndex, fieldIndex)
         }
-        
-        // 3. This point is only reached if the writer is going to write the provided field next.
+        // 3. Write the provided field since it is the same as the writer's row/field.
         try self.writer.write(field: value)
-        // 4.
-        #warning("TODO: Continue here") // Call next() on buffer returning an element and a boolean indicating whether it is the end of the row.
-//        if self.writer.fieldIndex == self.writer.expectedFields {
-//            try self.writer.endRow()
-//        }
+        // 4. How many fields per row there are? If unknown, stop.
+        guard self.writer.expectedFields > 0 else { return }
+        #warning("How to deal with the first ever row when no headers are given?")
+        while true {
+            // 5. If is not the end of the row, check the buffer and see whether the following fields are already cached.
+            while self.writer.fieldIndex < self.writer.expectedFields {
+                guard let field = self.buffer.retrieveField(at: self.writer.rowIndex, self.writer.fieldIndex) else { return }
+                try self.writer.write(field: field)
+            }
+            // 6. If it is the end of the row, write the row delimiter and pass to the next row.
+            try self.writer.endRow()
+        }
+    }
+    
+    /// Finishes the whole encoding operation by commiting to the writer any remaining row/field in the buffer.
+    ///
+    /// This function works even when the number of fields per row are unknown.
+    func completeEncoding() throws {
+        // 1. Remove from the buffer the rows/fields from the writer point.
+        var remainings = self.buffer.retrieveSequence(from: self.writer.rowIndex, fieldIndex: self.writer.fieldIndex)
+        // 2. After the removal there should be any more rows/fields in the buffer.
+        guard self.buffer.isEmpty else { throw CSVEncoder.Error.corruptedBuffer() }
+        // 3. Iterate through all the remaining rows.
+        while let row = remainings.next() {
+            // 4. If the writer is further back from the next remaining row. Fill the writer with empty rows.
+            while self.writer.rowIndex < row.index {
+                try self.writer.endRow()
+            }
+            // 5. Iterate through all the fields in the row.
+            for field in row.fields {
+                // 6. If the row is further back from the next remaining field. Fill the writer with empty fields.
+                while self.writer.fieldIndex < field.index {
+                    try self.writer.write(field: "")
+                }
+                // 7. Write the targeted field.
+                try self.writer.write(field: field.value)
+            }
+            // 8. Finish the targeted row.
+            try self.writer.endRow()
+        }
+        // 9. Finish the file.
+        try self.writer.endFile()
     }
 }
 
@@ -124,4 +163,10 @@ fileprivate extension CSVEncoder.Error {
               help: "An already written CSV row cannot be rewritten. Be mindful on the encoding order.",
               userInfo: ["Row index": rowIndex, "Field index": fieldIndex, "Value": value])
     }
+    /// Error raised when the encoding operation finishes, but there are still values in the buffer.
+    static func corruptedBuffer() -> CSVError<CSVEncoder> {
+        .init(.bufferFailure,
+              reason: "The encoding operation finished, but there were still values in the encoding buffer.",
+              help: "This should never happen, please contact the repo maintainer sending data with a way to replicate this error.")
+    }
 }

sources/Codable/Encodable/Shadow/SinkBuffer.swift

@@ -13,6 +13,12 @@ extension ShadowEncoder.Sink {
 }
 
 extension ShadowEncoder.Sink.Buffer {
+    ///
+    var isEmpty: Bool {
+        #warning("TODO")
+        fatalError()
+    }
+    
     /// The number of rows being hold by the receiving buffer.
     var count: Int {
         #warning("TODO")
@@ -22,7 +28,7 @@ extension ShadowEncoder.Sink.Buffer {
     /// Returns the number of fields that have been received for the given row.
     ///
     /// If none, it returns *zero*.
-    func fieldCount(forRowIndex rowIndex: Int) -> Int {
+    func fieldCount(for rowIndex: Int) -> Int {
         #warning("TODO")
         fatalError()
     }
@@ -32,4 +38,51 @@ extension ShadowEncoder.Sink.Buffer {
         #warning("TODO")
         fatalError()
     }
+    
+    /// Retrieves and removes from the buffer the indicated value.
+    func retrieveField(at rowIndex: Int, _ fieldIndex: Int) -> String? {
+        #warning("TODO")
+        fatalError()
+    }
+    
+    /// Retrieves and removes from the buffer all rows/fields from the given indices.
+    ///
+    /// This function never returns rows at an index smaller than the passed `rowIndex`. Also, for the `rowIndex`, it doesn't return the fields previous the `fieldIndex`.
+    func retrieveSequence(from rowIndex: Int, fieldIndex: Int) -> RowSequence {
+        #warning("TODO")
+        fatalError()
+    }
+}
+
+extension ShadowEncoder.Sink.Buffer {
+    ///
+    struct RowSequence: Sequence, IteratorProtocol {
+        ///
+        mutating func next() -> Row? {
+            #warning("TODO")
+            fatalError()
+        }
+        
+        var isEmpty: Bool {
+            #warning("TODO")
+            fatalError()
+        }
+    }
+}
+
+extension ShadowEncoder.Sink.Buffer {
+    ///
+    struct Row {
+        ///
+        let index: Int
+        ///
+        let fields: [Field]
+    }
+    
+    struct Field {
+        ///
+        let index: Int
+        ///
+        let value: String
+    }
 }

tests/CodableTests/DecodingRegularUsageTests.swift

@@ -1,15 +1,13 @@
 import XCTest
-@testable import CodableCSV
+import CodableCSV
 
-/// Tests for the decodable pet store data.
+/// Tests checking the regular decoding usage.
 final class DecodingRegularUsageTests: XCTestCase {
     override func setUp() {
         self.continueAfterFailure = false
     }
 }
 
-// MARK: -
-
 extension DecodingRegularUsageTests {
     /// Test data used throughout this `XCTestCase`.
     private enum TestData {

tests/CodableTests/DecodingSinglesTests.swift

@@ -8,8 +8,6 @@ final class DecodingSinglesTests: XCTestCase {
     }
 }
 
-// MARK: -
-
 extension DecodingSinglesTests {
     /// Tests the decoding of a completely empty file.
     func testEmptyFile() throws {