Package net.sf.saxon.ma.map

Class AbstractFixedMap

java.lang.Object

net.sf.saxon.ma.MapOrArray

net.sf.saxon.ma.map.MapItem

net.sf.saxon.ma.map.MapWithTypeCache

net.sf.saxon.ma.map.AbstractFixedMap

All Implemented Interfaces:

Iterable<KeyValuePair>, Callable, FunctionItem, GroundedValue, Item, Sequence

Direct Known Subclasses:

FixedMap, FixedMapWithStringKeys

public abstract class AbstractFixedMap
extends MapWithTypeCache
implements Iterable<KeyValuePair>

A general-purpose XDM map implementation that is ordered, that holds any kind of key, and that supports incremental modification only by copying the whole map to a different structure. Any duplicates added during map construction follow "use-last" semantics - the new value replaces the old. This structure is therefore unsuited to cases where duplicates need custom handling.

The implementation is based on an array of keys, an array of corresponding values, and a mutable Java java.util.HashMap (but encapsulated so no mutation can take place after the map has been built) that maps atomic match keys to integer positions in the array. If put or remove operations are subsequently attempted, the map is copied to a different implementation structure that supports functional modification.

The underlying implementation uses an instance of HashMap<AtomicMatchKey, KeyValuePair> For many data types this means that the key is held twice, once as the key, and once as part of the value. The reason for this is that the keys() function needs to return the original keys as supplied, complete with type annotation, which would not (always) have the same equality semantics. The AtomicMatchKey is computed from the actual key and in some cases is simply a wrapper with a different equals() method.

Nested Class Summary

Nested classes/interfaces inherited from class net.sf.saxon.ma.map.MapItem

MapItem.KeyIterator

Field Summary

Fields

Modifier and Type	Field	Description
protected HashMap<AtomicMatchKey,Integer>	index
protected GroundedValue[]	values

Fields inherited from class net.sf.saxon.ma.map.MapWithTypeCache

knownKeyType, knownValueType

Fields inherited from class net.sf.saxon.ma.map.MapItem

mapConstructorDuplicatesAction, xslMapDuplicatesAction, xslRecordDuplicatesAction

Constructor Summary

Constructors

Constructor	Description
AbstractFixedMap()

Method Summary

Modifier and Type	Method	Description
protected void	ensureIndexed()	Ensure that an index exists, creating it if necessary.
GroundedValue	get(AtomicValue key)	Get an entry from the Map
static GeneralMapBuilder	getBuilder(int specVersion)	Factory method to get a MapBuilder which can be used to construct an instance of a AbstractFixedMap
protected abstract AtomicValue	getKey(int position)	Get the key at a given offset.
static int	getOffset(HashMap<AtomicMatchKey,Integer> index, AtomicMatchKey key)	Get the offset in the index of a given key, or -1 if the key is not present.
int	getPosition(AtomicValue key)	Get the offset in the index of a given key, or -1 if the key is not present.
protected GroundedValue	getValue(int position)	Get the value at a given offset.
Iterator<KeyValuePair>	iterator()	Return an iterator of key-value pairs.
Iterable<KeyValuePair>	keyValuePairs()	Get the content of the map as an iterable collection of key value pairs
MapItem	put(AtomicValue key, GroundedValue value)	Create a new map containing the existing entries in the map plus an additional entry, without modifying the original.
static boolean	putOffsetIfAbsent(HashMap<AtomicMatchKey,Integer> index, AtomicMatchKey key, int value)	Put an entry in the index if the key is currently absent
MapItem	remove(AtomicValue key)	Remove an entry from the map
int	size()	Get the size of the map
String	toString()	Returns a string representation of the object.

Methods inherited from class net.sf.saxon.ma.map.MapWithTypeCache

conforms, setKnownType

Methods inherited from class net.sf.saxon.ma.map.MapItem

atomize, call, deepEqual40, deepEquals, effectiveBooleanValue, entries, export, followingKeyValuePairs, getAnnotations, getArity, getDescription, getFunctionItemType, getFunctionName, getGenre, getItemType, getItemTypeOfSequence, getOperandRoles, getSpecVersion, getTypedValue, getU, getUnicodeStringValue, getWithPlan, isArray, isEmpty, isKnownToConform, isMap, isTrustedResultType, itemAt, keys, makeNewContext, mapToString, precedingKeyValuePairs, setSpecVersion, toShortString

