org.erights.e.elib.tables
Class FlexMap

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

All Implemented Interfaces:

EPrintable, Iteratable, Marker, PassByProxy, Persistent, Serializable

Direct Known Subclasses:

FlexBijection, FlexMapImpl, FlexTrijection, WeakKeyMap, WeakValueMap

public abstract class FlexMap

extends EMap

implements PassByProxy

Safe: A modifiable map.

Author:

Mark S. Miller

See Also:

Serialized Form

Field Summary

(package private) static long

serialVersionUID

Fields inherited from class org.erights.e.elib.tables.EMap

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

HONORARY, HONORED_NAMES

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

HONORARY, HONORED_NAMES

Constructor Summary

(package private)

FlexMap() Only subclasses within the package

Method Summary

Object[]	__optUncall() Enabled: A FlexMap is unconditionally transparent
void	__printOn(TextWriter out) Enabled: Prints using E language notation
Object	clone() Suppressed: Arguments defaults to keyType() and valueType().
ESet	domain() Enabled:
(package private) static FlexMap	fromColumns(ConstList keys, ConstList values) Helps with a literal pattern, an array of keys and a matching array of values, as gotten from getColumn().
static FlexMap	fromPairs(Object[][] pairs, boolean strict) Enabled: Helps with another convenient literal pattern, an array of key-element pairs.
static FlexMap	fromTypes(Class keyType, Class valType) Enabled:
static FlexMap	fromTypes(Class keyType, Class valType, int capacity) Enabled:
static FlexMap	interning(Class valType) Enabled: @see #interning(Class, int)
static FlexMap	interning(Class valType, int capacity) Enabled: The resulting table should optimize for the assumption that keys are typically interned, but should work regardless.
static FlexMap	make() Enabled:
static FlexMap	make(int capacity) Enabled:
void	put(Object key, Object value) Enabled: Like 'put' of three arguments, but defaults 'strict' to false.
abstract void	put(Object key, Object value, boolean strict) Enabled: Causes 'key' to map to 'value'.
void	putAll(EMap other) Enabled: Defaults 'strict' to false
void	putAll(EMap other, boolean strict) Enabled: Add all the associations of 'other' to this map.
EMap	readOnly() Enabled:
abstract void	removeAll() Enabled: Removes all associations from this map, leaving this map empty.
void	removeKey(Object key) Enabled: Defaults 'strict' to false
abstract void	removeKey(Object key, boolean strict) Enabled: Removes the given key (or its equivalent, according to the equal function) from the collection.
void	removeKeys(EMap mask) Enabled: defaults to not strict
void	removeKeys(EMap mask, boolean strict) Enabled: Remove from this map all associations whose key is in 'mask'.
ConstMap	snapshot() Enabled:

Methods inherited from class org.erights.e.elib.tables.EMap

and, butNot, contains, diverge, diverge, extract, get, get, getKeys, getKeys, getPair, getPair, getValues, getValues, intersects, iterate, keyType, maps, optExtract, or, or, printOn, size, sortKeys, sortKeys, sortValues, sortValues, toString, valueType, with, without

Methods inherited from class java.lang.Object

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

Field Detail

serialVersionUID

static final long serialVersionUID

Constructor Detail

FlexMap

FlexMap()

Only subclasses within the package

Method Detail

snapshot

public ConstMap snapshot()

Enabled:

Specified by:

snapshot in class EMap

readOnly

public EMap readOnly()

Enabled:

Specified by:

readOnly in class EMap

domain

public ESet domain()

Enabled:

Specified by:

domain in class EMap

put

public void put(Object key,
                Object value)

Enabled: Like 'put' of three arguments, but defaults 'strict' to false.

put

public abstract void put(Object key,
                         Object value,
                         boolean strict)

