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

view tests/farray-array.t @ 649:4ee9a8042f4a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
common.subr: _get_jail_from_path() now just returns when the jail is dying. But it prints the name of the jail if it is yet dying. Real error reporting must not consistently be done in the caller.
author Franz Glasner <fzglas.hg@dom66.de>
date Fri, 27 Sep 2024 21:21:34 +0200
parents 2d0201f54870
children 57ee25cec0dd
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_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_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_destroy TEST
  $ check_no_array_artifacts

Create, clear 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_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_print_length TEST
  0 (no-eol)
  $ farray_length _var TEST
  $ test ${_var} -eq 0
  $ farray_destroy TEST
  $ check_no_array_artifacts

Duplicate destruction

  $ farray_create TEST 1 2 3
  $ farray_destroy TEST
  $ farray_destroy TEST
  ERROR: farray `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


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
  [70]

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

  $ check_no_array_artifacts

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

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

  $ farray_destroy DUP
  $ check_no_array_artifacts