Thursday, May 13, 2010

google's guava library tutorial part 2: joys of Ordering

In the first part of my tutorial , I explained anything related to Strings in Guava. In this part of my tutorial, I will explain the Ordering class which combines the power of Comparators with Collections' functionality and which adds other interesting features (such as compound comparators). This class is really useful if you need to order your Iterable, find the maximum/minimum element in your Iterable, find the index of an arbitrary element. It implements Comparator interface for backward compatibility.

I will use a basic Employee class during my examples. Employee is a mutable class with three attributes: id, name and years of service..



class Employee implements Comparable < Employee > {
private int id;
private String name;
private int yearsOfService;

public Employee(int id, String name, int yearsOfService){
this.id = id;
this.name = name;
this.yearsOfService = yearsOfService;
}
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public int getYearsOfService() {
return yearsOfService;
}
public void setYearsOfService(int yearsOfService) {
this.yearsOfService = yearsOfService;
}
@Override
public int compareTo(Employee employee) {
return this.getName().compareTo(employee.getName());
}

@Override
public String toString() {
String toString = "id="+id
+"-name="+name+"-years of service="+yearsOfService;

return toString;
}

}


As I implemented Comparable in the Employee class, I have to add compareTo(). In this method I only compare the name of the employees. I'll create three employees and add them to an ArrayList.


Employee sezinKarli = new Employee(4, "Sezin Karli", 4);
Employee darthVader = new Employee(3, "Darth Vader", 5);
Employee hanSolo = new Employee(2, "Han Solo", 10);
List < Employee > employeeList =
Lists.newArrayList(sezinKarli, hanSolo, darthVader);
System.out.println("employee list: "+employeeList);
//output:
//employee list: [id=4-name=Sezin Karli-years of service=4,
// id=2-name=Han Solo-years of service=10,
// id=3-name=Darth Vader-years of service=5]


There are many ways to create an Ordering. You can create one using the good old Comparator, using a predefined list of objects that explicitly imposes the ordering strategy, using the toString() method of the objects in hand and using the compareTo() method of the objects. You'll need to implement Comparable in your object if you want to take the compareTo() road. Lets create two comparators. One for comparing the years of service and another for employee id.


Comparator < Employee > yearsComparator =
new Comparator < Employee >(){
@Override
public int compare(Employee employee1, Employee employee2) {
return (
employee1.getYearsOfService() - employee2.getYearsOfService());
}
};

Comparator < Employee > idComparator =
new Comparator < Employee >(){
@Override
public int compare(Employee employee1, Employee employee2) {
return (employee1.getId() - employee2.getId());
}
};


//Create an Ordering from a Comparator
Ordering < Employee > orderUsingYearsComparator =
Ordering.from(yearsComparator);
//Sort the employee list using years comparator
List < Employee > sortedCopy =

orderUsingYearsComparator.sortedCopy(employeeList);
System.out.println(
"sorted copy based on years of service comparator: "+sortedCopy);
/*
output:
sorted copy based on years of service comparator:
[id=4-name=Sezin Karli-years of service=4,
id=3-name=Darth Vader-years of service=5,
id=2-name=Han Solo-years of service=10]

*/


The example above is not different from calling Collections.sort() with the comparator in hand but notice that we don't sort Collections but Iterables.

With explicit(), we create an Ordering where we impose an order explicitly.
I want to order en enum type (colors) and I want red, blue, green as order. I created the enum type as instance variable.

static enum Colors{RED, GREEN, BLUE, YELLOW};


Not lets see the Ordering part.

Ordering < Colors > explicitOrdering =
Ordering.explicit(Colors.RED, Colors.BLUE, Colors.GREEN);

List < Colors > colorList =
Lists.newArrayList(Colors.BLUE, Colors.RED,
Colors.BLUE, Colors.GREEN, Colors.RED);

List < Colors > sortedCopy8 =
explicitOrdering.sortedCopy(colorList);
System.out.println("ordered color list: "+sortedCopy8);
//ordered color list: [RED, RED, BLUE, BLUE, GREEN]
//we imposed the RED, BLUE, GREEN order and
//the result conforms to that


Notice that explicit() works only with the given objects. You can't sort you iterable if you didnt specify the order in explicit(). If you try to to that you'll get IncomparableValueException.

Let me show you how to create an Ordering using toString() method of the object in hand.


Ordering < Object > usingToString = Ordering.usingToString();
// returns an ordering which uses the natural
// order comparator on toString() results of objects
List < Employee > sortedCopy3 =
usingToString.sortedCopy(employeeList);
System.out.println("sorted usingToString: "+sortedCopy3);

/*
sorted usingToString:
[id=2-name=Han Solo-years of service=10,
id=3-name=Darth Vader-years of service=5,
id=4-name=Sezin Karli-years of service=4]
*/


Lets create an Ordering with natural ordering (using compareTo() of the objects)


Ordering < Employee > natural = Ordering.natural();
List < Employee > sortedCopy4 = natural.sortedCopy(employeeList);
System.out.println("sorted with natural: "+sortedCopy4);
/*
sorted with natural:
[id=3-name=Darth Vader-years of service=5,
id=2-name=Han Solo-years of service=10,
id=4-name=Sezin Karli-years of service=4]

*/


We can do binary search on the sorted list for an element. Notice that the Ordering that calls the binary search method and Ordering that sorted the Iterable in hand must be the same. binarySearch() was available in Collections class just like min() and max() we'll see in next examples.


int binarySearch = natural.binarySearch(sortedCopy4, sezinKarli);
System.out.println("My index in the list: "+binarySearch); // 2


I will add elements of employee list, 2 null elements to a new list so we can explore new methods related to the handling of null elements.


List < Employee > employeeListWithNulls =
new ArrayList < Employee > (employeeList);
employeeListWithNulls.add(null);
employeeListWithNulls.add(null);



2 methods can be used for changing the handling of null elements. nullsFirst(), (nullsLast()) returns an Ordering which puts null elements to the beginning (end) of every non-null value.


// sort the employee list with natural ordering
// and put the null elements to the beginning
List < Employee > sortedCopy5 =
natural.nullsFirst().sortedCopy(employeeListWithNulls);
System.out.println("nulls first: "+sortedCopy5);
/*
nulls first:
[null, null, id=3-name=Darth Vader-years of service=5,
id=2-name=Han Solo-years of service=10,
id=4-name=Sezin Karli-years of service=4]

*/

// sort the employee list with natural ordering
//and put the null elements to the ending
List < Employee > sortedCopy6 =
natural.nullsLast().sortedCopy(employeeListWithNulls);
System.out.println("nulls last: "+sortedCopy6);

/*
nulls last:
[id=3-name=Darth Vader-years of service=5,
id=2-name=Han Solo-years of service=10,
id=4-name=Sezin Karli-years of service=4, null, null]

*/


I'd like to find the employee with the highest (lowest) time of service. I can do a sort based on years of service but that'll be slower then doing a single sweep for finding the element with max (min) year of service.


Employee employeeWithMaxYearsOfService =
orderUsingYearsComparator.max(employeeList);
System.out.println(employeeWithMaxYearsOfService);
// Han solo has the biggest year of service for the company

//lets find the minimum
Employee employeeWithMinYearsOfService =
orderUsingYearsComparator.min(employeeList);
System.out.println(employeeWithMinYearsOfService);
// Sezin has the smallest year of service for the company


/*
* min() and max() can be used for any iterable.
* Notice that these methods are overloaded and
* it's possible to use them on two elements or
* an arbitrary number of elements (var-arg)
* */

//Sezin or Darth has the longest year of service?
Employee max =
orderUsingYearsComparator.max(sezinKarli, darthVader);
System.out.println(max); //Vader

//Lets see the var-arg version,
// The result below must be the same
//with employeeWithMaxYearsOfService
//because we used each element in the
// employee list and the same Ordering
Employee max2 =
orderUsingYearsComparator.max(sezinKarli, darthVader, hanSolo);
System.out.println(
"Are the max results the same?: "
+max2.equals(employeeWithMaxYearsOfService)); //true



In each ordering we defined an increasing order. We can reverse the Ordering calling reverse() and obtaining a new Ordering. Lets build a new ordering that'll use the idComparator.


Ordering < Employee > reverseIdOrdering =
Ordering.from(idComparator).reverse();

// We will have an ordering of decreasing employee ids if we use
// this Ordering
List < Employee > employeeWithReverseIdOrder =

reverseIdOrdering.sortedCopy(employeeList);
System.out.println(
"employeeWithReverseIdOrder:"+ employeeWithReverseIdOrder);
/*
employeeWithReverseIdOrder:[
id=4-name=Sezin Karli-years of service=4,
id=3-name=Darth Vader-years of service=5,
id=2-name=Han Solo-years of service=10]

*/
// As you can see the ids are 4, 3 and
//2 (an array with decreasing order



A useful ability of Orderings is the fact that you can combine multiple Comparators with it. Call compound() for this. If the result of comparator1 is 0 then the second one will be called and this will continue until a non-zero value (a larger/smaller relationship) is obtained from the comparator. If all comparators return 0 then the elements are treated as equal (we get 0 from the combined comparator).


List < Employee > newEmployeeList =
Lists.newArrayList(new Employee(1, "Mr Pink", 8),
new Employee(2, "Mr Brown", 8), new Employee(3, "Mr Green", 3),
new Employee(4, "Mr Yellow", 5));

//We previously created an Ordering
// by id (orderUsingYearsComparator)
//Now lets add id comparator to this Ordering

Ordering < Employee > combinedComparatorOrdering =
orderUsingYearsComparator.compound(idComparator);
List < Employee > sortedCopy7 =
combinedComparatorOrdering.sortedCopy(newEmployeeList);
//First by years of service then by id
System.out.println("Combined comparators: "+sortedCopy7);
/*Combined comparators:
[id=3-name=Mr Green-years of service=3,
id=4-name=Mr Yellow-years of service=5,
id=1-name=Mr Pink-years of service=8,
id=2-name=Mr Brown-years of service=8]
*/



As you can see the years of service increase (3 then 5 then two 8). When years of service comparator see that the result is a draw the second comparator is called. As you can see Mr Pink and Mr Brown have the same years of service so their id are inspected and the order between them is calculated. As the id of Mr Pink is less than Mr Brown's he's before Mr Brown.

This is all for compound comparators.
There are two slightly different methods for checking if the iterable in hand is ordered. isOrdered() checks if each element is less than/equal to the subsequent element. isStrictlyOrdered() checks if each element is strictly less than the subsequent element.


List < Integer > integers = Lists.newArrayList(1, 2, 3, 4);
// This should return true from isOrdered() and isStrictlyOrdered()
// because the numbers are increasing( isOrdered() = true)
// and there's no consecutive and equal
// elements (isStrictlyOrdered = true)

boolean ordered = Ordering.natural().isOrdered(integers);
System.out.println("isOrdered: "+ordered);
boolean strictlyOrdered =
Ordering.natural().isStrictlyOrdered(integers);
System.out.println("isStrictlyOrdered: "+strictlyOrdered);

//Lets use another list with equal elements inside

List < Integer > newIntegers =
Lists.newArrayList(1, 2, 3, 3, 4);
// The numbers are increasing( isOrdered() = true)
// and there's consecutive and equal
// elements (isStrictlyOrdered = false)

ordered = Ordering.natural().isOrdered(newIntegers);
System.out.println("isOrdered: "+ordered);
strictlyOrdered =
Ordering.natural().isStrictlyOrdered(newIntegers);
System.out.println("isStrictlyOrdered: "+strictlyOrdered);



Using functions as Ordering is quite interesting, but I will explain functional programming capabilities later so lets skip it for the moment.

Tuesday, May 11, 2010

google's guava library tutorial part 1: fun with string-related stuff

I was planning to create a Guava tutorial. But it seems like it'll be too large for a single post, so I opted on splitting it into several parts. The first part contains everything related to Strings. Four main classes are explained:
  • CharMatcher (which can be considered as a light form of JDK's Pattern+Matcher with string manipulation capabilities)
  • Joiner and MapJoiner (which are useful for joining iterables or arrays into string representations)
  • Splitter (which is split() of JDK on steroids).


CharMatcher can be thought as a Pattern+Matcher of JDK in a more simple and practical form. It's not a full fledged replacement because you can't use regular expressions as you do on JDK.

String string = "Scream 4";
// I get a predefined CharMatcher 
//which will accept letters or digits
CharMatcher matcher = CharMatcher.JAVA_LETTER_OR_DIGIT;
// You can find how many times a letter
// or a digit is seen
// Much more practical to use a Pattern 
//and a Matcher then iterate over the 
//Matcher results for counting
int count = matcher.countIn(string);
System.out.println("Letter or digit count: "+count);
// 7 characters

/*
* matchesAllOf (matchesNoneOf) checks 
* if all (none) of the elements
* in the given string matches with the
* matcher in hand.
* */
System.out.println(matcher.matchesAllOf("scream")); 
// true
System.out.println(matcher.matchesAllOf("scream ")); 
// false because there's an empty 
//space at the end
System.out.println(matcher.matchesNoneOf("_?=)(")); 
// true because no letters or 
//digits in it


You can negate the matcher so it accepts the complementary character set. e.g. if our CharMatcher was accepting {a, b, c}, it'll accept any character except {a, b, c}.

CharMatcher negatedMatcher = matcher.negate();
/*
* You can think that true, false,
* true will become false, true, false
* because now our matcher is a
* non-letter, non-digit matcher.
* But no, the result will be false,
* false, false.
* The interesting one is the second one.
* The negatedMatcher matches only
* the empty space part of "scream ".
* So it returns "false".
* */

System.out.println(negatedMatcher.matchesAllOf("scream")); 
//false
System.out.println(negatedMatcher.matchesAllOf("scream "));
//false
System.out.println(negatedMatcher.matchesNoneOf("_?=)("));
//false



removeFrom() and retainFrom() are really convenient methods. The first one removes the matching string while the second one extracts the matching string.


String review = "Scream 4 is the #1 teen-slasher!";
CharMatcher whitespaceMatcher = CharMatcher.JAVA_WHITESPACE;
String result = whitespaceMatcher.removeFrom(review); 
// This matcher will remove the 
//matching characters (whitespaces)
System.out.println("The sentence without whitespaces: "+result);
//output: Scream4isthe#1teen-slasher!

/*
* I want the numbers in the text above.
* I can do that by first taking 
*the predefined digit CharMatcher and
* then calling retainFrom() for 
* the string in hand.
* */
String result2 = CharMatcher.DIGIT.retainFrom(review);
System.out.println("Retained digits: "+result2); 
// I'll get '41' as a result 
// because I have 4 and 1 as digits



indexIn() returns the index of the first matching character.

//I'd like to learn the index
// of the digit result too.
//The first element is '4'

int indexOfDigit = CharMatcher.DIGIT.indexIn(review);
System.out.println("index Of Digit: "+indexOfDigit); 
// 4's index is 7


Although it's possible to use CharMatcher with predefined matcher setting you can as well build your own.

CharMatcher onlyEvenNumbersMatcher = CharMatcher.anyOf("2468"); 
// This accepts any even number
CharMatcher noEvenNumbersMatcher = CharMatcher.noneOf("2468"); 
// This accepts everything 
//but even numbers
CharMatcher largeAtoZ = CharMatcher.inRange('A', 'Z');
CharMatcher aToZ = CharMatcher.inRange('a', 'z').or(largeAtoZ);
// we added A-Z with 'or' here. 
// You can join CharMatchers
// with "and" too.

System.out.println(
"Even numbers matcher result: "
+onlyEvenNumbersMatcher.matchesAllOf("1354")); 
// false. 1,3,5 are not ok

System.out.println(
"Even numbers matcher result: "
+onlyEvenNumbersMatcher.matchesAllOf("starwars")); 
// false. only even numbers are ok

System.out.println(
"Even numbers matcher result: "
+onlyEvenNumbersMatcher.matchesAllOf("2466")); 
// true. all of them are even

System.out.println(
"No even numbers matcher result: "
+noEvenNumbersMatcher.matchesAllOf("1354")); 
// false. 4 is not ok

System.out.println(
"No even numbers matcher result: "
+noEvenNumbersMatcher.matchesAllOf("1337")); 
// true. none of them are even

System.out.println(
"No even numbers matcher result: "
+noEvenNumbersMatcher.matchesAllOf("supermario")); 
// true. none of them are even

System.out.println(
"a to Z matcher result: "+aToZ.matchesAllOf("sezin")); 
System.out.println(
"a to Z matcher result: "+aToZ.matchesAllOf("Sezin")); 
System.out.println(
"a to Z matcher result: "+aToZ.matchesAllOf("SeZiN")); 
System.out.println(
"a to Z matcher result: "+aToZ.matchesAllOf("SEZIN")); 
// true. all strings are ok.
// All of the characters are 
// in {a, .., z} and {A, .., Z} range

System.out.println(
"a to Z matcher result: "+aToZ.matchesAllOf("scream4")); 
// false. if 4 was not here every
// character in hand was in [a-Z]   


You can use trimFrom(), trimLeadingFrom() and trimTrailingFrom() for enhanced trimming capability. Next class is the Joiner class. You probably know splitting capabilities of JDK. It's a mystery why a string joining mechanism is not added to JDK. Guava's Joiner is here to help you in case you need one. Joiner basically takes an iterable or an array and joins all the elements inside as Strings. After that, you can directly add it to a StringBuilder, an Appendable (like PrintWriter, BufferedWriter ... etc), or obtain a String in the "element1 SEPARATOR element2...." form. We choose the separator with on() method of Joiner class. It's possible to use a CharMatcher, a Pattern or a String as separator.

// lets build an array list with 
//4 letters content
ArrayList charList = Lists.newArrayList("a", "b", "c", "d");
StringBuilder buffer = new StringBuilder();

// You can easily add the joined
// element list to a StringBuilder
buffer = Joiner.on("|").appendTo(buffer, charList);
System.out.println(
"Joined char list appended to buffer: "+buffer.toString());
// Joined char list appended to buffer: a|b|c|d

//Below we join a list with ", "
// separator for obtaining a String
String joinedCharList = Joiner.on(", ").join(charList);
System.out.println(
"Joined char list as String: "+joinedCharList);

//Joined char list as String: a, b, c, d

//I'm adding a null value for
// further exploration of Joiner features
charList.add(null);
System.out.println(charList);
//  null at the end: 
//[a, b, c, d, null]

// Below the Joiner will skip
// null valued elements automatically
String join4 = Joiner.on(" - ").skipNulls().join(charList);
System.out.println(join4); 
// output: a - b - c - d

// Below, the Joiner will give
// a value to null valued elements automatically
join4 = Joiner.on(" - ").
useForNull("defaultValue").join(charList);
System.out.println(join4);
// output: a - b - c - d - defaultValue




If you have predefined String values no need to create an array or an iterable for joining them. Notice that you can join an arbitrary number of objects with the method below. The method works with var-args.

join4 = Joiner.on("|").
join("first", "second", "third", "fourth", "rest");
System.out.println(join4); 
//output: first|second|third|fourth|rest


Notice that if neither skipNulls() nor useForNull(String)is used, the joining methods will throw NullPointerException if any given element is null.

Joiner is for iterables and arrays. Joiner.MapJoiner inner class is the map counterpart of Joiner. You can join the map content directly using Joiner.MapJoiner class. First you have to build a Joiner and assign it a separator(1) using on(). Then you can call withKeyValueSeparator() which takes the separator(2) between key value pairs This map joiner can be used to join a map for obtaining a string or this can be appended to an Appendable. The form of the result is "key1 SEPARATOR(1) value1 SEPARATOR(2) key2 SEPARATOR(1) value2 SEPARATOR(2)..." without the empty spaces.

Map < String, Long > employeeToNumber = Maps.newHashMap(); 
// Create a Map using static
// method of Maps

employeeToNumber.put("obi wan", 1L);
employeeToNumber.put("bobba", 2L);

MapJoiner mapJoiner = 
Joiner.on("|").withKeyValueSeparator("->"); 
// | between each key-value pair 
//and -> between a key and its value
String join5 = mapJoiner.join(employeeToNumber);
System.out.println(join5);
//output is "obi wan->1|bobba->2".


Google Guava library contains a cool Splitter class that harness more power than the JDK's split functionality.

String text = "I have to test my string splitter,
for this purpose I'm writing this text,  ";

//I want to split the text
// above using ","
// I'll have three elements
// with the usual splitter:
// first sentence, then the 
//second sentence and the empty space at the end.

String[] split = text.split(","); // split with ","
System.out.println(Arrays.asList(split)); 
//output: [I have to test my string splitter,   
//for this purpose I'm writing this text,   ]


I'd want to remove the empty elements and then trim each element to remove the unnecessary empty spaces before and after them. I can do this in several steps with the old splitter. It's quite easy with Guava's Splitter.

// Again, the on parameter is the separator. 
//You can use a CharMatcher, 
//a Pattern or a String as a separator.
Iterable split2  = Splitter.on(",").omitEmptyStrings()
.trimResults().split(text);
System.out.println(Lists.newArrayList(split2));

// output: 
//[I have to test my string splitter,
// for this purpose I'm writing this text]

// I can split tokens of length 5 
//from the string in hand
Iterable split3 = Splitter.fixedLength(5).split(text);
System.out.println(Lists.newArrayList(split3)); 
// each token's length is 5
//output:
//[I hav, e to , test , my st, ring , split,
// ter, ,  for , this , purpo, se I', m wri,
// ting , this , text,,   ]


Notice that trimming is applied before checking for an empty result, regardless of the order in which the trimResults() and omitEmptyStrings() methods were invoked.

Strings class contains a number of utility methods.Most of them are checking String objects'. emptyToNull() and nullToEmpty() are quite similar. emptyToNull (nullToEmpty) returns the given string if it is non-empty (non-null) else it returns an empty (null) string.

String emptyToNull = Strings.emptyToNull("test");
System.out.println(emptyToNull); 
// returns "test" because it's not empty

emptyToNull = Strings.emptyToNull("");
System.out.println(emptyToNull); 
// returns null because the argument is empty


isNullOrEmpty() is quite practical. I don't remember how many times I had to write (string != null && !string.isEmpty())in my code.
String arg = "";
boolean nullOrEmpty = Strings.isNullOrEmpty(arg); 
// arg is empty
System.out.println("Null or Empty?: "+nullOrEmpty); 
// true because it's empty

arg =  null;
nullOrEmpty = Strings.isNullOrEmpty(arg); // arg is null
System.out.println("Null or Empty?: "+nullOrEmpty); 
// true because it's null

arg = "something";
nullOrEmpty = Strings.isNullOrEmpty(arg); 
// arg is not null or empty so the result is 'false'
System.out.println("Null or Empty?: "+nullOrEmpty);



I'll show you repeat() which returns a string consisting of the given number of concatenated copies of the input string.

String repeat = Strings.repeat("beetlejuice", 3); 
System.out.println(repeat); 
// output is "beetlejuicebeetlejuicebeetlejuice"


padEnd() and padStart() are quite similar. The first one adds the given char at the end of the given string as many times as the given integer value allows. The second one adds to the start.

String padEnd = Strings.padEnd("star wars", 15, 'X');
String padStart = Strings.padStart("star wars", 15, 'X');
System.out.println("padEnd: "+padEnd); 
// padEnd: star warsXXXXXX

System.out.println("padStart: "+padStart); 
// padStart: XXXXXXstar wars

System.out.println(padStart.length() == 15);
// true, because we give 15 as character limit


This is all for string-related classes of Guava.