Stream: ideas

Topic: List.reserve, Str.reserve api

Brendan Hansknecht (Oct 10 2022 at 15:45):

List.reserve and Str.reserve have a different api, which do we prefer:

List.reserve: Enlarge the list for at least capacity additional elements
Str.reserve: Make sure at least some number of bytes fit in this string without reallocating

Basically, should we reserve x additional items, or should we reserve to x items?

Richard Feldman (Oct 10 2022 at 15:56):

thinking about it some, I think the Str.reserve behavior is better because it doesn't need to deal with the possibility of addition overflowing

Richard Feldman (Oct 10 2022 at 15:58):

although maybe that's inconvenient to use :thinking:

Richard Feldman (Oct 10 2022 at 15:59):

I suppose if I'm doing reserve it's because I'm about to add some things onto an existing collection, so the number I'll have handy is the number of new things I want to add

Richard Feldman (Oct 10 2022 at 15:59):

plus I suppose it's no trouble to just use normal +, which handles integer overflow automatically

Richard Feldman (Oct 10 2022 at 16:00):

ok I've convinced myself that the way List.reserve does it is better :big_smile:

Brendan Hansknecht (Oct 10 2022 at 17:35):

I think most languages use the Str version and have the user do addition if they need it. I think that I generally see it used when creating a contain that you know a rough max size for.

Brendan Hansknecht (Oct 10 2022 at 17:35):

That said, for the new container case, either version would do the same thing. So I guess the List version also covers the case.

Brendan Hansknecht (Oct 10 2022 at 17:36):

Also, should the list version do a panicking addition or just do a saturating addition....i would assume saturating.

Richard Feldman (Oct 10 2022 at 17:49):

yeah I guess saturating is probably fine

Richard Feldman (Oct 10 2022 at 17:49):

although the allocation is likely to fail anyway haha

Richard Feldman (Oct 10 2022 at 17:49):

if you actually need more than that

Brendan Hansknecht (Oct 10 2022 at 18:01):

Yeah, my thought exactly, so just let the allocation fail instead jumping to panic. I think it should be slightly faster....though this is a pretty far micro optimization. Anyway, I'll update this and add smarter capacity calculation to Str in a PR

Richard Feldman (Oct 10 2022 at 18:39):

sounds great!

Kevin Gillette (Dec 21 2022 at 15:45):

What about using tags to support both cases, rather than making the caller do math in the non-selected case? The tag based approach seems to have worked well enough for List.range

Brendan Hansknecht (Dec 21 2022 at 18:11):

That would definitely work. I'm open to either. I guess it mostly depends on whether or not we actually want to support the other use case or if the simple API is enough. In general i think there is at least a minor cost to making it a tag. All calls become more verbose and essentially require parens.

Richard Feldman (Dec 21 2022 at 18:42):

I don't think the distinction is worth complicating the API in this case. I think we should just pick one!

Last updated: Jun 16 2026 at 16:19 UTC