Skip to content

hugmanrique/Jacobin

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
src
 
 
 
 
 
 
 
 
 
 
 
 

πŸ”Œ 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

About

πŸ”Œ The ultimate binary data reading and writing library

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published