Share your thoughts in the 2024 State of Clojure Survey!

Welcome! Please see the About page for a little more info on how this works.

0 votes
in Docs by
retagged by

I’m wondering if the docstring for clojure.zip/next could be misleading to some, it reads:

Moves to the next loc in the hierarchy, depth-first. When reaching the
end, returns a distinguished loc detectable via end? If already at the
end, stays there.

Some people might assume, without more guidance, that the end of the zipper is the last node in the zipper and that calling next at that point will leave the zipper located at the last node.

As far I understand it (which may be not far), the Clojure zipper end state is hit when you’ve called next after the last node in the zipper, after which:

  • the zipper is no longer navigable or updatable.
  • you can still call root (or node which at this point is equivalent to root), next and end? but otherwise, I think, it is game over.

Some code to show behaviour:

(require '[clojure.zip :as czip])
(->> [1 2 3]
     czip/vector-zip
     (iterate czip/next)
     (take 10)
     (map (juxt czip/node czip/end?)))
;; => ([[1 2 3] false]
;;     [1 false]
;;     [2 false]
;;     [3 false]
;;     [[1 2 3] true]
;;     [[1 2 3] true]
;;     [[1 2 3] true]
;;     [[1 2 3] true]
;;     [[1 2 3] true]
;;     [[1 2 3] true])

The next docstring might want to talk more about what “end” is and what reaching the end state means. Maybe something like:

Moves to the next loc in the hierarchy, depth-first.
When reaching the end, which is after the last node, returns a distinguished loc detectable via end?. If already at the end, stays there.
When at end, valid calls are end?, next and root.

If the docstring is not the right place, maybe the zipper overview could elaborate?

1 Answer

0 votes
by

"returns a distinguished loc" is clear: the zipper's end marker is not one of the nodes.

Webster's Second Unabridged (1956) defines "distinguished" as "distinct; differentiated". As for a computer-science definition of "distinguished value", I did not find one online, but OpenAI Chat got it right, so it must be out there somewhere: 'the term "distinguished value" typically refers to a specific value within a data structure or system that has a special meaning or purpose. This value is often used as a marker or sentinel to indicate the beginning or end of a certain section of data or to signal a certain condition or state. For example, in a linked list data structure, the value "NULL" is often used as a distinguished value to indicate the end of the list..'

...