3. Script Language > Arrays and Data-Structures > !ARM. - Multidimensional Dynamic Arrays

Array Management Commands Overview

Previous Top Next

MiniRobotLanguage (MRL)

Array Management Commands

Comprehensive Guide to Core Array Management Commands in MiniRobotLanguage (MRL)

Overview

The ARM (Array Management) commands in MiniRobotLanguage (MRL) provide essential tools for creating, maintaining, configuring, and destroying two-dimensional (2D) arrays. These arrays are emulated as grid-like structures—visualized as a chessboard with rows and columns (e.g., [1,1] to [8,8])—within a one-dimensional framework, supporting three data types: strings (“s”), integers (“i”), and floating-point numbers (“f”). The management commands outlined here (ARM.Clear, ARM.Copy, ARM.Count, ARM.End, ARM.EndAll, ARM.GetDims, ARM.GetType, ARM.New, ARM.Redim, ARM.Resize, ARM.Validate) enable developers to initialize arrays, adjust their structure, validate their state, and clean up resources efficiently. These commands are critical for applications such as:

- Game Development: Setting up and resetting game boards or matrices for games like chess or puzzles.
- Data Management: Maintaining dynamic data structures for scientific calculations, image processing, or storage.
- Resource Optimization: Ensuring efficient memory usage by properly creating and destroying arrays.

This guide provides an exhaustive exploration of each command, detailing its purpose, syntax, parameters, practical examples, remarks, limitations, and related commands. All indices are 1-based, aligning with MRL’s grid structure, and operations require valid array handles created with ARM.New. Performance considerations are noted, as MRL’s 1D emulation of 2D arrays may introduce linear overhead for large datasets.

Commands

1. ARM.Clear

Efficiently clears all elements in a 2D array, resetting them to their default values—such as 0 for integers or floats, and an empty string (“”) for strings—while preserving the array’s dimensions, data type, and handle validity. This command is ideal for reinitializing game boards, clearing pixel grids, or preparing arrays for new data without altering their structure.

Syntax

ARM.Clear|$$ARR

Parameters
$$ARR - (Variable, maximum 5 characters) The handle of the 2D array to clear, referencing an existing array created with ARM.New.

Examples
' Example 1: Clearing a String Array (Game Board Reset)
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|2
ARM.Set|$$ARR|1|1|Value1
ARM.Set|$$ARR|2|2|Value2
ARM.Clear|$$ARR
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!|Lab_failed ' Verifies empty string (“”)
ARM.Get|$$ARR|2|2|$$VAL
JIV.$$VAL!|Lab_failed
ARM.End|$$ARR

' Example 2: Clearing an Integer Array (Matrix Reset)
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|1
ARM.Set|$$ARI|1|1|42
ARM.Set|$$ARI|2|1|17
ARM.Clear|$$ARI
ARM.Get|$$ARI|1|1|$$VAL
JIV.$$VAL!0|Lab_failed ' Verifies default integer value (0)
ARM.End|$$ARI

Remarks
- Resets all elements to their default values—0 for integers or floats, and an empty string (“”) for strings—without altering the array’s dimensions, data type, or handle validity, ensuring seamless integration with existing workflows.
- Highly useful for reinitializing game boards (e.g., clearing a chessboard between matches), resetting pixel grids in image processing, or preparing matrices for new data in scientific computing.
- Performs efficiently with linear time complexity proportional to the array size, making it suitable for both small and medium-sized arrays.
- Does not affect the array handle or its validity, allowing immediate reuse after clearing.
- For large arrays, consider performance implications due to MRL’s 1D emulation of 2D structures, though the operation remains predictable and scalable.

Limitations
- Attempting to clear an invalid or non-existent $$ARR handle results in a runtime error; use ARM.Validate to check handle validity beforehand.
- Lacks the ability to clear specific regions within the array; the command resets all elements uniformly.
- While efficient, clearing very large arrays may introduce minor delays due to the linear traversal of elements.

See Also
ARM.Fill, ARM.New, ARM.End, ARM.Validate

