diff options
Diffstat (limited to 'vespajlib/src/main/java/com/yahoo/tensor/Tensor.java')
-rw-r--r-- | vespajlib/src/main/java/com/yahoo/tensor/Tensor.java | 45 |
1 files changed, 23 insertions, 22 deletions
diff --git a/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java b/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java index d650b88f202..ac9dc4e4eca 100644 --- a/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java +++ b/vespajlib/src/main/java/com/yahoo/tensor/Tensor.java @@ -40,7 +40,7 @@ import static com.yahoo.tensor.functions.ScalarFunctions.Hamming; * A multidimensional array which can be used in computations. * <p> * A tensor consists of a set of <i>dimension</i> names and a set of <i>cells</i> containing scalar <i>values</i>. - * Each cell is is identified by its <i>address</i>, which consists of a set of dimension-label pairs which defines + * Each cell is identified by its <i>address</i>, which consists of a set of dimension-label pairs which defines * the location of that cell. Both dimensions and labels are string on the form of an identifier or integer. * <p> * The size of the set of dimensions of a tensor is called its <i>rank</i>. @@ -55,7 +55,9 @@ import static com.yahoo.tensor.functions.ScalarFunctions.Hamming; * @author bratseth */ public interface Tensor { - int INVALID_INDEX = -1; + + /** The constant signaling a nonexisting value in operations addressing tensor values by index. */ + int invalidIndex = -1; // ----------------- Accessors @@ -65,25 +67,24 @@ public interface Tensor { default boolean isEmpty() { return size() == 0; } /** - * Returns the number of cells in this. - * Allows for very large tensors, but if you only handle size in the int range - * prefer sizeAsInt(). - **/ + * Returns the number of cells in this, allowing for very large tensors. + * Prefer sizeAsInt in implementations that cannot handle sizes outside the int range. + */ default long size() { return sizeAsInt(); } /** - * Safe way to get size as an int and detect when not possible. - * Prefer this over size() as - * @return size() as an int + * Returns the size of this as an int or throws an exception if it is too large to fit in an int. + * Prefer this over size() with implementations that only handle sizes in the int range. + * + * @throws IndexOutOfBoundsException if the size is too large to fit in an int */ default int sizeAsInt() { - long sz = size(); - if (sz > Integer.MAX_VALUE) { - throw new IndexOutOfBoundsException("size = " + sz + ", which is too large to fit in an int"); - } - return (int) sz; + long size = size(); + if (size > Integer.MAX_VALUE) + throw new IndexOutOfBoundsException("size = " + size + ", which is too large to fit in an int"); + return (int) size; } /** Returns the value of a cell, or 0.0 if this cell does not exist */ @@ -91,7 +92,8 @@ public interface Tensor { /** Returns true if this cell exists */ boolean has(TensorAddress address); - /** null = no value present. More efficient that if (t.has(key)) t.get(key) */ + + /** Returns the value at this address, or null of it does not exist. */ Double getAsDouble(TensorAddress address); /** @@ -132,7 +134,7 @@ public interface Tensor { /** * Returns a new tensor where existing cells in this tensor have been * modified according to the given operation and cells in the given map. - * Cells in the map outside of existing cells are thus ignored. + * Cells in the map outside existing cells are thus ignored. * * @param op the modifying function * @param cells the cells to modify @@ -151,9 +153,9 @@ public interface Tensor { /** * Returns a new tensor where existing cells in this tensor have been - * removed according to the given set of addresses. Only valid for sparse + * removed according to the given set of addresses. Only valid for mapped * or mixed tensors. For mixed tensors, addresses are assumed to only - * contain the sparse dimensions, as the entire dense subspace is removed. + * contain the mapped dimensions, as the entire indexed subspace is removed. * * @param addresses list of addresses to remove * @return a new tensor where cells have been removed @@ -503,11 +505,10 @@ public interface Tensor { public TensorAddress getKey() { return address; } /** - * Returns the direct index which can be used to locate this cell, or -1 if not available. - * This is for optimizations mapping between tensors where this is possible without creating a - * TensorAddress. + * Returns the direct index which can be used to locate this cell, or Tensor.invalidIndex if not available. + * This is for optimizations mapping between tensors where this is possible without creating a TensorAddress. */ - long getDirectIndex() { return INVALID_INDEX; } + long getDirectIndex() { return invalidIndex; } /** Returns the value as a double */ @Override |