nz.ac.waikato.jdsl.core.util
Class Converter

java.lang.Object
  nz.ac.waikato.jdsl.core.util.Converter

public class Converter
extends java.lang.Object

Provides for conversion of JDSL data structures to java.util Collections and Java base types and for conversion of java.util Collections to JDSL data structures.

The conversion format is method(from,to), where from is the instance you wish to convert and to is a new instance that you wish to contain the contents of the converted instance. If the to instance is non-empty, the old contents will be retained with the new contents added in, and the new elements added to the end (for linear data structures).

In methods that convert iterators to dictionaries or priority queues, we try to resolve the iterator's contents as Locators or KeyEntries (as appropriate). Failing this, we insert elements of the iterator with themselves as their keys.

JDSL data structures are all multi-maps, but the corresponding java.util data structures need not be. In the event a conversion is requested to a single-map java.util Collection, and the JDSL data structure has multiple copies of one key or element in violation of the java.util structure's requirements, an InvalidContainerException will be thrown.

If a conversion fails due to elements that are unacceptable to the to java.util instance for reasons other than these, its exception (ClassCastException, IllegalArgumentExeption) will be allowed to pass through.

In all descriptions of time complexity, N is the number of elements in the from data structure.

Constructor Summary

Converter()

Method Summary

static void	arrayToSequence(java.lang.Object[] from, Sequence to) Places the contents of an array into a sequence, preserving order.
static void	dictionaryToMap(InspectableDictionary from, java.util.Map to) Places the contents of a dictionary into a map.
static void	dictionaryToSortedMap(InspectableDictionary from, java.util.SortedMap to) Places the contents of a dictionary into a sorted map.
static void	iteratorToDictionary(java.util.Iterator from, Dictionary to) Places the contents of a java.util iterator into a dictionary.
static void	iteratorToList(ObjectIterator from, java.util.List to) Places the contents of a JDSL iterator into a List, preserving order.
static void	iteratorToMap(ObjectIterator from, java.util.Map to) Places the contents of a JDSL iterator into a Map.
static void	iteratorToPriorityQueue(java.util.Iterator from, PriorityQueue to) Places the contents of a java.util iterator into a PQ.
static void	iteratorToSequence(java.util.Iterator from, Sequence to) Places the contents of a java.util iterator into a sequence.
static void	iteratorToSet(ObjectIterator from, java.util.Set to) Places the contents of a JDSL iterator into a Set.
static void	listToSequence(java.util.List from, Sequence to) Places the contents of a list into a sequence, preserving order.
static void	mapToDictionary(java.util.Map from, Dictionary to) Places the contents of a map into a dictionary.
static void	sequenceToList(InspectableSequence from, java.util.List to) Places the contents of a sequence into a list, preserving order.
static void	sequenceToSet(InspectableSequence from, java.util.Set to) Places the contents of a sequence into a set.
static void	setToSequence(java.util.Set from, Sequence to) Places the contents of a set into a sequence.
static void	sortedmapToOrderedDictionary(java.util.SortedMap from, OrderedDictionary to) Places the contents of a sorted map into an ordered dictionary.
static void	treeToSet(InspectableTree from, java.util.Set to) Places the contents of a tree into a set.

Methods inherited from class java.lang.Object

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

Constructor Detail

Converter

public Converter()

Method Detail

sequenceToList

public static void sequenceToList(InspectableSequence from,
                                  java.util.List to)

Places the contents of a sequence into a list, preserving order. Running-time is O(N) for ref implementations of Sequence, including ArraySequence and NodeSequence, and for all current util implementations of List, including ArrayList (amortized O(N)), LinkedList, and Vector (amortized O(N)). Dependent upon after() in Sequence and add(Object) in List for unknown implementations. The method used here is different from the method used in other converters, because elements() does not necessarily preserve order.

Parameters:

from - The sequence to convert

to - The list to convert to

listToSequence

