z85 is a Ruby gem written in C that implements the Z85 binary-to-text encoding.
Z85 as such is provided by the methods encode/decode:
# 💣 USE THESE ONLY IF YOU KNOW WHAT YOU ARE DOING.
Z85.encode("\x86O\xD2o\xB5Y\xF7[") # => "HelloWorld"
Z85.decode("HelloWorld") # => "\x86O\xD2o\xB5Y\xF7["Buffers to be encoded, however, must have a number of bytes divisible by 4:
The binary frame SHALL have a length that is divisible by 4 with no remainder [...] It is up to the application to ensure that frames and strings are padded if necessary.
Arbitrary binaries may no satisfy that, so z85 provides *_with_padding variants to automate padding on your behalf:
# 👍 USE THESE ONES FOR ARBITRARY BINARIES.
"\x86O".bytesize # => 2, no problem
Z85.encode_with_padding("\x86O") # => "Hed^H2"
Z85.decode_with_padding("Hed^H2") # => "\x86O"Given foo, the method encode_with_padding does this:
- Since
foohas three bytes, the method appends one\0:foo\0. - Encodes that padded string, which yields
w]zO/. - Appends the counter, returning
w]zO/1.
The method decode_with_padding just undoes that, so given w]zO/1:
- Chops the counter, obtaining
w]zO/. - Decodes that string, which yields
foo\0. - Chops as many
\0s as the counter says, returningfoo.
Padding support was inspired by https://github.com/artemkin/z85.
Since padding does not belong to the Z85 specification, if you encode with padding using z85, and decode using another library, the decoding end will probably need to implement what decode_with_padding does. Should be straightforward, just emulate what is described in the previous section.
Encoded strings are Encoding::US_ASCII, and decoded ones are Encoding::ASCII_8BIT, also known as Encoding::BINARY.
To be as faithful to the spec as possible, z85 takes the C reference implementation as basis, and adds minimal changes to interact with Ruby objects. Then, there are a couple of personal touches here and there for performance, clarity, or style.
The test suite contains the reference C test suite, and adds roundtrip verifications for a variety of files.
Released under the MIT License, Copyright (c) 2019–ω Xavier Noria.