πŸ”Œ The ultimate binary data reading and writing library
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.gitignore
.travis.yml
LICENSE
README.md
overview.html
pom.xml

README.md

πŸ”Œ Jacobin

jitpack javadocs tests codeclimate license

Jacobin is the ultimate binary reading and writing library. It provides high performance and easy-to-use binary DataReaders, DataWriters and FileEditors, a class that supports both reading and writing to a random access file.

Features

  • Primitive signed and unsigned reading and writing methods
  • Supports parsing and writing UTF-8 strings
  • Memory-efficient offset manipulation (by only keeping the needed byte buffers loaded)
  • Different implementations for each endianness format
  • Atomic offset setting, only reads and writes require synchronization
  • Readable and Writable interfaces
  • 64-bit (long) offsets

Getting started

You can install Jacobin using Maven by adding the JitPack repository to your pom.xml file:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

Next, add the Jacobin dependency:

<dependency>
    <groupId>com.github.hugmanrique</groupId>
    <artifactId>Jacobin</artifactId>
    <version>master-SNAPSHOT</version>
</dependency>

You will need to have Java 8 version 45 or later (older versions might work).

You can find instructions for other package managers such as Gradle on the JitPack project page.

Reading binary data

Jacobin works by wrapping Java streams. Let's try to read data from a ByteArrayInputStream:

ByteArrayInputStream stream = new ByteArrayInputStream(
    new byte[] { 0x78, 0x56, 0x34, 0x12 }
);

Now, let's create a DataReader instance:

LittleEndianDataReader reader = new LittleEndianDataReader(stream);

That's it! You can now use any endianness-dependent methods such as #readUInt32:

long value = reader.readUInt32(); // 0x12345678

Let's say we want to go back to the beginning, skip two bytes and read an int16:

reader.reset();
reader.skip(2);

int otherValue = reader.readInt16(); // 0x1234

You can read more about all the available methods on the LittleEndianDataReader and BigEndianDataReader javadoc pages.

You should always follow general Java I/O good practices such as closing your streams when they are no longer needed. DataReader implements Closeable. 😊

Writing binary data

Jacobin also provides an OutputStream wrapper called DataWriter:

ByteArrayOutputStream stream = new ByteArrayOutputStream();
BigEndianDataWriter writer = new BigEndianDataWriter(stream);

Let's try to write two int64s:

writer.writeInt64(0x123456789ABCDEF0L);
writer.writeInt64(0x9ABCDEF012345678L);

You can check the data was written correctly by converting the OutputStream to a byte array:

byte[] writtenBytes = stream.toByteArray(); // { 0x12, 0x34, ..., 0x56, 0x78 }

You can read more about all the available methods on the LittleEndianDataWriter and BigEndianDataWriter javadoc pages.

Working with random access files

A random access file behaves like a large array of bytes stored in the file system. A FileEditor provides a Readable and Writable implementation that supports both reading and writing to a random access file.

File myAwesomeFile = Paths.get("foo/bar.dat").toFile();

FileEditor editor = new LittleEndianFileEditor(myAwesomeFile);

Now, let's try to move the offset to the eighth byte (starting from 0) and write the bytes of an array in that position:

byte[] importantData = new byte[] { 0x12, 0x34, 0x56 };

editor.setOffset(8);
editor.write(importantData);

Jacobin tries to follow the same semantics as the Java I/O streams API, so you are probably already familiar with them 😎

You can read more about the LittleEndianFileEditor and BigEndianFileEditor classes on their javadoc pages.

Make sure to checkout the Javadocs overview page to see a list of all the available classes and utilities.

License

MIT Β© Hugo Manrique