Fix issue with use of "root" uncons / uncons1 and clarify docs

[pchiusano]

I was looking into clarifying the docs on uncons and uncons1 to say that they should be used in conjunction with Stream.scope (see #797) and noticed what I'd say is a problem - if you use uncons but don't have a surrounding scope call or Pull (which uses scope), you can have a finalizer not run. This test used to fail:

    "early termination of uncons" in {
      var n = 0
      Stream(1,2,3).onFinalize(Task.delay(n = 1)).uncons.run.unsafeRun
      n shouldBe 1
    }

That test is now fixed, by adding a call to scope in runFold, but the note about using scope in conjunction with uncons still applies if you want prompt finalization.

Sorry @jedesah but my docs kind of clobber some of your work in #797. I felt like the docs were trying to cover too many things (like the fact that if you reference an effectful stream twice, its effects are repeated... which is not really specific to uncons at all, just a general property of effectful streams).

This could be backported to 0.9 series also? Not sure how important that is, this would only show up if you were using uncons at the "root" of your stream, which I think would be super rare.

[jedesah]

As much as it's kind of neat to show that you can implement take with uncons, I don't think it's the best example as it doesn't really show what uncons is typically useful for. Perhaps my mapFirstN was a little odd I'll admit. I find a common use case for uncons is doing some kind of sneak peak on a Stream before deciding exactly how to process the remainder of it. Perhaps an example in that vein would meet everyone's approval?

@pchiusano I agree that referencing an effectful Stream twice is a general problem, however uncons seems to often be the solution to achieve what is desired in a proper way. I'll admit I have not fully wrapped my head around the differences between fs2 and scalaz-stream and perhaps uncons is no longer a particularly common solution to that problem. Perhaps this common pitfall should be documented somewhere else at the very least.

[pchiusano]

Agree on documenting the "don't reuse an effectful stream unless you want to repeat the effects", maybe in guide somewhere? I don't think we will get very far discussing what uncons is "typically" useful for... it's just so general purpose. :) Why do you pattern match on a list and check for `::` or `Nil`? Lots of reasons. For implementing 'take', for peeking into the list, implementing a left fold... whatever! uncons is the same sort of thing. I'd actually be ok with just getting rid of any of the language in the docs suggesting that uncons is "for" one thing or another and just move that general info to the guide. But if we're going to keep the docs, I'd maybe give a handful of examples and don't try to influence people's thinking much. Maybe just say like "this can be used to walk through or peek into a stream, which is useful in lots of ways, for example:" and then like 2 or 3 different examples. Would you like to take a crack at that? I thought your mapFirstN example was a little... weird. I think 'take' is good, it's like the simplest possible stateful function, and something in the "peeking into the stream" vein which is as simple as possible would be good too. (Like perhaps 'dropWhile', which has to put the element back if it doesn't match the predicate) Maybe also a parsing task - think CSV - you peel off the first line, with an uncons, parse out the header, then pass the tail and that header to a csv row parser that produces rows given a header. Not sure if that made any sense...

…

On Fri, Feb 10, 2017 at 4:17 PM, Jean-Rémi Desjardins < ***@***.***> wrote: As much as it's kind of neat to show that you can implement take with uncons, I don't think it's the best example as it doesn't really show what uncons is typically useful for. Perhaps my mapFirstN was a little odd I'll admit. I find a common use case for uncons is doing some kind of sneak peak on a Stream before deciding exactly how to process the remainder of it. Perhaps an example in that vein would meet everyone's approval? @pchiusano <https://github.com/pchiusano> I agree that referencing an effectful Stream twice is a general problem, however uncons seems to often be the solution to achieve what is desired in a proper way. I'll admit I have not fully wrapped my head around the differences between fs2 and scalaz-stream and perhaps uncons is no longer a particularly common solution to that problem. Perhaps this common pitfall should be documented somewhere else at the very least. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#808 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAArQhTcjnMpDXIbLQJZPRzSpKNVcmDoks5rbNPRgaJpZM4L9uyy> .

[jedesah]

@pchiusano Sure I think what you said makes sense. I'll take a crack at it.