# Array manipulation functions.
#

#
# General one liners.  Brief description:
#
#   The *item functions operate on one array element.
#   The *items functions operate on as many elements as there are args.
#
# Note that unlike their inbuilt counterparts, these generally accept negative
# item numbers as the distance from the top of the array, starting with -1.
#
# Let's start with some basics:
#
#   getndelitems:   splice the items $1- from the array and return them as a list.
#   getndelindex:   splice the indices $1- from the array and return them as a list.
#   getnrolitems:   Splice items $2- from $0, put them at the end of $1, and return them.
#   itemnorm:       Supporting function.  Fixes/removes invalid item numbers.
#
alias itemnorm (ar,it) @:ni=numitems($ar);fe it it {@it+=0<=it?0:ni,it=0<=it&&it<ni?it:[]};return $it
alias getndelitems (ar,it) @:it=itemnorm($ar $it),:function_return=getitem($ar $it),delitems($ar $it)
alias getndelindex (ar,it) @:it=itemnorm($ar $it),:function_return=igetitem($ar $it),delitems($ar $indextoitem($ar $it))
alias getnrolitems (a1,a2,it) @:dt=:it=itemnorm($a1 $it);fe it it {setnextitem $a2 ${it=getitem($a1 $it)}};@delitems($a1 $dt);return $it
#
# Now onto some more complex functions:
#
#   getmaskitem[s]: return one/all array elements matching $1-.
#   getandmitem[s]: Get an' Del item[s] matching Mask ($1-) from array $0.
#   getanrmitem[s]: Get an' Rol item[s] matching Mask ($2-) from array $0 to $1.
#
alias getmaskitem  (ar,mask) @:it=getmatches($ar $mask);return ${getitem($ar $word($rand($#it) $it))}
alias getmaskitems (ar,mask) return $getitem($ar $getmatches($ar $mask))
alias getandmitem  (ar,mask) @:it=getmatches($ar $mask);return ${getndelitems($ar $word($rand($#it) $it))}
alias getandmitems (ar,mask) return $getndelitems($ar $getmatches($ar $mask))
alias getanrmitem  (a1,a2,mask) @:it=getmatches($a1 $mask);return ${getnrolitems($a1 $a2 $word($rand($#it) $it))}
alias getanrmitems (a1,a2,mask) return $getnrolitems($a1 $a2 $getmatches($a1 $mask))
#
# The set*item functions update arrays in certain potentially useful ways.
#
# The set*items functions call their set*item counterpart for each word given.
#
#   setnextitem[s]: set a new array element[s] with $1- as contents.
#   setranditem[s]: replace a random array element[s] with $1-
#   setrmaxitem[s]: setnextitem if $1 > numitems else setranditem.
#   setuniqitem[s]: setnextitem if the array item[s] doesn't already exist.
#
alias setnextitem  (ar,args) return $setitem($ar $numitems($ar) $args)
alias setnextitems (ar,args) fe args foo {@foo=setitem($ar $numitems($ar) $foo)};return $args
alias setranditem  (ar,args) return $setitem($ar $rand($numitems($ar)) $args)
alias setranditems (ar,args) fe args foo {@foo=setitem($ar $rand($numitems($ar)) $foo)};return $args
alias setrmaxitem  (ar,it,args) @:ni=numitems($ar);return $setitem($ar ${it>ni?ni:rand($ni)} $args)
alias setrmaxitems (ar,it,args) @:ni=numitems($ar);fe args foo {@foo=setitem($ar ${it>ni?ni++:rand($ni)} $foo)};return $args
alias setuniqitem  (ar,args) if (0>findit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       