search.php

<?php

declare(strict_types=1);

namespace Psl\Str\Byte;

use Psl\Str;

use function strpos;

/**
 * Returns the first position of the 'needle' string in the 'haystack' string,
 * or null if it isn't found.
 *
 * An optional offset determines where in the haystack the search begins. If the
 * offset is negative, the search will begin that many characters from the end
 * of the string.
 *
 * @pure
 *
 * @throws Str\Exception\OutOfBoundsException If $offset is out-of-bounds.
 *
 * @return null|int<0, max>
 *
 * @mago-ignore best-practices/no-boolean-literal-comparison
 */
function search(string $haystack, string $needle, int $offset = 0): null|int
{
    $offset = Str\Internal\validate_offset($offset, length($haystack));

    if ('' === $needle) {
        return null;
    }

    /** @var null|int<0, max> */
    return false === ($pos = strpos($haystack, $needle, $offset)) ? null : $pos;
}