public static void listToSequence(java.util.List from,
                                  Sequence to)

Places the contents of a list into a sequence, preserving order. Running-time is O(N) for ref implementations of Sequence, including ArraySequence (amortized O(N)) and NodeSequence, and for all current util implementations of List, including ArrayList, LinkedList, and Vector. Dependent upon insertLast() in Sequence and toArray() in List for unknown implementations.

Parameters:

from - The list to convert

to - The sequence to convert to

arrayToSequence

public static void arrayToSequence(java.lang.Object[] from,
                                   Sequence to)

Places the contents of an array into a sequence, preserving order. Running-time is O(N) for ref implementations of Sequence, including ArraySequence (amortized O(N)) and NodeSequence. Dependent upon insertLast() in Sequence and toArray() in List for unknown implementations.

Parameters:

from - The array to convert

to - The sequence to convert to

treeToSet

public static void treeToSet(InspectableTree from,
                             java.util.Set to)
                      throws InvalidContainerException

Places the contents of a tree into a set. Running-time is O(N) for known implementations of Tree and Set, except for TreeSet, which is O(NlogN). Dependent upon elements() in Tree and add() in Set.

Parameters:

from - The tree to convert

to - The set to convert to

Throws:

InvalidContainerException - if the tree has two of the same element, a violation of Set's properties

sequenceToSet

public static void sequenceToSet(InspectableSequence from,
                                 java.util.Set to)
                          throws InvalidContainerException

Places the contents of a sequence into a set. Running-time is O(N) for known implementations of Sequence and Set. Dependent upon elements() in Sequence and add() in Set.

Parameters:

from - The sequence to convert

to - The set to convert to

Throws:

InvalidContainerException - if the sequence has two of the same element, a violation of Set's properties

setToSequence

public static void setToSequence(java.util.Set from,
                                 Sequence to)

Places the contents of a set into a sequence. Running-time is O(N) for ref implementations of Sequence, including ArraySequence (amortized O(N)) and NodeSequence, and for all current util implementations of Set. Dependent upon insertLast() in Sequence and iterator() in List for unknown implementations.

Parameters:

from - The set to convert

to - The sequence to convert to

mapToDictionary

public static void mapToDictionary(java.util.Map from,
                                   Dictionary to)
                            throws InvalidKeyException

Places the contents of a map into a dictionary. Running-time is O(N) expected for known implementations of Dictionary and Map, except O(NlogN) for TreeMap. Dependent upon insert() in Dictionary, and entrySet() in Map.

Parameters:

from - The map to convert

to - The dictionary to convert to

Throws:

InvalidKeyException - if the map has a key that the dictionary can't deal with properly

sortedmapToOrderedDictionary

public static void sortedmapToOrderedDictionary(java.util.SortedMap from,
                                                OrderedDictionary to)
                                         throws InvalidKeyException

Places the contents of a sorted map into an ordered dictionary. Running-time is O(NlogN) for known implementations of Dictionary and SortedMap. Dependent upon insert() in Dictionary, and entrySet() in Map.

Parameters:

from - The sorted map to convert

to - The ordered dictionary to convert to

Throws:

InvalidKeyException - if the map has a key that the dictionary can't deal with properly

dictionaryToMap

public static void dictionaryToMap(InspectableDictionary from,
                                   java.util.Map to)
                            throws InvalidContainerException

Places the contents of a dictionary into a map. Running-time is O(N) expected for known implementations of Dictionary and Map, except O(NlogN) for TreeMap. Dependent upon iterator used in implementation of Dictionary, and runtime of add() in Map.

Parameters:

from - The dictionary to convert

to - The map to convert to

Throws:

InvalidContainerException - if the tree has two of the same element, a violation of Map's properties

dictionaryToSortedMap

public static void dictionaryToSortedMap(InspectableDictionary from,
                                         java.util.SortedMap to)
                                  throws InvalidContainerException

