find-first-fail: renamed from binsearch.

find-first-fail/find-first-fail

@@ -0,0 +1,214 @@
+#!/bin/bash
+
+: <<'=cut'
+=encoding utf8
+
+=head1 NAME
+
+find-first-fail - find the lowest argument that makes a command fail
+
+
+=head1 SYNOPSIS
+
+B<find-first-fail> [-2] [-q] I<command>
+
+
+=head1 DESCRIPTION
+
+B<find-first-fail> runs I<command> with a single number. It returns highest
+value that I<command> succeeds for.
+
+It finds the value by first testing the value 1. As long as the value
+succeeds, the value is doubled. When the value fails, B<find-first-fail>
+does a binary search between this value and the previous value.
+
+If the value 1 fails, B<find-first-fail> instead searches for the highest
+value that I<command> fails for.
+
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-2>
+
+Instead of passing the command a single argument, give the command 2
+arguments: I<from> I<to>.
+
+=item B<-q>
+
+Quiet. Ignore output from I<command>.
+
+
+=back
+
+
+=head1 EXAMPLES
+
+=head2 Find the last file
+
+This is a silly way to find the last non-existing file (namely 244):
+
+  touch {245..800}
+  find-first-fail ls
+
+This is a silly way to find the last file (namely 800):
+
+  touch {1..800}
+  find-first-fail ls
+
+=head2 Test a bash function
+
+Test how long an argument /bin/echo can take
+
+  . $(which find-first-fail)
+  singleecho() {
+    /bin/echo $(perl -e 'print "x"x'$1) >/dev/null
+  }
+  find-first-fail singleecho
+
+=head2 Test a bash function that takes from and to as arguments
+
+Use a function that takes two arguments. It finds the line number
+after HOME=.
+
+  . $(which find-first-fail)
+  greplines() {
+      env | perl -ne "$1..$2 and print" | grep HOME=
+  }
+  find-first-fail -2 -q greplines
+
+=head2 Test complex command and show what is run
+
+Complex commands can also be run:
+
+  find-first-fail -v perl -e 'exit(shift > 129)'
+
+
+=head1 AUTHOR
+
+Copyright (C) 2020 Ole Tange,
+http://ole.tange.dk and Free Software Foundation, Inc.
+
+
+=head1 LICENSE
+
+Copyright (C) 2012 Free Software Foundation, Inc.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+at your option any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+=head1 SEE ALSO
+
+B<eval>(1)
+
+=cut
+
+find-first-fail() {
+    _find-first-fail() {
+	low=$1
+	high=$2
+	# echo $low-$high
+	if [ $low -gt $(($high - 2)) ]; then
+	    return
+	fi
+	shift
+	shift
+	middle=$(( ( $low + $high ) / 2 ))
+	if _run $low $middle "$@" ; then
+	    low=$middle
+	else
+	    high=$middle
+	fi
+	_find-first-fail $low $high "$@"
+    }
+
+    _run() {
+	# run:
+	#   cmd $low $high
+	# or:
+	#   cmd $value
+	# Output is ignored if $quiet
+	# Exit value is negated if $not
+	_inner_run() {
+	    # _inner_run is needed if cmd is complex like:
+	    #   perl -e 'exit(  (shift) + (shift) > 10)'
+	    if $opt2 ; then
+		$verbose && echo "${cmd[@]}" "$a" "$b"
+		"${cmd[@]}" "$a" "$b"
+	    else
+		$verbose && echo "${cmd[@]}" "$b"
+		"${cmd[@]}" "$b"
+	    fi
+	}
+	local a="$1"
+	local b="$2"
+	shift
+	shift
+	# echo "a=$a b=$b $@"
+	local cmd=( "$@" )
+	eval "$not" _inner_run "$quiet"
+    }
+
+    quiet=""
+    opt2=false
+    verbose=false
+
+    # Parse and remove options
+    while getopts "2vq" options; do
+	case "${options}" in
+	    (2)   opt2=true;;
+	    (q)   quiet=">/dev/null 2>/dev/null";;
+	    (v)   verbose=true;;
+	    (-)   break;;
+	esac
+    done
+    shift $(( OPTIND - 1))
+
+    # If function(1) = false: run 'not function()' instead
+    if _run 1 1 "$@" ; then
+	not=''
+    else
+	not='!'
+    fi
+
+    # exponential search for the first value that is false
+    # low = previous value (function($low) == true)
+    # high = low * 2 (function($high) == false)
+    high=1
+    while _run 1 $high "$@" ; do
+	low=$high
+	high=$(( $high*2 ))
+	if [ $high -gt 4611686018427387900 ] ; then
+	    echo "$0: Error: exit value does not change of '$@'" >&2
+	    return
+	fi
+    done
+
+    # low = tested good
+    # high = tested fail
+    # Search low..high
+    # echo "low: $low high: $high not: $not"
+    _find-first-fail $low $high "$@" 2>/dev/null
+    echo $low
+}
+
+if [ -z "$*" ] ; then
+    # source the bash function
+    # . $(which find-first-fail)
+    true
+else
+    # find-first-fail command
+    find-first-fail "$@"
+fi