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?
