40 lines
2.7 KiB
Java
40 lines
2.7 KiB
Java
package com.github.btrekkie.connectivity;
|
|
|
|
/**
|
|
* A combining function for taking the augmentations associated with a set of ConnVertices and reducing them to a single
|
|
* result. The function is a binary operation for combining two values into one. For example, given vertices with
|
|
* augmentations A1, A2, A3, and A4, the combined result may be obtained by computing
|
|
* combine(combine(combine(A1, A2), A3), A4). In order for an augmentation result to be meaningful, the combining
|
|
* function must be commutative, meaning combine(x, y) is equivalent to combine(y, x), and associative, meaning
|
|
* combine(x, combine(y, z)) is equivalent to combine(combine(x, y), z).
|
|
*
|
|
* If a ConnGraph represents a game map, then one example of an augmentation would be the amount of gold accessible from
|
|
* a certain location. Each vertex would be augmented with the amount of gold in that location, and the combining
|
|
* function would add the two amounts of gold passed in as arguments. Another example would be the strongest monster
|
|
* that can reach a particular location. Each vertex with at least one monster would be augmented with a pointer to the
|
|
* strongest monster at that location, and the combining function would return the stronger of the two monsters passed
|
|
* in as arguments. A third example would be the number of locations accessible from a given vertex. Each vertex would
|
|
* be augmented with the number 1, and the combining function would add the two numbers of vertices passed in as
|
|
* arguments.
|
|
*
|
|
* ConnGraph treats two augmentation values X and Y as interchangeable if they are equal, as in
|
|
* X != null ? X.equals(Y) : Y == null. The same holds for two combined augmentation values, and for one combined
|
|
* augmentation value and one augmentation value.
|
|
*
|
|
* See the comments for ConnGraph.
|
|
*/
|
|
public interface Augmentation {
|
|
/**
|
|
* Returns the result of combining the specified values into one. Each argument is either the augmentation
|
|
* information associated with a vertex, or the result of a previous call to "combine".
|
|
*
|
|
* Note that a value of null is never passed in to indicate the absence of augmentation information. The fact that
|
|
* ConnGraph.getVertexAugmentation, for example, may return null when there is no associated augmentation might lead
|
|
* you to believe that a null argument indicates the absence of augmentation information, but again, it does not. A
|
|
* null argument can only mean that a vertex is explicitly associated with null augmentation information, due to a
|
|
* prior call to ConnGraph.setVertexAugmentation(vertex, null), or that the "combine" method previously returned
|
|
* null.
|
|
*/
|
|
public Object combine(Object value1, Object value2);
|
|
}
|