Mercurial > hgrepos > FreeBSD > ports > sysutils > local-bsdtools

view tests/farray-array.t @ 726:23f6d2993fa2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
farray.sh: Test the debug output and the destruction of complex objects. BUGS: No formal ownership management is done yet. It is planned to implement resource management with reference counting.
author Franz Glasner <fzglas.hg@dom66.de>
date Sun, 06 Oct 2024 16:19:45 +0200
parents 3adb26525b19
children 858f4208d9cb
line wrap: on
line source

Basic tests of farray.sh's farray_XXX functions

Shell is /bin/sh.


Setup
=====

  $ set -u
  $ . "${TESTDIR}/testsetup.sh"
  $ _p_datadir="${TESTDIR}/../share/local-bsdtools"
  $ . "${_p_datadir}/farray.sh"


Basic Creation and Destruction
==============================

Create an empty array

  $ farray_create EMPTY
  $ farray_print_length EMPTY
  0 (no-eol)
  $ farray_length _var EMPTY
  $ test ${_var} -eq 0
  $ farray_istrue EMPTY
  [1]
  $ farray_debug EMPTY
  DEBUG: array `EMPTY' has length 0
  $ farray_destroy EMPTY
  $ check_no_array_artifacts

Create and destroy an array

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'90 '
  $ farray_print_length TEST
  5 (no-eol)
  $ farray_length _var TEST
  $ test ${_var} -eq 5
  $ farray_istrue TEST
  $ farray_debug TEST
  DEBUG: array `TEST' has length 5
  DEBUG:   its contents:
  DEBUG:     1: `0'
  DEBUG:     2: `1'
  DEBUG:     3: `2'
  DEBUG:     4: `3  4   5'
  DEBUG:     5: `" 678" \'90 '
#  $ farray_debug "$TEST"
#  DEBUG: array with token `[a-f0-9]+' has length 5 (re)
#  DEBUG:   its contents:
#  DEBUG:     1: `0'
#  DEBUG:     2: `1'
#  DEBUG:     3: `2'
#  DEBUG:     4: `3  4   5'
#  DEBUG:     5: `" 678" \'90 '
  $ farray_destroy TEST
  $ check_no_array_artifacts

Create, clear and destroy an array

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'90 '
  $ farray_istrue TEST
  $ farray_print_length TEST
  5 (no-eol)
  $ farray_length _var TEST
  $ test ${_var} -eq 5
  $ farray_debug TEST
  DEBUG: array `TEST' has length 5
  DEBUG:   its contents:
  DEBUG:     1: `0'
  DEBUG:     2: `1'
  DEBUG:     3: `2'
  DEBUG:     4: `3  4   5'
  DEBUG:     5: `" 678" \'90 '
  $ farray_clear TEST
  $ farray_istrue TEST
  [1]
  $ farray_print_length TEST
  0 (no-eol)
  $ farray_length _var TEST
  $ test ${_var} -eq 0
  $ farray_destroy TEST
  $ farray_istrue TEST
  ERROR: object `TEST' not created properly: token empty
  [1]
  $ check_no_array_artifacts

Duplicate destruction

  $ farray_create TEST 1 2 3
  $ farray_destroy TEST
  $ farray_destroy TEST
  ERROR: object `TEST' not created properly: token empty
  [1]
  $ check_no_array_artifacts


Equality
========

Equality (empty)

  $ farray_create TEST1
  $ farray_create TEST2
  $ farray_are_equal TEST1 TEST2
  $ farray_destroy TEST1
  $ farray_destroy TEST2
  $ check_no_array_artifacts

Equality (non-empty)

  $ farray_create TEST1 0 1 2 '3  4   5' $'" 678" \\\'90 '
  $ farray_create TEST2 0 1 2 '3  4   5' $'" 678" \\\'90 '
  $ farray_are_equal TEST1 TEST2
  $ farray_destroy TEST1
  $ farray_destroy TEST2
  $ check_no_array_artifacts

In-Equality (non-empty, same length)

  $ farray_create TEST1 0 1 2 '3  4   5' $'" 678" \\\'90 '
  $ farray_create TEST2 0 1 2 '3  4   5' $'" 678" \\\'90'
  $ farray_are_equal TEST1 TEST2
  [1]
  $ farray_destroy TEST1
  $ farray_destroy TEST2
  $ check_no_array_artifacts

