uk.ac.sheffield.vtts.model

Class Manipulation

java.lang.Object

uk.ac.sheffield.vtts.model.Element

uk.ac.sheffield.vtts.model.Named

uk.ac.sheffield.vtts.model.Expression

uk.ac.sheffield.vtts.model.Function

uk.ac.sheffield.vtts.model.Manipulation

public class Manipulation
extends Function

Manipulation represents an expression manipulating a collection of items. The first operand is expected to be some kind of collection, whether a Set, List or Map. The remaining operands may be an element, an index, a key, or another collection. All Manipulations are functional, in that they do not modify an operand directly, but return a modified copy. If a side-effect is intended, the result must be reassigned to the same Parameter that stored the original collection, before the operation. There are nine Manipulation operations, whose names include: size, insert, remove, insertAll, removeAll, searchAt, replaceAt, insertAt and removeAt.

Version:

Broker@Cloud 1.0

Author:

Anthony J H Simons

Field Summary

Fields inherited from class uk.ac.sheffield.vtts.model.Function

expressions, maxOperands

Fields inherited from class uk.ac.sheffield.vtts.model.Expression

factory, type

Fields inherited from class uk.ac.sheffield.vtts.model.Named

name

Constructor Summary

Constructors

Constructor and Description
Manipulation() Creates a default Manipulation expression.
Manipulation(java.lang.String name) Creates a named Manipulation expression.
Manipulation(java.lang.String name, java.lang.String type) Creates a named and typed Manipulation expression.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.Object	evaluate() Executes this Manipulation on its operands.
java.lang.String	getType() Returns the result type of this Manipulation.
protected java.lang.Object	insert(java.lang.Object collection, java.lang.Object value) Returns a new collection in which the value has been inserted.
protected java.lang.Object	insertAll(java.lang.Object first, java.lang.Object second) Returns a new collection containing all of the first and second collections.
protected java.lang.Object	insertAt(java.lang.Object collection, java.lang.Object key, java.lang.Object value) Returns a new collection, in which a value is inserted opposite a key or index.
protected void	nameCheck() Checks the name of this Manipulation expression and sets the expected number of operands.
void	rebind(java.lang.Object result) Rebinds the unbound operands of this Manipulation expression, so that it yields the given expected result.
protected java.lang.Object	remove(java.lang.Object collection, java.lang.Object value) Returns a new collection in which the value has been removed.
protected java.lang.Object	removeAll(java.lang.Object first, java.lang.Object second) Returns a new collection containing those elements from the first, which were not present in the second collection.
protected java.lang.Object	removeAt(java.lang.Object collection, java.lang.Object key) Returns a new collection, in which a value is removed opposite a key or index.
protected java.lang.Object	replaceAt(java.lang.Object collection, java.lang.Object key, java.lang.Object value) Returns a new collection, in which a value is replaced opposite a key or index.
protected java.lang.Object	searchAt(java.lang.Object collection, java.lang.Object key) Searches a collection and returns the object found opposite a given key or index.
protected java.lang.Integer	size(java.lang.Object collection) Returns the size or cardinality of a collection.
protected void	typeCheck() Checks that the operand and result types are consistent.

Methods inherited from class uk.ac.sheffield.vtts.model.Function

addExpression, assign, equals, getExpressions, hashCode, isAssignable, isBound, operand, rebind, resolve, setName, toString, unbind

Methods inherited from class uk.ac.sheffield.vtts.model.Expression

getName, isBottom, isOrdered, setType

Methods inherited from class uk.ac.sheffield.vtts.model.Named

setName

Methods inherited from class uk.ac.sheffield.vtts.model.Element

safeEquals, safeHashCode, semanticError

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Manipulation

public Manipulation()

Creates a default Manipulation expression.

Manipulation

public Manipulation(java.lang.String name)

Creates a named Manipulation expression.

Parameters:

name - the set-theoretic operator name.

Manipulation

public Manipulation(java.lang.String name,
            java.lang.String type)

Creates a named and typed Manipulation expression.

Parameters:

name - the name of the set-theoretic operator.

type - the result type of the expression.

Method Detail

nameCheck

protected void nameCheck()

Checks the name of this Manipulation expression and sets the expected number of operands. Manipulations expect one to three operands, the first of which is always a collection of items (whether List, Set or Map). The operation "size" expects this single collection operand. The operations "insert, remove" expect the second operand to be an element of the collection. The operations "insertAll, removeAll" expect the second operand to be another collection. The operations "searchAt, removeAt" expect the second operand to be a key or index. The operations "insertAt, replaceAt" expect a similar second operand and an element value as the third operand.

Specified by:

nameCheck in class Function

typeCheck

protected void typeCheck()

Checks that the operand and result types are consistent. The first operand(0) must always be a collection type. Depending on the named operation, the operand(1) type must either be the same collection type; or the value-type, or the key-type of operand(0). If there is any operand(2), this is always the value-type. The result-type must either be the collection-type, the value-type or "Integer", according to the operation. Caches the values of paramType, valueType, keyType and pairType for use during binding and value synthesis. Caches the kind of collection, for dispatching during evaluation.

Specified by:

typeCheck in class Function

getType

