add a single-item version of `take`

[bakkot]

Per the readme, take gives you an array of n items. That's a useful operation, and it is true that this is a strict generalization of "give me a single item". But it comes up way less than the "give me a single item" version, and it's a shame to make the more common operation awkward (and require an extra allocation).

[tabatkins]

Fair! Hm, I still like take() for the N case, following Iterator helpers, but there's no obvious precedent to follow for a single-item one.

I guess takeOne could work. Or we can go with a synomym, like choose() or pick() or sample().

[bakkot]

Personally I'd go with sample (one item) and samples (n items).

[tabatkins]

Do we have precedent (positive or negative) in distinguishing APIs exclusively by singular vs plural? We try to avoid that in CSS, for example.

[js-choi]

Do we have precedent (positive or negative) in distinguishing APIs exclusively by singular vs plural? We try to avoid that in CSS, for example.

I recall that HTML might have a pair of properties that share the same name, except one ends in the plural “s” due to legacy reasons. I can’t find or remember what they were called, though.

Like the CSSWG, I also think distinguishing only by s is a naming antipattern. It’s a subtle distinction, and it’s hard to remember that both names exist—they share the same space in my brain’s memory. It is better is to distinguish similar names by a full word when possible.

What about take and take1, or sample and sample1?

Lisps often use this pattern, like macroexpand and macroexpand-1. The 1 word is much more memorable to me than a subtle s, which hardly gets any verbal emphasis in typical English speech.

[tabatkins]

I'm currently going with take() (clearly analogous to iterator helpers) and sample() (fairly common name across langs for a single-item pull). I think that'll be a fairly usable name pair.

(I'd rather avoid the Lisp pattern - it doesn't have precedent in the stdlib, DOM, or in userland libs I'm familiar with. If I did that I'd use a One prefix instead.)

Anyway, closing for now as the feedback is addressed, but if there are strong naming feelings feel free to open a new issue.

[michaelficarra]

I'd actually caution against allusion to Iterator.prototype.take. We had issues with that name for that operation and, if they were noticed earlier, we would've named it limit instead. The operation you're referring to here is appropriately named take, but not because of the relationship to Iterator.prototype.take. If we want the name to allude to something else, chunk, as in the iterator chunking proposal, would probably be more relevant.

[tabatkins]

Edit: Sorry, hit the button too early.

[tabatkins]

Ah, I wasn't familiar with those discussions. Still, Random's take() and sample() need to exhaust the iterator anyway, which closes it, so I think the allusion is just fine? (Even if using reservoir sampling you need to exhaust it.)