In-Equality (non-empty, different length)

  $ farray_create TEST1 0 1 2 '3  4   5' $'" 678" \\\'90 '
  $ farray_create TEST2   1 2 '3  4   5' $'" 678" \\\'90 '
  $ farray_are_equal TEST1 TEST2
  [1]
  $ farray_destroy TEST1
  $ farray_destroy TEST2
  $ check_no_array_artifacts


Get
===

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11

  $ farray_get _var TEST 1
  $ echo $_var
  0
  $ farray_tryget _var TEST 1
  $ echo $_var
  0
  $ farray_get _var TEST -5
  $ echo $_var
  0
  $ farray_tryget _var TEST -5
  $ echo $_var
  0
  $ farray_get _var TEST 6
  $ echo $_var
  11
  $ farray_tryget _var TEST 6
  $ echo $_var
  11
  $ farray_get _var TEST 0
  $ echo $_var
  11
  $ farray_tryget _var TEST 0
  $ echo $_var
  11
  $ farray_get _var TEST 5
  $ echo $_var
  " 678" \'910
  $ farray_tryget _var TEST 5
  $ echo $_var
  " 678" \'910
  $ farray_get _var TEST -1
  $ echo $_var
  " 678" \'910
  $ farray_tryget _var TEST -1
  $ echo $_var
  " 678" \'910

  $ farray_tryget _var TEST -6
  [1]
  $ ( farray_get _var TEST -6 )
  ERROR: array index out of bounds
  [70]
  $ farray_tryget _var TEST 7
  [1]
  $ ( farray_get _var TEST 7 )
  ERROR: array index out of bounds
  [70]

  $ farray_destroy TEST
  $ check_no_array_artifacts


Deleting
========

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
  $ farray_del TEST 1
  $ farray_debug TEST
  DEBUG: array `TEST' has length 5
  DEBUG:   its contents:
  DEBUG:     1: `1'
  DEBUG:     2: `2'
  DEBUG:     3: `3  4   5'
  DEBUG:     4: `" 678" \'910 '
  DEBUG:     5: `11'
  $ farray_destroy TEST
  $ check_no_array_artifacts

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
  $ farray_del TEST 0
  $ farray_debug TEST
  DEBUG: array `TEST' has length 5
  DEBUG:   its contents:
  DEBUG:     1: `0'
  DEBUG:     2: `1'
  DEBUG:     3: `2'
  DEBUG:     4: `3  4   5'
  DEBUG:     5: `" 678" \'910 '
  $ farray_destroy TEST
  $ check_no_array_artifacts

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
  $ farray_del TEST 4
  $ farray_debug TEST
  DEBUG: array `TEST' has length 5
  DEBUG:   its contents:
  DEBUG:     1: `0'
  DEBUG:     2: `1'
  DEBUG:     3: `2'
  DEBUG:     4: `" 678" \'910 '
  DEBUG:     5: `11'
  $ farray_destroy TEST
  $ check_no_array_artifacts

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
  $ ( farray_del TEST "" )
  ERROR: array index out of bounds
  [70]

  $ farray_destroy TEST
  $ check_no_array_artifacts

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
  $ ( farray_del TEST 7 )
  ERROR: array index out of bounds
  [70]

  $ farray_destroy TEST
  $ check_no_array_artifacts


Setting
=======

Append (relative)

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
  $ farray_set TEST "" $'the new value \\ \''
  $ farray_debug TEST
  DEBUG: array `TEST' has length 7
  DEBUG:   its contents:
  DEBUG:     1: `0'
  DEBUG:     2: `1'
  DEBUG:     3: `2'
  DEBUG:     4: `3  4   5'
  DEBUG:     5: `" 678" \'910 '
  DEBUG:     6: `11'
  DEBUG:     7: `the new value \ ''
  $ farray_destroy TEST
  $ check_no_array_artifacts

Append (explicit)

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
  $ farray_set TEST 7 $'the new value \\ \''
  $ farray_debug TEST
  DEBUG: array `TEST' has length 7
  DEBUG:   its contents:
  DEBUG:     1: `0'
  DEBUG:     2: `1'
  DEBUG:     3: `2'
  DEBUG:     4: `3  4   5'
  DEBUG:     5: `" 678" \'910 '
  DEBUG:     6: `11'
  DEBUG:     7: `the new value \ ''
  $ farray_destroy TEST
  $ check_no_array_artifacts