public java.lang.String getType()

Returns the result type of this Manipulation. Returns the explicitly given type, otherwise infers this type by a heuristic. By default, returns the type of the first operand; but if the operator is "size", returns "Integer" and if the operator is "searchAt", returns the associated value-type.

Overrides:

getType in class Function

Returns:

the type of this Manipulation.

Throws:

SemanticError - if no type can be inferred.

evaluate

public java.lang.Object evaluate()

Executes this Manipulation on its operands. Expects one operand for the size() operation, three operands for insertAt(), replaceAt() and two operands for all other operations. Checks the consistency of the operand types and then branches according to the number of operands, and the name of this Manipulation operation. In keeping with the side-effect free specification style, all modifications to an input collection return a new output collection in which the changes have been made. All indexing is from 1..n (rather than 0..n-1).

Specified by:

evaluate in class Expression

Returns:

an integer size, a found element, or a new collection.

size

protected java.lang.Integer size(java.lang.Object collection)

Returns the size or cardinality of a collection. Casts the argument to a Map or a Collection, and calls Java's built-in size() method.

Parameters:

collection - the collection.

Returns:

the size of the collection.

insert

protected java.lang.Object insert(java.lang.Object collection,
                      java.lang.Object value)

Returns a new collection in which the value has been inserted. For a Map, expects the value to be an Entry tuple; otherwise the value is of the value-type of the List or Set. Maps and Sets insert their values uniquely at unordered positions; whereas a Set inserts the value in final position.

Parameters:

collection - the input collection.

value - the value to insert.

Returns:

the output collection containing the inserted value.

remove

protected java.lang.Object remove(java.lang.Object collection,
                      java.lang.Object value)

Returns a new collection in which the value has been removed. For a Map, expects the value to be an Entry tuple; otherwise the value is of the value-type of the List or Set. Removes the unique occurrence of the value from a Map or Set, or the first occurrence from a List.

Parameters:

collection - the input collection.

value - the value to remove.

Returns:

the output collection missing the removed value.

insertAll

protected java.lang.Object insertAll(java.lang.Object first,
                         java.lang.Object second)

Returns a new collection containing all of the first and second collections. For a List, appends the second to the first List; for a Set, returns the union of the first and second Sets; and for a Map, returns the union with override of the first and second Maps, in which entries from the second may replace entries from the first, if they have the same key.

Parameters:

first - the first collection.

second - the second collection.

Returns:

a new collection containing the pooled elements.

removeAll

protected java.lang.Object removeAll(java.lang.Object first,
                         java.lang.Object second)

Returns a new collection containing those elements from the first, which were not present in the second collection. For a Set or Map, returns the set-difference of the two Sets or Maps; for a List, returns the bag-difference of the two Lists, preserving element order.

Parameters:

first - the first collection.

second - the second collection.

Returns:

a new collection subtracting all of the second from the first.

insertAt

protected java.lang.Object insertAt(java.lang.Object collection,
                        java.lang.Object key,
                        java.lang.Object value)

Returns a new collection, in which a value is inserted opposite a key or index. For a Map, stores the value opposite the key. If the key already exists in the Map, replaces the associated value. For a List, inserts the value at the key index, so long as the index is in range. Indexing is 1..size; and the insertion range allows size+1. This method is not defined for Sets.

Parameters:

collection - the input Map or List.

key - a key or Integer index.

value - the value to insert.

Returns:

a new collection, in which the value is present, indexed by the key.

removeAt

protected java.lang.Object removeAt(java.lang.Object collection,
                        java.lang.Object key)

Returns a new collection, in which a value is removed opposite a key or index. For a Map, removes the Map entry indexed by the key, if such an entry exists. For a List, removes the value at the key index, so long as the index is in range. Indexing is 1..size. This method is not defined for Sets.

Parameters:

collection - the input Map or List.

key - a key or Integer index.

Returns:

a new collection, in which the value originally indexed by the key is absent.

replaceAt

protected java.lang.Object replaceAt(java.lang.Object collection,
                         java.lang.Object key,
                         java.lang.Object value)

Returns a new collection, in which a value is replaced opposite a key or index. For a Map, replaces the value opposite the key. If the key is not present in the Map, inserts a Map entry for the key and value. For a List, replaces the value at the key index, so long as the index is in range. Indexing is 1..size. This method is not defined for Sets.

Parameters:

collection - the input Map or List.

key - a key or Integer index.

value - the value to replace.

Returns:

a new collection, in which the value is present, indexed by the key.

searchAt

protected java.lang.Object searchAt(java.lang.Object collection,
                        java.lang.Object key)

Searches a collection and returns the object found opposite a given key or index. For a Map, returns the value associated with the key, if one exists (null may be returned if not). For a List, returns the value stored at the key index, so long as the index is in range. Indices run from 1..n. This method is not defined for Sets.

Parameters:

collection - the input Map or List.

key - a key or Integer index.

Returns:

the value found opposite the key or index.

rebind

public void rebind(java.lang.Object result)

Rebinds the unbound operands of this Manipulation expression, so that it yields the given expected result.

Specified by:

rebind in class Expression

Parameters:

result - the expected result of this Manipulation expression.