Enabled: Causes 'key' to map to 'value'. If 'strict' is false (the default), this will overwrite a previous value if necessary. If 'strict' is true, this only succeeds if there is not already an association for 'key' in the map. If 'strict' is true and there is an already an association, even to the same value, this throws an Exception instead (XXX currently an IllegalArgumentException) and leaves the map unmodified.

Unlike Dictionary, this doesn't return the old value. If you want it, use 'get' first.

If the key is overwritten, then the key order is unchanged. If the key is novel, it's added to the end of the order.

Throws:

NotSettledException - if the key is not settled

See Also:

org.erights.e.elib.ref.Ref#isSettled

putAll

public void putAll(EMap other)

Enabled: Defaults 'strict' to false

putAll

public void putAll(EMap other,
                   boolean strict)

Enabled: Add all the associations of 'other' to this map. If there's a conflict, blow up if we're strict. Otherwise overwrite.

The order of the original keys is unchanged. This order is followed by the novel keys in their order in 'other'.

removeKey

public void removeKey(Object key)

Enabled: Defaults 'strict' to false

removeKey

public abstract void removeKey(Object key,
                               boolean strict)

Enabled: Removes the given key (or its equivalent, according to the equal function) from the collection. If 'strict' is false (the default), this does nothing if 'key' is not currently a key in the collection. If 'strict' is true and 'key' isn't already there to be removed, this throws an Exception (XXX currently an IllegalArgumentException).

Unlike Dictionary, this does not return the old value. If you want this for a FlexMap, use 'get' first.

If 'key' wasn't in the table, the table (including its order) is unmodified. Otherwise, the last key in the table is moved in the ordering to take the place of the removed 'key'.

Parameters:

key - the key to remove

removeKeys

public void removeKeys(EMap mask)

Enabled: defaults to not strict

removeKeys

public void removeKeys(EMap mask,
                       boolean strict)

Enabled: Remove from this map all associations whose key is in 'mask'.

The order is the original order modified by successive removals of keys in mask's order.

removeAll

public abstract void removeAll()

Enabled: Removes all associations from this map, leaving this map empty.

Rather than doing a write-fault (which would make a private copy to be immediately dropped) this decrements the sharing count and re-initializes.

clone

public Object clone()

Suppressed: Arguments defaults to keyType() and valueType().

Overrides:

clone in class Object

Returns:

a clone of this instance.

See Also:

java.lang.Cloneable

__optUncall

public Object[] __optUncall()

Enabled: A FlexMap is unconditionally transparent

Returns:

__printOn

public void __printOn(TextWriter out)
               throws IOException

Enabled: Prints using E language notation

Specified by:

__printOn in interface EPrintable

IOException

make

public static FlexMap make()

Enabled:

make

public static FlexMap make(int capacity)

Enabled:

fromTypes

public static FlexMap fromTypes(Class keyType,
                                Class valType)

Enabled:

fromTypes

public static FlexMap fromTypes(Class keyType,
                                Class valType,
                                int capacity)

Enabled:

interning

public static FlexMap interning(Class valType)

Enabled: @see #interning(Class, int)

interning

public static FlexMap interning(Class valType,
                                int capacity)

Enabled: The resulting table should optimize for the assumption that keys are typically interned, but should work regardless.

A good strategy would be to use an IdentityKeyColumn internally, and first try looking up the presented key by identity. If this fails, intern the key and try again. Only interned keys would be stored. XXX We currently don't do any such optimization.

Were we to do this optimization, the interned keys may not ever be garbage collected. One would hope that Java's interning table were weak, but no where does it state this in the spec.

fromColumns

static FlexMap fromColumns(ConstList keys,
                           ConstList values)
                    throws ArityMismatchException

Helps with a literal pattern, an array of keys and a matching array of values, as gotten from getColumn(). The new map has the same order.

ArityMismatchException

fromPairs

public static FlexMap fromPairs(Object[][] pairs,
                                boolean strict)

Enabled: Helps with another convenient literal pattern, an array of key-element pairs. Each key-element pair is put into the map in order.