leventov / Koloboke

Java Collections till the last breadcrumb of memory and performance

Koloboke

A family of projects around collections in Java (so far).

The Koloboke Collections API

A carefully designed extension of the Java Collections Framework with primitive specializations and more. Java 6+. Apache 2.0 license.

Compatibility with the Java Collections Framework

• All primitive specialization collections extend basic interfaces (Collection, Set, Map), hence could be used as drop-in replacements of slow collections of boxed values
• API for Java 6 and 7 is forward-compatible with all methods new in Java 8

JavaDoc: Java 6 | Java 7 | Java 8

Koloboke Compile

An annotation processor, generates implementations for collection-like abstract classes or interfaces. API agnostic, may be used to generate implementation for classes or interfaces, extending interfaces from the Koloboke Collections API, or, for example, interfaces from the Trove collections library. "Embeddable version" of the Koloboke implementation library.

Quick start

Add the following dependencies in your Maven pom.xml:

  <dependency>
    <groupId>com.koloboke</groupId>
    <artifactId>koloboke-compile</artifactId>
    <version>0.5.1</version>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>com.koloboke</groupId>
    <!-- `jdk6-7` instead of `jdk8` if you use Java 6 or 7 -->
    <artifactId>koloboke-impl-common-jdk8</artifactId>
    <version>1.0.0</version>
  </dependency>

Or in your Gradle build script, you should first apply the propdeps Gradle plugin to enable provided dependencies, and then configure the dependencies block:

dependencies {
    provided 'com.koloboke:koloboke-compile:0.5.1'
    // `jdk6-7` instead of `jdk8` if you use Java 6 or 7
    compile 'com.koloboke:koloboke-impl-common-jdk8:1.0.0'
}

Next step: read the Koloboke Compile tutorial.

Javadocs

The Koloboke implementation library

An efficient implementation of the Koloboke Collections API.

Compatibility with the Java Collections Framework

• Fail-fast semantics everywhere
• null keys are (optionally) supported, just like in java.util.HashMap
• Float.NaN and Double.NaN keys are treated consistently with boxed version (all NaNs are considered equal)

Quick start

Add the following dependencies in your Maven pom.xml:

  <dependencies>
    <dependency>
      <groupId>com.koloboke</groupId>
      <artifactId>koloboke-api-jdk8</artifactId>
      <version>1.0.0</version>
    </dependency>
    <dependency>
      <groupId>com.koloboke</groupId>
      <artifactId>koloboke-impl-jdk8</artifactId>
      <version>1.0.0</version>
      <scope>runtime</scope>
    </dependency>
  <dependencies>

Or to your Gradle build script:

dependencies {
    // `jdk6-7` instead of `jdk8` if you use Java 7 or older
    compile 'com.koloboke:koloboke-api-jdk8:1.0.0'
    runtime 'com.koloboke:koloboke-impl-jdk8:1.0.0'
}

Or similarly for your favourite build system.

Then you can start using collections. Replace all lines like

Map<Integer, Integer> map = new HashMap<>();

with

Map<Integer, Integer> map = HashIntIntMaps.newMutableMap();

Next step: see [the table of equivalents of JDK collection patterns] (http://leventov.github.io/Koloboke/api/1.0/java8/index.html#jdk-equivalents).

---

Releases (with changelog)

---

Contributing, Feedback & Support

Use issues or ask a question on StackOverflow.

---

How to build and develop

Gradle build requires Java 8 compiler, set JAVA_HOME environment variable to the JDK 8 location. Next to your JDK 8 location (i. e. a jdk1.8 directory), JDK 9 installation has to be present in a jdk-9 directory. For meta projects development, JDK 6 and JDK 7 also have to be present in jdk1.6 and jdk1.7 directories sibling to the jdk1.8 directory.

Then

$ git clone [e-mail]:leventov/Koloboke.git
$ cd Koloboke
$ ./gradlew :buildMeta
$ ./gradlew buildMain -x test -x findbugsMain -x findbugsTest
$ ./gradlew idea

Then you can open the project in IntelliJ IDEA.

To rebuild meta projects (code generators), run from the project root dir:

$ ./gradlew :cleanMeta :buildMeta

To rebuild either the lib, benchmarks or both, run

$ ./gradlew cleanMain buildMain

from the lib, benchmarks subdir or the root project dir respectively.

To build the lib for Java 8, run

$ ../gradlew cleanMain buildMain -PlibTargetJava=8

from the lib subdir.

If you want to generate proper Javadocs, especially for Java 6 or 7, you should specify javadocExecutable and jdkSrc build properties (see Gradle docs for how to do that). Typical javadocExecutable value is JAVA_HOME/bin/javadoc[.exe], jdkSrc should point to a directory which contain uncompressed JDK sources, i. e. package structure starting from java, javax, sun, etc. subdirs.

---

Project name history

• Trove (This project was started as a Trove fork, but has nothing in common with Trove for already very long time.)
• UntitledCollectionsProject, UCP
• Higher Frequency Trading Collections, OpenHFT Collections, HFT Collections, HFTC
• Koloboke (Collections) -- current name!