strncasecmp()

Introduzione

strncasecmp() confronta i primi N caratteri di due stringhe ignorando maiuscole e minuscole. È il membro "limitato" e insensibile al maiuscolo/minuscolo della famiglia di funzioni PHP per il confronto di stringhe:

• Non distingue tra maiuscole e minuscole, come strcasecmp(): A e a sono considerate uguali.
• Esamina solo i primi $length caratteri, come strncmp(): il resto di ciascuna stringa viene ignorato.

In breve: strncasecmp() sta a strncmp() come strcasecmp() sta a strcmp(): stesso compito, ma la differenza tra maiuscole e minuscole viene eliminata prima del confronto. Questa pagina tratta la sintassi, il vero significato del valore restituito, diversi esempi eseguibili e le insidie in cui si inciampa spesso nel codice reale.

Sintassi

strncasecmp(string $string1, string $string2, int $length): int

La funzione restituisce un intero, non un booleano: è la causa più comune di bug in assoluto (vedi Gotchas).

Cosa significa il valore restituito

Il valore restituito indica una direzione, non un vero/falso:

Solo il segno è garantito dal contratto della funzione. Non fare affidamento sul valore esatto (le versioni più vecchie di PHP restituivano la differenza tra i primi byte diversi; PHP 8 può restituire -1/0/1). Verifica sempre il risultato con < 0, === 0 o > 0.

Esempio di base

<?php

$string1 = "Hello World";
$string2 = "hello world";
$length  = 5;

$result = strncasecmp($string1, $string2, $length);

if ($result < 0) {
    echo "The first $length characters of $string1 are less than those of $string2";
} elseif ($result > 0) {
    echo "The first $length characters of $string1 are greater than those of $string2";
} else {
    echo "The first $length characters of $string1 are equal to those of $string2";
}

I primi cinque caratteri sono Hello e hello. Poiché il confronto ignora maiuscole e minuscole, risultano uguali, quindi l'output è:

The first 5 characters of Hello World are equal to those of hello world

Come $length cambia il risultato

Vengono esaminati solo i primi $length caratteri: tutto ciò che si trova dopo quell'indice è invisibile al confronto. Questo rende strncasecmp() ideale per verificare i prefissi.

<?php

// "image/png" vs "IMAGE/JPEG"
var_dump(strncasecmp("image/png", "IMAGE/JPEG", 6) === 0); // compares "image/" — true
var_dump(strncasecmp("image/png", "IMAGE/JPEG", 9) === 0); // now "png" vs "JPE" differs — false

Output:

bool(true)
bool(false)

Con una lunghezza di 6 entrambe le stringhe condividono il prefisso image/ (dopo aver uniformato maiuscole e minuscole), quindi sono uguali. Estendendo la finestra a 9, i suffissi diversi (png contro jpe) le rendono diverse.

Uso pratico: verificare un prefisso senza distinguere maiuscole e minuscole

Un'esigenza molto comune nel mondo reale è "questa stringa inizia con X, a prescindere dalle maiuscole?", ad esempio per riconoscere lo schema in un URL.

<?php

function startsWithIgnoreCase(string $haystack, string $prefix): bool
{
    return strncasecmp($haystack, $prefix, strlen($prefix)) === 0;
}

var_dump(startsWithIgnoreCase("HTTPS://w3docs.com", "https://")); // true
var_dump(startsWithIgnoreCase("ftp://files.example", "https://")); // false

Output:

bool(true)
bool(false)

Passando strlen($prefix) come lunghezza si confronta esattamente il prefisso e nient'altro. In PHP 8 si potrebbe usare anche str_starts_with(), ma questa funzione distingue tra maiuscole e minuscole: strncasecmp() resta la scelta idiomatica quando le maiuscole devono essere ignorate.

Gotchas

• Restituisce un int, mai un bool. Scrivere if (strncasecmp($a, $b, 3)) fa entrare nel blocco quando le stringhe sono diverse (un valore diverso da zero è truthy) e lo salta quando sono uguali (0 è falsy): l'opposto di ciò che la maggior parte delle persone intende. Confronta sempre in modo esplicito: if (strncasecmp($a, $b, 3) === 0).
• Lavora sui byte e non supporta il multibyte. $length conta i byte e la normalizzazione di maiuscole e minuscole funziona solo per l'ASCII (A–Z). Per testi con accenti o in alfabeti non latini, usa prima mb_strtolower() su entrambi gli operandi, oppure le funzioni di confronto mb_*.
• Un $length maggiore di entrambe le stringhe non è un problema. Il confronto si ferma semplicemente alla fine della stringa più corta, senza leggere oltre i limiti.
• Le stringhe vuote risultano uguali con qualsiasi lunghezza. strncasecmp("", "", 5) restituisce 0.

Funzioni correlate

• strncmp(): stesso confronto limitato, ma sensibile a maiuscole e minuscole.
• strcasecmp(): confronto senza distinzione tra maiuscole e minuscole sull'intera stringa.
• strcmp(): confronto sensibile a maiuscole e minuscole sull'intera stringa.
• substr_compare(): confronta a partire da un offset arbitrario, con un flag opzionale per ignorare maiuscole e minuscole.
• strpos(): trova la posizione in cui una stringa compare all'interno di un'altra.

Conclusione

strncasecmp() confronta i primi $length caratteri di due stringhe ignorando maiuscole e minuscole e restituisce un numero negativo, 0 o un numero positivo per indicare l'ordine di ordinamento. Usala quando ti serve una verifica del prefisso senza distinzione tra maiuscole e minuscole o quando vuoi confrontare solo la parte iniziale di due stringhe. Ricorda che il risultato è un intero, quindi controlla sempre esplicitamente il suo segno, e che la funzione opera sui byte: per il testo multibyte ricorri alle funzioni mb_*.

Esercizi