A code block, in Eclipse Collections terms, is a single-abstract-method object that is passed as a parameter to an iteration method. It is an abstraction that represents the evaluation of each element in the course of iteration. It helps us to further separate what is being done from how it is done. This topic enumerates the basic code block types—the Eclipse Collections interfaces and classes—and the relevant methods to which they apply.
What we call a "code block" in Eclipse Collections is roughly analogous to a lambda expression. The closest analog to a lambda in Java in versions prior to Java 8 is the anonymous inner class.
Here are two examples, one implementing Predicate using a Java 8+ lambda expression, and the other using an anonymous inner class.
MutableList<Person> texans =
this.people.select( each -> each.getAddress().getState().equals("TX"));
Verify.assertSize(1, texans);MutableList<Person> texans = this.people.select(
new Predicate<Person>()
{
public boolean accept(Person each)
{
return each.getAddress().getState().equals("TX");
}
});
Verify.assertSize(1, texans);In each case, if the value of state field for any element in people equals "TX" then the select method includes that element in the result list, texans.
This topic introduces the most commonly-used code blocks and the Eclipse Collections methods that use them. Along with the code block types described here, the current version of Eclipse Collections offers a full suite of primitive code blocks and corresponding code block factories, such as IntFunction, IntPredicate, and IntProcedure. These code blocks are used by methods on primitive collections.
|
Note
|
About parameter and argument These terms are often (if inaccurately) used interchangeably to refer to method or function inputs. (The usual distinction holds that parameter refers to a formal definition of the input, while argument denotes the actual values.) For the limited purposes of this guide—and in particular the scope of this topic—we use parameter to specify the input to an iteration method, such as select(). These parameters can take the form of a code block, (implementing Predicate) which itself is an object with methods. The input for a code block we’ll refer to here as the argument - in this example, the argument is each (the "current element" upon each iteration). |
A Predicate is a single-argument code block that evaluates an element and returns a boolean value. Also known as a discriminator or filter, it is used with the filtering methods select, reject, detect, anySatisfy, allSatisfy, and count.
| Description | Arguments | Returns | Used By | |
|---|---|---|---|---|
Predicate |
Evaluates each element of a collection |
One (T) |
boolean |
select, reject, detect, anySatisfy, allSatisfy, count |
Predicate2 |
Evaluates each element of a collection |
Two (T,P) |
boolean |
selectWith, rejectWith, detectWith, anySatisfyWith, allSatisfyWith, countWith |
The accept method is implemented to indicate the object passed to the method meets the criteria of this Predicate. Here is a Predicate implemented in a select method as an anonymous inner class:
MutableList<Integer> greaterThanFifty =
list.select(new Predicate<Integer>()
{
public boolean accept(Integer each)
{
return each > 50;
}
});The Predicates class can be used to build common filters. Predicates supports equals, not equals, less than, greater than, less than or equal to, greater than or equal to, in, not in, and, or, and numerous other predicate-type operations.
MutableList<Integer> myList =...
MutableList<Integer> selected1 = myList.select(Predicates.greaterThan(50));Supports equal, greaterThan, lessThan, in, notIn, and, or, instanceOf, null, notNull, anySatisfy, allSatisfy, etc. |
|
Works with methods suffixed with "With," such as selectWith. |
|
Supports empty, notEmpty, contains, isAlpha, isNumeric, isBlank, startsWith, endsWith, matches, etc. |
|
Supports isEven, isOdd, isPositive, isNegative, isZero. |
|
Supports isEven, isOdd, isPositive, isNegative, isZero. |
The Function code block in its most common usage takes each element of a collection as the argument to the code-block logic. It selects an attribute from the element via a "getter" — its valueOf method. It then returns a computed value or, if no evaluation logic is performed, the attribute itself.
Function code blocks are used as a parameter in a variety of common Eclipse Collections methods:
-
With the collect method to calculate a new value for each element of a given collection, and then return a transformed collection of the same type.
-
With the groupBy method to generate keys for each nested collection (values) of a new Multimap.
-
With the flatCollect method, where it must return an Iterable that gets "flattened" with other iterables, into a single collection.
-
With the Predicates factory’s attributeOperator methods - such as attributeLessThanOrEqualTo - to build Predicate (boolean) objects.
| Description | Arguments | Returns | Used By | |
|---|---|---|---|---|
Function |
Evaluates each element of a collection as the argument to the code block logic and returns a computed value |
One (T) |
Object (V) |
collect,flatCollect, groupBy |
Executes and returns a value (like Callable); represents deferred evaluation. |
Zero |
Object (V) |
getIfAbsent, getIfAbsentPut, ifPresentApply |
|
Used by injectInto methods; takes the accumulator argument as the first argument, and the current item of the collection as the second argument. |
Two (T,P) |
Object (V) |
forEachEntry injectInto collectWith |
|
Used by injectIntoWith; takes the injected argument as the first argument, the current item of the collection as the second argument, and the specified parameter for the third argument. The result of each subsequent iteration is passed in as the first argument. |
Three (T,P,?) |
Object (V) |
injectIntoWith |
Supports if and else using a discriminator with Function. |
|
This allows for multi-conditional or rule based selector using Predicates (use this with guidance). |
getToClass, getToString, getPassThru |
|
newFastList, newHashBag, newUnifiedMap, newUnifiedSet, nullValue, value |
|
fromFunction |
|
firstLetter, length, subString, toFirstChar, toInteger, toLowerCase, toPrimitive [type], toUpperCase, trim, firstLetter |
A Procedure is a code block that performs an evaluation on its single argument and returns nothing. A Procedure is most commonly used with ForEach -pattern methods.
Apply a Predicate to an object and increment a count if it returns true. |
|
Wrap a specified block and keeps track of the number of times it is executed. |
Chain together blocks of code to be executed in sequence; ChainedProcedure can chain Procedures, Functions or Function2s. |
|
Create an object form of a case statement, which instead of being based on a single switch value is based on a list of discriminator or block combinations. For the first discriminator that returns true for a given value in the case statement, the corresponding block will be executed. |
|
Evaluate the specified block only when a Predicate returns true. If the result of evaluating the Predicate is false, and the developer has specified that there is an elseProcedure, then the elseProcedure is evaluated. |
|
Same as IfProcedure, but with a second argument passed from the calling iteration method. |
|
Takes an int as a second argument; this is usually the index of the current element of a collection. |
Add elements to the specified collection when block methods are called. |
|
Remove element from the specified collection when block methods are called. |
|
Use a specified Function to calculate the key for an object and puts the object into the specified Map at the position of the calculated key. |
|
Use a specified Function to calculate the key for an object and puts the object with the key into the specified MutableMultimap. |
append, bind, caseDefault, fromObjectIntProcedure, ifElse, ifTrue, println, synchronizedEach |
|
addToCollection, fromProcedure |