2. ARM.Copy

Creates a complete and independent copy of a 2D array, duplicating all elements, dimensions, and data type into a new array handle. This command is essential for creating backups, supporting parallel processing, or generating templates without modifying the original array.

Syntax

ARM.Copy|$$SRC|$$DEST

Parameters
$$SRC - (Variable, maximum 5 characters) The handle of the source 2D array to copy from, referencing an existing array created with ARM.New.
$$DEST - (Variable, maximum 5 characters) The handle of the destination 2D array to copy to, which must be a new or previously cleared handle (use ARM.End if necessary).

Examples
' Example 1: Copying an Integer Array (Backup Creation)
ARM.New|$$SRC|i
ARM.Redim|$$SRC|2|2
ARM.Set|$$SRC|1|1|1
ARM.Set|$$SRC|2|2|2
ARM.New|$$DEST|i
ARM.Copy|$$SRC|$$DEST
ARM.Get|$$DEST|1|1|$$VAL
JIV.$$VAL!1|Lab_failed
ARM.Get|$$DEST|2|2|$$VAL
JIV.$$VAL!2|Lab_failed
ARM.Set|$$SRC|1|1|99 ' Modify source, verify copy remains unchanged
ARM.Get|$$DEST|1|1|$$VAL
JIV.$$VAL!1|Lab_failed
ARM.End|$$SRC
ARM.End|$$DEST

' Example 2: Copying a String Array (Template Generation)
ARM.New|$$SRC|s
ARM.Redim|$$SRC|3|1
ARM.Set|$$SRC|1|1|Item1
ARM.Set|$$SRC|2|1|Item2
ARM.New|$$DEST|s
ARM.Copy|$$SRC|$$DEST
ARM.Get|$$DEST|2|1|$$VAL
JIV.$$VAL!Item2|Lab_failed
ARM.End|$$SRC
ARM.End|$$DEST

Remarks
- Generates an identical, independent clone, preserving all data, structure, and type, ensuring the source array remains unchanged.
- The destination handle ($$DEST) must be new or previously cleared to avoid conflicts; use ARM.End on $$DEST if it exists.
- Highly valuable for creating backups before risky operations, supporting parallel processing of array data, or generating templates for game boards, pixel grids, or matrices.
- Operates with linear time complexity proportional to the array size, making it scalable but potentially slower for very large arrays due to MRL’s 1D emulation.
- Ensures data integrity by leaving the source array untouched, ideal for maintaining state in dynamic applications.

Limitations
- Requires $$DEST to be a new or cleared handle; attempting to copy into an existing, uncleared array causes a runtime error—validate with ARM.Validate or use ARM.End first.
- Copying very large arrays may require significant memory and processing time, potentially impacting performance.
- Does not support partial copying or selective element duplication; creates a full clone only.
- Invalid or non-existent $$SRC handles trigger errors.

See Also
ARM.New, ARM.End, ARM.Get, ARM.Validate

3. ARM.Count

Returns the number of rows or columns in a 2D array, allowing developers to query its dimensions for bounds checking or loop control.

Syntax

ARM.Count|$$ARR|$$DIM|$$COUNT

Parameters
$$ARR - (Variable, maximum 5 characters) The handle of the 2D array.
$$DIM - (Variable, maximum 5 characters) Specifies dimension: 1 for rows, 2 for columns.
$$COUNT - (Variable, maximum 5 characters) Receives the count of rows or columns.

Examples
' Example 1: Counting Rows and Columns in an Integer Array
ARM.New|$$ARR|i
ARM.Redim|$$ARR|3|4
SET|$$DIM|1
ARM.Count|$$ARR|$$DIM|$$COUNT
JIV.$$COUNT!3|Lab_failed ' Rows
SET|$$DIM|2
ARM.Count|$$ARR|$$DIM|$$COUNT
JIV.$$COUNT!4|Lab_failed ' Columns
ARM.End|$$ARR