Methods inherited from class net.sf.saxon.ma.MapOrArray

obtainRootJNode

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.saxon.om.FunctionItem

isSequenceVariadic

Methods inherited from interface net.sf.saxon.om.GroundedValue

asIterable, concatenate, containsNode, materialize

Methods inherited from interface net.sf.saxon.om.Item

getLabel, getLength, getStringValue, head, isStreamed, iterate, reduce, subsequence

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface net.sf.saxon.om.Sequence

makeRepeatable

Field Details

values

protected GroundedValue[] values

index

protected HashMap<AtomicMatchKey,Integer> index

Constructor Details

AbstractFixedMap

public AbstractFixedMap()

Method Details

getBuilder

public static GeneralMapBuilder getBuilder(int specVersion)

Factory method to get a MapBuilder which can be used to construct an instance of a AbstractFixedMap

Returns:

a class for building fixed maps

get

public GroundedValue get(AtomicValue key)

Get an entry from the Map

Specified by:

get in class MapItem

Parameters:

key - the value of the key

Returns:

the value associated with the given key, or null if the key is not present in the map.

getOffset

public static int getOffset(HashMap<AtomicMatchKey,Integer> index,
 AtomicMatchKey key)

Get the offset in the index of a given key, or -1 if the key is not present. Done this way for C# transpilation (maps with primitive int values work differently...)

Parameters:

index - the index of offsets

key - the wanted key

Returns:

the offset in the index, or -1 if absent

putOffsetIfAbsent

public static boolean putOffsetIfAbsent(HashMap<AtomicMatchKey,Integer> index,
 AtomicMatchKey key,
 int value)

Put an entry in the index if the key is currently absent

Parameters:

index - the index of offsets

key - the new key

value - the new value

Returns:

true if an entry was added, false if the key was already present

getPosition

public int getPosition(AtomicValue key)

Get the offset in the index of a given key, or -1 if the key is not present.

Parameters:

key - the wanted key

Returns:

the offset in the index, or -1 if absent

ensureIndexed

protected void ensureIndexed()

Ensure that an index exists, creating it if necessary. In many cases an index is only created on the first call on get(AtomicValue). This is because in scenarios such as JSON transformation there may be many maps generated during JSON parsing that are never referenced, or that are copied directly to the serialized output without ever being accessed by key.

size

public int size()

Get the size of the map

Specified by:

size in class MapItem

Returns:

the number of keys/entries present in this map

getKey

protected abstract AtomicValue getKey(int position)

Get the key at a given offset. This method is provided for use by subclasses, which can store the actual key in different ways.

Parameters:

position - the offset (sibling position within the ordered map) of the required key

Returns:

the key at the specified position

getValue

protected GroundedValue getValue(int position)

Get the value at a given offset.

Parameters:

position - the offset (sibling position within the ordered map) of the required key

Returns:

the key at the specified position

keyValuePairs

public Iterable<KeyValuePair> keyValuePairs()

Get the content of the map as an iterable collection of key value pairs

Specified by:

keyValuePairs in class MapItem

Returns:

an iterable collection of key value pairs

iterator

public Iterator<KeyValuePair> iterator()

Return an iterator of key-value pairs.

Specified by:

iterator in interface Iterable<KeyValuePair>

Returns:

an Iterator of key-value pairs.

put

public MapItem put(AtomicValue key,
 GroundedValue value)

Create a new map containing the existing entries in the map plus an additional entry, without modifying the original. If there is already an entry with the specified key, this entry is replaced by the new entry.

Specified by:

put in class MapItem

Parameters:

key - the key of the new entry

value - the value associated with the new entry

Returns:

the new map containing the additional entry

remove

public MapItem remove(AtomicValue key)

Remove an entry from the map

Specified by:

remove in class MapItem

Parameters:

key - the key of the entry to be removed

Returns:

a new map in which the requested entry has been removed; or this map unchanged if the specified key was not present

toString

public String toString()

Returns a string representation of the object.

Overrides:

toString in class Object