API reference · Arrays

InsertColumns

Append columns to a 2D array or overwrite its trailing columns.

FunctionArrays→VariantSource L611

Signature#

Function InsertColumns(ByVal vArr As Variant, ByVal vColumns As Variant, Optional ByVal bRedim As Boolean = True) As Variant

Parameters#

Parameter	VBA type	Default	Description
`vArr`	`Variant`ByVal	Required	Allocated 2D destination array. Its bounds form the output's starting bounds.
`vColumns`	`Variant`ByVal	Required	1D vector contributing one column, or 2D block contributing all of its columns. Its row count must equal vArr's row count; row lower bounds may differ.
`bRedim`	`Boolean`ByVal	`True`	True appends the supplied columns after the final source column. False keeps the source width and replaces the same number of trailing columns.

Returns#

Variant containing a new 2D array. Row bounds and the column lower bound are preserved; the column upper bound increases by the supplied width when bRedim=True. Returns Empty for unsupported shapes, mismatched row counts, or an overwrite wider than the source.

Example#

SEE THE TRANSFORMATIONAppend one column

Before

transactions2D · 2 × 2

Rows 1..2 · Columns 1..2

row / col	1	2
1	“Invoice A”	100
2	“Invoice B”	200

Additional input

tax1D · (2,)

Indices 0..1 · one dimension

0	1
20	40

After

result2D · 2 × 3

Rows 1..2 · Columns 1..3

row / col	1	2	3
1	“Invoice A”	100	20
2	“Invoice B”	200	40

The 0-based tax vector aligns by row position with the 1-based matrix.

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

Sub ExampleInsertColumns()
    Dim a As New Arrays
    Dim transactions As Variant, tax As Variant, result As Variant

    ReDim transactions(1 To 2, 1 To 2)
    transactions(1, 1) = "Invoice A": transactions(1, 2) = 100
    transactions(2, 1) = "Invoice B": transactions(2, 2) = 200
    tax = VBA.Array(20, 40)
    result = a.InsertColumns(transactions, tax)
    Debug.Print UBound(result, 2)      ' Expected: 3
    Debug.Print result(1, 3), result(2, 3) ' Expected: 20, 40
End Sub

Behavior and edge cases#

There is no insertion-position parameter. This function appends at the right edge or replaces columns at the right edge; it does not shift columns around an arbitrary position.
A 1D vColumns vector is interpreted vertically. Both 1D and 2D sources are aligned by row position, not by equal numeric subscripts.
With bRedim=False, the last supplied-width columns are overwritten and every other source value is retained. A block wider than the source returns Empty.
Only the supplied block's row count must match. Its column lower bound can differ because copying uses positional offsets.
Both inputs must be arrays; a non-array input returns Empty. Values are copied without comparison, and neither input array is modified.

Performance#

O(r × (c + k)) copy work for r rows, c original columns and k supplied columns. Output storage is O(r × (c + k)) when appending or O(r × c) when overwriting.

View implementation

Function InsertColumns(ByVal vArr As Variant, ByVal vColumns As Variant, Optional ByVal bRedim As Boolean = True) As Variant
    'Appends columns to a 2D array or overwrites its last columns when bRedim is False

    Dim vArr_Out                As Variant
    Dim lRow                    As Long
    Dim lCol                    As Long
    Dim lRowSource              As Long
    Dim lColSource              As Long
    Dim lStart                  As Long
    Dim lNumColumns             As Long
    Dim iDim                    As Integer

    If Not IsArray(vArr) Or Not IsArray(vColumns) Then Exit Function
    If Me.DimCounter(vArr) <> 2 Then Exit Function

    iDim = Me.DimCounter(vColumns)
    If iDim <> 1 And iDim <> 2 Then Exit Function

    If iDim = 1 Then
        If UBound(vColumns) - LBound(vColumns) <> UBound(vArr, 1) - LBound(vArr, 1) Then Exit Function
        lNumColumns = 1
    Else
        If UBound(vColumns, 1) - LBound(vColumns, 1) <> UBound(vArr, 1) - LBound(vArr, 1) Then Exit Function
        lNumColumns = UBound(vColumns, 2) - LBound(vColumns, 2) + 1
    End If

    If Not bRedim Then
        If lNumColumns > UBound(vArr, 2) - LBound(vArr, 2) + 1 Then Exit Function
    End If

    If bRedim Then
        ReDim vArr_Out(LBound(vArr, 1) To UBound(vArr, 1), LBound(vArr, 2) To UBound(vArr, 2) + lNumColumns)
    Else
        ReDim vArr_Out(LBound(vArr, 1) To UBound(vArr, 1), LBound(vArr, 2) To UBound(vArr, 2))
    End If

    For lRow = LBound(vArr, 1) To UBound(vArr, 1)
        For lCol = LBound(vArr, 2) To UBound(vArr, 2)
            vArr_Out(lRow, lCol) = vArr(lRow, lCol)
        Next lCol
    Next lRow

    lStart = UBound(vArr_Out, 2) - lNumColumns + 1

    For lRow = LBound(vArr_Out, 1) To UBound(vArr_Out, 1)
        lRowSource = lRow - LBound(vArr, 1)
        For lCol = lStart To UBound(vArr_Out, 2)
            If iDim = 1 Then
                vArr_Out(lRow, lCol) = vColumns(LBound(vColumns) + lRowSource)
            Else
                lColSource = LBound(vColumns, 2) + lCol - lStart
                vArr_Out(lRow, lCol) = vColumns(LBound(vColumns, 1) + lRowSource, lColSource)
            End If
        Next lCol
    Next lRow

    InsertColumns = vArr_Out
End Function