Guides

Convert array representations

Move between vectors, rectangular arrays, and arrays of row arrays.

Choose a representation#

Representation	Example indexing	Use
1D vector	values(i)	A list of values
2D rectangular	records(row, column)	Range.Value2 and table processing
1D of 1D rows	rows(i)(j)	Building row records with VBA.Array

SEE THE TRANSFORMATIONExpand a vector, then transpose it

Before

vector1D · (3,)

Indices 0..2 · one dimension

0	1	2
10	20	30

After

row2D · 1 × 3

Rows 1..1 · Columns 0..2

row / col	0	1	2
1	10	20	30

Shape sequence: 1D (3,) → 2D (3, 1) → 2D (1, 3). DimReduce then returns a 1D vector with indices 0..2.

Shaded headers are array indices, not data. Quoted cells are text. Values shown are derived from the source, not an Excel execution.

Sub ConvertRepresentations()
    Dim vector As Variant, column As Variant, row As Variant
    Dim nested As Variant, rectangular As Variant, restored As Variant
    vector = VBA.Array(10, 20, 30) ' Explicitly 0-based
    column = Arr.DimExpand(vector) ' Rows 0..2, column 1..1
    row = Arr.Transpose(column)   ' Row 1..1, columns 0..2
    restored = Arr.DimReduce(row) ' 1D indices 0..2

    nested = VBA.Array(VBA.Array("A", 10), VBA.Array("B", 20))
    rectangular = Arr.DimMerge(nested) ' Rows 0..1, columns 0..1
    nested = Arr.DimSplit(rectangular)
    Debug.Print nested(1)(0) ' Expected: B
    rectangular = Arr.Change_Lbound(rectangular, 1, 1)
    rectangular = Arr.Change_Lbound(rectangular, 1, 2)
    Debug.Print LBound(rectangular, 1), LBound(rectangular, 2) ' 1, 1
End Sub

Conversion rules#

DimExpand changes a 1D vector into a 2D column. It preserves vector indices as row indices, and creates column 1.
DimReduce accepts only a 2D single-row or single-column array. For a 1×1 array the row branch wins, so the surviving index comes from the column dimension.
DimSplit retains rectangular row bounds as outer bounds and column bounds as inner bounds.
DimMerge sizes the output using the first nested row. Every later row must support all those indices. Ragged rows are not validated and can raise errors.
Transpose accepts a 2D array and swaps both the dimensions and their bounds.
Change_Lbound copies values with new indices for one selected dimension.

A single cell is a scalar#

Reading multiple cells with Range.Value2 gives a 2D Variant array. Reading one cell gives a scalar. Wrap a scalar in an explicit 1×1 array before calling functions that require 2D data. DimExpand expects a 1D array and does not wrap a scalar.

Sub NormalizeSingleCell()
    Dim value As Variant, values As Variant
    value = ThisWorkbook.Worksheets(1).Range("A1").Value2
    ReDim values(1 To 1, 1 To 1)
    values(1, 1) = value
    Debug.Print Arr.DimCounter(values) ' Expected: 2
End Sub

Pass arrays in Variant containers#

Examples use Variant variables containing arrays, followed by ReDim when explicit bounds are needed. This follows Microsoft’s guidance on passing arrays to ByVal parameters.