Documentation for custom encoding/decoding strategies added

Author: dehesa

README.md

@@ -365,11 +365,10 @@ let decoder = CSVDecoder {
     $0.delimiters.field = "\t"
     $0.headerStrategy = .firstLine
     $0.bufferingStrategy = .keepAll
-}
-
-decoder.decimalStrategy = .custom { (decoder) in
-    let value = try Float(from: decoder)
-    return Decimal(value)
+    $0.decimalStrategy = .custom({ (decoder) in
+        let value = try Float(from: decoder)
+        return Decimal(value)
+    })
 }
 ```
 
@@ -458,13 +457,12 @@ let encoder = CSVEncoder {
     $0.delimiters = (field: ";", row: "\r\n")
     $0.dateStrategy = .iso8601
     $0.bufferingStrategy = .sequential
-}
-
-encoder.floatStrategy = .convert(positiveInfinity: "∞", negativeInfinity: "-∞", nan: "≁")
-encoder.dataStrategy = .custom { (data, encoder) in
-    let string = customTransformation(data)
-    var container = try encoder.singleValueContainer()
-    try container.encode(string)
+    $0.floatStrategy = .convert(positiveInfinity: "∞", negativeInfinity: "-∞", nan: "≁")
+    $0.dataStrategy = .custom { (data, encoder) in
+        let string = customTransformation(data)
+        var container = try encoder.singleValueContainer()
+        try container.encode(string)
+    }
 }
 ```
 

sources/declarative/decodable/DecoderConfiguration.swift

