Package com.apple.foundationdb.linear

Class AbstractRealVector

java.lang.Object
com.apple.foundationdb.linear.AbstractRealVector
All Implemented Interfaces:
RealVector
Direct Known Subclasses:
DoubleRealVector, FloatRealVector, HalfRealVector
public abstract class AbstractRealVector extends Object implements RealVector
Common implementation skeleton for every RealVector subtype in this package. Holds the canonical double[] storage, memoizes the three derived values that are pure functions of the data (hashCode(), getRawData(), l2SquaredNorm()), and delegates the precision-specific bits (raw-byte format, conversions to other vector representations) to concrete subclasses.

The class is intentionally precision-agnostic at this level — every accessor returns double, and subclasses only differ in storage resolution (which they truncate to in their constructors) and in the wire format produced by computeRawData(). Mutable storage is the special case modeled by MutableDoubleRealVector; everything else inheriting from this class is treated as immutable for the lifetime of the instance (per the constructor contract).

  • Field Details

    • data

      @Nonnull protected final double[] data

    • hashCodeSupplier

      @Nonnull protected Supplier<Integer> hashCodeSupplier

  • Constructor Details

    • AbstractRealVector

      protected AbstractRealVector(@Nonnull double[] data)
      Constructs a new RealVector with the given data.

      This constructor uses the provided array directly as the backing store for the vector. It does not create a defensive copy. Therefore, any subsequent modifications to the input array will be reflected in this vector's state. The contract of this constructor is that callers do not modify data after calling the constructor. We do not want to copy the array here for performance reasons.

      Parameters:
      data - the components of this vector
      Throws:
      NullPointerException - if the provided data array is null.

  • Method Details

    • getNumDimensions

      public int getNumDimensions()
      Returns the number of elements in the vector.
      Specified by:
      getNumDimensions in interface RealVector
      Returns:
      the number of elements

    • getComponent

      public double getComponent(int dimension)
      Gets the component of this object at the specified dimension.

      The dimension is a zero-based index. For a 3D vector, for example, dimension 0 might correspond to the x-component, 1 to the y-component, and 2 to the z-component. This method provides direct access to the underlying data element.

      Specified by:
      getComponent in interface RealVector
      Parameters:
      dimension - the zero-based index of the component to retrieve.
      Returns:
      the component at the specified dimension as a double.
      Throws:
      IndexOutOfBoundsException - if the dimension is negative or greater than or equal to the number of dimensions of this object.

    • getData

      @Nonnull public double[] getData()
      Returns the underlying double[] data array.

      The returned array is guaranteed to be non-null. Note that this method returns a direct reference to the internal array, not a copy — callers must not mutate it unless the concrete subtype is MutableDoubleRealVector.

      Specified by:
      getData in interface RealVector
      Returns:
      the data array, never null.

    • getRawData

      @Nonnull public byte[] getRawData()
      Gets the raw byte data representation of this object.

      This method provides a direct, unprocessed view of the object's underlying data. The format of the byte array is implementation-specific and should be documented by the concrete class that implements this method.

      Specified by:
      getRawData in interface RealVector
      Returns:
      a non-null byte array containing the raw data.

    • computeRawData

      @Nonnull protected abstract byte[] computeRawData()
      Computes the raw byte data representation of this object.

      This method provides a direct, unprocessed view of the object's underlying data. The format of the byte array is implementation-specific and should be documented by the concrete class that implements this method.

      Returns:
      a non-null byte array containing the raw data.

    • equals

      public boolean equals(Object o)
      Compares this vector to the specified object for equality.

      The result is true if and only if the argument is not null and is a RealVector object that has the same data elements as this object. This method performs a deep equality check on the underlying data elements using Objects.deepEquals(Object, Object).

      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare with this RealVector for equality.
      Returns:
      true if the given object is a RealVector equivalent to this vector, false otherwise.

    • hashCode

      public int hashCode()
      Returns a hash code value for this object. The hash code is computed once and memoized.
      Overrides:
      hashCode in class Object
      Returns:
      a hash code value for this object.

    • computeHashCode

      protected int computeHashCode()
      Computes a hash code based on the internal data array.
      Returns:
      the computed hash code for this object.

    • toString

      public String toString()
      Returns a string representation of the object.

      This method provides a default string representation by calling toString(int) with a predefined indentation level of 3.

      Overrides:
      toString in class Object
      Returns:
      a string representation of this object with a default indentation.

    • toString

      public String toString(int limitDimensions)
      Generates a string representation of the data array, with an option to limit the number of dimensions shown.

      If the specified limitDimensions is less than the actual number of dimensions in the data array, the resulting string will be a truncated view, ending with ", ..." to indicate that more elements exist. Otherwise, the method returns a complete string representation of the entire array.

      Parameters:
      limitDimensions - The maximum number of array elements to include in the string. A non-positive value will cause an VerifyException.
      Returns:
      A string representation of the data array, potentially truncated.
      Throws:
      com.google.common.base.VerifyException - if limitDimensions is not positive

    • l2SquaredNorm

      public double l2SquaredNorm()
      Returns the squared L2 norm Σ_i this[i]^2. Implementations typically memoize this since the value is reused by RealVector.l2Norm() and several distance helpers.

      Memoized via the l2SquaredNormSupplier so repeated calls — including the ones driving RealVector.l2Norm() — share a single computation.

      Specified by:
      l2SquaredNorm in interface RealVector
      Returns:
      the squared L2 norm of this vector

    • computeL2SquaredNorm

      protected double computeL2SquaredNorm()
      Computes the squared L2 norm from scratch as dot(this). Backs the memoizing supplier behind l2SquaredNorm(); subclasses normally don't need to call it directly.
      Returns:
      the squared L2 norm of this vector

    • fromInts

      @Nonnull protected static double[] fromInts(@Nonnull int[] ints)
      Widens an int[] to a freshly allocated double[] suitable for handing to the array-by-reference constructor. Used by subclass int-constructors so the call site does not need to manage the widening copy.
      Parameters:
      ints - the source components
      Returns:
      a new double[] of the same length, each element widened from the corresponding ints[i]

    • fromLongs

      @Nonnull protected static double[] fromLongs(@Nonnull long[] longs)
      Widens a long[] to a freshly allocated double[] suitable for handing to the array-by-reference constructor. Used by subclass long-constructors so the call site does not need to manage the widening copy. Note that long values outside the 53-bit mantissa of double may lose precision in the widening.
      Parameters:
      longs - the source components
      Returns:
      a new double[] of the same length, each element widened from the corresponding longs[i]