Implement Stream::size_hint

[yoshuawuyts]

Equal to https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.size_hint. Don't think this needs to be marked async. This would've been useful to calculate the right pre-alloc size for calling collect into a vec in #125. Thanks!

[taiki-e]

Could you explain the value of size_hint that cannot be implemented manually?

[yoshuawuyts]

@taiki-e I feel its mostly API consistency?

Though with iter size hint it's useful when pre-allocating structures. For example when using collect for vec it would've been useful to get an estimate of how much to allocate. Right now we start with an empty vector and allocate as we go, which is not nearly as efficient as it could be.

[taiki-e]

The problem is that size_hint always returns the default value because async_std::stream::Stream cannot be implemented manually. So, currently, calling size_hint for optimization is a needless operation.

[taiki-e]

IMO, we should wait for the upstream to add size_hint, instead of adding such a “useless API”.

[yoshuawuyts]

@taiki-e ah yeah, fair point.

Though I don't disagree, I do see value in implementing all APIs sooner rather than later though. This way we can have the external API that folks can call, which can be incorporated in app logic — and later when we fix the impl nobody needs to rewrite their code.

Or well, that's the theory.

[yoshuawuyts]

Yay, rust-lang/futures-rs#1853 landed!

[yoshuawuyts]

We're now blocked on futures-preview@0.3.0-alpha.19 landing to implement this.

[yoshuawuyts]

Sweet, this has landed! This means we can now rely on size_hint for optimizing allocations in FromStream impls!

cc/ @sunjay