Overview

IJDK (Incava Java Development Kit) is a library of general-purpose Java code, much of it inspired by and modeled on the equivalent in Ruby. For example, reading a file:

    List<String> lines = IO.readLines("foo.txt");

Note the similarity to idiomatic Ruby:

    lines = IO.readlines "foo.txt"

Usage

IJDK has a very expansive (and growing) library for Java I/O and collections, as an alternative to the JDK. IJDK is mostly inspired by Ruby, and parallels Ruby classes (such as Map/Hash and List/Array) closely, usually moreso than it does the Apache Commons and Guava libraries.

As IJDK grows and gets more behavior, modules -- such as I/O -- may be split into subprojects.

Enhanced collections

IJDK contains collection classes that extend the List (ArrayList) and Map (HashMap/TreeMap) classes from the JDK.

Array

An extension of ArrayList, with Ruby-like methods (thus the name matching Array in Ruby).

    Integer x = null;
    Array<Integer> nums = Array.of(1, 3, 5, 7);
    
    x = nums.get(0);
    assertEqual(1, x);
    
    x = nums.get(-1);
    assertEqual(7, x);
    
    nums.append(9).append(11).append(13);
    assertEqual(Array.of(1, 3, 5, 7, 9, 11, 13), nums);

    x = nums.get(-3);
    assertEqual(9, x);
    
    x = nums.first();
    assertEqual(1, x);

    x = nums.last();
    assertEqual(13, x);
    
    x = nums.takeFirst();
    assertEqual(1, x);
    assertEqual(Array.of(3, 5, 7, 9, 11, 13), nums);
    
    x = nums.takeFirst();
    assertEqual(3, x);
    assertEqual(Array.of(5, 7, 9, 11, 13), nums);

    x = nums.takeLast();
    assertEqual(13, x);
    assertEqual(Array.of(5, 7, 9, 11), nums);

    StringArray sa = nums.toStringArray();
    assertEqual(StringArray.of("5", "7", "9", "11"), sa);

    nums.append(2).append(2).append(2);
    assertEqual(Array.of(5, 7, 9, 11, 2, 2, 2), nums);

    Array<Integer> uniq = nums.unique();
    assertEqual(Array.of(5, 7, 9, 11, 2), uniq);

    assertEqual(true, nums.containsAny(2, 3));
    assertEqual(false, nums.containsAny(3, 4));

    nums.removeAll(2);
    assertEqual(Array.of(5, 7, 9, 11), nums);

    nums.set(0, 4);
    assertEqual(Array.of(4, 7, 9, 11), nums);

    nums.set(-1, 10);
    assertEqual(Array.of(4, 7, 9, 10), nums);

    nums.set(-2, 8);
    assertEqual(Array.of(4, 7, 8, 10), nums);

    nums.set(1, 6);
    assertEqual(Array.of(4, 6, 8, 10), nums);

    x = nums.getRandomElement();
    assertEqual(true, Array.of(4, 6, 8, 10).contains(x));

    String str = nums.join(" + ");
    assertEqual("4 + 6 + 8 + 10", str);

    Array<Integer> odds = Array.of(1, 3, 5);
    Array<Integer> evens = Array.of(2, 4, 6);
    Array<Integer> numbers = odds.plus(evens);
    assertEqual(Array.of(1, 3, 5, 2, 4, 6), numbers);
    
    Array<Integer> squares = numbers.minus(Array.of(2, 3, 5, 6));
    assertEqual(Array.of(1, 4), squares);

    Array<Integer> elements = numbers.elements(1, 0, -2, 0, -4);
    assertEqual(Array.of(3, 1, 4, 1, 5), elements);

    Array<Integer> ary = Array.of(3, 7, 1).sorted();
    assertEqual(Array.of(1, 3, 7), ary);

    Array<Integer> ary = Array.of(3, 7, 1).reverse();
    assertEqual(Array.of(1, 7, 3), ary);

Hash

