org.erights.e.elib.tables
Class EList

java.lang.Object
  |
  +--org.erights.e.elib.tables.EList

All Implemented Interfaces:

EPrintable, Iteratable, Marker, Persistent, Serializable

Direct Known Subclasses:

ConstList, FlexList, ROList

public abstract class EList

extends Object

implements EPrintable, Persistent, Iteratable

Safe: A EList is a sequence of values.

'EList' is a query-only interface that's agnostic about whether the data can change and whether a EList can be cast to an object by which to change it. 'EList' is also agnostic about the basis for equality between tables. Subtypes do pin these issues down:

ConstList guarantees immutability, uses value-based equality, and can be transparently passed-by-copy over the network.

FlexList extends EList with mutation operations.

Author:

Mark S. Miller

See Also:

org.erights.e.elib.tables.ConstList, org.erights.e.elib.tables.FlexList, Serialized Form

Field Summary

private static long

serialVersionUID

Fields inherited from interface org.erights.e.elib.serial.Persistent

HONORARY, HONORED_NAMES

Constructor Summary

(package private)

EList() Only subclasses within the package

Method Summary

ConstList	add(Object other) Enabled: Concatenates (snapshots of) this list and other.
ConstMap	asKeys() Enabled: Turns [a, b, ...] into [a => null, b => null, ...]
ConstMap	asMap() Enabled: Turns [a, b, ...] into [0 => a, 1 => b, ...]
ConstSet	asSet() Enabled: Returns a set whose elements are the values in this list
boolean	contains(Object candidate) Enabled: Does the candidate appear as a value in this list?
FlexList	diverge() Enabled: 'valueType' defaults to Object.class
FlexList	diverge(Class valueType) Enabled: Returns a FlexList whose initial state is a snapshot of the state of this list at the time of the diverge() request.
abstract Object	get(int index) Enabled: What value does 'index' map to?
Object	getArray() Enabled: type defaults to valueType() and start,bound defaults to everything (0,size()).
Object	getArray(Class type) Enabled: start,bound defaults to everything (0,size()).
Object	getArray(Class type, int start, int bound) Enabled: Returns a divergent array of type.
boolean	includes(EList candidate) Enabled: Does this list include candidate as a sub-list?
int	indexOf1(Object candidate) Enabled: The first index at which 'candidate' appears in this list, or -1 if none.
int	indexOf1(Object candidate, int start) Enabled: The first index >= 'start' at which 'candidate' appears in this list, or -1 if none.
void	iterate(AssocFunc func) Enabled: Call 'func' with each index-value pair in the table in order.
Object	last() Enabled: 'a.last()' is equivalent to 'a[a.size()-1]'.
int	lastIndexOf1(Object candidate) Enabled: The last index at which 'candidate' appears in this list, or -1 if none.
int	lastIndexOf1(Object candidate, int start) Enabled: The last index <= 'start' at which 'candidate' appears in this list, or -1 if none.
int	lastStartOf(EList candidate) Enabled: The last index at which 'candidate' begins as a sub-list of this list, or -1 if none.
int	lastStartOf(EList candidate, int start) Enabled: The last index <= start at which 'candidate' appears as a sub-list of this list, or -1 if none.
ConstList	multiply(int n) Enabled: Return the result of concatenating n snapshots of this list
void	printOn(String left, String sep, String right, TextWriter out) Enabled: Prints 'left', the values separated by 'sep', and 'right'.
abstract EList	readOnly() Enabled: Returns a read-only facet on this list.
ConstList	run(int start, int bound) Enabled: Returns a snapshot of the sublist from 'start' (inclusive) to 'bound' (exclusive).
ConstList	run(Object intReg) Enabled: Returns a snapshot of the run at intReg.
abstract int	size() Enabled: How many entries are in the list?
abstract ConstList	snapshot() Enabled: Returns a ConstList whose state is a snapshot of the state of this list at the time of the snapshot() request.
ConstList	sort() Enabled: A snapshot of the list sorted into ascending order
ConstList	sort(CompFunc func) Enabled: A snapshot of the list sorted into ascending order according to func
int	startOf(EList candidate) Enabled: The first index at which 'candidate' begins as a sub-list of this list, or -1 if none.
int	startOf(EList candidate, int start) Enabled: The first index >= start at which 'candidate' begins as a sub-list of this list, or -1 if none.
String	toString() Suppressed:
abstract Class	valueType() Enabled: All values in this table must be of this type
ConstList	with(int index, Object value) Enabled: Return a ConstList just like this list except that the element at index is value.
ConstList	with(Object value) Enabled: A ConstList equivalent to 'this snapshot() + [value]'

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.erights.e.elib.oldeio.EPrintable

__printOn

Field Detail

serialVersionUID

private static final long serialVersionUID

Constructor Detail

EList

EList()

Only subclasses within the package

Method Detail

snapshot

public abstract ConstList snapshot()

Enabled: Returns a ConstList whose state is a snapshot of the state of this list at the time of the snapshot() request. A ConstList returns itself.

readOnly

public abstract EList readOnly()

Enabled: Returns a read-only facet on this list. Someone holding this facet may see changes, but they cannot cause them.

diverge

public FlexList diverge(Class valueType)