Replace the last element

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
  $ farray_set TEST 0 $'the new replaced value \\ \''
  $ farray_debug TEST
  DEBUG: array `TEST' has length 6
  DEBUG:   its contents:
  DEBUG:     1: `0'
  DEBUG:     2: `1'
  DEBUG:     3: `2'
  DEBUG:     4: `3  4   5'
  DEBUG:     5: `" 678" \'910 '
  DEBUG:     6: `the new replaced value \ ''
  $ farray_destroy TEST
  $ check_no_array_artifacts

Replace the first element

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
  $ farray_set TEST 1 $'the new replaced value \\ \''
  $ farray_debug TEST
  DEBUG: array `TEST' has length 6
  DEBUG:   its contents:
  DEBUG:     1: `the new replaced value \ ''
  DEBUG:     2: `1'
  DEBUG:     3: `2'
  DEBUG:     4: `3  4   5'
  DEBUG:     5: `" 678" \'910 '
  DEBUG:     6: `11'
  $ farray_destroy TEST
  $ check_no_array_artifacts

Replace some element in the middle

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
  $ farray_set TEST 5 $'the new replaced value \\ \' 2 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 6
  DEBUG:   its contents:
  DEBUG:     1: `0'
  DEBUG:     2: `1'
  DEBUG:     3: `2'
  DEBUG:     4: `3  4   5'
  DEBUG:     5: `the new replaced value \ ' 2 '
  DEBUG:     6: `11'
  $ farray_destroy TEST
  $ check_no_array_artifacts

Out of bounds

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11
  $ ( farray_set TEST 8 )
  ERROR: array index out of bounds (cannot create holes)
  [70]
  $ farray_destroy TEST
  $ check_no_array_artifacts


Splicing
========

Replace complete array

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 1 ""  INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 9
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` v 4 '
  DEBUG:     5: ` v 5 '
  DEBUG:     6: ` v 6 '
  DEBUG:     7: ` v 7 '
  DEBUG:     8: ` v 8 '
  DEBUG:     9: ` v 9 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 3
  DEBUG:   its contents:
  DEBUG:     1: ` I 1 '
  DEBUG:     2: ` I 2 '
  DEBUG:     3: ` I 3 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Insert at the beginning (prepend)

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 1 0  INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 0
  $ farray_debug TEST
  DEBUG: array `TEST' has length 12
  DEBUG:   its contents:
  DEBUG:     1: ` I 1 '
  DEBUG:     2: ` I 2 '
  DEBUG:     3: ` I 3 '
  DEBUG:     4: ` v 1 '
  DEBUG:     5: ` v 2 '
  DEBUG:     6: ` v 3 '
  DEBUG:     7: ` v 4 '
  DEBUG:     8: ` v 5 '
  DEBUG:     9: ` v 6 '
  DEBUG:     10: ` v 7 '
  DEBUG:     11: ` v 8 '
  DEBUG:     12: ` v 9 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Insert at the end (extend)

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST "" 0  INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 0
  $ farray_debug TEST
  DEBUG: array `TEST' has length 12
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` v 4 '
  DEBUG:     5: ` v 5 '
  DEBUG:     6: ` v 6 '
  DEBUG:     7: ` v 7 '
  DEBUG:     8: ` v 8 '
  DEBUG:     9: ` v 9 '
  DEBUG:     10: ` I 1 '
  DEBUG:     11: ` I 2 '
  DEBUG:     12: ` I 3 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Insert in the middle

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 4 0  INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 0
  $ farray_debug TEST
  DEBUG: array `TEST' has length 12
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` I 1 '
  DEBUG:     5: ` I 2 '
  DEBUG:     6: ` I 3 '
  DEBUG:     7: ` v 4 '
  DEBUG:     8: ` v 5 '
  DEBUG:     9: ` v 6 '
  DEBUG:     10: ` v 7 '
  DEBUG:     11: ` v 8 '
  DEBUG:     12: ` v 9 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

"Clear" (empty inserted)

  $ farray_create DELETED
  $ farray_create INSERTED
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 1 "" INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 9
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` v 4 '
  DEBUG:     5: ` v 5 '
  DEBUG:     6: ` v 6 '
  DEBUG:     7: ` v 7 '
  DEBUG:     8: ` v 8 '
  DEBUG:     9: ` v 9 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 0
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

