Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/stickytools/sticky-encoding

High-performance binary encoding/decoding for `Swift.Codable` types.
https://github.com/stickytools/sticky-encoding

binary binary-data binary-decoding binary-encoded binary-encoding codable ios linux macos osx swift swift-4 swift-codable swift-decodable swift-encodable

Last synced: 3 months ago
JSON representation

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

Host: GitHub
URL: https://github.com/stickytools/sticky-encoding
Owner: stickytools
License: apache-2.0
Created: 2018-04-15T21:24:31.000Z (almost 7 years ago)
Default Branch: master
Last Pushed: 2020-02-03T23:26:37.000Z (almost 5 years ago)
Last Synced: 2024-09-29T22:04:28.714Z (4 months ago)
Topics: binary, binary-data, binary-decoding, binary-encoded, binary-encoding, codable, ios, linux, macos, osx, swift, swift-4, swift-codable, swift-decodable, swift-encodable
Language: Swift
Homepage: https://stickytools.io/sticky-encoding
Size: 896 KB
Stars: 46
Watchers: 5
Forks: 7
Open Issues: 2
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

README

        ## ⚡️ 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 ![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-lightgray.svg?style=flat)



   





   





   





  





  



---

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](https://stickytools.io/sticky-encoding) - Extensive user guides and reference documentation!  100% documented API, full examples and many hidden details.

* [Contributing Guide](CONTRIBUTING.md) - 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](Sources/Documentation/Sections/Binary Format.md).

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:

```Swift

    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`.

```Swift

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

   let bytes = try encoder.encode(string)

```

Basic structs and classes can also be encoded.

```Swift

   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:

```Swift

    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.

```Swift

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

```

### Encoded Data

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

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

```Swift

   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](https://github.com/stickytools/sticky-encoding).

## Communication and Contributions

- If you **found a bug**, _and can provide steps to reliably reproduce it_, [open an issue](https://github.com/stickytools/sticky-encoding/issues).

- If you **have a feature request**, [open an issue](https://github.com/stickytools/sticky-encoding/issues).

- If you **want to contribute**

   - Fork it! [StickyEncoding repository](https://github.com/stickytools/sticky-encoding)

   - 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](CONTRIBUTING.md).

## Installation

### Swift Package Manager

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

Please see [Swift Package Manager](https://swift.org/package-manager/#conceptual-overview) for further information.

### CocoaPods

StickyEncoding is available through [CocoaPods](http://cocoapods.org). To install it, simply add the following line to your Podfile:

```ruby

   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](https://github.com/tonystone/vagrant-swift)

>

> See the [README](https://github.com/tonystone/vagrant-swift/blob/master/README.md) for instructions.

>

## Author

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

## License

StickyEncoding is released under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)