[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Bug-readline] Minor bone to pick regarding the doc for next_history()

From: Glenn Golden
Subject: [Bug-readline] Minor bone to pick regarding the doc for next_history()
Date: Tue, 24 Mar 2015 08:50:20 -0600
User-agent: Mutt/1.5.23 (2014-03-12)

>From history.3, readline 6.3.006:

  HIST_ENTRY * next_history (void)

    Move the current history offset forward to the next history entry,
    and return the a pointer to that entry.  If there is no next entry, 
    return a NULL pointer.

This leaves unstated what happens to the value of 'offset' if there
is "no next entry", and it seems there is no simple 'right' answer.

>From experiments (via perl Term::ReadLine::Gnu) the actual behavior w.r.t
the value of 'offset' after the call completes seems to be

    offset = (offset < history_length) ? offset+1 : offset;

which means that there are really two relevant forms of "no next entry" upon
calling next_history():

  Case 1: offset == history_length-1

  Case 2: offset >  history_length-1

Case 1 is the ordinary situation: Prior to the call, the value of offset
corresponds to the last history entry (since offset is effectively 0-origin)
and in this case the doc is correct as-is if read literally: The first sentence
implies that incrementation of offset is unconditional, and indeed following
the call, offset is bumped to be equal to history_length, i.e. it refers to
the (nonexistent) history entry just past the end. (Not criticizing this
behavior, assuming it is intentional.) 

But in Case 2, the doc is not quite accurate, because the value of offset is
not incremented.

Admittedly, Case 2 would probably arise only due to programmer error,
but nevertheless it can happen. (For example: First call next_history() when
offset == history_length-1, which sets offset to history_length, then call
it again from this state.)

Small point, even pedantic, but just got burred by it, so perhaps someone else
might too.

If you agree with this, I'll be happy to submit a doc patch to history.3.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]