"Clear" (no inserted)

  $ farray_create DELETED
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 1 ""
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 9
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` v 4 '
  DEBUG:     5: ` v 5 '
  DEBUG:     6: ` v 6 '
  DEBUG:     7: ` v 7 '
  DEBUG:     8: ` v 8 '
  DEBUG:     9: ` v 9 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 0
  $ farray_destroy DELETED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Cut out some part in the middle

  $ farray_create DELETED
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 2 5
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 5
  DEBUG:   its contents:
  DEBUG:     1: ` v 2 '
  DEBUG:     2: ` v 3 '
  DEBUG:     3: ` v 4 '
  DEBUG:     4: ` v 5 '
  DEBUG:     5: ` v 6 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 4
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 7 '
  DEBUG:     3: ` v 8 '
  DEBUG:     4: ` v 9 '
  $ farray_destroy DELETED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Cut out some part from the beginning

  $ farray_create DELETED
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 1 6
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 6
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` v 4 '
  DEBUG:     5: ` v 5 '
  DEBUG:     6: ` v 6 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 3
  DEBUG:   its contents:
  DEBUG:     1: ` v 7 '
  DEBUG:     2: ` v 8 '
  DEBUG:     3: ` v 9 '
  $ farray_destroy DELETED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Cut out some part at the end (1)

  $ farray_create DELETED
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 0 1
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 1
  DEBUG:   its contents:
  DEBUG:     1: ` v 9 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 8
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` v 4 '
  DEBUG:     5: ` v 5 '
  DEBUG:     6: ` v 6 '
  DEBUG:     7: ` v 7 '
  DEBUG:     8: ` v 8 '
  $ farray_destroy DELETED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Cut out some part at the end (1)

  $ farray_create DELETED
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST -1 ""
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 2
  DEBUG:   its contents:
  DEBUG:     1: ` v 8 '
  DEBUG:     2: ` v 9 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 7
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` v 4 '
  DEBUG:     5: ` v 5 '
  DEBUG:     6: ` v 6 '
  DEBUG:     7: ` v 7 '
  $ farray_destroy DELETED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Splice at the beginning (shrink)

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 1 4  INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 4
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` v 4 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 8
  DEBUG:   its contents:
  DEBUG:     1: ` I 1 '
  DEBUG:     2: ` I 2 '
  DEBUG:     3: ` I 3 '
  DEBUG:     4: ` v 5 '
  DEBUG:     5: ` v 6 '
  DEBUG:     6: ` v 7 '
  DEBUG:     7: ` v 8 '
  DEBUG:     8: ` v 9 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Splice at the end (shrink)

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST -3 4  INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 4
  DEBUG:   its contents:
  DEBUG:     1: ` v 6 '
  DEBUG:     2: ` v 7 '
  DEBUG:     3: ` v 8 '
  DEBUG:     4: ` v 9 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 8
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` v 4 '
  DEBUG:     5: ` v 5 '
  DEBUG:     6: ` I 1 '
  DEBUG:     7: ` I 2 '
  DEBUG:     8: ` I 3 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Splice in the middle (shrink)

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 3 4  INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 4
  DEBUG:   its contents:
  DEBUG:     1: ` v 3 '
  DEBUG:     2: ` v 4 '
  DEBUG:     3: ` v 5 '
  DEBUG:     4: ` v 6 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 8
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` I 1 '
  DEBUG:     4: ` I 2 '
  DEBUG:     5: ` I 3 '
  DEBUG:     6: ` v 7 '
  DEBUG:     7: ` v 8 '
  DEBUG:     8: ` v 9 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Splice at the beginning (grow)

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 1 2  INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 2
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 10
  DEBUG:   its contents:
  DEBUG:     1: ` I 1 '
  DEBUG:     2: ` I 2 '
  DEBUG:     3: ` I 3 '
  DEBUG:     4: ` v 3 '
  DEBUG:     5: ` v 4 '
  DEBUG:     6: ` v 5 '
  DEBUG:     7: ` v 6 '
  DEBUG:     8: ` v 7 '
  DEBUG:     9: ` v 8 '
  DEBUG:     10: ` v 9 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Splice at the end (grow)

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST -1 2  INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 2
  DEBUG:   its contents:
  DEBUG:     1: ` v 8 '
  DEBUG:     2: ` v 9 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 10
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` v 4 '
  DEBUG:     5: ` v 5 '
  DEBUG:     6: ` v 6 '
  DEBUG:     7: ` v 7 '
  DEBUG:     8: ` I 1 '
  DEBUG:     9: ` I 2 '
  DEBUG:     10: ` I 3 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Splice in the middle (grow)

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 3 2  INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 2
  DEBUG:   its contents:
  DEBUG:     1: ` v 3 '
  DEBUG:     2: ` v 4 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 10
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` I 1 '
  DEBUG:     4: ` I 2 '
  DEBUG:     5: ` I 3 '
  DEBUG:     6: ` v 5 '
  DEBUG:     7: ` v 6 '
  DEBUG:     8: ` v 7 '
  DEBUG:     9: ` v 8 '
  DEBUG:     10: ` v 9 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Splice at the beginning (no length change)

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 1 3 INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 3
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 9
  DEBUG:   its contents:
  DEBUG:     1: ` I 1 '
  DEBUG:     2: ` I 2 '
  DEBUG:     3: ` I 3 '
  DEBUG:     4: ` v 4 '
  DEBUG:     5: ` v 5 '
  DEBUG:     6: ` v 6 '
  DEBUG:     7: ` v 7 '
  DEBUG:     8: ` v 8 '
  DEBUG:     9: ` v 9 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Splice at the end (no length change)

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST -2 3 INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 3
  DEBUG:   its contents:
  DEBUG:     1: ` v 7 '
  DEBUG:     2: ` v 8 '
  DEBUG:     3: ` v 9 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 9
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` v 4 '
  DEBUG:     5: ` v 5 '
  DEBUG:     6: ` v 6 '
  DEBUG:     7: ` I 1 '
  DEBUG:     8: ` I 2 '
  DEBUG:     9: ` I 3 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts

