Binary safe comparison of two strings from an offset, up to length characters

- « substr

- substr_count »

- PHP Manual
- String Functions
- Binary safe comparison of two strings from an offset, up to length characters

# substr_compare

(PHP 5, PHP 7, PHP 8)

substr_compare — Binary safe comparison of two strings from an offset, up to length characters

### Description

substr_compare(
string `$haystack`,
string `$needle`,
int `$offset`,
?int `$length` = `null`,
bool `$case_insensitive` = `false`
): int

substr_compare() compares `haystack` from position `offset` with `needle` up to `length` characters.

### Parameters

`haystack`

  The main string being compared.

`needle`

  The secondary string being compared.

`offset`

  The start position for the comparison. If negative, it starts counting from the end of the string.

`length`

  The length of the comparison. The default value is the largest of the length of the `needle` compared to the length of `haystack` minus the `offset`.

`case_insensitive`

  If `case_insensitive` is `true`, comparison is case insensitive.

### Return Values

Returns `-1` if `haystack` from position `offset` is less than `needle`, `1` if it is greater than `needle`, and `0` if they are equal. If `offset` is equal to (prior to PHP 7.2.18, 7.3.5) or greater than the length of `haystack`, or the `length` is set and is less than 0, substr_compare() prints a warning and returns `false`.

### Changelog

Version | Description
--- | ---
8.2.0 | This function now returns `-1` or `1`, where it previously returned a negative or positive number.
8.0.0 | `length` is nullable now.
7.2.18, 7.3.5 | `offset` may now be equal to the length of `haystack`.

### Examples

Example #1 A substr_compare() example

    <?php
    echo substr_compare("abcde", "bc", 1, 2); // 0
    echo substr_compare("abcde", "de", -2, 2); // 0
    echo substr_compare("abcde", "bcg", 1, 2); // 0
    echo substr_compare("abcde", "BC", 1, 2, true); // 0
    echo substr_compare("abcde", "bc", 1, 3); // 1
    echo substr_compare("abcde", "cd", 1, 2); // -1
    echo substr_compare("abcde", "abc", 5, 1); // warning
    ?>

### See Also

- strncmp() - Binary safe string comparison of the first n characters