strncmpi

Compare first n characters of strings (case insensitive)

Syntax

tf = strncmpi(s1,s2,n)

Description

tf = strncmpi(s1,s2,n) compares up to n characters of s1 and s2, ignoring any differences in letter case, and returns true(1) if the two are identical and false(0) otherwise. Text is considered identical if the content of each is the same up to the end or the first n characters, whichever comes first, ignoring case. The return result tf is of data type logical.

The first two input arguments can be any combination of string arrays, character vectors, and cell arrays of character vectors.

Examples

Compare First N Characters While Ignoring Case

Create two character vectors. Compare the first four characters of each, ignoring case.

s1 = 'DATA.TAR.GZ';
s2 = 'data-samples.xls';

tf = strncmpi(s1,s2,4)

tf = logical
   1

tf is 1 because s1 starts with 'DATA', and s2 starts with 'data'.

Find Starting Text While Ignoring Case

Create a string array that contains names. Find the names that start with 'JEAN', ignoring case.

s1 = ["Jacques";
      "Jean";
      "Jeanne";
      "Jean-Luc";
      "Julie"];
s2 = "JEAN";

tf = strncmpi(s1,s2,4)

tf = 5×1 logical array

   0
   1
   1
   1
   0

tf is 1 for all names whose first four characters match 'JEAN' when you ignore case.

Alternatively, you can use the startsWith function.

tf = startsWith(s1,s2,'IgnoreCase',true)

tf = 5×1 logical array

   0
   1
   1
   1
   0

Input Arguments

s1,s2 — Input text

character vector | character array | cell array of character vectors | string array

Input text, with each input specified as a character vector, a character array, a cell array of character vectors, or a string array. The order of the inputs does not affect the comparison results.

• If both s1 and s2 are string arrays or cell arrays of character vectors, then s1 and s2 must be the same size, unless one of them is scalar.

• If both s1 and s2 are character arrays with multiple rows, then s1 and s2 can have different numbers of rows.

• When comparing a nonscalar cell array of character vectors or string array to a multirow character array, the cell array or string array must be a column vector with the same number of rows as the character array.

Data Types: char | cell | string

n — Maximum number of characters to compare

integer

Maximum number of characters to compare, specified as an integer.

• If n is 0, then strncmpi always returns true(1). By convention, the zeroth character of a character vector or a string scalar is always '', a 0-by-0 character array.

• If n is less than 0, then strncmpi treats it as 0.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

tf — True or false result

true(1) | false(0) | logical array

True or false result, returned as true(1) or false(0) or as a logical array.

• If each input is either a string scalar or a character vector, then tf is a scalar.

• If at least one input is either a string array or a cell array of character vectors, then tf is an array the same size as the input array.

• If one input is a character array with multiple rows, and the other input is either a scalar cell or a string scalar, then tf is an n-by-1 array, where n is the number of rows in the character array.

• If both inputs are character arrays, tf is a scalar.

Tips

• The strncmpi function is intended for comparison of text. If used on numeric arrays, strncmpi always returns false(0).

• For case-sensitive text comparison, use strncmp instead of strncmpi.

• Although strncmpi shares a name with a C function, it does not follow the C language convention of returning 0 when the text inputs match.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The strncmpi function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Enumeration inputs are not supported.

• Input values from the char class must be in the range 0-127.

• When one input is a cell array and the other input is a character array, the character array must be a compile-time row vector.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

• s1 and s2 must be string arrays or cell arrays of character vectors.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a