When should Operations return a Collection?

[AlexandruGG]

---

Based on the above I thought I'd start a wider discussion, with the main question: when should operations return a collection object?

Here's what I think: I appreciate the consistency in knowing that a lot of the operations return the same object. There is definitely some benefit to that. However, I think even more important elements can be:

• convenience -> what requires less effort on the user side when using the Collection library?
• familiarity -> what will the user be familiar with from other packages/programming languages?
• intuition -> when a user reads a method's name and looks at an example, does it come natural what the method is doing?
• use cases -> how is the operation going to be used in conjunction with other methods?

Based on the above, I found a nice little principle that I feel fits quite well. Let me know if it makes sense: operations should return a collection object IF they are meant to be chained. With this I present a couple examples:

// Classic usage, makes complete sense for these methods to return the same object to allow chainability
Collection::fromIterable([1, 2, 3])
    ->map(...)
    ->flatten(...)
    ->filter(...)
;


// In this usage, it's quite hard to find a use case where you would want to continue to chain anything after `contains`
Collection::fromIterable([1, 2, 3])
    ->contains(2) // [true] -> we have a bool so far
    ->whatCanIChainHere()? // -> the only thing I might want to do here is call `current` to get the value
;

Let me know if these things make sense. I can see a few methods which would benefit from having their return type changed, like contains, has, nullsy, falsy, truthy. As a user I think I would expect a simple boolean from all of these.

Others which are a bit more debatable would be first, get, head, where in many cases a user would expect to get the value. Though for these we could argue that you might still want to chain something.

[AlexandruGG]

@drupol let me know if this makes sense when you have a chance to go over it and think about it

[drupol]

Sure, let me think about it carefully :)

[AlexandruGG]

@drupol hey, did you have a chance to go through this? 😄

[drupol]

Not yet but I will for sure!

[drupol]

We should categorize 3 types of return:

1. A scalar value; int or bool for example: ::count(), ::has(), ...
2. A plain collection
3. A collection of collection; eg: ::span(), ::partition()

Do you see something else to add?

[AlexandruGG]

I like this approach

[AlexandruGG]

@drupol are you ok with us making the change for the scalars for the next release (i.e. 4.2)?

I can prepare a PR for that if you give me the green light

[drupol]

Sure! you can prepare any PRs, submit them as draft, and then we discuss them. Just like I did for #119 and #116.

[drupol]

Should ::first() and ::last() do the same?

[AlexandruGG]

sorry I think I missed this.

first, get, head, last could also be decent candidates for this but I'm not too sure, I think for now let's keep them as is because it allows a bit more flexibility. For example I might want to take the first item, apply some transformation, and only then extract it via current

[drupol]

Fair enough.