substr_compare

(PHP 5, PHP 7, PHP 8)

substr_compare — Comparação binária de duas strings a partir de uma posição até n caracteres

Descrição

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

substr_compare() compara haystack a partir da posição offset com needle até length caracteres.

Parâmetros

haystack: A string principal a ser comparada.
needle: A string secundária a ser comparada.
offset: A posição inicial para a comparação. Se negativa, inicia contando da final da string.
length: O comprimento da comparação. O valor padrão é o maior comprimento entre o comprimento de needle comparado com o comprimento de haystack menos o offset.
case_insensitive: Se case_insensitive for true, a comparação é insensível a maiúsculas/minúsculas.

Valor Retornado

Retorna um valor menor que 0 se string1 for abaixo de string2; um valor maior que 0 se string1 for acima de string2 e 0 se elas forem iguais. Nenhum significado em particular pode ser inferido com confiança desse valor a não ser o seu sinal.

Se offset for igual a (antes do PHP 7.2.18, 7.3.5) ou maior que o comprimento de haystack, ou length estiver definido e menor que 0, substr_compare() mostra um alerta e retorna false.

Registro de Alterações

Versão	Descrição
8.2.0	Não é mais garantido que esta função retornará `strlen($string1) - strlen($string2)` quando os comprimentos das strings não forem iguais, mas ppodem agora retornar `-1` ou `1` no lugar.
8.0.0	`length` agora pode ser nulo.
7.2.18, 7.3.5	`offset` agora pode ser iagual ao comprimento de `haystack`.

Exemplos

Exemplo #1 Exemplo de substr_compare()

<?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); // alerta
?>

Veja Também

strncmp() - Comparação de strings segura para binários dos primeiros n caracteres

Melhore Esta Página

Aprenda Como Melhorar Esta Página • Envie uma Solicitação de Modificação • Reporte um Problema

＋adicione uma nota

Notas Enviadas por Usuários (em inglês) 3 notes

down

jimmetry at gmail dot com ¶

12 years ago

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);
}

?>

down

Skyborne ¶

12 years ago

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';
var_dump(substr_compare($hash, '$5$', 0)); # int(34)
var_dump(substr_compare($hash, '$5$', 0, 3)); # int(0)
var_dump(PHP_VERSION); # string(6) "5.3.14"
?>

down

bishop at php dot net ¶

8 years ago

This function efficiently implements checks for strings beginning or ending with other strings:

<?php

function str_begins($haystack, $needle) {
  return 0 === substr_compare($haystack, $needle, 0, strlen($needle));
}

function str_ends($haystack,  $needle) {
  return 0 === substr_compare($haystack, $needle, -strlen($needle));
}

var_dump(str_begins('http://example.com', 'https://'));

?>

Note that these are not multi-byte character set aware.

＋adicione uma nota