Enabled: Returns a FlexList whose initial state is a snapshot of the state of this list at the time of the diverge() request.

Further changes to the original and/or the new list are independent -- they diverge.

The new list is constrained to only hold values of 'valueType'. XXX valueType should be of type ValueGuard rather than Class.

diverge

public FlexList diverge()

Enabled: 'valueType' defaults to Object.class

sort

public ConstList sort()

Enabled: A snapshot of the list sorted into ascending order

sort

public ConstList sort(CompFunc func)

Enabled: A snapshot of the list sorted into ascending order according to func

getArray

public Object getArray(Class type,
                       int start,
                       int bound)

Enabled: Returns a divergent array of type.

XXX Should 'type' be of type ValueGuard rather than Class?

getArray

public Object getArray(Class type)

Enabled: start,bound defaults to everything (0,size()).

getArray

public Object getArray()

Enabled: type defaults to valueType() and start,bound defaults to everything (0,size()).

get

public abstract Object get(int index)
                    throws IndexOutOfBoundsException

Enabled: What value does 'index' map to?

Returns:

nullOk; the value at index may be null.

Throws:

IndexOutOfBoundsException - if index isn't in 0..!size.

last

public Object last()
            throws IndexOutOfBoundsException

Enabled: 'a.last()' is equivalent to 'a[a.size()-1]'.

Throws:

IndexOutOfBoundsException - if this list is empty.

contains

public boolean contains(Object candidate)

Enabled: Does the candidate appear as a value in this list?

size

public abstract int size()

Enabled: How many entries are in the list?

iterate

public void iterate(AssocFunc func)

Enabled: Call 'func' with each index-value pair in the table in order.

Specified by:

iterate in interface Iteratable

valueType

public abstract Class valueType()

Enabled: All values in this table must be of this type

XXX Should this return a ValueGuard rather than a Class?

add

public ConstList add(Object other)

Enabled: Concatenates (snapshots of) this list and other.

XXX If they have a common class, we should use it.

The default implementation here insists that other coerces to an EList, but this is overridden in the Twine subclass.

with

public ConstList with(Object value)

Enabled: A ConstList equivalent to 'this snapshot() + [value]'

with

public ConstList with(int index,
                      Object value)

Enabled: Return a ConstList just like this list except that the element at index is value.

To do the side-effect-free operation corresponding to the conventional

     foo[index] := value
 

do

     foo with= (index, value)
 

Unlike the conventional assignment, this doesn't change the list, but rather assigns to the foo variable a new list derived from the original list by the with/2 operation. This expands to

     foo := foo.with(index, value)
 

multiply

public ConstList multiply(int n)

Enabled: Return the result of concatenating n snapshots of this list

asMap

public ConstMap asMap()

Enabled: Turns [a, b, ...] into [0 => a, 1 => b, ...]

asKeys

public ConstMap asKeys()

Enabled: Turns [a, b, ...] into [a => null, b => null, ...]

asSet

public ConstSet asSet()

Enabled: Returns a set whose elements are the values in this list

includes

public boolean includes(EList candidate)

Enabled: Does this list include candidate as a sub-list?

run

public ConstList run(Object intReg)

Enabled: Returns a snapshot of the run at intReg.

run

public ConstList run(int start,
                     int bound)

Enabled: Returns a snapshot of the sublist from 'start' (inclusive) to 'bound' (exclusive).

indexOf1

public int indexOf1(Object candidate)

Enabled: The first index at which 'candidate' appears in this list, or -1 if none.

indexOf1

public int indexOf1(Object candidate,
                    int start)

Enabled: The first index >= 'start' at which 'candidate' appears in this list, or -1 if none.

lastIndexOf1

public int lastIndexOf1(Object candidate)

Enabled: The last index at which 'candidate' appears in this list, or -1 if none.

Note that choosing '-1' leads to a programming pun that's too tempting to avoid (though it should be documented). If you want the index of, for example, the beginning of the last dot-separated substring of a string, you can say "lastIndexOf1('.')+1". If there is no dot, this returns 0, which is the correct answer for this case.

lastIndexOf1

public int lastIndexOf1(Object candidate,
                        int start)

Enabled: The last index <= 'start' at which 'candidate' appears in this list, or -1 if none.

startOf

public int startOf(EList candidate)

Enabled: The first index at which 'candidate' begins as a sub-list of this list, or -1 if none.

startOf

public int startOf(EList candidate,
                   int start)

Enabled: The first index >= start at which 'candidate' begins as a sub-list of this list, or -1 if none.

lastStartOf

public int lastStartOf(EList candidate)

Enabled: The last index at which 'candidate' begins as a sub-list of this list, or -1 if none.

lastStartOf

public int lastStartOf(EList candidate,
                       int start)

Enabled: The last index <= start at which 'candidate' appears as a sub-list of this list, or -1 if none.

printOn

public void printOn(String left,
                    String sep,
                    String right,
                    TextWriter out)
             throws IOException

Enabled: Prints 'left', the values separated by 'sep', and 'right'.

'left' value0 'sep' ... 'right'

IOException

toString

public String toString()

Suppressed:

Overrides:

toString in class Object

Returns:

a string representation of the object.