Breaker methods

[alanrodas]

Hello there. I just started to use this library, and I love it so far.

I have a question though

In the docs, it states that:
"The core concept is this : static calls return values from their methods, while chained calls update the value of the object they're working on. Which means that an Underscore object don't return its value until you call the ->obtain method on it — until then you can chain as long as you want, it will remain an object. The exception are certains properties that are considered breakers and that will return the object's value. An example is Arrays->get."

I cannot find more documentation of what this "breakers" methods are. I would expect methods such as "size" or "contains" will be breakers so I can do things such as

$array = Arrays::from(array(1,2,3));
$isTwoThere = $array->contains(2) ? 'true' : 'false;

but apparently the way to go is:

$isTwoThere = $array->contains(2)->obtain() ? 'true' : 'false;

Maybe is because I'm new to this (and to PHP pretty much too) but I cannot see the point in chaining after you called "contains" or "size", or any other method that one would expect "true", "false" or numeric returns.

Can you explain why this decision and if there is a better way on achieving this kind of "querying" over an array than calling "obtain".

[Anahkiasen]

You can just do Arrays::contains([1, 2, 3], 2) to skip chaining altogether. I do admit contains should probably be a break (any method returning a boolean really). For integers it's different as we do have integer methods that you would want to chain.

In any case changing this would be involve a new major so we'd need to properly think this through once and for all

[alanrodas]

Actually, I realized that, after doing contains, you cannot chain anything after, as it states "The Type Boolean is not valid" throwing an InvalidArgumentException. I'm guessing this is true for any method returning a boolean.

As for the integers, is "Arrays::from(array(1,2,3))->length()->paddingLeft(3)" the most common use case?? Or the most common case is "Arrays::from(array(1,2,3))->length()->obtain() > 7".
Unfortunately PHP does not support operator overloading, or one could solve this kind of issues easily and support both cases.

So, wouldn't it be a good idea to have two methods for integer returning method?? Something like:
length_() Which returns a Number Repository
length() Such that it's length_()->obtain()

Of course, I understand that this is a major update too, but I wonder if it's not worth thinking on it.

For now, I will probably be forking this and adapt it to my needs, but if you believe this changes are acceptable, maybe I can PR you some changes in the future. Please let me know.