RegisterSign In

API Documentation: Class OrderedSetString

Package: com.mckoi.data
extends java.util.AbstractSet<java.lang.String>
implements java.util.SortedSet<java.lang.String>

An ordered set of variable length string values mapped over a DataFile object. Set modifications are immediately reflected in the underlying data file. This object grows and shrinks the size of the underlying data file as values are inserted and removed from the set.

For value look up, this class implements a binary search algorithm over the address space of all characters of all strings stored in the file. The string items are encoded in the DataFile such that each string item is followed by an 0x0FFFF character. While this structure is able to store strings of any length, it should be noted that the search algorithm will read and store an entire string in memory for each item it visits during the search. It is therefore recommended that excessively large strings should not be stored in this structure if good search performance is wanted.

OrderedSetString stores 64 bits of meta information (a static magic value) at the start of the DataFile on any set that contains a none zero quantity of strings. This meta information is intended to help identify DataFile structures that are formatted by this object.

This object implements java.lang.SortedSet<String>.

PERFORMANCE: While the string search and iteration functions are efficient, the size() query requires a full scan of all the strings in the set to compute.

Constructors Summary

OrderedSetString(DataFile data, Comparator<String> collator)
OrderedSetString(DataFile data)

Methods Summary

int size()
boolean isEmpty()
Iterator<String> iterator()
boolean contains(Object str)
boolean add(String value)
boolean remove(Object value)
void clear()
Comparator<String> comparator()
SortedSet<String> subSet(String from_element, String to_element)
SortedSet<String> headSet(String to_element)
SortedSet<String> tailSet(String from_element)
String first()
String last()

Constructor Details

OrderedSetString(DataFile data, Comparator<String> collator)

Creates this structure mapped over the given DataFile object. 'collator' describes the collation of strings in the set, or null if the order of strings should be lexicographical.

Note that the collator object behavior must be consistent over all use of instances of this object on a DataFile object. An OrderedSetString that has managed a backed DataFile under one collation will not work correctly if the collation is changed. If such a situation happens, the class function behavior is undefined.

OrderedSetString(DataFile data)

Creates this structure mapped over the given DataFile object. The order of strings in this string set is lexicographical.

Method Details

int size()

Returns the total number of elements in the set or Integer.MAX_VALUE if the set contains more values than Integer.MAX_VALUE.

PERFORMANCE: This operation will scan the entire set to determine the number of elements, therefore this operation does not scale with large sets.

boolean isEmpty()

Returns true if the set is empty.

Iterator<String> iterator()

Returns an Iterator over all the strings stored in this set in collation order.

boolean contains(Object str)

Returns true if the set contains the given string. Assumes the set is ordered by the collator.

boolean add(String value)

Adds a string to the set in sorted order as defined by the collator defined when the object is created. Returns true if the set does not contain the string and the string was added, false if the set already contains the value.

boolean remove(Object value)

Removes the value from the set if it is present. Assumes the set is ordered by the collator.

void clear()

Clears the set of all string items.

Comparator<String> comparator()

The comparator for this set.

SortedSet<String> subSet(String from_element, String to_element)

Returns the sorted subset of string items from this set between the string 'from_element' (inclusive) and 'to_element' (exclusive), as ordered by the collation definition. The behavior of this method follows the contract as defined by java.util.AbstractSet.

SortedSet<String> headSet(String to_element)

Returns the sorted subset of string items from this set between the start and 'to_element' (exclusive) from this set, as ordered by the collation definition. The behavior of this method follows the contract as defined by java.util.AbstractSet.

SortedSet<String> tailSet(String from_element)

Returns the sorted subset of string items from this set between the string 'from_element' (inclusive) and the end of the set, as ordered by the collation definition. The behavior of this method follows the contract as defined by java.util.AbstractSet.

String first()

Returns the first (lowest) string item currently in this set.

String last()

Returns the last (highest) string item currently in this set.

The text on this page is licensed under the Creative Commons Attribution 3.0 License. Java is a registered trademark of Oracle and/or its affiliates.
Mckoi is Copyright © 2000 - 2020 Diehl and Associates, Inc. All rights reserved.