Lack of documentation about mapfile callback

[Léa Gris]

man bash.1
> When callback is evaluated, it is supplied the index of the next 
> array element to be assigned and the line to be assigned to that 
> element as additional arguments. callback is evaluated after the
> line is read but before the array element is assigned.

I can not find real-life implementation example of the mapfile callback
that fit the implied scenario of this behavior of invoking the callback
before the last array entry is assigned.

What I figured out by experimentation, is that while the last element is
not assigned to MAPFILE as seen from the callback context, the
assignment is effective after the callback returns.

Example:

----- BEGIN BASH
#!/usr/bin/env bash

callback() {
  echo "Entering Callback"
  printf 'Next index is: %d\n' $1
  printf 'Next entry is: %q\n' "$2"
  printf 'MAPFILE size: %d\n' "${#MAPFILE[@]}"
  typeset -p MAPFILE
  echo "Exiting Callback"
}

mapfile -t -C callback -c 3 <<'EOF'
Entry0
Entry1
Entry2
Entry3
Entry4
Entry5
Entry6
Entry7
Entry8
EOF
----- END BASH

And then the output:
----- BEGIN OUTPUT
Entering Callback
Next index is: 2
Next entry is: Entry2
MAPFILE size: 2
declare -a MAPFILE=([0]="Entry0" [1]="Entry1")
Exiting Callback
Entering Callback
Next index is: 5
Next entry is: Entry5
MAPFILE size: 5
declare -a MAPFILE=([0]="Entry0" [1]="Entry1" [2]="Entry2" [3]="Entry3"
[4]="Entry4")
Exiting Callback
Entering Callback
Next index is: 8
Next entry is: Entry8
MAPFILE size: 8
declare -a MAPFILE=([0]="Entry0" [1]="Entry1" [2]="Entry2" [3]="Entry3"
[4]="Entry4" [5]="Entry5" [6]="Entry6" [7]="Entry7")
Exiting Callback
----- END OUTPUT


It reveals the weirdness of running the callback before the last
assignment from the quantum.
First call to callback has a MAPFILE with 2 entries, while the next two
have 3 entries.
There must be a reason or an intended scenario for this implementation,
but with so few documentation and no real-world usage example, it is
unclear to me.

-- 
Lea Gris