Splice in the middle (no length change)

  $ farray_create DELETED
  $ farray_create INSERTED  ' I 1 ' ' I 2 ' ' I 3 '
  $ farray_create TEST ' v 1 ' ' v 2 ' ' v 3 ' ' v 4 ' ' v 5 ' ' v 6 ' ' v 7 ' ' v 8 '  ' v 9 '
  $ farray_splice DELETED TEST 4 3 INSERTED
  $ farray_debug DELETED
  DEBUG: array `DELETED' has length 3
  DEBUG:   its contents:
  DEBUG:     1: ` v 4 '
  DEBUG:     2: ` v 5 '
  DEBUG:     3: ` v 6 '
  $ farray_debug TEST
  DEBUG: array `TEST' has length 9
  DEBUG:   its contents:
  DEBUG:     1: ` v 1 '
  DEBUG:     2: ` v 2 '
  DEBUG:     3: ` v 3 '
  DEBUG:     4: ` I 1 '
  DEBUG:     5: ` I 2 '
  DEBUG:     6: ` I 3 '
  DEBUG:     7: ` v 7 '
  DEBUG:     8: ` v 8 '
  DEBUG:     9: ` v 9 '
  $ farray_destroy DELETED
  $ farray_destroy INSERTED
  $ farray_destroy TEST
  $ check_no_array_artifacts


Searching
=========

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11

  $ farray_find _var TEST 0
  $ echo $_var
  1
  $ farray_find _var TEST $'" 678" \\\'910 '
  $ echo $_var
  5
  $ farray_find _var TEST '11'
  $ echo $_var
  6
  $ farray_find _var TEST $'" 678" \\\'910 ' "" ""
  $ echo $_var
  5
  $ farray_find _var TEST '11' 1 5
  [1]

  $ farray_find _var TEST '11' 7
  [1]

  $ farray_find _var TEST '11' 7 6
  [1]

  $ farray_find _var TEST '11' 1 ""
  $ echo $_var
  6

  $ ( farray_find _var TEST '11' 1 7 )
  ERROR: end index exceeds array length
  [70]

  $ ( farray_find _var TEST '11' -6 )
  ERROR: start index must be >= 1
  [70]

  $ ( farray_find _var TEST '11' 1 -6 )
  ERROR: end index must be >= 1
  [70]

  $ farray_contains TEST '0'
  $ farray_contains TEST $'" 678" \\\'910 '
  $ farray_contains TEST '11'

  $ farray_contains TEST '0 '
  [1]

  $ farray_destroy TEST
  $ check_no_array_artifacts


Iterating
=========

  $ farray_create TEST 0 1 2 '3  4   5' $'" 667788" \\\'910 ' 11

