Home/ Manual/ strings / functions/ substr_compare

substr_compare

PHP function Edit on GitHub ✎

(PHP 5, PHP 7, PHP 8)

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

Description

substr_compare(string $haystack, string $needle, int $offset, int|null $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 Return

Errors/Exceptions

Throws a ValueError if offset is greater than the length of haystack and length is not 0, or if length is less than 0.

Changelog

Version	Description
8.0.0	Now throws a `ValueError` if `offset` is out of range or `length` is negative. Previously, an `E_WARNING` was raised and false was returned.
8.0.0	`length` is nullable now.
7.2.18, 7.3.5	`offset` may now be equal to the length of `haystack`.

Examples

A substr_compare() example

php

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