base64

the 64th base of rfc4648

This is a library for base64 encoding and decoding raw data.

Install

Via the copy and paste method

resolvers += "softprops-maven" at "http://dl.bintray.com/content/softprops/maven"

libraryDependencies += "me.lessis" %% "base64" % "0.2.0"

Via a more civilized method which will do the same without all the manual work.

> ls-install base64

Note If you are a bintray-sbt user you can optionally specify the resolver as

resolvers += bintray.Opts.resolver.repo("softprops", "maven")

Usage

This library encodes and decodes Byte Arrays but exposes a typeclass interface for providing input defined as

trait Input[T] {
  def bytes: Array[Byte]
}

Instances of this typeclass are defined for java.nio.ByteBuffer, String, (String, java.nio.charset.Charset), and Array[Bytes].

Standard Encoding

To base64 encode input simply invoke the Encode objects apply method

base64.Encode("Man")

This returns a Byte Array. To make this output human readable, you may wish to create a String from its output.

URL-Safe Encoding

When working with web applications its a common need to base64 encode information in a urlsafe way. Do do so with this library just invoke urlSafe with input on the Encode object

new String(base64.Encode.urlSafe("hello world?")) // aGVsbG8gd29ybGQ_

Multiline Encoding

Fixing the width of base64 encoded data is, in some cases, a desireble property. In these cases, set the multiline flag to true when encoding.

val in = "Base64 is a group of similar binary-to-text encoding schemes that represent binary data in an ASCII string format by translating it into a radix-64 representation. The term Base64 originates from a specific MIME content transfer encoding."

new String(base64.Encode(in, multiline = true))

will produce

QmFzZTY0IGlzIGEgZ3JvdXAgb2Ygc2ltaWxhciBiaW5hcnktdG8tdGV4dCBlbmNvZGluZyBzY2hl
bWVzIHRoYXQgcmVwcmVzZW50IGJpbmFyeSBkYXRhIGluIGFuIEFTQ0lJIHN0cmluZyBmb3JtYXQg
YnkgdHJhbnNsYXRpbmcgaXQgaW50byBhIHJhZGl4LTY0IHJlcHJlc2VudGF0aW9uLiBUaGUgdGVy
bSBCYXNlNjQgb3JpZ2luYXRlcyBmcm9tIGEgc3BlY2lmaWMgTUlNRSBjb250ZW50IHRyYW5zZmVy
IGVuY29kaW5nLg==

Omitting padding

You can omit padding from the output of encodings by setting pad option to false

This will have the following effect on the results

With padding

new String(base64.Encode("paddington")) // cGFkZGluZ3Rvbg==

Without padding

new String(base64.Encode("paddington", pad = false)) // cGFkZGluZ3Rvbg

Decoding

A dual for each is provided with the Decode object.

new String(base64.Decode.urlSafe(base64.Encode.urlSafe("hello world?"))) // hello world?

Why

Chances are you probably need a base64 codec.

Chances are you probably don't need everything that came with the library you use to base64 encode data.

This library aims to only do one thing. base64 _. That's it.

A seconday goal was to fully understand rfc4648 from first principals. Implementation is a good learning tool. You should try it.

Performance

Performance really depends on your usecase, no matter library you use. An attempt was made to compare the encoding and decoding performance with the same input data against apache commons-codec base64 and netty 4.0.7.final base64.

For encoding and decoding I found the following general repeating performance patterns when testing 15,000 runs for each library for each operation.

enc apache commons (byte arrays) took 97 ms
enc netty (byte buf)             took 95 ms
enc ours (byte arrays)           took 121 ms
dec apache commons (byte arrays) took 77 ms
dec netty (byte buf)             took 171 ms
dec ours (byte arrays)           took 85 ms

Take this with a grain of salt. None of these will be the performance bottle neck of your application. This was just a simple measurement test to make sure this library was not doing something totally naive.

inspiration and learning

taken from

Doug Tangren (softprops) 2013-2014

softprops / base64 0.2.0