Doc that lazy-seq with-meta forces realization

Question

Applying meta to a lazy-seq causes realization:

(def x (vary-meta (lazy-seq (prn :realized)) assoc :foo :bar)) :realized

This might be surprising, so modify docstring of lazy-seq to mention it.

Patch:

Answer 1

Comment made by: alexmiller

I think it's likely that seq() is called here so that the old LazySeq instance and the new one share the sequence. Otherwise the pre-meta and post-meta versions would be performing the same function calls on the same inputs but would be disconnected, which seems bad.

Answer 2

Comment made by: alexmiller

I'm not really sure where this would be documented. Maybe on the http://clojure.org/metadata page?

Answer 3

Comment made by: mpenet

That would make sense yes and on the docstring of lazy-seq as well.

Answer 4

Comment made by: alexmiller

I added a sentence to the metadata page and updated the description to be more applicable here to a docstring change.

Answer 5

Comment made by: michaelblume

With this patch, with-meta doesn't realize the seq, but realization still only happens once -- would this be an acceptable approach?

Answer 6

Comment made by: michaelblume

Added test

Answer 7

Reference: https://clojure.atlassian.net/browse/CLJ-1800 (reported by mpenet)