Merge branch 'release-candidate' into stable

Author: jverkoey

.swift-version

@@ -0,0 +1 @@
+4.2

.travis.yml

@@ -8,14 +8,14 @@ branches:
 
 matrix:
   include:
-    - name: "OS X Xcode 10.1"
+    - name: "OS X / Xcode 10.1"
       os: osx
       osx_image: xcode10.1
       language: swift
       script:
         - swift test
 
-    - name: "Linux Swift 4.2.2"
+    - name: "Ubuntu 16.04 / Swift 4.2.2"
       os: linux
       dist: xenial
       language: c
@@ -27,7 +27,7 @@ matrix:
       script:
         - swift test
 
-    - name: "Linux Swift latest"
+    - name: "Ubuntu 16.04 / Swift latest"
       os: linux
       dist: xenial
       language: c

BinaryCodable.podspec

@@ -0,0 +1,15 @@
+Pod::Spec.new do |s|
+  s.name = 'BinaryCodable'
+  s.version = '0.1.0'
+  s.license = 'Apache 2.0'
+  s.summary = 'Codable-like interfaces for binary representations.'
+  s.homepage = 'https://github.com/jverkoey/BinaryCodable'
+  s.authors = { 'BinaryCodable authors' => '[email protected]' }
+  s.source = { :git => 'https://github.com/jverkoey/BinaryCodable.git', :tag => s.version }
+  s.documentation_url = 'https://github.com/jverkoey/BinaryCodable/'
+
+  s.ios.deployment_target = '12.0'
+  s.osx.deployment_target = '10.12'
+
+  s.source_files = ['Sources/*.swift', 'Sources/*/*.swift']
+end

CHANGELOG.md

@@ -0,0 +1,11 @@
+# 0.1.0
+
+This is the first minor, unstable release of BinaryCodable. The public API for this library is subject to change unexpectedly until 1.0.0 is reached, at which point breaking changes will be mitigated and communicated ahead of time. This initial release includes the following features:
+
+- Encode from Swift types to `Data`.
+- Decode from `Data` to Swift types.
+- Efficiently encode/decode large blocks of arbitrary data.
+- Lazy decoding (read bytes from a source only as they're needed).
+- Encode and decode fixed-width integer types.
+- Encode and decode strings with or without terminators.
+- Cap decoding containers to a maximum length.

Docs/ComparisonToSwiftCodable.md

@@ -0,0 +1,56 @@
+# Comparison to Swift Codable
+
+Binary Codable is similar to Swift [Codable](https://developer.apple.com/documentation/foundation/archives_and_serialization) in that both define an encodable and decodable type that concrete types are expected to implement and both provide encoders and decoders.
+
+Binary Codable is distinct from Swift Codable in the assumptions it makes about how external representations are structured. Swift Codable assumes that external representations have a pre-determined structure (JSON, PropertyList, etc...). Binary Codable, on the other hand, views external representations purely as binary data. This distinction is reflected in the difference of the APIs provided by the BinaryEncoder and BinaryCoder types.
+
+## Interface comparison
+
+Swift Codable and Binary Codable's related types are outlined below.
+
+| Swift Codable | Binary Codable    |
+|:--------------|:------------------|
+| `Codable`     | `BinaryCodable`   |
+| `Encodable`   | `BinaryEncodable` |
+| `Decodable`   | `BinaryDecodable` |
+
+| Swift Codable Encoder          | Binary Codable Encoder              |
+|:-------------------------------|:------------------------------------|
+| `KeyedEncodingContainer`       | No equivalent                       |
+| `UnkeyedEncodingContainer`     | `SequentialBinaryEncodingContainer` |
+| `SingleValueEncodingContainer` | No equivalent                       |
+
+| Swift Codable Encoding Container | Binary Codable Encoding Container                                         |
+|:---------------------------------|:--------------------------------------------------------------------------|
+| `encode(_ value: Int8)`          | `encode<T>(_ value: T) where T: FixedWidthInteger`                        |
+| `encode(_ value: Int16)`         | `encode<T>(_ value: T) where T: FixedWidthInteger`                        |
+| `encode(_ value: Int32)`         | `encode<T>(_ value: T) where T: FixedWidthInteger`                        |
+| `encode(_ value: Int64)`         | `encode<T>(_ value: T) where T: FixedWidthInteger`                        |
+| `encode(_ value: UInt8)`         | `encode<T>(_ value: T) where T: FixedWidthInteger`                        |
+| `encode(_ value: UInt16)`        | `encode<T>(_ value: T) where T: FixedWidthInteger`                        |
+| `encode(_ value: UInt32)`        | `encode<T>(_ value: T) where T: FixedWidthInteger`                        |
+| `encode(_ value: UInt64)`        | `encode<T>(_ value: T) where T: FixedWidthInteger`                        |
+| `encode<T>(_ value: T)`          | `encode<T>(_ value: T)`                                                   |
+| `encode(_ value: String)`        | `encode(_ value: String, encoding: String.Encoding, terminator: UInt8?)`  |
+| No equivalent                    | `encode<S>(sequence: S) throws where S: Sequence, S.Element == UInt8`     |
+
+| Swift Codable Decoder          | Binary Codable Decoder              |
+|:-------------------------------|:------------------------------------|
+| `KeyedDecodingContainer`       | No equivalent                       |
+| `UnkeyedDecodingContainer`     | `SequentialBinaryDecodingContainer` |
+| `SingleValueDecodingContainer` | No equivalent                       |
+
+| Swift Codable Decoding Container                | Binary Codable Decoding Container                                       |
+|:------------------------------------------------|:------------------------------------------------------------------------|
+| `decode(_ type: Int8.Type) -> Int8`             | `decode<T>(_ type: T.Type) -> T where T: FixedWidthInteger`             |
+| `decode(_ type: Int16.Type) -> Int16`           | `decode<T>(_ type: T.Type) -> T where T: FixedWidthInteger`             |
+| `decode(_ type: Int32.Type) -> Int32`           | `decode<T>(_ type: T.Type) -> T where T: FixedWidthInteger`             |
+| `decode(_ type: Int64.Type) -> Int64`           | `decode<T>(_ type: T.Type) -> T where T: FixedWidthInteger`             |
+| `decode(_ type: UInt8.Type) -> UInt8`           | `decode<T>(_ type: T.Type) -> T where T: FixedWidthInteger`             |
+| `decode(_ type: UInt16.Type) -> UInt16`         | `decode<T>(_ type: T.Type) -> T where T: FixedWidthInteger`             |
+| `decode(_ type: UInt32.Type) -> UInt32`         | `decode<T>(_ type: T.Type) -> T where T: FixedWidthInteger`             |
+| `decode(_ type: UInt64.Type) -> UInt64`         | `decode<T>(_ type: T.Type) -> T where T: FixedWidthInteger`             |
+| `decode<T>(_ type: T.Type) where T : Decodable` | `decode<T>(_ type: T.Type) -> T where T: BinaryDecodable`               |
+| `decode(_ type: String.Type) -> String`         | `decodeString(encoding: String.Encoding, terminator: UInt8?) -> String` |
+| No equivalent                                   | `decode(length: Int) -> Data`                                           |
+| No equivalent                                   | `peek(length: Int) -> Data`                                             |