|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > !ARM. - Multidimensional Dynamic Arrays > Array Management > ARM. - Array Operations |
MiniRobotLanguage (MRL)
ARM.Copy
Copies the contents of one two-dimensional array to another, preserving structure and data.
Intention
The ARM.Copy command duplicates the contents of a source two-dimensional (2D) array into a destination 2D array, maintaining the structure (rows and columns) and data values while preserving both arrays’ handles. This is a key command for data duplication in MiniRobotLanguage, enabling developers to create backups, duplicates, or snapshots of 2D arrays for tasks like saving a game board state (e.g., duplicating a chessboard-like grid), creating identical pixel grids for image processing, or replicating matrices for scientific computations. 2D arrays, visualized as a grid like a chessboard with rows and columns (e.g., [1,1] to [8,8]), are emulated within a one-dimensional structure in MRL, and ARM.Copy ensures exact replication, including the data type (strings, integers, or floating-point numbers). It’s particularly useful in applications requiring data preservation, such as games, image editing, or data analysis, where maintaining an identical copy is critical for comparison, rollback, or parallel processing. Both source and destination arrays must have matching dimensions and data types for a successful copy; otherwise, an error occurs.
Illustration:
📋 2D Array Copying: A chessboard-like grid with handle $$ARR [A1, A2; B1, B2] (2x2) is copied to $$AR2, resulting in $$AR2 [A1, A2; B1, B2], preserving all values and structure.
🔑 Handles: Both $$ARR and $$AR2 remain valid, with identical contents and dimensions.
Syntax
ARM.Copy|$$SRC|$$DST
Parameter Explanation
P1 - $$SRC - (Variable, 5 characters max)
The handle of the source 2D array to copy from. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains unchanged after the operation.
P2 - $$DST - (Variable, 5 characters max)
The handle of the destination 2D array to copy into. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it must have the same dimensions and data type as the source array; otherwise, an error occurs. The destination array’s contents are overwritten with the source data.
Examples
'--------------------------------------------------------
' ARM.Copy - Sample 1: Copying a String Array (Game Board)
'--------------------------------------------------------
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|2
' Set values in source array
ARM.Set|$$ARR|1|1|A1
ARM.Set|$$ARR|1|2|A2
ARM.Set|$$ARR|2|1|B1
ARM.Set|$$ARR|2|2|B2
DBP.2D Array (chessboard-like) in $$ARR: [A1, A2; B1, B2] (2x2)
' Create and resize destination array
ARM.New|$$AR2|s
ARM.Redim|$$AR2|2|2
ARM.Copy|$$ARR|$$AR2
DBP.2D Array in $$AR2 after copy: [A1, A2; B1, B2] (2x2, identical to $$ARR)
' Check if $$AR2 has the same values
ARM.Get|$$AR2|1|1|$$VAL
JIV.$$VAL!A1|Lab_failed
ARM.Get|$$AR2|1|2|$$VAL
JIV.$$VAL!A2|Lab_failed
ARM.Get|$$AR2|2|1|$$VAL
JIV.$$VAL!B1|Lab_failed
ARM.Get|$$AR2|2|2|$$VAL
JIV.$$VAL!B2|Lab_failed
ARM.End|$$ARR
ARM.End|$$AR2
'
'--------------------------------------------------------
' ARM.Copy - Sample 2: Copying a Numeric Array (Matrix)
'--------------------------------------------------------
ARM.New|$$ARR|i
ARM.Redim|$$ARR|2|3
' Set values in source array
ARM.Set|$$ARR|1|1|1
ARM.Set|$$ARR|1|2|2
ARM.Set|$$ARR|1|3|3
ARM.Set|$$ARR|2|1|4
ARM.Set|$$ARR|2|2|5
ARM.Set|$$ARR|2|3|6
DBP.2D Array (matrix) in $$ARR: [1, 2, 3; 4, 5, 6] (2x3)
' Create and resize destination array
ARM.New|$$AR2|i
ARM.Redim|$$AR2|2|3
ARM.Copy|$$ARR|$$AR2
DBP.2D Array in $$AR2 after copy: [1, 2, 3; 4, 5, 6] (2x3, identical to $$ARR)
ARM.End|$$ARR
ARM.End|$$AR2
'
'--------------------------------------------------------
' ARM.Copy - Sample 3: Copying a Floating-Point Array (Image Pixel Grid) for Backup
'--------------------------------------------------------
ARM.New|$$ARR|f
ARM.Redim|$$ARR|3|2
' Set values in source array
ARM.Set|$$ARR|1|1|1.5
ARM.Set|$$ARR|1|2|-2.7
ARM.Set|$$ARR|2|1|3.14
ARM.Set|$$ARR|2|2|0.5
ARM.Set|$$ARR|3|1|-1.8
ARM.Set|$$ARR|3|2|4.2
DBP.2D Array (pixel grid) in $$ARR: [1.5, -2.7; 3.14, 0.5; -1.8, 4.2] (3x2)
' Create and resize destination array
ARM.New|$$AR2|f
ARM.Redim|$$AR2|3|2
ARM.Copy|$$ARR|$$AR2
DBP.2D Array in $$AR2 after copy: [1.5, -2.7; 3.14, 0.5; -1.8, 4.2] (3x2, identical to $$ARR)
ARM.End|$$ARR
ARM.End|$$AR2
'
Remarks
- The source and destination array handles must be stored in variables with a maximum length of 5 characters (e.g., $$ARR, $$AR2) and must be valid (created by ARM.New) before using ARM.Copy. Use ARM.Validate to ensure both handles are valid if there’s any doubt, and ARM.GetDims to verify that both arrays have identical dimensions before copying.
- The source and destination arrays must have the same dimensions and data type (strings, integers, or floating-point, as specified during ARM.New); mismatches will result in errors. Use ARM.GetType to verify data types if needed.
- Copying overwrites all existing data in the destination array, so ensure this action is intentional, especially in applications like games (backing up board states), image processing (duplicating pixel grids), or scientific computing (replicating matrices). The source array remains unchanged, as shown in the examples with verification steps.
- The performance of copying a 2D array in MRL, due to its emulation within a one-dimensional structure, is generally efficient with minimal overhead. However, for very large arrays, copying may take slightly longer, though this is typically negligible for most practical use cases, such as duplicating game boards or pixel grids.
- This command is ideal for data duplication in applications like games (saving states), image processing (creating backups of images), or scientific computing (replicating matrices for parallel processing or comparison).
Limitations
- Both array handles (source and destination) must not exceed 5 characters and must be valid; attempting to copy with an invalid handle may cause runtime errors.
- The source and destination arrays must have identical dimensions and data types; mismatches will result in errors, requiring careful setup with ARM.Redim and matching data types during ARM.New.
- Copying very large 2D arrays may introduce minor performance overhead due to the emulation in MRL, but this is typically insignificant for most applications like game boards or small matrices.
- The command assumes both handles refer to 2D arrays; using it on other data types or structures may lead to undefined behavior or errors.
See also:
• ARM.New
• ARM.Get