Add new section on details of Codable conformance. (#2371)

* Add new section on details of Codable conformance.

* Expand section on Codable errors.

* Missed some.

* Move discussion of Codable errors to Alternatives Considered.

Author: stephentyrone

proposals/0425-int128.md

@@ -51,11 +51,6 @@ Considered for sordid history).
 The `[U]Int128` types conform to `AtomicRepresentable` on targets with
 `_hasAtomicBitWidth(_128)` set (notably x86\_64, arm64, and arm64\_32).
 
-The `[U]Int128` types conform to `Codable`; however, many existing encoders
-and decoders do not support such large integer types. Therefore they are
-encoded as a pair of 64b integers. This pair is always in little-endian
-order, regardless of the endianness of the architecture.
-
 The actual API of the types is uninteresting; they are entirely constrained by
 their protocol conformances. Notably, these types conform to the following
 protocols, and hence to any protocol that they refine:
@@ -77,6 +72,78 @@ protocols, and hence to any protocol that they refine:
 ¹ For the purposes of this discussion, arm64\_32 and similar architectures
 are "64b targets."
 
+### Codable details
+
+An earlier version of this proposal conformed `[U]Int128` to `Codable`
+with a representation as a pair of `[U]Int64` values. During the first review
+period several people made excellent points:
+
+- Making it possible for encoders to customize how they represent these types
+is desirable. Some cannot represent all 64b values or might prefer to use a
+string representation, others might prefer to treat 128b integers as native
+values to encode.
+
+- If we make it customizable but provide a default behavior, some decoders 
+would have to support that default as well as their desired representation,
+for compatibility with any encodings created between when we added support
+and when they defined their preferred encoding.
+
+For this reason, the proposal has been updated to add new protocol requirements
+for encoders and decoders to support `[U]Int128`, but with default
+implementations that throw an EncodingError or DecodingError unconditionally,
+allowing implementations to choose their preferred behavior when they add
+support without worrying about compatibility with a defaulted implementation.
+
+Thus, the following requirements will be added:
+```swift
+protocol KeyedEncodingContainerProtocol {
+  mutating func encode(_ value: Int128, forKey key: Key) throws
+  mutating func encode(_ value: UInt128, forKey key: Key) throws
+  mutating func encodeIfPresent(_ value: Int128?, forKey key: Key) throws
+  mutating func encodeIfPresent(_ value: UInt128?, forKey key: Key) throws
+  // And matching changes to KeyedEncodingContainer<Key>
+}
+
+protocol KeyedDecodingContainerProtocol {
+  func decode(_ type: Int128.Type, forKey key: Key) throws -> Int128
+  func decode(_ type: UInt128.Type, forKey key: Key) throws -> UInt128
+  func decodeIfPresent(_ type: Int128.Type, forKey key: Key) throws -> Int128?
+  func decodeIfPresent(_ type: UInt128.Type, forKey key: Key) throws -> UInt128?
+  // And matching changes to KeyedDecodingContainer<Key>
+}
+
+protocol UnkeyedEncodingContainer {
+  mutating func encode(_ value: Int128) throws
+  mutating func encode(_ value: UInt128) throws
+  mutating func encode<T: Sequence>(
+    contentsOf sequence: T
+  ) throws where T.Element == Int128
+  mutating func encode<T: Sequence>(
+    contentsOf sequence: T
+  ) throws where T.Element == UInt128
+}
+
+protocol UnkeyedDecodingContainer {
+  mutating func decode(_ type: Int128.Type) throws -> Int128
+  mutating func decode(_ type: UInt128.Type) throws -> UInt128
+  mutating func decodeIfPresent(_ type: Int128.Type) throws -> Int128?
+  mutating func decodeIfPresent(_ type: UInt128.Type) throws -> UInt128?
+}
+
+protocol SingleValueEncodingContainer {
+  mutating func encode(_ value: Int128) throws
+  mutating func encode(_ value: UInt128) throws
+}
+
+protocol SingleValueDecodingContainer {
+  func decode(_ type: Int128.Type) throws -> Int128
+  func decode(_ type: UInt128.Type) throws -> UInt128
+}
+```
+and given default implementations. The default encode implementations throw
+`EncodingError.invalidValue`, and the default decode implementations throw
+`DecodingError.typeMismatch`.
+
 ## Source compatibility
 
 This proposal has no effect on source compatibility.
@@ -126,14 +193,6 @@ While other fixed-width integer types are interesting, 128 bits is a couple
 orders of magnitude more useful than all the others for general-purpose
 software at this point in time.
 
-### Codable conformance
-Because many existing encoders and decoders do not already support 128b
-integers, we use a pair of 64b integers instead. To maximize compatibility,
-or to improve human-readability, we could instead encode these types as
-decimal or hexadecimal strings. However, this would be somewhat less 
-efficient in some use cases, and it is possible for users to achieve the
-same effect by converting to a string before encoding.
-
 ### NSNumber bridging
 `[U]Int128` will not bridge to `NSNumber`. In the future, Swift will need
 a careful rethinking of how best to handle type-erased numbers, but we don't
@@ -142,3 +201,11 @@ that isn't supported on all platforms. In addition, the most common use for
 such bridging, unpacking type-erased fields from encoded dictionaries, is
 somewhat moot since most existing coders do not support 128b integers. We
 will likely revisit this more holistically in the future.
+
+### Codable errors
+It would be nice to introduce new `unsupportedType` error cases for the
+default Codable conformances, but we cannot add new cases with associated
+values and constrained availability to existing enums, which prevents
+attaching context or a useful debug description. It's more useful for users
+if we use existing error cases `invalidValue` and `typeMismatch` but put an
+actionable message in that description field.