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.



comments?