[PATCH v6] generalizing sorted-array handling

[Yann Dirson <ydirson@altern.org>]

I hope the improvements to the usage syntax in this version would help
to get more feedback.  I don't plan to do much more structural work on
this, unless reviewers complain.  I want to get my focus back to
bulk-rename/builk-rm patches, which will make heavy use of this API.

Changes from v5:

* moved doc to Documentation/api-sorted-array.txt as suggested by
  Jonathan Nieder, made it a bit more comprehensive as well.

* changed API with:
  * renamed low-level wrapper-decl macros with a leading underscore
  * provide high-level wrapper-decl macros for everyday use, which
    declare the required generic funcs for use (as static funcs)

Those high-level macros make the entry points more numerousas
previously noted, but we gain much in usage clarity, as well as
consistent API (no more argument differences between macros of a
single level)

By using those macros we lose the control we had on all the
intermediate funcs, but that should not be much of a problem.


Notes on current API:

* The macro names are a bit heavy-weight.  Better ideas welcome.

* could gain a dealloc API, to minimize the explicit use of the _nr
  and _alloc vars


The following binary-search occurences were not converted:

* read-cache.c::index_name_pos has widely-used API with 2 low-coupled
  cmp/init params: sorted-array could be generalized at the cost of
  using stdarg, but is it worth it ?

* pack-revindex.c::find_pack_revindex is a bit special and needs more
  thought

* cache-tree.c::subtree_pos and sha1_file::find_pack_entry_one too

* sha1_lookup.c stuff probably too special