@@ -49,6 +49,16 @@ extension Strategy {
         /// 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.
+        ///
+        /// Custom `nil` decoding adheres to the same behavior as a custom `Decodable` type. For example:
+        ///
+        ///     let decoder = CSVDecoder()
+        ///     decoder.nilStrategy = .custom({
+        ///         let container = try $0.singleValueContainer()
+        ///         let string = try container.decode(String.self)
+        ///         return string == "-"
+        ///     })
+        ///
         /// - 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`.
@@ -65,11 +75,22 @@ extension Strategy {
         ///
         /// The value: `True`, `TRUE`, `TruE` or `YES`are accepted.
         case insensitive
-        /// Decodes the `Bool` from an underlying `0`/`1`
+        /// Decodes the `Bool` from an underlying `0` or `1`
         case numeric
-        /// Decodes the `Bool` as a custom value decoded by the given closure.
+        /// 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.
+        ///
+        /// Custom `Bool` decoding adheres to the same behavior as a custom `Decodable` type. For example:
+        ///
+        ///     let decoder = CSVDecoder()
+        ///     decoder.boolStrategy = .custom({
+        ///         let container = try $0.singleValueContainer()
+        ///         switch try container.decode(String.self) {
+        ///         case "si": return true
+        ///         case "no": return false
+        ///         default: throw CSVError<CSVDecoder>(...)
+        ///         }
+        ///     })
         ///
-        /// 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.
@@ -80,9 +101,16 @@ extension Strategy {
     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.
+        /// Decode the `Decimal` 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.
+        ///
+        /// Custom `Decimal` decoding adheres to the same behavior as a custom `Decodable` type. For example:
+        ///
+        ///     let decoder = CSVDecoder()
+        ///     decoder.decimalStrategy = .custom({
+        ///         let value = try Float(from: decoder)
+        ///         return Decimal(value)
+        ///     })
         ///
-        /// 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.
@@ -101,9 +129,17 @@ extension Strategy {
         case iso8601
         /// 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.
+        /// Decode the `Date` 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.
+        ///
+        /// Custom `Date` decoding adheres to the same behavior as a custom `Decodable` type. For example:
+        ///
+        ///     let decoder = CSVDecoder()
+        ///     decoder.dateStrategy = .custom({
+        ///         let container = try $0.singleValueContainer()
+        ///         let string = try container.decode(String.self)
+        ///         // Now returns the date represented by the custom string or throw an error if the string cannot be converted to a 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.
@@ -116,9 +152,17 @@ extension Strategy {
         case deferredToData
         /// Decode the `Data` from a Base64-encoded string.
         case base64
-        /// Decode the `Data` as a custom value decoded by the given closure.
+        /// Decode the `Data` 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.
+        ///
+        /// Custom `Data` decoding adheres to the same behavior as a custom `Decodable` type. For example:
+        ///
+        ///     let decoder = CSVDecoder()
+        ///     decoder.dataStrategy = .custom({
+        ///         let container = try $0.singleValueContainer()
+        ///         let string = try container.decode(String.self)
+        ///         // Now returns the data represented by the custom string or throw an error if the string cannot be converted to a 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.

sources/declarative/encodable/EncoderConfiguration.swift

@@ -46,9 +46,16 @@ extension Strategy {
     public enum NilEncoding {
         /// `nil` is encoded as an empty string.
         case empty
-        /// Encode `nil` as a custom value encoded by the given closure.
+        /// Encode `nil` as a custom value encoded by the given closure. If the closure fails to encode a value into the given encoder, the error will be bubled up.
+        ///
+        /// Custom `nil` encoding adheres to the same behavior as a custom `Encodable` type. For example:
+        ///
+        ///     let encoder = CSVEncoder()
+        ///     encoder.nilStrategy = .custom({
+        ///         var container = try $0.singleValueContainer()
+        ///         try container.encode("-")
+        ///     })
         ///
-        /// If the closure fails to encode a value into the given encoder, the error will be bubled up.
         /// - parameter encoding: Function receiving the encoder instance to encode `nil`.
         /// - parameter encoder: The encoder on which to encode a custom `nil` representation.
         case custom(_ encoding: (_ encoder: Encoder) throws -> Void)
@@ -60,9 +67,16 @@ extension Strategy {
         case deferredToString
         /// Encode the `Bool` as `0` or `1`
         case numeric
-        /// Encode the `Bool` as a custom value encoded by the given closure.
+        /// Encode the `Bool` as a custom value encoded by the given closure. If the closure fails to encode a value into the given encoder, the error will be bubled up.
+        ///
+        /// Custom `Bool` encoding adheres to the same behavior as a custom `Encodable` type. For example:
+        ///
+        ///     let encoder = CSVEncoder()
+        ///     encoder.boolStrategy = .custom({
+        ///         var container = try $1.singleValueContainer()
+        ///         try container.encode($0 ? "si" : "no")
+        ///     })
         ///
-        /// If the closure fails to encode a value into the given encoder, the error will be bubled up.
         /// - parameter encoding: Function receiving the necessary instances to encode a custom `Decimal` value.
         /// - parameter value: The value to be encoded.
         /// - parameter encoder: The encoder on which to generate a single value container.
@@ -74,9 +88,16 @@ extension Strategy {
         /// The locale used to write the number (specifically the `decimalSeparator` property).
         /// - parameter locale: The locale used to encode a `Decimal` value into a `String` value. If `nil`, the current user's locale will be used.
         case locale(_ locale: Locale? = nil)
-        /// Encode the `Decimal` as a custom value encoded by the given closure.
+        /// Encode the `Decimal` as a custom value encoded by the given closure. If the closure fails to encode a value into the given encoder, the error will be bubled up.
+        ///
+        /// Custom `Decimal` encoding adheres to the same behavior as a custom `Encodable` type. For example:
+        ///
+        ///     let encoder = CSVEncoder()
+        ///     encoder.decimalStrategy = .custom({
+        ///         var container = try $1.singleValueContainer()
+        ///         try container.encode($0.description)
+        ///     })
         ///
-        /// If the closure fails to encode a value into the given encoder, the error will be bubled up.
         /// - parameter encoding: Function receiving the necessary instances to encode a custom `Decimal` value.
         /// - parameter value: The value to be encoded.
         /// - parameter encoder: The encoder on which to generate a single value container.
@@ -96,9 +117,17 @@ extension Strategy {
         /// Encode the `Date` as a string formatted by the given formatter.
         /// - parameter formatter: The date formatter used to encode a `Date` value into a `String`.
         case formatted(_ formatter: DateFormatter)
-        /// Formats dates by calling a user-defined function.
+        /// Formats dates by calling a user-defined function. If the closure fails to encode a value into the given encoder, the error will be bubled up.
+        ///
+        /// Custom `Date` encoding adheres to the same behavior as a custom `Encodable` type. For example:
+        ///
+        ///     let encoder = CSVEncoder()
+        ///     encoder.dateStrategy = .custom({
+        ///         var container = try $1.singleValueContainer()
+        ///         let customRepresentation: String = // transform Date $0 into a String or throw if the date cannot be converted.
+        ///         try container.encode(customRepresentation)
+        ///     })
         ///
-        /// If the closure fails to encode a value into the given encoder, the error will be bubled up.
         /// - parameter encoding: Function receiving the necessary instances to encode a custom `Date` value.
         /// - parameter value: The value to be encoded.
         /// - parameter encoder: The encoder on which to generate a single value container.
@@ -111,9 +140,17 @@ extension Strategy {
         case deferredToData
         /// Encoded the `Data` as a Base64-encoded string.
         case base64
-        /// Formats data blobs by calling a user defined function.
+        /// Formats data blobs by calling a user defined function. If the closure fails to encode a value into the given encoder, the encoder will encode an empty automatic container in its place.
+        ///
+        /// Custom `Data` encoding adheres to the same behavior as a custom `Encodable` type. For example:
+        ///
+        ///     let encoder = CSVEncoder()
+        ///     encoder.dataStrategy = .custom({
+        ///         var container = try $1.singleValueContainer()
+        ///         let customRepresentation: String = // transform Data $0 into a String or throw if the data cannot be converted.
+        ///         try container.encode(customRepresentation)
+        ///     })
         ///
-        /// If the closure fails to encode a value into the given encoder, the encoder will encode an empty automatic container in its place.
         /// - parameter encoding: Function receiving the necessary instances to encode a custom `Data` value.
         /// - parameter value: The value to be encoded.
         /// - parameter encoder: The encoder on which to generate a single value container.