' Example 2: Counting Dimensions in a String Array
ARM.New|$$STR|s
ARM.Redim|$$STR|2|2
SET|$$DIM|1
ARM.Count|$$STR|$$DIM|$$COUNT
JIV.$$COUNT!2|Lab_failed
ARM.End|$$STR

Remarks
- Provides quick access to array dimensions for bounds checking, loop control, or validation before operations like ARM.Set or ARM.Get.
- Operates with constant-time complexity, ensuring high efficiency regardless of array size.
- Works with any valid array handle, regardless of data type (strings, integers, or floats).
- Essential for dynamic applications where array sizes may change, such as resizing game boards or matrices.
- Can be paired with ARM.GetDims for retrieving both dimensions in a single call if needed.

Limitations
- $$DIM must be 1 or 2; invalid values (e.g., 0 or 3) cause runtime errors.
- Requires a valid $$ARR handle; invalid or non-existent handles trigger errors—validate with ARM.Validate if unsure.
- Does not provide both dimensions in one call; use ARM.GetDims for that purpose.

See Also
ARM.GetDims, ARM.Redim, ARM.Resize, ARM.Validate

4. ARM.End

Destroys a specific 2D array, freeing its memory and invalidating its handle to prevent further use, ensuring efficient resource management.

Syntax

ARM.End|$$ARR

Parameters
$$ARR - (Variable, maximum 5 characters) The handle of the 2D array to destroy.

Examples
' Example 1: Ending an Integer Array
ARM.New|$$ARR|i
ARM.Redim|$$ARR|2|2
ARM.Set|$$ARR|1|1|1
ARM.End|$$ARR ' Array is destroyed
' Attempting further operations on $$ARR will fail

' Example 2: Ending a String Array After Use
ARM.New|$$STR|s
ARM.Redim|$$STR|1|1
ARM.Set|$$STR|1|1|Data
ARM.End|$$STR ' Frees memory, invalidates handle

Remarks
- Frees memory associated with the array, preventing memory leaks and ensuring resource efficiency.
- Invalidates the handle ($$ARR); subsequent use causes errors unless recreated with ARM.New.
- Use after array operations are complete to maintain clean memory usage, especially in long-running applications.
- Operates with constant-time complexity, making it highly efficient.
- Ideal for managing individual arrays in multi-array applications, such as games with multiple boards or datasets.

Limitations
- Invalid or already destroyed $$ARR handles cause runtime errors.
- No rollback or recovery option; once ended, data is permanently lost unless copied beforehand with ARM.Copy.
- Does not affect other arrays in the session; use ARM.EndAll for batch cleanup if needed.

See Also
ARM.EndAll, ARM.New, ARM.Validate, ARM.Copy

5. ARM.EndAll

Destroys all existing 2D arrays in the current MRL session, freeing their memory and invalidating all array handles to ensure comprehensive resource cleanup.

Syntax

ARM.EndAll

Parameters
None.

Remarks
- Cleans up all array resources in a single command, ideal for session cleanup or terminating an application.
- Invalidates all array handles; new arrays must be created with ARM.New.
- Use cautiously, as all data in existing arrays is lost permanently—consider using ARM.Copy for backups if needed.
- Efficient for batch cleanup, with linear complexity based on the total size of all arrays.
- Perfect for resource management in complex applications with multiple arrays, such as games or data analysis tools.

Limitations
- No selective ending; destroys all arrays in the session without exception.
- Cannot be undone; ensure critical data is backed up before use.
- May introduce minor delays for sessions with many large arrays due to cumulative memory freeing.

See Also
ARM.End, ARM.New, ARM.Validate, ARM.Copy

6. ARM.GetDims

Retrieves both the number of rows and columns in a 2D array, storing them in separate variables for convenient access and dimension management.

Syntax

ARM.GetDims|$$ARR|$$ROWS|$$COLS

Parameters
$$ARR - (Variable, maximum 5 characters) The handle of the 2D array.
$$ROWS - (Variable, maximum 5 characters) Receives the number of rows.
$$COLS - (Variable, maximum 5 characters) Receives the number of columns.