Places the contents of a dictionary into a sorted map. Running-time is O(NlogN) for known implementations of Dictionary and Map. Dependent upon iterator used in implementation of Dictionary, and runtime of add() in Map.

Parameters:

from - The dictionary to convert

to - The map to convert to

Throws:

InvalidContainerException - if the tree has two of the same element, a violation of Map's properties

iteratorToSequence

public static void iteratorToSequence(java.util.Iterator from,
                                      Sequence to)

Places the contents of a java.util iterator into a sequence. Running-time is O(N) for ref implementations of Sequence, including ArraySequence (amortized O(N)) and NodeSequence. Dependent upon insertLast() in Sequence for unknown implementations. Also dependent on having an O(N) iterator.

Parameters:

from - The iterator to convert

to - The sequence to convert to

iteratorToDictionary

public static void iteratorToDictionary(java.util.Iterator from,
                                        Dictionary to)
                                 throws InvalidKeyException

Places the contents of a java.util iterator into a dictionary. Runs in O(N) expected time for HashtableDictionary, O(NlogN) for RedBlackTree. Is dependent upon insert() for other implementations, and is dependent on having an O(N) iterator. In converting iterators to dictionaries, we try to resolve the iterator's contents as Entries -- failing this, we insert elements of the iterator with themselves as their keys.

Parameters:

from - The iterator to convert

to - The dictionary to convert to

Throws:

InvalidKeyException - if the iterator has a non-locator or entry that the dictionary can't treat as a key, or if the iterator has a locator or entry which the dictionary can't deal with

iteratorToPriorityQueue

public static void iteratorToPriorityQueue(java.util.Iterator from,
                                           PriorityQueue to)
                                    throws InvalidKeyException

Places the contents of a java.util iterator into a PQ. Runs in O(NlogN) time for all known implementations of PriorityQueue. Is dependent upon insert() for other implementations, and is dependent on having an O(N) iterator. In converting iterators to PQs, we try to resolve the iterator's contents as Entries -- failing this, we insert elements of the iterator with themselves as their keys.

Parameters:

from - The iterator to convert

to - The PQ to convert to

Throws:

InvalidKeyException - if the iterator has a non-locator or entry that the PQ can't treat as a key, or if the iterator has a locator or entry which the PQ can't deal with

iteratorToList

public static void iteratorToList(ObjectIterator from,
                                  java.util.List to)

Places the contents of a JDSL iterator into a List, preserving order. Runs in O(N) time for all known implementations of List. Is dependent upon add() for other implementations, and is dependent on having an O(N) iterator.

Parameters:

from - The iterator to convert

to - The list to convert to

iteratorToSet

public static void iteratorToSet(ObjectIterator from,
                                 java.util.Set to)
                          throws InvalidContainerException

Places the contents of a JDSL iterator into a Set. Runs in O(N) expected time for HashSet, O(NlogN) for TreeSet. Is dependent upon add() for other implementations, and is dependent on having an O(N) iterator.

Parameters:

from - The iterator to convert

to - The set to convert to

Throws:

InvalidContainerException - if the tree has two of the same element, a violation of Set's properties

iteratorToMap

public static void iteratorToMap(ObjectIterator from,
                                 java.util.Map to)
                          throws java.lang.IllegalArgumentException,
                                 InvalidContainerException

Places the contents of a JDSL iterator into a Map. Runs in O(N) expected time for HashMap, O(NlogN) for TreeMap. Is dependent upon put() for other implementations, and is dependent on having an O(N) iterator. In converting iterators to maps, we try to resolve the iterator's contents as Locators or KeyEntries -- failing this, we insert elements of the iterator with themselves as their keys.

Parameters:

from - The iterator to convert

to - The map to convert to

Throws:

InvalidKeyException - if the iterator has a non-locator or entry that the map can't treat as a key, or if the iterator has a locator or entry which the map can't deal with

java.lang.IllegalArgumentException

InvalidContainerException