Reversible conversions between types
Scala Java Shell
Latest commit c75cbab Jan 10, 2017 @piyushnarang piyushnarang committed on GitHub Merge pull request #264 from piyushnarang/release0.9.5
Update README & version as part of 0.9.5 Bijection release
Permalink
Failed to load latest commit information.
bijection-avro/src Adapt toJson to work similarly as toBinary in order to support genera… Sep 27, 2016
bijection-clojure Add scalafmt (#252) Aug 25, 2016
bijection-core/src Add scalafmt (#252) Aug 25, 2016
bijection-finagle-mysql/src Add support to publish all bijection modules with Scala 2.12 (#263) Jan 7, 2017
bijection-guava/src Add scalafmt (#252) Aug 25, 2016
bijection-hbase/src Clean Up Build To Clear The Path to 2.12 (#257) Nov 26, 2016
bijection-jodatime/src Add scalafmt (#252) Aug 25, 2016
bijection-json/src Add scalafmt (#252) Aug 25, 2016
bijection-json4s/src Add scalafmt (#252) Aug 25, 2016
bijection-macros/src Add scalafmt (#252) Aug 25, 2016
bijection-netty/src/main/scala/com/twitter/bijection/netty Add scalafmt (#252) Aug 25, 2016
bijection-protobuf/src Add scalafmt (#252) Aug 25, 2016
bijection-scrooge/src Add support to publish all bijection modules with Scala 2.12 (#263) Jan 7, 2017
bijection-thrift/src Add scalafmt (#252) Aug 25, 2016
bijection-util/src Add scalafmt (#252) Aug 25, 2016
project Fix up build, get bijection-util onto 2.12 (#262) Dec 11, 2016
.gitignore Clean Up Build To Clear The Path to 2.12 (#257) Nov 26, 2016
.scalafmt.conf Clean Up Build To Clear The Path to 2.12 (#257) Nov 26, 2016
.travis.yml Add support to publish all bijection modules with Scala 2.12 (#263) Jan 7, 2017
CHANGES.md Bugfix release Feb 16, 2016
COMMITTERS.md Create COMMITTERS.md Aug 26, 2016
CONTRIBUTING.md Add CONTRIBUTING.md Mar 21, 2013
LICENSE first commit. Jan 2, 2013
NOTICE first commit. Jan 2, 2013
README.md Update version & README Jan 9, 2017
build.sbt Add support to publish all bijection modules with Scala 2.12 (#263) Jan 7, 2017
sbt Add support for Scala 2.12.0 (#258) Nov 30, 2016
version.sbt Set version to 0.9.6-SNAPSHOT Jan 9, 2017

README.md

Bijection

Build Status Codecov Latest version Chat

A Bijection is an invertible function that converts back and forth between two types, with the contract that a round-trip through the Bijection will bring back the original object. Moreover, the inverse has the same property.

See the current API documentation for more information.

Examples:

> ./sbt bijection-core/console
scala> import com.twitter.bijection._
scala> Bijection[Int, java.lang.Integer](42)
res0: java.lang.Integer = 42

In addition to Bijection, we have Injection. An Injection embeds a type A in a larger space of type B. Every item from A can be round-tripped through B, but not every B can be mapped to A. So Injection is like a pair of function: A => B, B => Try[A].

import com.twitter.bijection._

scala> Injection[Int, String](100)
res0: String = 100

scala> Injection.invert[Int, String](res0)
res1: Try[Int] = Success(100)

If we want to treat an Injection like a Bijection (over a restricted subspace of the larger set), we use the B @@ Rep[A] syntax, for instance: String @@ Rep[Int]

Bijection[Int, String @@ Rep[Int]](100)
res2: com.twitter.bijection.package.@@[String,com.twitter.bijection.Rep[Int]] = 100

Use invert to reverse the transformation:

scala> Bijection.invert[Int, String @@ Rep[Int]](res2)
res3: Int = 100

If you import Conversion.asMethod you can use .as[T] to use an available Bijection/Injection to T:

scala> import com.twitter.bijection.Conversion.asMethod
import com.twitter.bijection.Conversion.asMethod

scala> 1.as[java.lang.Integer]
res6: java.lang.Integer = 1

Bijections and Injections can also be composed. As with functions, andThen composes forward, compose composes backward.

This example round-trips a long into a GZipped base64-encoded string:

scala> val injection = Injection.long2BigEndian andThen Bijection.bytes2GZippedBase64
injection: com.twitter.bijection.Injection[Long,Array[Byte]] = <function1>

scala> injection(123456789L)
res1: com.twitter.bijection.GZippedBase64String = GZippedBase64String(H4sIAAAAAAAAAGNgYGBgjz4rCgBpa5WLCAAAAA==)

scala> injection.invert(res1)
res2: Try[Long] = Success(123456789)

When you have bijections between a path of items you can Bijection.connect or Injection.connect them:

scala> import com.twitter.bijection.Injection.connect
import com.twitter.bijection.Injection.connect

scala> import com.twitter.bijection.Base64String
import com.twitter.bijection.Base64String

scala> import Conversion.asMethod
import Conversion.asMethod

scala> implicit val long2String2Bytes2B64 = connect[Long,String,Array[Byte],Base64String]
string2Long2Bytes2B64: com.twitter.bijection.Bijection[String,com.twitter.bijection.Base64String] = <function1>

scala> 243L.as[Base64String]
res0: com.twitter.bijection.Base64String = Base64String(MjQz)

scala> long2String2Bytes2B64.invert(res0)
res1: Try[Long] = Success(243)

Supported Bijections/Injections

Bijection implicitly supplies Bijections between:

  • all numeric types <-> their boxed java counterparts
  • containers/primitives <-> Json (Injections via bijection-json)
  • thrift/protobuf/avro <-> Array[Byte] (Injections via bijection-protobuf/bijection-thrift/bijection-avro)
  • all numeric types <-> big-endian Array[Byte] encodings (Injections)
  • all numeric types <-> String (Injections)
  • Bijections for all asScala, asJava pairs provided by scala.collection.JavaConverters
  • String <-> utf8 encoded bytes
  • Array[Byte] <-> GZippedBytes
  • Array[Byte] <-> Base64String
  • Array[Byte] <-> GZippedBase64String
  • Array[Byte] <-> java.nio.ByteBuffer
  • Class[T] <-> String (Injection)
  • A => B <-> C => D (function conversion)
  • Bijection/Injection builders for all tuples. ((String,Int) <-> (Array[Byte], java.lang.Integer) is built automatically, for example.)

Additionally there is a method to generate Bijections between most of Scala's built in types: Bijection.toContainer[Int,String,List[Int],Vector[String] returns Bijection[List[Int], Vector[String]

If you see a reversible conversion that is not here and related to types in the standard library of Java or Scala, please contribute!

Serialization via Bufferable

Bufferable[T] handles putting and getting a type T into a ByteBuffer in a composable way. Bufferable[T] instances for all primitives/tuples/containers are provided. Bijections and Injections to any of these types give you binary serialization via Bufferable.

Documentation

To learn more and find links to tutorials and information around the web, check out the Bijection Wiki.

The latest ScalaDocs are hosted on Bijection's Github Project Page.

Get Involved + Code of Conduct

Pull requests and bug reports are always welcome!

Discussion occurs primarily on the Bijection mailing list. Issues should be reported on the GitHub issue tracker.

We use a lightweight form of project governence inspired by the one used by Apache projects. Please see Contributing and Committership for our code of conduct and our pull request review process. The TL;DR is send us a pull request, iterate on the feedback + discussion, and get a +1 from a Committer in order to get your PR accepted.

The current list of active committers (who can +1 a pull request) can be found here: Committers

A list of contributors to the project can be found here: Contributors

Maven

Bijection modules are available on maven central. The current groupid and version for all modules is, respectively, "com.twitter" and 0.9.5.

Current published artifacts are

  • bijection-core
  • bijection-protobuf
  • bijection-thrift
  • bijection-guava
  • bijection-scrooge
  • bijection-json
  • bijection-util
  • bijection-clojure
  • bijection-netty
  • bijection-avro
  • bijection-hbase

Every artifact is published against Scala "2.10", "2.11" and "2.12". To pull in the jars, make sure to add your desired scala version as a suffix, ie:

bijection-core_2.10 or bijection-core_2.11 or bijection-core_2.12.

Chat

Gitter

Authors

License

Copyright 2012 Twitter, Inc.

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0