Examples
' Example 1: Getting Array Dimensions for an Integer Array
ARM.New|$$ARR|i
ARM.Redim|$$ARR|3|4
ARM.GetDims|$$ARR|$$ROWS|$$COLS
JIV.$$ROWS!3|Lab_failed
JIV.$$COLS!4|Lab_failed
ARM.End|$$ARR

' Example 2: Retrieving Dimensions for a Float Array
ARM.New|$$FLT|f
ARM.Redim|$$FLT|2|3
ARM.GetDims|$$FLT|$$ROWS|$$COLS
JIV.$$ROWS!2|Lab_failed
ARM.End|$$FLT

Remarks
- Provides both dimensions in a single, efficient call, more convenient than using ARM.Count twice.
- Operates with constant-time complexity, ensuring high performance regardless of array size.
- Useful for validating array sizes before operations, managing loops, or resizing dynamically (e.g., in game boards or matrices).
- Works with any valid array handle, independent of data type (strings, integers, or floats).
- Can be paired with ARM.Validate to ensure the handle is active before querying.

Limitations
- Requires a valid $$ARR handle; invalid or non-existent handles cause errors—use ARM.Validate if unsure.
- Does not provide dimension-specific counts individually; use ARM.Count for that purpose if needed.
- No option to query only one dimension in this call, though ARM.Count can serve that role.

See Also
ARM.Count, ARM.Redim, ARM.Resize, ARM.Validate

7. ARM.GetType

Retrieves the data type of a 2D array (strings “s”, integers “i”, or floats “f”), enabling type validation before performing type-specific operations.

Syntax

ARM.GetType|$$ARR|$$TYPE

Parameters
$$ARR - (Variable, maximum 5 characters) The handle of the 2D array.
$$TYPE - (Variable, maximum 5 characters) Receives the type as “s”, “i”, or “f”.

Remarks
- Essential for type checking before performing type-specific operations, such as numeric calculations with ARM.Sum or string manipulations.
- Operates with constant-time complexity, ensuring high efficiency.
- Returns one of “s”, “i”, or “f” as a single-character string, enabling robust error handling.
- Useful for debugging, validating array compatibility, or ensuring correct data handling in dynamic applications.
- Can be paired with ARM.Validate to confirm the handle is active before querying.

Limitations
- Requires a valid $$ARR handle; invalid or non-existent handles cause errors—use ARM.Validate if unsure.
- Does not allow changing the array type after creation; use ARM.New to create a new array with a different type.
- Returns only the current type; no historical or dynamic type tracking.

See Also
ARM.New, ARM.Sum, ARM.Validate, ARM.Set

8. ARM.New

Creates a new 2D array with a specified data type, initializing it with default dimensions (1x1) or custom dimensions if provided, serving as the foundation for all array operations in MRL.

Syntax

ARM.New|$$ARR|$$TYPE|$$ROWS|$$COLS

Parameters
$$ARR - (Variable, maximum 5 characters) The handle for the new array.
$$TYPE - (String, maximum 1 character) Data type: “s” for strings, “i” for integers, “f” for floats.
$$ROWS - (Variable, maximum 5 characters, optional) Number of rows (defaults to 1).
$$COLS - (Variable, maximum 5 characters, optional) Number of columns (defaults to 1).

Examples
' Example 1: Creating a Default Integer Array
ARM.New|$$ARR|i
ARM.Count|$$ARR|1|$$ROWS
JIV.$$ROWS!1|Lab_failed
ARM.Count|$$ARR|2|$$COLS
JIV.$$COLS!1|Lab_failed
ARM.End|$$ARR

' Example 2: Creating a 2x3 String Array
SET|$$ROWS|2
SET|$$COLS|3
ARM.New|$$ARR|s|$$ROWS|$$COLS
ARM.Count|$$ARR|1|$$ROWS
JIV.$$ROWS!2|Lab_failed
ARM.Count|$$ARR|2|$$COLS
JIV.$$COLS!3|Lab_failed
ARM.End|$$ARR