An extension of HashMap, with Ruby-like methods (thus the name matching Hash in Ruby, and avoiding a collision with java.util.Map).

    // generic type inferred by context:
    Hash<String, String> h = Hash.empty();
    assertEqual(new HashMap<String, String>(), h);

    // creates a map from one key/value pair
    Hash<String, String> h = Hash.of("one", "1");
    HashMap<String, String> expected = new HashMap<String, String>();
    expected.put("one", "1");    
    assertEqual(expected, h);

    // creates a map from two key/value pairs
    Hash<String, String> h = Hash.of("one", "1", "two", "2");
    HashMap<String, String> expected = new HashMap<String, String>();
    expected.put("one", "1");    
    expected.put("two", "2");
    assertEqual(expected, h);

    // creates a map from three key/value pairs
    Hash<String, String> h = Hash.of("first", "abc", "second", "def", "third", "ghi");
    HashMap<String, String> expected = new HashMap<String, String>();
    expected.put("first", "abc");
    expected.put("second", "def");
    expected.put("third", "ghi");
    assertEqual(expected, h);

    // set() returns the map, so methods can be chained:
    Hash<String, String> h = Hash.of("first", "abc");
    h.set("second", "def").set("third", "ghi").set("fourth", "jkl");
    
    HashMap<String, String> expected = new HashMap<String, String>();
    expected.put("first", "abc");
    expected.put("second", "def");
    expected.put("third", "ghi");
    expected.put("fourth", "jkl");
    
    assertEqual(expected, h);

    // same as keySet, but a shorter name:
    Hash<String, String> h = Hash.of("first", "abc", "second", "def", "third", "ghi");
    
    Set<String> expected = new HashSet<String>();
    expected.add("first");
    expected.add("second");
    expected.add("third");
    
    assertEqual(expected, h.keys(), message("h.keys", h.keys()));

    // same as entrySet, but, like keys/keySet, a shorter name:
    Hash<String, String> h = Hash.of("first", "abc", "second", "def", "third", "ghi");

    HashMap<String, String> expected = new HashMap<String, String>();
    expected.put("first", "abc");
    expected.put("second", "def");
    expected.put("third", "ghi");
    
    assertEqual(expected.entrySet(), h.entries(), message("h.entries", h.entries()));

    // Hash is iterable, and can be used in for loops:
    Hash<String, String> h = Hash.of("first", "abc", "second", "def", "third", "ghi");
    for (java.util.Map.Entry<String, String> entry : h) {
        String exp = h.get(entry.getKey());
        assertEqual(exp, entry.getValue(), message("entry", entry));
    }

    // fetch throws an exception if there is no entry for the given key and a default is not given:
    Hash<String, String> h = Hash.of("first", "abc", "second", "def", "third", "ghi");
    assertEqual("abc", h.fetch("first"));
    assertEqual("xyz", h.fetch("fourth", "xyz"));
    assertEqual(null, h.fetch("fourth", null));
    try {
        h.fetch("fourth");
    }
    catch (IllegalArgumentException iae) {
        // expected
    }

Common Collections

Classes for common Java collections of generics, such as a list of strings, and a list of integers:

StringArray

Formerly StringList, an Array of Strings.

   // instead of Array<String>; varargs constructor
   StringArray sa = new StringArray("apple", "banana", "cherry");
   boolean result = sa.anyStartsWith("ba");  // true
   boolean result = sa.anyStartsWith("do");  // false
   StringArray lines = sa.toLines();          // returns each element appended with "\n"
   
   File file = new File("input.txt");
   StringArray lines = StringArray.from(file);

IntegerArray

   // instead of Array<Integer>; varargs constructor
   IntegerArray il = new IntegerArray(3, 6, 9);
   int max = il.maximum();                 // max == 9
   int avg = il.average();                 // avg == 6
   int min = il.minimum();                 // min == 3

Tuples

    Pair<String, Integer> score = Pair.create("Bird", 33);
    // score.first() == "Bird", score.second() == 33

Similarly, the nearly identical KeyValue:

    KeyValue<String, Double> kv = KeyValue.of("one", 1.23);
    // kv.key() == "one", kv.value() == 1.23

And Triple:

    Triple<String, Integer, Double> t = Triple.of("abc", 123, 3.14);

Str

Str is an alternative to java.lang.String, more inspired by the Ruby String class.

    Str s = Str.of("hello, world");
    assertThat(s, equalTo("hello, world"));

    Character ch = s.get(5);
    assertThat(ch, equalTo(','));

    ch = s.get(-5);
    assertThat(ch, equalTo('w'));

    ch = s.first();
    assertThat(ch, equalTo('h'));

    ch = s.last();
    assertThat(ch, equalTo('d'));

    Boolean b = s.startsWith("hello");
    assertThat(b, equalTo(true));

    b = s.endsWith("rld");
    assertThat(b, equalTo(true));

    Str t = s.left(2);
    assertThat(t, equalTo("he"));

    t = s.right(5);
    assertThat(t, equalTo("world"));

    Str u = t.padLeft('.', 10);
    assertThat(u, equalTo(".....world"));

    u = t.pad('*', 8);
    assertThat(u, equalTo("world***"));

    u = new Str("ho! ", 3);
    assertThat(u, equalTo("ho! ho! ho! "));

    List<String> list = Str.of("first,    second  \nthird").toList();
    assertThat(list, equalTo(org.incava.ijdk.collect.Array.of("first", "second", "third")));

    t = s.quote();
    assertThat(t, equalTo("\"hello, world\""));

    u = t.unquote();
    assertThat(u, equalTo("hello, world"));

    t = s.snip(6);
    assertThat(t, equalTo("hello-"));

