[Tcl-bugs] [ tcl-Bugs-1710795 ] First|Next|Done docs are confusing

[SourceForge.net <no...@so...>]

Bugs item #1710795, was opened at 2007-05-01 21:28
Message generated for change (Settings changed) made by dkf
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=110894&aid=1710795&group_id=10894

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: 15. Dict Object
Group: current: 8.5a6
>Status: Closed
>Resolution: Fixed
Priority: 7
Private: No
Submitted By: Don Porter (dgp)
Assigned to: Donal K. Fellows (dkf)
Summary: First|Next|Done docs are confusing

Initial Comment:

The Tcl_DictObj(First|Next|Done) routines
are offered to manage an iteration through
the contents of a dictionary.

The documentation says:

"The donePtr argument points to a variable that is
updated to be zero  of there are further key/value
pairs to be iterated over, or non-zero if the
iteration is complete."

I interpret that to mean a result of (*donePtr = 1)
means the next call to Tcl_DictObjNext would fail
to return anything, so it need not be made.

That's not what the implementation does.

The implementation has (*donePtr = 1) means that
the current call did not return anything.

Either scheme is workable, but the docs need
to be more clear.  Confusion about whether/when
Tcl_DictObjDone() needs to be called caused
Tcl Bug 1710709.


----------------------------------------------------------------------

Comment By: Donal K. Fellows (dkf)
Date: 2007-05-02 00:05

Message:
Logged In: YES 
user_id=79902
Originator: NO

Originally, Done was only called when you wanted to break out of iterating
early, and this was found to work well enough in the basic implementations
in tclDictObj.c. But later on (when I was writing the bytecode compiled
versions IIRC) I discovered that this in fact sucked and was too hard to
use right, and that it was better instead to arrange for Done to be always
callable after the iteration completed. (I believe that the Done call can
be avoided in the same circumstances that it always could be avoided, but
it's easier to avoid having to explain it by making repeat calls
idempotent.)

I do not recall at what point I wrote the documentation. :-)

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=110894&aid=1710795&group_id=10894