Remarks
- Initializes a new array with default values (0 for integers/floats, empty string for strings) based on the specified type.
- Required as the first step before any other ARM operations; establishes the array handle for subsequent commands.
- Optional dimensions allow immediate sizing; use ARM.Redim or ARM.Resize to adjust later if needed.
- Operates with linear time complexity for initialization, scalable with array size.
- Essential for setting up game boards, pixel grids, or matrices in MRL applications.

Limitations
- $$ARR must not already exist; attempting to reuse an active handle causes errors—use ARM.End or ARM.EndAll if reusing handles.
- Invalid $$TYPE (not “s”, “i”, or “f”) results in runtime errors.
- Large initial dimensions may consume significant memory, potentially impacting performance—optimize for smaller initial sizes if possible.

See Also
ARM.Redim, ARM.Resize, ARM.End, ARM.GetType

9. ARM.Redim

Redefines the dimensions (rows and columns) of an existing 2D array, resizing it while preserving existing data where possible, offering a flexible way to adjust array structure.

Syntax

ARM.Redim|$$ARR|$$ROWS|$$COLS

Parameters
$$ARR - (Variable, maximum 5 characters) The handle of the 2D array to resize.
$$ROWS - (Variable, maximum 5 characters) New number of rows.
$$COLS - (Variable, maximum 5 characters) New number of columns.

Examples
' Example 1: Redimensioning a String Array (Expanding a Game Board)
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|2
ARM.Set|$$ARR|1|1|Data
ARM.Redim|$$ARR|3|3 ' Expands, preserving existing data
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!Data|Lab_failed
ARM.Count|$$ARR|1|$$ROWS
JIV.$$ROWS!3|Lab_failed
ARM.End|$$ARR

' Example 2: Shrinking an Integer Array
ARM.New|$$ARI|i
ARM.Redim|$$ARI|3|2
ARM.Set|$$ARI|1|1|1
ARM.Redim|$$ARI|2|1 ' Shrinks, preserving overlapping data
ARM.Get|$$ARI|1|1|$$VAL
JIV.$$VAL!1|Lab_failed
ARM.End|$$ARI

Remarks
- Preserves existing data in the overlapping region; new elements are initialized to defaults (0, empty string, or 0.0) based on type.
- Useful for dynamically adjusting game boards, pixel grids, or matrices during runtime to accommodate changing data needs.
- Operates with linear time complexity based on array size, with potential delays for large changes due to data shifting.
- Does not change the array’s data type; use ARM.New to create an array with a different type.
- Can be combined with ARM.Count or ARM.GetDims to verify new dimensions.

Limitations
- Requires a valid $$ARR handle; invalid handles cause errors—validate with ARM.Validate if unsure.
- Large changes in dimensions may impact performance due to data shifting and reallocation.
- No option to change the data type; use ARM.New for a new type.
- Data outside the overlapping region is lost when shrinking; ensure backups with ARM.Copy if needed.

See Also
ARM.New, ARM.Resize, ARM.Count, ARM.Copy

10. ARM.Resize

Resizes a 2D array, adjusting its dimensions (rows and columns) while optionally preserving existing data within the overlapping region, offering fine-grained control over array structure.

Syntax

ARM.Resize|$$ARR|$$ROWS|$$COLS|$$PRESERVE