Range

A Range is a pair of integers. It converts to arrays, and supports iteration.

    Range r = new Range(3, 7);
    r.includes(4); // true
    r.includes(2); // false

    // inclusive of both first and last values
    for (Integer i : r) {
        // iterate from 3 *through* 7
    }

    Array<Integer> list = r.toArray(); // list == [ 3, 4, 5, 6, 7 ]

    // exclusive of last value
    for (Integer i : r.upTo()) {
        // iterate from 3 *through* 6
    }

Iterators

Null-safe Iterators

"Safe" iterators for arrays and collections, which handles the case when they are null.

    String[] ary = new String[0];
    for (String str : Iterate.over(ary)) { // executes zero times
    }
    String[] ary = null;
    for (String str : Iterate.over(ary)) {  // also executes zero times
    }

    List<String> list = null;
    for (String str : Iterate.over(list)) {  // executes zero times
    }

Thus the common idiom as shown below is simplified:

    List<String> list;   // set somewhere
    if (list != null) {
        for (String str : list) {
        }
    }

now:

    List<String> list;   // set somewhere
    for (String str : Iterate.over(list)) {
    }

Numeric Iterators

Execute a given number of times, similar to Ruby:

    3.times { puts "hello" }

    for (Integer i : Iterate.count(3)) {
        System.out.println("hi");
    }

Index/Value Iterators

Returned by Iterate.each (as opposed to Iterate.over, the iterator class It has a value and an index (which starts from zero):

    List<String> list = Arrays.asList(new String[] { "a", "b", "c" });
    for (It<String> it : Iterate.each(list)) {
        // use it.index() and it.value()
    }

    String[] ary = new String[] { "a", "b", "c" };
    for (It<String> it : Iterate.each(ary)) {
        // use it.index() and it.value()
    }

Non-Null Iterator

Iterate.overNonNull yields only non-null elements.

    List<String> list = Arrays.asList(null, "b", null, null, "e", null, "g");
    for (It<String> it : Iterate.overNonNull(list)) {
        // will get the strings "b", "e", and "g" only
    }

MultiMap

Does one-to-many mappings.

    MultiMap<String, String> firstToLastNames = new MultiMap<String, String>();
    firstToLastNames.put("James", "Gosling");
    firstToLastNames.put("James", "Rumbaugh");
    firstToLastNames.put("James", "Foley");
    for (String lastName : firstToLastNames.get("James")) {
    }

Int

An alternate class to Integer:

    Integer num = Int.toInteger("1");   // num == 1
    Integer num = Int.toInteger("");    // num == null
    Integer num = Int.toInteger("xyz"); // num == null
    Integer num = Int.toInteger(null);  // num == null

    Int num = Int.of("1");   // num.obj() == 1
    Int num = Int.of("");    // num.obj() == null
    Int num = Int.of("xyz"); // num.obj() == null
    Int num = Int.of(null);  // num.obj() == null

Pathname

Pathname extends java.io.File with Ruby-like functionality:

    Pathname pn = new Pathname("abc/def.txt");
    pn.baseName();     // == "def.txt"
    pn.relativePath(); // == "abc/def.txt"
    pn.extension();    // == "txt"

Comp

org.incava.ijdk.lang.Comp extends and replaces Comparable (compareTo) usage, normalizing the result to be simply -1, 0, or 1. Comp also contains the methods lt (less than), lte (less than or equal), gt (greater than), and gte (greater than or equal), for simpler comparisons:

   if (Comp.gte("abc", "bbc")) {
   }
   if (Comp.lt("def", "fed")) {
   }

Assertions

org.incava.test.Assertions has been split apart from IJDK, and is available at Attest.

Miscellaneous

• colorized strings (on ANSI terminals)

• logical package structure

The primary classes are in org.incava.ijdk.lang (roughly the equivalent of java.lang) and org.incava.ijdk.collect.

The names of the shadow classes follow the convention of the class that they wrap, with shorter names, such as Str (String), Int (Integer), Obj (Object), etc.

Installation

From the GitHub project ijdk, download and build the project with Gradle.

IJDK is available in the Maven repository.

repositories {
    mavenCentral()
}

dependencies {
    compile group: 'org.incava', name: 'ijdk', version: '3.9.0'
}

Help

Send email to jeugenepace at gmail dot com if you have questions or feedback about IJDK.

More Examples

More detailed examples are at the IJDK Cookbook.

Credits

Much of this was inspired by Ruby and Perl.