PHP substr_compare() Function

Usage — The PHP substr_compare() function is used to perform comparison of two strings from an offset or start position, up to length characters. This function is binary-safe and can optionally be case-sensitive.

It has the following syntax:

PHP

int substr_compare ( string $main_str , string $str , int $offset [, int $length [, bool $case_insensitivity = false ]] )

Here is an example of using substr_compare():

PHP

// Output — 0
echo substr_compare("Hello world","lo world",3, 5);

Return Value — This function returns an integer value < 0 if main_str from position offset is less than str, > 0 if it is greater than str, and 0 if they are equal. If offset is equal to or greater than the length of main_str, or the length is set and is less than 1 (prior to PHP 5.5.11), substr_compare() prints a warning and returns FALSE.

PHP Version and Changelog — The substr_compare() function is available in PHP 5, PHP 7. Starting from PHP version 5.1.0, you can also use negative offsets. In PHP 5.5.11 and later, you can also set the length parameter to zero.

Relevant Functions — Other related PHP functions that you should know about are: strncmp() which performs binary safe string comparison of the first n characters.

Go Directly To — usage, parameters, working examples or additional tips.

Parameters

main_str

The main_str parameter is used to specify the main string being compared. This is a required parameter.

str

The str parameter is used to specify the secondary string being compared. This is a required parameter.

offset

The offset parameter is used to specify the start position for the comparison. If negative, it starts counting from the end of the string. This is a required parameter.

length

The length parameter is used to specify the length of the comparison. The default value is the largest of the length of the str compared to the length of main_str less the offset. This is an optional parameter.

case_insensitivity

The case_insensitivity parameter is used to specify if the comparison should be case-insensitive or not. If set to TRUE, comparison is case insensitive. This is an optional parameter and its default value is FALSE.

Working Examples

Here are some examples of using the substr_compare() function:

PHP

// Output — 0
echo substr_compare("abcde", "bc", 1, 2);

// Output — 0
echo substr_compare("abcde", "de", -2, 2);

// Output — 0
echo substr_compare("abcde", "bcg", 1, 2);

// Output — 0
echo substr_compare("abcde", "BC", 1, 2, true);

// Output — 1
echo substr_compare("abcde", "bc", 1, 3);

// Output — -1
echo substr_compare("abcde", "cd", 1, 2);

// Output — warning
echo substr_compare("abcde", "abc", 5, 1);
 

Additional Tips

Here are some of the most upvoted tips taken from the comment section of the PHP manual:

  1. When you came to this page, you may have been looking for something a little simpler: A function that can check if a small string exists within a larger string starting at a particular index. Using substr_compare() for this can leave your code messy, because you need to check that your string is long enough (to avoid the warning), manually specify the length of the short string, and like many of the string functions, perform an integer comparison to answer a true/false question.

    I put together a simple function to return TRUE if $str exists within $mainStr. If $loc is specified, the $str must begin at that index. If not, the entire $mainStr will be searched.

    PHP

    function contains_substr($mainStr, $str, $loc = false) {
        if ($loc === false) return (strpos($mainStr, $str) !== false);
        if (strlen($mainStr) < strlen($str)) return false;
        if (($loc + strlen($str)) > strlen($mainStr)) return false;
        return (strcmp(substr($mainStr, $loc, strlen($str)), $str) == 0);
    }
    

    Suggested by - jimmetry at gmail dot com

  2. Take note of the length parameter: “The default value is the largest of the length of the str compared to the length of main_str less the offset.”

    This is not the length of str as you might (I always) expect, so if you leave it out, you’ll get unexpected results. Example:

    PHP

    $hash = '$5$lalalalalalalala$crypt.output.here';
    
    // Output — int(34)
    var_dump(substr_compare($hash, '$5$', 0));
    
    // Output — int(0)
    var_dump(substr_compare($hash, '$5$', 0, 3));
    

    Suggested by - Skyborne

Further Reading

  1. You can read more about the PHP substr_compare() function on PHP.net.

Reader Comments

1. You can register or login to post a comment. Asking readers to register improves the quality of discussion.

2. As a registered user, you will also get to access features like choosing between a light and dark theme or anything else that we might implement in future.

Follow Us For Updates

FacebookTwitterGoogle+
Go To Top