Wrong example or description for "segment" method?

[manamski]

Why in description of method SEGMENT has two parameters, but one of the examples has three parameters? "->segment('/', 0, true)"

Method description:

/**
 * Get a segment from a string based on a delimiter.
 * Returns an empty string when the offset doesn't exist.
 * Use a negative index to start counting from the last element.
 * 
 * @param string $delimiter
 * @param int $index
 * 
 * @return \Spatie\String\String
 */
public function segment($delimiter, $index)    <-- 2 parameters

Example:
string('foo/bar/baz')->segment('/', 0, true); // baz <-- 3 parameters

Why do not use:
string('foo/bar/baz')->segment('/', -1); // baz

[manamski]

I think I know myself.
Because there is no value "-0" (for the last element) and string('foo/bar/baz')->segment('/', -1); return before last element "bar" not "baz".
So, why not create a new method "segmentRev($delimiter, $index)", but with positive index counting from the last element?
0 = the last element ("baz")
1 = before last element ("bar")
2 = previous element ("foo")

Edit:
I looked at the source code of the method "lastSegment":

    public function lastSegment($delimiter)
    {
        return (new static($this->string))->segment($delimiter, -1);
    }

...and found that it uses the index with a value "-1". Well, now I don't understand.

[sebastiandedeyne]

The example with 3 parameters is a mistake, probably a remnant of an older version of the package.

The correct usage is:

string('foo/bar/baz')->segment('/', 0); // 0 returns the first segment
string('foo/bar/baz')->segment('/', 1); // 1 returns the second segment
string('foo/bar/baz')->segment('/', -1); // -1 returns the last segment

(if I'd write this again, I'd probably use a 1-based index, and disallow querying for the 0 segment)

[manamski]

Thank you for the explanation.