org.w3c.cci2.SparseArray Maven / Gradle / Ivy
/*
* ====================================================================
* Project: openMDX, http://www.openmdx.org/
* Description: SparseArray
* Owner: OMEX AG, Switzerland, http://www.omex.ch
* ====================================================================
*
* This software is published under the BSD license as listed below.
*
* Copyright (c) 2006-2008, OMEX AG, Switzerland
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or
* without modification, are permitted provided that the following
* conditions are met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* * Neither the name of the openMDX team nor the names of its
* contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
* CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
* INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
* BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
* TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
* ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*
* ------------------
*
* This product includes software developed by other organizations as
* listed in the NOTICE file.
*/
package org.w3c.cci2;
import java.util.List;
import java.util.ListIterator;
import java.util.SortedMap;
/**
* SparseArray
*
* Setting a value to null is equivalent to removing the entry.
*/
public interface SparseArray extends SortedMap, Iterable {
/**
* A list backed up by the sparse array:
* - its size() is the sparse array's
lastKey() + 1
* - the sparse array's un-populated positions are represented as
null values
* get(int) and set(int,E) operations are allowed for any index >= 0
* add(E) is allowed
*
*
* @return a List representing this SparseArray
*/
List asList();
/**
* This iterator skips all null values.
*
* @return an iterator for the non-null elements
*/
ListIterator populationIterator();
/**
* Returns a view of the portion of this sparse array whose keys range from
* fromKey, inclusive, to toKey, exclusive. (If
* fromKey and toKey are equal, the returned sparse array
* is empty.) The returned sparse array is backed by this sparse array, so
* changes in the returned sparse array are reflected in this sparse array,
* and vice-versa. The returned Map supports all optional map operations
* that this sparse array supports.
*
* The map returned by this method will throw an
* IllegalArgumentException if the user attempts to insert a key
* outside the specified range.
*
* Note: this method always returns a half-open range (which
* includes its low endpoint but not its high endpoint). If you need a
* closed range (which includes both endpoints), and the key type
* allows for calculation of the successor a given key, merely request the
* subrange from lowEndpoint to successor(highEndpoint).
* Sparse arrays are map whose keys are integers.
* The following idiom obtains a view containing all of the key-value
* mappings in m whose keys are between low and
* high, inclusive:
*
*
Map sub = m.subMap(low, high + 1);
*
* A similarly technique can be used to generate an open range
* (which contains neither endpoint). The following idiom obtains a
* view containing all of the key-value mappings in m whose keys
* are between low and high, exclusive:
*
* Map sub = m.subMap(low + 1, high);
*
* @param fromKey low endpoint (inclusive) of the subMap.
* @param toKey high endpoint (exclusive) of the subMap.
*
* @return a view of the specified range within this sparse array.
*
* @throws IllegalArgumentException if fromKey is greater than
* toKey; or if this map is itself a subMap, headMap,
* or tailMap, and fromKey or toKey are not
* within the specified range of the subMap, headMap, or tailMap.
* @throws NullPointerException if fromKey or toKey is
* null.
*/
SparseArray subMap(Integer fromKey, Integer toKey);
/**
* Returns a view of the portion of this sparse array whose keys are
* strictly less than toKey. The returned sparse array is backed by this
* sparse array, so changes in the returned sparse array are reflected in this
* sparse array, and vice-versa. The returned map supports all optional map
* operations that this sparse array supports.
*
* The map returned by this method will throw an IllegalArgumentException
* if the user attempts to insert a key outside the specified range.
*
* Note: this method always returns a view that does not contain its
* (high) endpoint. If you need a view that does contain this endpoint,
* and the key type allows for calculation of the successor a given
* key, merely request a headMap bounded by successor(highEndpoint).
* Sparse arrays are map whose keys are integers.
* The following idiom obtains a view containing all of the
* key-value mappings in m whose keys are less than or equal to
* high:
*
*
Map head = m.headMap(high + 1);
*
* @param toKey high endpoint (exclusive) of the subMap.
*
* @return a view of the specified initial range of this sparse array.
*
* @throws IllegalArgumentException if this map is itself a subMap,
* headMap, or tailMap, and toKey is not within the
* specified range of the subMap, headMap, or tailMap.
* @throws NullPointerException if toKey is null.
*/
SparseArray headMap(Integer toKey);
/**
* Returns a view of the portion of this sparse array whose keys are greater
* than or equal to fromKey. The returned sparse array is backed
* by this sparse array, so changes in the returned sparse array are reflected
* in this sparse array, and vice-versa. The returned map supports all
* optional map operations that this sparse array supports.
*
* The map returned by this method will throw an
* IllegalArgumentException if the user attempts to insert a key
* outside the specified range.
*
* Note: this method always returns a view that contains its (low)
* endpoint. If you need a view that does not contain this endpoint, and
* the element type allows for calculation of the successor a given value,
* merely request a tailMap bounded by successor(lowEndpoint).
* Sparse arrays are map whose keys are integers.
* The following idiom obtains a view containing all of the
* key-value mappings in m whose keys are strictly greater than
* low:
*
*
Map tail = m.tailMap(low + 1);
*
* @param fromKey low endpoint (inclusive) of the tailMap.
*
* @return a view of the specified final range of this sparse array.
*
* @throws IllegalArgumentException if this map is itself a subMap,
* headMap, or tailMap, and fromKey is not within the
* specified range of the subMap, headMap, or tailMap.
* @throws NullPointerException if fromKey is null.
*/
SparseArray tailMap(Integer fromKey);
}