Array Utilities

Description

This example demonstrates the array utility functions for comparing and concatenating byte arrays:

arrayEqual() for comparing two arrays element-by-element
concatArrays() for joining multiple Uint8Arrays into a new array

Prerequisites

No LocalNet required

Run This Example

From the repository root:

cd examples
npm run example common/03-array-utilities.ts

Code

View source on GitHub

/**
 * Example: Array Utilities
 *
 * This example demonstrates the array utility functions for comparing and
 * concatenating byte arrays:
 * - arrayEqual() for comparing two arrays element-by-element
 * - concatArrays() for joining multiple Uint8Arrays into a new array
 *
 * Prerequisites:
 * - No LocalNet required
 */

import { arrayEqual, concatArrays } from '@algorandfoundation/algokit-utils/common'
import { formatBytes, printHeader, printInfo, printStep, printSuccess } from '../shared/utils.js'

function main() {
  printHeader('Array Utilities Example')

  // Step 1: arrayEqual() - Comparing Equal Arrays
  printStep(1, 'arrayEqual() - Comparing Equal Arrays')

  const arr1 = new Uint8Array([1, 2, 3, 4, 5])
  const arr2 = new Uint8Array([1, 2, 3, 4, 5])

  printInfo(`Array 1: ${formatBytes(arr1)}`)
  printInfo(`Array 2: ${formatBytes(arr2)}`)
  printInfo(`arrayEqual(arr1, arr2): ${arrayEqual(arr1, arr2)}`)
  printInfo(`Arrays with identical content return true`)

  // Step 2: arrayEqual() - Different Length Arrays
  printStep(2, 'arrayEqual() - Different Length Arrays')

  const shortArr = new Uint8Array([1, 2, 3])
  const longArr = new Uint8Array([1, 2, 3, 4, 5])

  printInfo(`Short array (length ${shortArr.length}): ${formatBytes(shortArr)}`)
  printInfo(`Long array (length ${longArr.length}): ${formatBytes(longArr)}`)
  printInfo(`arrayEqual(shortArr, longArr): ${arrayEqual(shortArr, longArr)}`)
  printInfo(`Different lengths return false (fast check before element comparison)`)

  // Step 3: arrayEqual() - Same Length, Different Content
  printStep(3, 'arrayEqual() - Same Length, Different Content')

  const arrA = new Uint8Array([1, 2, 3, 4, 5])
  const arrB = new Uint8Array([1, 2, 99, 4, 5]) // Different value at index 2

  printInfo(`Array A: ${formatBytes(arrA)}`)
  printInfo(`Array B: ${formatBytes(arrB)}`)
  printInfo(`arrayEqual(arrA, arrB): ${arrayEqual(arrA, arrB)}`)
  printInfo(`Same length but different content at index 2 returns false`)

  // Step 4: arrayEqual() - Edge Cases
  printStep(4, 'arrayEqual() - Edge Cases')

  // Empty arrays
  const empty1 = new Uint8Array([])
  const empty2 = new Uint8Array([])
  printInfo(`Empty arrays: arrayEqual([], []): ${arrayEqual(empty1, empty2)}`)

  // Single element
  const single1 = new Uint8Array([42])
  const single2 = new Uint8Array([42])
  printInfo(`Single element: arrayEqual([42], [42]): ${arrayEqual(single1, single2)}`)

  // Same reference
  const sameRef = new Uint8Array([1, 2, 3])
  printInfo(`Same reference: arrayEqual(arr, arr): ${arrayEqual(sameRef, sameRef)}`)

  // Step 5: concatArrays() - Joining Multiple Arrays
  printStep(5, 'concatArrays() - Joining Multiple Arrays')

  const first = new Uint8Array([1, 2, 3])
  const second = new Uint8Array([4, 5, 6])
  const third = new Uint8Array([7, 8, 9])

  printInfo(`First array: ${formatBytes(first)}`)
  printInfo(`Second array: ${formatBytes(second)}`)
  printInfo(`Third array: ${formatBytes(third)}`)

  const concatenated = concatArrays(first, second, third)
  printInfo(`\nconcatArrays(first, second, third):`)
  printInfo(`Result: ${formatBytes(concatenated)}`)
  printInfo(`Result length: ${concatenated.length} bytes`)

  // Step 6: concatArrays() - Different Sized Arrays
  printStep(6, 'concatArrays() - Different Sized Arrays')

  const tiny = new Uint8Array([1])
  const small = new Uint8Array([2, 3])
  const medium = new Uint8Array([4, 5, 6, 7])
  const large = new Uint8Array([8, 9, 10, 11, 12, 13, 14, 15])

  printInfo(`Tiny (1 byte): ${formatBytes(tiny)}`)
  printInfo(`Small (2 bytes): ${formatBytes(small)}`)
  printInfo(`Medium (4 bytes): ${formatBytes(medium)}`)
  printInfo(`Large (8 bytes): ${formatBytes(large)}`)

  const combined = concatArrays(tiny, small, medium, large)
  printInfo(`\nconcatArrays(tiny, small, medium, large):`)
  printInfo(`Result: ${formatBytes(combined)}`)
  printInfo(`Result length: ${combined.length} bytes (1 + 2 + 4 + 8 = 15)`)

  // Step 7: concatArrays() Returns New Array (Doesn't Modify Inputs)
  printStep(7, 'concatArrays() - Returns New Array (Non-Mutating)')

  const original1 = new Uint8Array([10, 20, 30])
  const original2 = new Uint8Array([40, 50, 60])

  printInfo(`Before concat:`)
  printInfo(`  original1: ${formatBytes(original1)}`)
  printInfo(`  original2: ${formatBytes(original2)}`)

  const result = concatArrays(original1, original2)

  printInfo(`\nAfter concat:`)
  printInfo(`  original1: ${formatBytes(original1)} (unchanged)`)
  printInfo(`  original2: ${formatBytes(original2)} (unchanged)`)
  printInfo(`  result: ${formatBytes(result)} (new array)`)

  // Prove they are different objects
  printInfo(`\nVerifying result is a new array:`)
  printInfo(`  result === original1: ${result === original1}`)
  printInfo(`  result === original2: ${result === original2}`)

  // Modify result and show originals are unaffected
  result[0] = 99
  printInfo(`\nAfter modifying result[0] = 99:`)
  printInfo(`  result: ${formatBytes(result)}`)
  printInfo(`  original1: ${formatBytes(original1)} (still unchanged)`)

  // Step 8: concatArrays() - Edge Cases
  printStep(8, 'concatArrays() - Edge Cases')

  // Single array
  const singleInput = new Uint8Array([1, 2, 3])
  const singleResult = concatArrays(singleInput)
  printInfo(`Single input: concatArrays([1,2,3]) = ${formatBytes(singleResult)}`)
  printInfo(`  Is new array: ${singleResult !== singleInput}`)

  // Empty arrays
  const emptyResult = concatArrays(new Uint8Array([]), new Uint8Array([1, 2]), new Uint8Array([]))
  printInfo(`With empty arrays: concatArrays([], [1,2], []) = ${formatBytes(emptyResult)}`)

  // No arguments
  const noArgs = concatArrays()
  printInfo(`No arguments: concatArrays() = ${formatBytes(noArgs)} (empty array)`)

  // Step 9: Practical Use Cases
  printStep(9, 'Practical Use Cases')

  printInfo('Common scenarios for array utilities:')

  printInfo('\n1. Comparing cryptographic hashes:')
  const hash1 = new Uint8Array([0xab, 0xcd, 0xef, 0x12])
  const hash2 = new Uint8Array([0xab, 0xcd, 0xef, 0x12])
  printInfo(`   hash1 === hash2 (reference): ${hash1 === hash2}`)
  printInfo(`   arrayEqual(hash1, hash2) (content): ${arrayEqual(hash1, hash2)}`)

  printInfo('\n2. Building transaction data:')
  const prefix = new Uint8Array([0x54, 0x58]) // "TX"
  const txData = new Uint8Array([0x01, 0x02, 0x03])
  const prefixedTx = concatArrays(prefix, txData)
  printInfo(`   Prefix + TxData: ${formatBytes(prefixedTx)}`)

  printInfo('\n3. Concatenating signature components:')
  const r = new Uint8Array([0x30, 0x31, 0x32, 0x33]) // r component
  const s = new Uint8Array([0x40, 0x41, 0x42, 0x43]) // s component
  const signature = concatArrays(r, s)
  printInfo(`   r + s = ${formatBytes(signature)}`)

  // Step 10: Summary
  printStep(10, 'Summary')

  printInfo('Array Comparison:')
  printInfo('  - arrayEqual(a, b) - Compare two arrays element-by-element')
  printInfo('  - Returns false immediately if lengths differ (efficient)')
  printInfo('  - Works with any ArrayLike<T> type')

  printInfo('\nArray Concatenation:')
  printInfo('  - concatArrays(...arrays) - Join multiple Uint8Arrays')
  printInfo('  - Returns a new Uint8Array (non-mutating)')
  printInfo('  - Works with any ArrayLike<number> type')
  printInfo('  - Handles empty arrays and single inputs gracefully')

  printSuccess('Array Utilities example completed successfully!')
}

main()

Array Utilities

Description

Prerequisites

Run This Example

Code

Other examples in Common Utilities