MANUAL (by name)

  $ _v=''
  > _i=1
  > while farray_tryget _v TEST ${_i}; do
  >     printf "  IDX: \`%d', VAL: \`%s'\\n" "${_i}" "${_v}"
  >     _i=$((_i + 1))
  > done
    IDX: `1', VAL: `0'
    IDX: `2', VAL: `1'
    IDX: `3', VAL: `2'
    IDX: `4', VAL: `3  4   5'
    IDX: `5', VAL: `" 667788" \'910 '
    IDX: `6', VAL: `11'

MANUAL (by value, reversed, using negative indexes)

  $ _v=''
  > _i=0
  > while farray_tryget _v "$TEST" ${_i}; do
  >     printf "  IDX: \`%d', VAL: \`%s'\\n" "${_i}" "${_v}"
  >     _i=$((_i - 1))
  > done
    IDX: `0', VAL: `11'
    IDX: `-1', VAL: `" 667788" \'910 '
    IDX: `-2', VAL: `3  4   5'
    IDX: `-3', VAL: `2'
    IDX: `-4', VAL: `1'
    IDX: `-5', VAL: `0'

ITERATE (for each, by name)

  $ farray_for_each TEST $'printf "EACH: %s at idx %d: value is \\`%s\\\'\\n"'
  EACH: TEST at idx 1: value is `0'
  EACH: TEST at idx 2: value is `1'
  EACH: TEST at idx 3: value is `2'
  EACH: TEST at idx 4: value is `3  4   5'
  EACH: TEST at idx 5: value is `" 667788" \'910 '
  EACH: TEST at idx 6: value is `11'

ITERATE (for each, by value)

  $ farray_for_each "$TEST" $'printf "EACH: %s at idx %d: value is \\`%s\\\'\\n"'
  EACH: _farr_A\?:[a-f0-9]+ at idx 1: value is `0' (re)
  EACH: _farr_A\?:[a-f0-9]+ at idx 2: value is `1' (re)
  EACH: _farr_A\?:[a-f0-9]+ at idx 3: value is `2' (re)
  EACH: _farr_A\?:[a-f0-9]+ at idx 4: value is `3  4   5' (re)
  EACH: _farr_A\?:[a-f0-9]+ at idx 5: value is `" 667788" \\'910 ' (re)
  EACH: _farr_A\?:[a-f0-9]+ at idx 6: value is `11' (re)

REVERSE ITERATE (for each, by name)

  $ farray_reversed_for_each TEST $'printf "EACH: %s at idx %d: value is \\`%s\\\'\\n"'
  EACH: TEST at idx 6: value is `11'
  EACH: TEST at idx 5: value is `" 667788" \'910 '
  EACH: TEST at idx 4: value is `3  4   5'
  EACH: TEST at idx 3: value is `2'
  EACH: TEST at idx 2: value is `1'
  EACH: TEST at idx 1: value is `0'

ITERATE (for each, by value)

  $ farray_reversed_for_each "$TEST" $'printf "EACH: %s at idx %d: value is \\`%s\\\'\\n"'
  EACH: _farr_A\?:[a-f0-9]+ at idx 6: value is `11' (re)
  EACH: _farr_A\?:[a-f0-9]+ at idx 5: value is `" 667788" \\'910 ' (re)
  EACH: _farr_A\?:[a-f0-9]+ at idx 4: value is `3  4   5' (re)
  EACH: _farr_A\?:[a-f0-9]+ at idx 3: value is `2' (re)
  EACH: _farr_A\?:[a-f0-9]+ at idx 2: value is `1' (re)
  EACH: _farr_A\?:[a-f0-9]+ at idx 1: value is `0' (re)

  $ farray_destroy TEST
  $ check_no_array_artifacts


Eval / Quoting
==============

# Use Dollar-Single-Quotes
  $ _var1=$'" 678" \\\'910 '
# Use just Single-Quotes
  $ _var2='" 678" \'\''910 '
