stickytools / sticky-encoding

High-performance binary encoding/decoding for `Swift.Codable` types.

⚡️ Stay tuned for updates: upcoming version 1.0.0 (currently in beta) ⚡️

Please star this github repository to stay up to date and show your support.

StickyEncoding

     

---

StickyEncoding facilitates the encoding and decoding of Codable values into and out of a binary format that can be stored on disk or sent over a socket.

Documentation

• User Guides & Reference - Extensive user guides and reference documentation! 100% documented API, full examples and many hidden details.
• Contributing Guide - If you'd like to contribute and need instructions on the build environment, this is the place to go.

Quick Start Guide

Encoding is done using a BinaryEncoder instance and will encode any Encodable type whether you declare conformance to Encodable and let the compiler create the code, or you manually implement the conformance yourself.

Decoding is done using a BinaryDecoder instance and can decode any Decodable type that was previously encoded using the BinaryEncoder. Of course you can declare Encodable or Decodable conformance by using Codable as well.

StickyEncoding creates a compact binary format that represents the encoded object or data type. You can read more about the format in the document Binary Format.

To facilitate many use cases, StickyEncoding encodes the data to an instance of EncodedData. EncodedData contains a binary format suitable for writing directly to memory, disk, or into a byte array. Or in the case of decoding, the format facilitates rapid decoding to Swift instances.

Encoding

To create an instance of a BinaryEncoder:

    let encoder = BinaryEncoder()

Note: You may optionally pass your own userInfo BinaryEncoder(userInfo:) structure and it will be available to you during the encoding.

You can encode any top-level single value type including Int, UInt, Double, Bool, and Strings. Simply pass the value to the instance of the BinaryEncoder and call encode.

   let string = "You can encode single values of any type."

   let bytes = try encoder.encode(string)

Basic structs and classes can also be encoded.

   struct Employee: Codable {
        let first: String
        let last: String
        let employeeNumber: Int
   }

   let employee = Employee(first: "John", last: "Doe", employeeNumber: 2345643)

   let bytes = try encoder.encode(employee)

As well as Complex types with sub classes.

Decoding

To create an instance of a BinaryDecoder:

    let decoder = BinaryDecoder()

Note: You may optionally pass your own userInfo BinaryDecoder(userInfo:) structure and it will be available to you during the decoding.

To decode, you pass the Type of object to create, and an instance of encoded data representing that type.

   let employee = try decoder.decode(Employee.self, from: bytes)

Encoded Data

The BinaryEncoder.encode method returns type Array<UInt8> (likewise BinaryDecoder.decode accepts an Array<UInt8> instance).

[Array<UInt8> is easily converted to other types such as Swift.Data for passing to Foundation methods to store and load data from file.

   let bytes = try encoder.encode(employee)

   // Write the bytes directly to a file.
   FileManager.default.createFile(atPath: "employee.bin", contents: Data(bytes))

Sources and Binaries

You can find the latest sources and binaries on github.

Communication and Contributions

• If you found a bug, and can provide steps to reliably reproduce it, open an issue.
• If you have a feature request, open an issue.
• If you want to contribute
  • Fork it! StickyEncoding repository
  • Create your feature branch: git checkout -b my-new-feature
  • Commit your changes: git commit -am 'Add some feature'
  • Push to the branch: git push origin my-new-feature
  • Submit a pull request :-)

Note: for a instructions on how to build and test StickyEncoding for contributing please see the Contributing Guide.

Installation

Swift Package Manager

StickyEncoding supports dependency management via Swift Package Manager on Darwin as well as Linux.

Please see Swift Package Manager for further information.

CocoaPods

StickyEncoding is available through CocoaPods. To install it, simply add the following line to your Podfile:

   pod "StickyEncoding"

Minimum Requirements

Build Environment

Platform	Swift	Swift Build	Xcode
Linux	4.2	✔	✘
OSX	4.2	✔	Xcode 10.2

Minimum Runtime Version

iOS	OS X	tvOS	watchOS	Linux
8.0	10.10	9.0	2.0	Ubuntu 14.04, 16.04, 16.10

Note:

To build and run on Linux we have a a preconfigure Vagrant file located at https://github.com/tonystone/vagrant-swift

See the README for instructions.

Author

Tony Stone (https://github.com/tonystone)

License

StickyEncoding is released under the Apache License, Version 2.0

sticky-encoding's Issues

Endianness support

In order to support the transmission of objects in binary to systems with differing endianness, support should be added to choose the Endianness for encoding/decoding.

'EncodedData' does not conform to expected type 'Sequence'

When trying to save EncodedData to a file I get the following error.

Argument type 'EncodedData' does not conform to expected type 'Sequence'

This is the code I'm using:

let encoder = BinaryEncoder()
if let encoded = try? encoder.encode([String]()) {
  FileManager.default.createFile(atPath: "export.bin", contents: Data(encoded))
}

I see the same result in both an iOS project and a Linux project. Any help would be appreciated.

CBOR?

Hey! This sound very similar to CBOR. There is a (CBOR Swift implementation of but without proper Encoding/Decoding solution.

Have you thought about switching over to the CBOR standard instead of rolling your own? :)

CocoaPods and Carthage support

CocoaPods and Carthage support would be great as SPM does not work with iOS projects and many developers only use libraries that support these package managers.