Sizing Vectors and Matrices

Every operation that writes a result sizes its destination implicitly, so calling Size() explicitly is optional. The Size() overloads differ by type.

Sizing does not preserve content. Size() — and the properties that alias it (Length, Rows, Cols) — re-allocate the container and discard whatever it held. To change the size and keep the values already stored, use Resize(...) instead: it resizes while preserving them.

Values do happen to survive a Size() call when the new size still fits within the memory already allocated, since no re-allocation takes place. Never rely on that: it is a side effect of tuning parameters chosen for performance and memory usage, and it changes when they change. Use Resize(...) whenever the content matters.

Vector.Size() overloads:

  • Vector.Size(TMtxVec Src)
  • Vector.Size(TMtxVec Src, Boolean AComplex)
  • Vector.Size(Int32 ALength, TMtxFloatPrecision aFloatPrecision)
  • Vector.Size(Int32 ALength, Boolean aIsComplex, Boolean aIsDouble)

VectorInt.Size() overloads:

  • VectorInt.Size(TMtxVecBase Src)
  • VectorInt.Size(Int32 ALength)
  • VectorInt.Size(Int32 ALength, TIntPrecision aPrecision)

Matrix.Size() overloads:

  • Matrix.Size(TMtxVec Src)
  • Matrix.Size(TMtxVec Src, Boolean AComplex)
  • Matrix.Size(Int32 ARows, Int32 ACols)
  • Matrix.Size(Int32 ARows, Int32 ACols, TMtxFloatPrecision aFloatPrecision)
  • Matrix.Size(Int32 ARows, Int32 ACols, TMtxVec aFloatPrecisionRef)
  • Matrix.Size(Int32 ARows, Int32 ACols, Boolean AComplex)
  • Matrix.Size(Int32 ARows, Int32 ACols, Boolean AComplex, Boolean aIsDouble)

MatrixInt.Size() overloads:

  • MatrixInt.Size(TMtxVecBase Src)
  • MatrixInt.Size(TMtxVecBase Src, TIntPrecision aPrecision)
  • MatrixInt.Size(Int32 ARows, Int32 ACols)
  • MatrixInt.Size(Int32 ARows, Int32 ACols, TIntPrecision aPrecision)

TVec.Size() overloads:

  • TVec.Size(TMtxVecBase Src, TMtxFloatPrecision aFloatPrecision)
  • TVec.Size(TMtxVecBase Src, Boolean AComplex)
  • TVec.Size(Int32 ALength)
  • TVec.Size(Int32 ALength, TMtxFloatPrecision aFloatPrecision)
  • TVec.Size(Int32 ALength, TMtxVec FloatRef)
  • TVec.Size(Int32 ALength, Boolean AComplex)
  • TVec.Size(Int32 ALength, Boolean AComplex, Boolean aIsDouble)

TMtx.Size() overloads:

  • TMtx.Size(Int32 ARows, Int32 ACols)
  • TMtx.Size(Int32 ARows, Int32 ACols, TMtxFloatPrecision aFloatPrecision)
  • TMtx.Size(Int32 ARows, Int32 ACols, TMtxVec FloatPrecisionRef)
  • TMtx.Size(Int32 ARows, Int32 ACols, Boolean AComplex)
  • TMtx.Size(Int32 ARows, Int32 ACols, Boolean AComplex, Boolean aIsDouble)

Resize() — change the size and keep the values:

Resize is the counterpart to Size: it changes the length or shape while preserving the values already allocated. Use it whenever the existing content matters.

  • TVec.Resize(Len, ZeroIt) — resize the vector to Len.
  • TVec.Resize(Src, Len, ZeroIt) — resize and fill with the first Len values of Src. If Src is shorter than Len and ZeroIt is True, the remaining values are set to zero.
  • TMtx.Resize(NewRows, NewCols) — reshape the matrix, preserving the values in already allocated memory.
  • TMtx.Resize(Src, NewRows, NewCols) — resize the calling matrix from Src.

The value types Vector and Matrix expose the same Resize overloads, as do TVecInt / TMtxInt and VectorInt / MatrixInt.

Vector a = new Vector();
a.SetIt(false, new double[] {1, 2, 3});
a.Resize(5, true);       // [1, 2, 3, 0, 0] - values kept, tail zeroed
a.Resize(2, false);      // [1, 2]          - truncated, values kept

Vector b = new Vector();
b.Resize(a, 4, true);    // b takes a's first 4 values, zero-filled if shorter

Matrix m = new Matrix();
m.SetIt(2, 2, false, new double[] {1, 2, 3, 4});
m.Resize(3, 3);          // the existing 2x2 values are preserved

Capacity — pre-allocating to avoid re-allocation:

Capacity sets a floor on allocation: sizing the object will never allocate less than Capacity. Setting it up-front lets a container grow to its expected maximum without repeatedly re-allocating.

  • Any re-allocation implied by a new Capacity happens at the next call to Size — setting Capacity alone does not allocate.
  • Do not assume existing values survive a Capacity change.
  • Capacity equals CapacityInElements and is rounded up to a multiple of 16 bytes. It can never be odd — an odd value is raised to the next even one.
  • For an object taken from the object cache, a Capacity specified below the object cache size is not considered — the cached object is already at least that large, so the value places no additional constraint on it.
  • CapacityInBytes / CapacityInElements express the same limit in bytes or elements; when the storage precision changes, CapacityInElements is adjusted while CapacityInBytes is retained.
  • CapacityStep controls automatic growth: 0 never grows Capacity on its own, 1 grows it to match the largest size requested, and a value greater than 1 grows it by that factor.

Key difference: Vector.Size(10) does not compile — use Vector.Size(10, false, true). TVec.Size(10) DOES compile. This is a known API inconsistency.

Enum values for precision/rounding:

EnumValues
TMtxFloatPrecisionmvDouble, mvDoubleComplex, mvSingle, mvSingleComplex
TRoundingrnRound, rnTrunc
TComparecmpAbsolute, cmpRelative
TIntPrecisionprInt16, prInt32, prInt8