Benchmarks scaffolding & Nil/Bool strategies

Author: dehesa

Package.swift

@@ -8,10 +8,12 @@ let package = Package(
     ],
     products: [
         .library(name: "CodableCSV", targets: ["CodableCSV"]),
+//        .executable(name: "CodableCSV-Benchmarks", targets: ["CodableCSV-Benchmarks"])
     ],
     dependencies: [],
     targets: [
         .target(name: "CodableCSV", dependencies: [], path: "sources"),
         .testTarget(name: "CodableCSVTests", dependencies: ["CodableCSV"], path: "tests"),
+//        .target(name: "CodableCSV-Benchmarks", dependencies: ["CodableCSV"], path: "benchmarks"),
     ]
 )

README.md

@@ -99,7 +99,7 @@ A `CSVReadder` parses CSV data from a given input (`String`, or `Data`, or file)
         """
     let reader = try CSVReader(input: string) { $0.headerStrategy = .firstLine }
 
-    let headers = reader.headers      // ["numA", "numB", "numC"]
+    let headers = reader.headers     // ["numA", "numB", "numC"]
     let rowA = try reader.readRow()  // ["1", "2", "3"]
     let rowB = try reader.readRow()  // ["4", "5", "6"]
     ```
@@ -316,7 +316,7 @@ let result = try decoder.decode(CustomType.self, from: data)
 
 ```swift
 let decoder = CSVDecoder { $0.bufferingStrategy = .sequential }
-let content: [Student] = try decoder([Student].self, from: URL("~/Desktop/Student.csv"))
+let content: [Student] = try decoder.decode([Student].self, from: URL("~/Desktop/Student.csv"))
 ```
 
 If you are dealing with a big CSV file, it is preferred to used direct file decoding, a `.sequential` or `.unrequested` buffering strategy, and set *presampling* to false; since then memory usage is drastically reduced.
@@ -325,17 +325,21 @@ If you are dealing with a big CSV file, it is preferred to used direct file deco
 
 The decoding process can be tweaked by specifying configuration values at initialization time. `CSVDecoder` accepts the [same configuration values as `CSVReader`](#Reader-configuration) plus the following ones:
 
+-   `nilStrategy` (default: `.empty`) indicates how the `nil` *concept* (absence of value) is represented on the CSV.
+
+-   `boolStrategy` (default: `.insensitive`) defines how strings are decoded to `Bool` values.
+
 -   `floatStrategy` (default `.throw`) defines how to deal with non-conforming floating-point numbers (e.g. `NaN`).
 
 -   `decimalStrategy` (default `.locale`) indicates how strings are decoded to `Decimal` values.
 
--   `dataStrategy` (default `.deferredToDate`) specify how strings are decoded to `Date` values.
+-   `dateStrategy` (default `.deferredToDate`) specify how strings are decoded to `Date` values.
 
 -   `dataStrategy` (default `.base64`) indicates how strings are decoded to `Data` values.
 
 -   `bufferingStrategy` (default `.keepAll`) controls the behavior of `KeyedDecodingContainer`s.
 
-    Selecting a buffering strategy directly affect the the decoding performance and the amount of memory used during the process. For more information check this README's [Tips using `Codable`](#Tips-using-codable) section and the [`Strategy.DecodingBuffer` definition](sources/Codable/Decodable/DecodingStrategy.swift).
+    Selecting a buffering strategy affects the the decoding performance and the amount of memory used during the process. For more information check this README's [Tips using `Codable`](#Tips-using-codable) section and the [`Strategy.DecodingBuffer` definition](sources/Codable/Decodable/DecodingStrategy.swift).
 
 The configuration values can be set during `CSVDecoder` initialization or at any point before the `decode` function is called.
 
@@ -377,6 +381,10 @@ If you are dealing with a big CSV content, it is preferred to use direct file en
 
 The encoding process can be tweaked by specifying configuration values. `CSVEncoder` accepts the [same configuration values as `CSVWriter`](#Writer-configuration) plus the following ones:
 
+-   `nilStrategy` (default: `.empty`) indicates how the `nil` *concept* (absence of value) is represented on the CSV.
+
+-   `boolStrategy` (default: `.deferredToString`) defines how Boolean values are encoded to `String` values.
+
 -   `floatStrategy` (default `.throw`) defines how to deal with non-conforming floating-point numbers (e.g. `NaN`).
 
 -   `decimalStrategy` (default `.locale`) indicates how decimal numbers are encoded to `String` values.
@@ -412,7 +420,7 @@ encoder.dataStrategy = .custom { (data, encoder) in
 </p></details>
 </ul>
 
-## Tips using `Codable`
+### Tips using `Codable`
 
 `Codable` is fairly easy to use and most Swift standard library types already conform to it. However, sometimes it is tricky to get custom types to comply to `Codable` for specific functionality. That is why I am leaving here some tips and advices concerning its usage:
 
@@ -597,3 +605,22 @@ struct Student: Codable {
 <p align="center">
 <img src="docs/Assets/Roadmap.svg" alt="Roadmap"/>
 </p>
+
+The library has been heavily documented and any contribution is welcome. Please take a look at the [How to contribute](docs/CONTRIBUTING.md) document or peer into a more detailed roadmap on the [Github projects](https://github.com/dehesa/CodableCSV/projects). 
+
+### Community
+
+If `CodableCSV` is not of your liking, the Swift community has other CSV solutions:
+- [CSV.swift](https://github.com/yaslab/CSV.swift) is a simpler library with a focus on conforming to the [RFC4180](https://tools.ietf.org/html/rfc4180) standard.
+
+  It offers a great imperative CSV reader/writer and a row decoder. However, it lacks configurability (such  as custom field/row delimiters, escaping scalar selection, presampling, etc.) and a CSV encoder. It doesn't support whole CSV file decoding and it doesn't mirror Foundation's JSON & PLIST decoder/encoder APIs.
+
+- [SwiftCSV](https://github.com/swiftcsv/SwiftCSV) is an older/popular CSV parse-only library.
+
+  It offers a well-tested imperative CSV parser with a slower development cycle. It lacks an imperative writer, an encoder, a decoder, and parsing configuration values.
+
+- [SwiftCSVExport](https://github.com/vigneshuvi/SwiftCSVExport) reads/writes CSV imperatively with great Objective-C support.
+
+  It offers an imperative CSV reader/writer relying on the Objective-C toolchain, which makes it great to use on Objective-C project.
+
+There are many good tools outside the Swift community. Since writing them all would be a hard task, I will just point you to the great [AwesomeCSV](https://github.com/secretGeek/awesomeCSV) github repo. Take it a look! There are a lot of treasures to be found there.

benchmarks/main.swift

@@ -0,0 +1,4 @@
+import Foundation
+import CodableCSV
+
+print("Benchmarks go here")

sources/Codable/Decodable/Containers/SingleValueDecodingContainer.swift

@@ -58,16 +58,26 @@ extension ShadowDecoder.SingleValueContainer {
     }
 
     func decodeNil() -> Bool {
-        (try? self.lowlevelDecode { $0.isEmpty }) ?? false
+        switch self.decoder.source.configuration.nilStrategy {
+        case .empty: return (try? self.lowlevelDecode { $0.isEmpty }) ?? false
+        case .custom(let closure): return closure(self.decoder)
+        }
     }
 
     func decode(_ type: Bool.Type) throws -> Bool {
-        try self.lowlevelDecode {
-            switch $0.uppercased() {
-            case "TRUE", "YES": return true
-            case "FALSE", "NO", "": return false
-            default: return nil
+        switch self.decoder.source.configuration.boolStrategy {
+        case .deferredToBool:
+            return try self.lowlevelDecode { Bool($0) }
+        case .insensitive:
+            return try self.lowlevelDecode {
+                switch $0.uppercased() {
+                case "TRUE", "YES": return true
+                case "FALSE", "NO", "": return false
+                default: return nil
+                }
             }
+        case .custom(let closure):
+            return try closure(self.decoder)
         }
     }
 

sources/Codable/Decodable/DecoderConfiguration.swift

@@ -5,6 +5,10 @@ extension CSVDecoder {
     @dynamicMemberLookup public struct Configuration {
         /// The underlying `CSVReader` configurations.
         @usableFromInline private(set) internal var readerConfiguration: CSVReader.Configuration
+        /// The strategy to use when decoding a `nil` representation.
+        public var nilStrategy: Strategy.NilDecoding
+        /// The strategy to use when decoding Boolean values.
+        public var boolStrategy: Strategy.BoolDecoding
         /// The strategy to use when dealing with non-conforming numbers.
         public var floatStrategy: Strategy.NonConformingFloat
         /// The strategy to use when decoding decimal values.
@@ -19,6 +23,8 @@ extension CSVDecoder {
         /// Designated initializer setting the default values.
         public init() {
             self.readerConfiguration = .init()
+            self.nilStrategy = .empty
+            self.boolStrategy = .insensitive
             self.floatStrategy = .throw
             self.decimalStrategy = .locale(nil)
             self.dateStrategy = .deferredToDate
@@ -40,12 +46,49 @@ extension CSVDecoder.Configuration {
 // MARK: -
 
 extension Strategy {
+    /// The strategy to use for decoding `nil` representations.
+    public enum NilDecoding {
+        /// An empty string is considered a `nil` value.
+        ///
+        /// An empty string can be both the absence of characters between field delimiters and an empty escaped field (e.g. `""`).
+        case empty
+        /// Decodes the `nil` as a custom value decoded by the given closure.
+        /// - parameter decoding: Function receiving the CSV decoder used to parse a custom `nil` value.
+        /// - parameter decoder: The decoder on which to fetch a single value container to obtain the underlying `String` value.
+        /// - returns: Boolean indicating whether the encountered value was a `nil` representation. If the value is not supported, return `false`.
+        case custom(_ decoding: (_ decoder: Decoder) -> Bool)
+    }
+    
+    /// The strategy to use for decoding `Bool` values.
+    public enum BoolDecoding {
+        /// Defer to `Bool`'s `LosslessStringConvertible` initializer.
+        ///
+        /// For a value to be considered `true` or `false`, it must be a string with the exact value of `"true"` or `"false"`.
+        case deferredToBool
+        /// Decodes a Boolean from an underlying string value by transforming `true`/`false` and `yes`/`no` disregarding case sensitivity.
+        ///
+        /// The value: `True`, `TRUE`, `TruE` or `YES`are accepted.
+        case insensitive
+        /// Decodes the `Bool` as a custom value decoded by the given closure.
+        ///
+        /// If the closure fails to decode a value from the given decoder, the error will be bubled up.
+        /// - parameter decoding: Function receiving the CSV decoder used to parse a custom `Bool` value.
+        /// - parameter decoder: The decoder on which to fetch a single value container to obtain the underlying `String` value.
+        /// - returns: Boolean value decoded from the underlying storage.
+        case custom(_ decoding: (_ decoder: Decoder) throws -> Bool)
+    }
+    
     /// The strategy to use for decoding `Decimal` values.
     public enum DecimalDecoding {
         /// The locale used to interpret the number (specifically `decimalSeparator`).
         case locale(Locale? = nil)
         /// Decode the `Decimal` as a custom value decoded by the given closure.
-        case custom((_ decoder: Decoder) throws -> Decimal)
+        ///
+        /// If the closure fails to decode a value from the given decoder, the error will be bubled up.
+        /// - parameter decoding: Function receiving the CSV decoder used to parse a custom `Decimal` value.
+        /// - parameter decoder: The decoder on which to fetch a single value container to obtain the underlying `String` value.
+        /// - returns: `Decimal` value decoded from the underlying storage.
+        case custom(_ decoding: (_ decoder: Decoder) throws -> Decimal)
     }
 
     /// The strategy to use for decoding `Date` values.
@@ -61,7 +104,12 @@ extension Strategy {
         /// Decode the `Date` as a string parsed by the given formatter.
         case formatted(DateFormatter)
         /// Decode the `Date` as a custom value decoded by the given closure.
-        case custom((_ decoder: Decoder) throws -> Date)
+        ///
+        /// If the closure fails to decode a value from the given decoder, the error will be bubled up.
+        /// - parameter decoding: Function receiving the CSV decoder used to parse a custom `Date` value.
+        /// - parameter decoder: The decoder on which to fetch a single value container to obtain the underlying `String` value.
+        /// - returns: `Date` value decoded from the underlying storage.
+        case custom(_ decoding: (_ decoder: Decoder) throws -> Date)
     }
 
     /// The strategy to use for decoding `Data` values.
@@ -71,7 +119,12 @@ extension Strategy {
         /// Decode the `Data` from a Base64-encoded string.
         case base64
         /// Decode the `Data` as a custom value decoded by the given closure.
-        case custom((_ decoder: Decoder) throws -> Data)
+        ///
+        /// If the closure fails to decode a value from the given decoder, the error will be bubled up.
+        /// - parameter decoding: Function receiving the CSV decoder used to parse a custom `Data` value.
+        /// - parameter decoder: The decoder on which to fetch a single value container to obtain the underlying `String` value.
+        /// - returns: `Data` value decoded from the underlying storage.
+        case custom(_ decoding: (_ decoder: Decoder) throws -> Data)
     }
 
     /// Indication of how many rows are cached for reuse by the decoder.
@@ -86,15 +139,15 @@ extension Strategy {
         /// Forward/Backwards decoding jumps are allowed. A row that has been previously decoded can be decoded again.
         /// - remark: This strategy consumes the largest amount of memory from all the supported options.
         case keepAll
+//        /// Only CSV fields that have been decoded but not requested by the user are being kept in memory.
+//        ///
+//        /// *Keyed containers* can be used to read rows/fields unordered. However, previously requested rows cannot be requested again or an error will be thrown.
+//        /// - remark: This strategy tries to keep the cache to a minimum, but memory usage may be big if the user doesn't request intermediate rows.
+//        case unrequested
         /// No rows are kept in memory (except for the CSV row being decoded at the moment)
         ///
         /// *Keyed containers* can be used, but at a file-level any forward jump will discard the in-between rows. At a row-level *keyed containers* may still be used for random-order reading.
         /// - remark: This strategy provides the smallest usage of memory from them all.
         case sequential
-        /// Only CSV fields that have been decoded but not requested by the user are being kept in memory.
-        ///
-        /// *Keyed containers* can be used to read rows/fields unordered. However, previously requested rows cannot be requested again or an error will be thrown.
-        /// - remark: This strategy tries to keep the cache to a minimum, but memory usage may be big if the user doesn't request intermediate rows.
-//        case unrequested
     }
 }

sources/Codable/Decodable/Internal/Source.swift

@@ -59,10 +59,10 @@ extension ShadowDecoder {
                 self.field = { [unowned buffer = self.buffer, unowned reader = self.reader] in
                     var result: [String]
                     var nextIndex = reader.rowIndex
-                    // C.1. Is the requested row in the buffer? (only the row right before the writer's pointer shall be in teh buffer).
+                    // C.1. Is the requested row in the buffer? (only the row right before the writer's pointer shall be in the buffer).
                     if $0 == nextIndex-1 {
                         result = try buffer.fetch(at: $0) ?! DecodingError.expiredCache(rowIndex: $0, fieldIndex: $1)
-                    // C.2. Is the user trying to queried a previously decoded row?
+                    // C.2. Is the user trying to query a previously decoded row?
                     } else if $0 < nextIndex-1 {
                         throw DecodingError.expiredCache(rowIndex: $0, fieldIndex: $1)
                     // C.3. Is the row further along?

sources/Codable/Encodable/Containers/SingleValueEncodingContainer.swift

@@ -50,11 +50,17 @@ extension ShadowEncoder.SingleValueContainer {
     }
 
     mutating func encodeNil() throws {
-        try self.lowlevelEncoding { String() }
+        switch self.encoder.sink.configuration.nilStrategy {
+        case .empty: try self.lowlevelEncoding { String() }
+        case .custom(let closure): try closure(self.encoder)
+        }
     }
 
     mutating func encode(_ value: Bool) throws {
-        try self.lowlevelEncoding { String(value) }
+        switch self.encoder.sink.configuration.boolStrategy {
+        case .deferredToString: try self.lowlevelEncoding { String(value) }
+        case .custom(let closure): return try closure(value, self.encoder)
+        }
     }
 
     mutating func encode(_ value: Int) throws {