[Rd] findInterval Documentation Suggestion

[brodie gaslam]

I've found over time that R documentation that comes off as terse at
first blush is usually revealed to be precise, concise, and complete
on close reading.  I'm sure this is also true of `?findInterval`, but
for whatever reason my brain simply refuses to extract meaning from it.

Part of the problem may be that we interact with the function via a
compressed form of the bounds of the intervals (only specify left bounds
for 2nd interval onwards), but the semantics are described mostly in
terms of the intervals themselves.  This requires indirections to map
the parameters to the concepts.

An alternative is to first describe what the function does directly in
terms of its inputs, and subsequent relate that to the intervals.  If I
understand correctly (in default mode) the function can be described as:

     Given a vector of non-decreasing values 'vec', for each value in
     'x' return the highest position in 'vec' that corresponds to a
     value less than or equal to that 'x' value, or zero if none are.
     Equivalently, if the values in 'vec' are taken to be the closed
     left-bounds of contiguous half-open intervals, return which of
     those intervals each value of 'x' lies in.

Compared to the original:

     Given a vector of non-decreasing breakpoints in ‘vec’, find the
     interval containing each element of ‘x’; i.e., if ‘i <-
     findInterval(x,v)’, for each index ‘j’ in ‘x’ v[i[j]] <= x[j] <
     v[i[j] + 1] where v[0] := - Inf, v[N+1] := + Inf, and ‘N <-
     length(v)’.  At the two boundaries, the returned index may differ
     by 1, depending on the optional arguments ‘rightmost.closed’ and
     ‘all.inside’.

Obviously you would be right to question whether someone who claims not
to understand the documentation should venture to re-write it.
Nonetheless I attach a proposed alternate version in the hopes that
someone who clearly understand the original might use or adapt parts of it to
make `?findInterval` more accessible to those comprehension-challenged
like me.


Best,

Brodie