craterdog.collections.abstractions.OrderedCollection Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of java-collection-framework Show documentation
Show all versions of java-collection-framework Show documentation
A set of interfaces and classes that define a Java collection framework.
/************************************************************************
* Copyright (c) Crater Dog Technologies(TM). All Rights Reserved. *
************************************************************************
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. *
* *
* This code is free software; you can redistribute it and/or modify it *
* under the terms of The MIT License (MIT), as published by the Open *
* Source Initiative. (See http://opensource.org/licenses/MIT) *
************************************************************************/
package craterdog.collections.abstractions;
import craterdog.core.Iterator;
import craterdog.collections.primitives.RandomizedTree;
import java.util.Arrays;
import java.util.Comparator;
import org.slf4j.ext.XLogger;
import org.slf4j.ext.XLoggerFactory;
/**
* This abstract class defines the invariant methods that all ordered collections must inherit.
* An ordered collection automatically orders its elements based on the comparison function
* implemented by a specified Comparator. If no comparator is specified, the
* elements extend the Comparable interface.
*
* @author Derk Norton
* @param The type of element managed by this collection.
*/
public abstract class OrderedCollection extends OpenCollection {
static private final XLogger logger = XLoggerFactory.getXLogger(OrderedCollection.class);
private final RandomizedTree tree;
/**
* This constructor creates a new empty collection with no comparator function.
*
* @param duplicatesAllowed Whether or not duplicate elements are allowed.
*/
protected OrderedCollection(boolean duplicatesAllowed) {
logger.entry(duplicatesAllowed);
tree = new RandomizedTree<>(duplicatesAllowed);
logger.exit();
}
/**
* This constructor creates a new collection with no comparator function and seeds
* it with the elements from the specified array.
*
* @param elements The elements to be used to seed the new collection.
* @param duplicatesAllowed Whether or not duplicate elements are allowed.
*/
protected OrderedCollection(E[] elements, boolean duplicatesAllowed) {
this(elements, duplicatesAllowed, null);
}
/**
* This constructor creates a new collection with no comparator function and seeds
* it with the elements from the specified collection.
*
* @param elements The elements to be used to seed the new collection.
* @param duplicatesAllowed Whether or not duplicate elements are allowed.
*/
protected OrderedCollection(Iterable elements, boolean duplicatesAllowed) {
this(elements, duplicatesAllowed, null);
}
/**
* This constructor creates a new collection with the specified comparator function.
*
* @param duplicatesAllowed Whether or not duplicate elements are allowed.
* @param comparator The comparator to be used to compare two elements during ordering.
*/
protected OrderedCollection(boolean duplicatesAllowed, Comparator comparator) {
logger.entry(duplicatesAllowed, comparator);
tree = new RandomizedTree<>(duplicatesAllowed, comparator);
logger.exit();
}
/**
* This constructor creates a new collection with the specified comparator function and seeds
* it with the elements from the specified array.
*
* @param elements The elements to be used to seed the new collection.
* @param duplicatesAllowed Whether or not duplicate elements are allowed.
* @param comparator The comparator to be used to compare two elements during ordering.
*/
protected OrderedCollection(E[] elements, boolean duplicatesAllowed, Comparator comparator) {
logger.entry(elements, duplicatesAllowed, comparator);
tree = new RandomizedTree<>(duplicatesAllowed, comparator);
tree.addAll(Arrays.asList(elements));
logger.exit();
}
/**
* This constructor creates a new collection with the specified comparator function and seeds
* it with the elements from the specified collection.
*
* @param elements The elements to be used to seed the new collection.
* @param duplicatesAllowed Whether or not duplicate elements are allowed.
* @param comparator The comparator to be used to compare two elements during ordering.
*/
protected OrderedCollection(Iterable elements, boolean duplicatesAllowed, Comparator comparator) {
logger.entry(elements, duplicatesAllowed, comparator);
tree = new RandomizedTree<>(duplicatesAllowed, comparator);
for (E element : elements) {
tree.add(element);
}
logger.exit();
}
@Override
public Iterator createIterator() {
logger.entry();
Iterator iterator = new OrderedIterator();
logger.exit(iterator);
return iterator;
}
@Override
public int getSize() {
logger.entry();
int result = tree.size();
logger.exit(result);
return result;
}
@Override
public E getElement(int index) {
logger.entry(index);
index = normalizedIndex(index);
E element = tree.get(index - 1); // convert to zero based indexing
logger.exit(element);
return element;
}
@Override
public int getIndex(E element) {
logger.entry(element);
int index = tree.indexOf(element) + 1; // convert to ordinal based indexing
logger.exit(index);
return index;
}
@Override
public OrderedCollection getElements(int firstIndex, int lastIndex) {
logger.entry(firstIndex, lastIndex);
firstIndex = normalizedIndex(firstIndex);
lastIndex = normalizedIndex(lastIndex);
OrderedCollection result = copy();
result.removeAll();
Iterator iterator = createIterator();
iterator.toIndex(firstIndex);
int numberOfElements = lastIndex - firstIndex + 1;
while (numberOfElements-- > 0) {
E element = iterator.getNext();
logger.debug("Including element: {}", element);
result.addElement(element);
}
logger.exit(result);
return result;
}
@Override
public boolean addElement(E element) {
logger.entry(element);
boolean result = tree.add(element);
logger.exit(result);
return result;
}
@Override
public boolean removeElement(E element) {
logger.entry(element);
boolean result = tree.remove(element);
logger.exit(result);
return result;
}
@Override
public void removeAll() {
logger.entry();
tree.clear();
logger.exit();
}
/**
* This method returns the comparator that is used to order the elements in this collection.
*
* @return The comparator that is used to order the elements in this collection.
*/
public Comparator getComparator() {
logger.entry();
Comparator comparator = tree.comparator();
logger.exit(comparator);
return comparator;
}
/*
* This iterator class implements the Iterator abstraction It utilizes the
* underlying tree iterators from the underlying tree implementation. Like most iterators,
* it should be used to access a collection exclusively without any other requests, especially
* requests that change the length of the collection, being made directly on the same collection.
*/
private class OrderedIterator extends Iterator {
private java.util.ListIterator iterator = tree.listIterator();
@Override
public void toStart() {
iterator = tree.iterator();
}
@Override
public void toIndex(int index) {
index = normalizedIndex(index);
iterator = tree.listIterator(index - 1);
}
@Override
public void toEnd() {
iterator = tree.listIterator(tree.size());
}
@Override
public boolean hasPrevious() {
return iterator.nextIndex() > 0;
}
@Override
public boolean hasNext() {
return iterator.nextIndex() < tree.size();
}
@Override
public E getNext() {
if (!hasNext()) throw new IllegalStateException("The iterator is at the end of the ordered collection.");
return iterator.next();
}
@Override
public E getPrevious() {
if (!hasPrevious()) throw new IllegalStateException("The iterator is at the beginning of the ordered collection.");
return iterator.previous();
}
}
}