Parameters
$$ARR - (Variable, maximum 5 characters) The handle of the 2D array to resize.
$$ROWS - (Variable, maximum 5 characters

10. ARM.Sum

Calculates the sum of all elements in a numeric 2D array (integers or floats), useful for aggregate computations.

Syntax

ARM.Sum|$$ARR|$$SUM

Parameters
$$ARR - (Variable, max 5 characters) The handle of the numeric 2D array.
$$SUM - (Variable, max 5 characters) Receives the total sum.

Examples
' Example 1: Summing an Integer Array
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|2
ARM.Set|$$ARI|1|1|1
ARM.Set|$$ARI|1|2|2
ARM.Set|$$ARI|2|1|3
ARM.Set|$$ARI|2|2|4
ARM.Sum|$$ARI|$$SUM
JIV.$$SUM!10|Lab_failed
ARM.End|$$ARI

' Example 2: Summing a Float Array
ARM.New|$$ARF|f
ARM.Redim|$$ARF|2|1
ARM.Set|$$ARF|1|1|1.5
ARM.Set|$$ARF|2|1|2.5
ARM.Sum|$$ARF|$$SUM
JIV.$$SUM!4.0|Lab_failed
ARM.End|$$ARF

Remarks
- Computes the total sum across all elements; linear time complexity.
- Applicable only to numeric arrays (“i” or “f”); string arrays cause errors.
- Useful for totaling scores, pixel intensities, or matrix values.
- $$SUM inherits the array’s numeric type (integer or float).
- Empty arrays return 0.

Limitations
- Fails on string arrays; use ARM.GetType to validate type first.
- No range-based summing; sums the entire array (use ARM.SumRow for rows).

See Also
ARM.SumRow, ARM.GetType, ARM.Set

11. ARM.SumRow

Calculates the sum of all elements in a specified row of a numeric 2D array, providing row-level aggregation.

Syntax

ARM.SumRow|$$ARR|$$ROW|$$SUM

Parameters
$$ARR - (Variable, max 5 characters) The handle of the numeric 2D array.
$$ROW - (Variable, max 5 characters) 1-based row index to sum.
$$SUM - (Variable, max 5 characters) Receives the row sum.

Examples
' Example 1: Summing Row 1 in an Integer Array
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|3
ARM.Set|$$ARI|1|1|1
ARM.Set|$$ARI|1|2|2
ARM.Set|$$ARI|1|3|3
ARM.Set|$$ARI|2|1|4
ARM.Set|$$ARI|2|2|5
ARM.Set|$$ARI|2|3|6
SET|$$ROW|1
ARM.SumRow|$$ARI|$$ROW|$$SUM
JIV.$$SUM!6|Lab_failed
ARM.End|$$ARI

' Example 2: Summing Row 2 in a Float Array
ARM.New|$$ARF|f
ARM.Redim|$$ARF|2|2
ARM.Set|$$ARF|1|1|1.5
ARM.Set|$$ARF|1|2|2.5
ARM.Set|$$ARF|2|1|3.5
ARM.Set|$$ARF|2|2|4.5
SET|$$ROW|2
ARM.SumRow|$$ARF|$$ROW|$$SUM
JIV.$$SUM!8.0|Lab_failed
ARM.End|$$ARF

Remarks
- Computes the sum of all elements in the specified row; linear time complexity per row.
- Applicable only to numeric arrays (“i” or “f”); string arrays cause errors.
- Useful for row-wise totals in games (e.g., score sums), image processing (pixel intensity), or matrix analysis.
- $$SUM inherits the array’s numeric type (integer or float).
- Empty rows return 0.

Limitations
- Fails on string arrays; use ARM.GetType to validate type first.
- $$ROW must be within bounds; out-of-bounds values cause errors.
- No column-wise summing; use ARM.Sum for the entire array if needed.

See Also
ARM.Sum, ARM.GetType, ARM.Count

12. ARM.Swap

Swaps the values at two specified positions (row, column) in a 2D array, allowing for dynamic reordering of elements.

Syntax

ARM.Swap|$$ARR|$$ROW1|$$COL1|$$ROW2|$$COL2

Parameters
$$ARR - (Variable, max 5 characters) The handle of the 2D array.
$$ROW1 - (Variable, max 5 characters) 1-based row index of the first position.
$$COL1 - (Variable, max 5 characters) 1-based column index of the first position.
$$ROW2 - (Variable, max 5 characters) 1-based row index of the second position.
$$COL2 - (Variable, max 5 characters) 1-based column index of the second position.

Examples
' Example 1: Swapping Values in an Integer Array
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|2
ARM.Set|$$ARI|1|1|1
ARM.Set|$$ARI|1|2|2
ARM.Set|$$ARI|2|1|3
ARM.Set|$$ARI|2|2|4
SET|$$ROW1|1
SET|$$COL1|1
SET|$$ROW2|2
SET|$$COL2|2
ARM.Swap|$$ARI|$$ROW1|$$COL1|$$ROW2|$$COL2
ARM.Get|$$ARI|1|1|$$VAL
JIV.$$VAL!4|Lab_failed
ARM.Get|$$ARI|2|2|$$VAL
JIV.$$VAL!1|Lab_failed
ARM.End|$$ARI

' Example 2: Swapping Strings in a Game Board
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|2
ARM.Set|$$ARR|1|1|King
ARM.Set|$$ARR|1|2|Queen
ARM.Set|$$ARR|2|1|Pawn
ARM.Set|$$ARR|2|2|Bishop
SET|$$ROW1|1
SET|$$COL1|1
SET|$$ROW2|2
SET|$$COL2|2
ARM.Swap|$$ARR|$$ROW1|$$COL1|$$ROW2|$$COL2
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!Bishop|Lab_failed
ARM.Get|$$ARR|2|2|$$VAL
JIV.$$VAL!King|Lab_failed
ARM.End|$$ARR

Remarks
- Exchanges values at the two specified positions; constant-time operation.
- Useful for reordering game pieces, swapping pixel values, or rearranging matrix elements.
- Preserves data type; both positions must be valid and within array bounds.
- Often used in puzzle games or data reorganization tasks.
- No type conversion; values must match the array’s data type.

Limitations
- Out-of-bounds indices ($$ROW1, $$COL1, $$ROW2, $$COL2) cause errors.
- Swaps only two positions at a time; no support for multiple swaps or ranges.
- Type mismatches are not handled; ensure both positions are valid for the array’s type.

See Also
ARM.Get, ARM.Set, ARM.Count

13. ARM.Transpose

Transposes a 2D array, swapping rows and columns to create a new grid where rows become columns and columns become rows, preserving all element values.

Syntax

ARM.Transpose|$$ARR

Parameters
$$ARR - (Variable, max 5 characters) The handle of the 2D array to transpose.

Examples
' Example 1: Transposing a 2x3 Integer Array to 3x2
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|3
ARM.Set|$$ARI|1|1|1
ARM.Set|$$ARI|1|2|2
ARM.Set|$$ARI|1|3|3
ARM.Set|$$ARI|2|1|4
ARM.Set|$$ARI|2|2|5
ARM.Set|$$ARI|2|3|6
ARM.Transpose|$$ARI
ARM.Count|$$ARI|1|$$ROW
JIV.$$ROW!3|Lab_failed
ARM.Count|$$ARI|2|$$COL
JIV.$$COL!2|Lab_failed
ARM.Get|$$ARI|1|1|$$VAL
JIV.$$VAL!1|Lab_failed ' [1,1] stays [1,1] in transposed
ARM.Get|$$ARI|2|1|$$VAL
JIV.$$VAL!4|Lab_failed ' [2,1] moves to [2,1]
ARM.End|$$ARI

' Example 2: Transposing a String Array
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|2
ARM.Set|$$ARR|1|1|A
ARM.Set|$$ARR|1|2|B
ARM.Set|$$ARR|2|1|C
ARM.Set|$$ARR|2|2|D
ARM.Transpose|$$ARR
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!A|Lab_failed
ARM.Get|$$ARR|2|1|$$VAL
JIV.$$VAL!C|Lab_failed
ARM.End|$$ARR

Remarks
- Swaps rows and columns in-place, transforming an RxC array into a CxR array.
- Preserves all element values and data type, only reorienting their positions.
- Useful for matrix operations, image processing (e.g., rotating pixel grids), or reorienting game boards.
- Operation is efficient, with linear complexity proportional to array size.
- Can be combined with ARM.Rotate for additional transformations.

Limitations
- Modifies the array in-place; no option to create a copy.
- Large arrays may experience performance delays due to element reordering.
- No support for partial transposition or custom row/column mappings.

See Also
ARM.Rotate, ARM.Reverse, ARM.Count

ARM - Array Management Commands

ARM - Array Management Commands

Array Management Commands Overview

Previous Top Next