# Use a Double-Quotes to insert a single quote
  $ _var3='" 678" \'"'"'910 '
  $ test "${_var1}" = "${_var2}"
  $ test "${_var1}" = "${_var3}"
  $ eval _evar="\$(_farr_quote_for_eval \"\${_var1}\")"
  $ eval printf '%s' "${_evar}"
  " 678" \'910  (no-eol)
  $ _var1=$'" 678" \\\'910\t\''
  $ _var2='" 678" \'\''910	'\'''
  $ _var3='" 678" \'"'"'910	'"'"''
  $ test "${_var1}" = "${_var2}"
  $ test "${_var1}" = "${_var3}"
  $ eval _evar="\$(_farr_quote_for_eval \"\${_var1}\")"
  $ eval printf '%s' "${_evar}"
  " 678" \'910	' (no-eol)
  $ _var1=$'" 678" \\\'910\t\''
  $ eval _evar="\$(_farr_quote_for_eval_strict \"\${_var1}\")"
  $ eval printf '%s' "${_evar}"
  " 678" \'910	' (no-eol)


Join
====

  $ farray_create TEST 0 1 2 '3  4   5' $'" 678" \\\'910 ' 11

  $ farray_join _var TEST
  $ echo "$_var"
  0 1 2 3  4   5 " 678" \'910  11

  $ farray_join _var TEST '---'
  $ echo "$_var"
  0---1---2---3  4   5---" 678" \'910 ---11

  $ farray_join_for_eval _var TEST
  $ echo "$_var"
  '0' '1' '2' '3  4   5' $'" 678" \\\'910 ' '11'

  $ farray_print_join_for_eval TEST
  '0' '1' '2' '3  4   5' $'" 678" \\\'910 ' '11' (no-eol)

  $ farray_clear TEST

  $ farray_join _var TEST
  $ echo "/${_var}/"
  //

  $ farray_print_join_for_eval TEST

  $ farray_join_for_eval _var TEST
  $ echo "!${_var}!"
  !!

  $ farray_join _var TEST '---'
  $ echo "/${_var}/"
  //
  $ farray_destroy TEST
  $ check_no_array_artifacts


Parameter Checks
================

  $ ( farray_create )
  ERROR: missing farray name
  [70]

  $ ( farray_append )
  ERROR: missing farray name or token value
  [70]

  $ TEST=''
  $ (farray_append TEST)
  ERROR: object `TEST' not created properly: token empty
  [70]

  $ check_no_array_artifacts

  $ farray_create DUP
  $ (farray_create DUP)
  ERROR: object `DUP' already created \(value `_farr_A\?:[a-f0-9]+'\) (re)
  [70]

  $ check_no_array_artifacts
  _farr_A_[0-9a-f]+__=0 (re)
  [1]

  $ farray_destroy DUP
  $ check_no_array_artifacts


Cross Type Checks
=================

  $ farray_create TEST
  $ (falist_set TEST key value)
  ERROR: object `TEST' is not an alist
  [70]
  $ farray_destroy TEST
  $ check_no_array_artifacts


Other Type Checks
=================

  $ farray_type
  unknown (no-eol)
  $ farray_type __UNKNOWN_VARIABLE__
  unknown (no-eol)
  $ testvar='foo'
  $ farray_type testvar
  value (no-eol)
  $ testvar=''
  $ farray_type testvar
  null (no-eol)
  $ farray_isarray testvar
  [1]
  $ farray_create TEST
  $ falist_type TEST
  array (no-eol)
  $ farray_isarray TEST
  $ farray_destroy TEST
  $ check_no_array_artifacts


Generic Destruction
===================

  $ farray_create TEST i1 i2
  $ farray_debug TEST
  DEBUG: array `TEST' has length 2
  DEBUG:   its contents:
  DEBUG:     1: `i1'
  DEBUG:     2: `i2'
  $ _farr_destroy_object "$TEST"
  $ check_no_array_artifacts
  $ (_farr_destroy_object "$TEST")
  ERROR: farray `_farr_A\?:([a-f0-9]+)' not created properly: no storage for token `\1' (re)
  [1]
  $ TEST=''
  $ _farr_destroy_object "$TEST"
  $ check_no_array_artifacts


Complex Debug
=============

  $ farray_create TEST i1 i2
  $ farray_create ITEM1 i11 i22
This also transfers ownership
  $ farray_append TEST "$ITEM1"
  $ farray_debug TEST
  DEBUG: array `TEST' has length 3
  DEBUG:   its contents:
  DEBUG:     1: `i1'
  DEBUG:     2: `i2'
  DEBUG:     3: -->
      DEBUG: array with token `[a-f0-9]+' has length 2 (re)
      DEBUG:   its contents:
      DEBUG:     1: `i11'
      DEBUG:     2: `i22'
  $ farray_destroy TEST
  $ check_no_array_artifacts