PHP String substr_compare() Function

The substr_compare() is a built-in function of PHP, which helps to compare the two strings from a specified start position to specified end position. This function is a binary-safe function and optionally case-sensitive. PHP 5 and above versions support this function.

Syntax

The syntax of substr_compare() function is given below.

substr_compare( String $main_str,  String $str, int start_pos, int length, Boolean case-insensitivity = FALSE) 

It consists of five parameters in which three are mandatory, and the remaining two are optional. Below is the description for these parameters:

Parameters

$main_str (required): It is the main string parameter of this function which needs to be compared. It is a mandatory parameter.

$str (required): It is the second string parameter of this function which is specified to be compared. It is also a mandatory parameter as main_str.

$start_pos (required): It is a mandatory parameter, which has an integer value. This parameter specifies the value, where to start a comparison of $str in $main_str. In other words, - it provides the start position for the comparison.

If the passed value is negative, then it starts comparing from the end of the string.

$length (optional): This parameter is not mandatory to pass in this function. It consists the length of the comparison, means it specifies how much of $str to compare.

$case-insensitivity (optional): This parameter contains the Boolean value, which specifies whether to perform case-sensitive comparison or not. It is an optional parameter as $length. If case-insensitivity is TRUE, then the comparison will be case-insensitive.

FALSE -Case-sensitive (default value)
TRUE - Case-insensitive

Return Values

This function returns the following values:

Return 0 - If both the given strings are equal.

Return < 0 - If $main_str (from start position) is less than $str.

Return > 0 - If $main _str (from start position) is greater than $str.

Note: If $length parameter value is equal and greater than the length of the main string ($main_str), then this function displays a warning and will return FALSE.

Changelog

Version	Description
PHP 5.1.0	It is possible to use a negative start_pos.
PHP 5.5.11	$length can be 0 now.
PHP 7.2.18, 7.3.5	$start_pos may be equal to the length of main string ($main_str).

Examples

Below few numbers of examples are given to learn the working of substr_compare() function.

Example 1

In the below example, we are passing 3 mandatory parameters in this function. Lets's see the working of substr_compare() with three arguments.

<?php
	$main_str = "Good health Good life.";
	$string2 = "Good health Good life.";
	// both strings are equal to each other.
	echo substr_compare($main_str, $string2, 0). "</br>";

	// the main string is 11 chracters greater than string2 including whitespace.
	echo substr_compare($main_str, "Good health", 0). "</br>";

	// the main string is 5 characters shorter than string2 including whitespace.
echo substr_compare($main_str, "Good health Good life. Good", 0). "</br>";
?>

Output:

0
11
-5

Example 2

<?php
	// main strting is greater than the second string.
	echo substr_compare("Hello javaTpoint","Hello", 0). "</br>";

	// both strings are equal, as comparison start at 6th position.
	echo substr_compare("Hello javaTpoint","javaTpoint", 6). "</br>";

	// main string and next comparable string are not same, so it will return -1
	echo substr_compare("Hello javaTpoint","hie", 0). "</br>";
?>

Output:

11		
0		
-1

Example 3

<?php
	// both strings are equal from position 0 to 4.
	echo substr_compare("Hello javaTpoint","Hello", 0, 4). "</br>";

	// second string is not found between 6 to 10 position, because by default it is case-sensitive.
	echo substr_compare("Hello javaTpoint","JAVATPOINT", 6, 10). "</br>";

	//As Hello is present in the string, but not found between 5 to 14 range.
	echo substr_compare("Hello javaTpoint","Hello", 5, 14). "</br>";
?>

Output:

0		
1		
-1

Example 4: Case-sensitive/insensitive

In the below example, we are passing all the five parameters in this function. Lets's see the working of substr_compare() with all arguments.

<?php
	$main_str = "Good health Good life.";
	$string2 = "Good health Good life.";
	$case_insensitivity = FALSE;
	// here, this function works as case-insensitive
	echo substr_compare($main_str, $string2, 0, 9, TRUE). "</br>";

	// here, this function case-sensitive 
	echo substr_compare($main_str, "GOOD Health", 0, 11, $case_insensitivity). "</br>";

	//the function works as case-insensitive
	echo substr_compare($main_str, "GOOD health", 0, 11, TRUE). "</br>";
?>

Output: