com.blackperl.Perl
Class Map

java.lang.Object
  |
  +--com.blackperl.Perl.Map

public class Map

extends java.lang.Object

Static-method implementation of the Perl map keyword. The map function iterates over a list of values, applying a function to each one in turn. It is similar in this aspect to grep (see Grep), except that map is more about the evaluation of the provided function, and less about selecting a sub-set of the input list.

map takes a block to execute-- one of MapBlock or GrepBlock-- and gathers together the values that the eval() method of the block returns. Thus, unlike grep, map may produce more elements than it is fed as input. In Perl, this is often used for such tasks as generating associative arrays (the analog of java.util.HashTable) or applying list-oriented processing to a set of input values as part of a larger pipeline (with the output often going to another map, or possibly a grep).

Unfortunately, things like creating hash tables on the fly are not as easy in Java, as there is no clear way in the foundation classes to promote a List instance into a Map, which is the base interface needed to instantiate classes such as java.util.HashTable or java.util.Hashmap from existing data. Instead, the developer would use the functionality of the MapBlock or GrepBlock in the form of a named (usually private) inner-class with accessors to build up a Map from the input objects, then retrieve that data through the accessors after map has completed. One of the examples below illustrates this concept.

This first example shows very basic usage of map, applying the split method of the String class to the passed-in elements and producing an arbitrary number of String objects as a result:

     import com.blackperl.Perl.Map;
     import com.blackperl.Perl.MapBlock;
 
     // Assume "lines" is of type String[]
     Object[] all = Map.map(new MapBlock() {
         public Object[] eval(Object o) {
             return ((String)o).split(",");
         } }, lines);
     // "all" is now an array of strings all split up by commas
 

This example used arrays rather than List instances, and it suffers from the same limitations seen in Grep. That is, the returned array is always of type Object[], and thus the elements have to be explicitly cast when they are later referenced.

A common use of map in Perl is to turn an array of strings into a testable associative array, so that further input values can be tested against the list without having to explicitly traverse the list for every test. This next example shows how this can be done:

     import com.blackperl.Perl.Map;
     import com.blackperl.Perl.MapBlock;
     import java.util.HashMap;
     import java.util.List;
 
     class MapMaker implements MapBlock
     {
         private java.util.Map internalMap;
 
         public MapMaker(java.util.Map map) { internalMap = map; }
 
         Object[] eval(Object o)
         {
             internalMap.put((String)o, Boolean.valueOf(true));
             return null;
         }
     }
 
     // An instance field, which wouldn't otherwise be accessible to a
     // MapBlock instance
     HashMap booleanWordMap = new HashMap();
 
     // Assume "words" is set up elsewhere as some implementation of List
     Map.map(new MapMaker(booleanWordMap), words);
     // The booleanWordMap hash table now has each string that was
     // contained within the List called words as a key. The value for
     // each of these keys is the Boolean object equivalent of "true".
 

One could have the MapMaker code count the words, rather than just map them to true, depending on the needs of the program itself.

In cases where it is known that the mapping function is only going to produce at most one output element per input element, the GrepBlock interface may be used in place of MapBlock. This makes it a little easier to write the eval hook cleanly, without the need to create and return an array when only one value is being passed. The next example shows this (while also using the Ucfirst component):

     import com.blackperl.Perl.Map;
     import com.blackperl.Perl.GrepBlock;
     import com.blackperl.Perl.Ucfirst;
     import java.util.List;
 
     // Assume again that "words" is some List object set up elsewhere
     List capitalizedWords = Map.map(new GrepBlock() {
         Object eval(Object word) {
             return Ucfirst.ucfirst(((String)word).toLowerCase());
         } }, words);
 

When this has run, the List object capitalizedWords contains all the strings from words in the same order. Each of these new strings has been capitalized by first shifting the whole string to lower-case with the toLowerCase method, then passing that result to Ucfirst.ucfirst(java.lang.String). In other words, this code recreates a common Perl idiom:

     @capitalized_words = map { ucfirst lc $_ } @words;
 

All components in this package provide an instance method to retrieve a singleton object which may be used to call the static methods, if the programmer prefers using an object to static invocation.

If this is the JDK 1.5 ("Tiger") edition of the package, this class is suitable for use via static import. The invocation from the second example could instead be expressed as (with the changed import line included):

     import com.blackperl.Perl.Map.map;
 
     map(new MapMaker(booleanWordMap), words);
 

Method Summary

static com.blackperl.Perl.Map	instance() The instance method is used to retrieve the Map singleton that applications can use in lieu of invoking the methods statically.
static java.util.List	map(com.blackperl.Perl.GrepBlock block, java.util.List list) Map the functionality specified by eval() in the GrepBlock instance over the objects contained in the List, returning all the values produced as a result.
static java.lang.Object[]	map(com.blackperl.Perl.GrepBlock block, java.lang.Object[] objArray) Perform map using a GrepBlock interface and an array of objects (rather than a List instance).
static java.util.List	map(com.blackperl.Perl.MapBlock block, java.util.List list) Map the functionality specified by eval() in the MapBlock instance over the objects contained in the List, returning all the values produced as a result.
static java.lang.Object[]	map(com.blackperl.Perl.MapBlock block, java.lang.Object[] objArray) Perform map using a MapBlock interface and an array of objects (rather than a List instance).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

instance

public static com.blackperl.Perl.Map instance()

The instance method is used to retrieve the Map singleton that applications can use in lieu of invoking the methods statically.

Returns:

Singleton instance of the Map class

map

public static java.util.List map(com.blackperl.Perl.GrepBlock block,
                                 java.util.List list)

Map the functionality specified by eval() in the GrepBlock instance over the objects contained in the List, returning all the values produced as a result.

Parameters:

block - The GrepBlock instance that provides eval()

list - The List instance with objects to evaluate in sequence

Returns:

A List instance containing the values returned in the evaluation of the values in list

map

public static java.lang.Object[] map(com.blackperl.Perl.GrepBlock block,
                                     java.lang.Object[] objArray)

Perform map using a GrepBlock interface and an array of objects (rather than a List instance).

Parameters:

block - The GrepBlock instance that provides eval()

objArray - The array of Object to evaluate in sequence

Returns:

An array (possibly empty) of the objects produced by eval()

map

public static java.util.List map(com.blackperl.Perl.MapBlock block,
                                 java.util.List list)

Map the functionality specified by eval() in the MapBlock instance over the objects contained in the List, returning all the values produced as a result.

Parameters:

block - The MapBlock instance providing the eval() method

list - A List instance providing the objects to be evaluated

Returns:

A List instance containing the values returned in the evaluation of the values in list

map

public static java.lang.Object[] map(com.blackperl.Perl.MapBlock block,
                                     java.lang.Object[] objArray)

Perform map using a MapBlock interface and an array of objects (rather than a List instance).

Parameters:

block - The MapBlock instance providing the eval() method

objArray - The array of Object to evaluate in sequence

Returns:

An array (possibly empty) of the objects produced by eval()