{
"title": "strcmpi",
"category": "strings/core",
"keywords": [
"strcmpi",
"case insensitive compare",
"string compare",
"text equality",
"cell array"
],
"summary": "Compare text inputs for equality without considering letter case, matching MATLAB's `strcmpi` semantics.",
"references": [
"https://www.mathworks.com/help/matlab/ref/strcmpi.html"
],
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [],
"broadcasting": "matlab",
"notes": "Runs on the host; GPU inputs are gathered automatically before comparison so results match MATLAB exactly."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 2,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::strings::core::strcmpi::tests",
"integration": "builtins::strings::core::strcmpi::tests::strcmpi_cell_array_scalar_casefold"
},
"description": "`strcmpi(a, b)` compares text values without considering letter case. It returns logical `true` when inputs match case-insensitively and `false` otherwise. Supported text types mirror MATLAB: string scalars/arrays, character vectors and arrays, and cell arrays filled with character vectors.",
"behaviors": [
"**Case-insensitive**: Letter case is ignored. `\"RunMat\"`, `\"runmat\"`, and `\"RUNMAT\"` all compare equal.",
"**Accepted text types**: Works with string arrays, character vectors or matrices, and cell arrays of character vectors. Mixed combinations are normalised automatically.",
"**Implicit expansion**: Scalar operands expand against array operands so element-wise comparisons follow MATLAB broadcasting rules.",
"**Character arrays**: Rows are compared individually. Results are column vectors whose length equals the number of rows in the character array.",
"**Cell arrays**: Each cell is treated as a text scalar. Scalar cells expand across the other operand before comparison.",
"**Missing strings**: Elements whose value is `missing` (`\"<missing>\"`) always compare unequal, even to other missing values, matching MATLAB.",
"**Result form**: Scalar comparisons return logical scalars. Otherwise the result is a logical array that matches the broadcast shape."
],
"examples": [
{
"description": "Compare Two Strings Ignoring Case",
"input": "tf = strcmpi(\"RunMat\", \"runmat\")",
"output": "tf = logical\n 1"
},
{
"description": "Find Case-Insensitive Matches Inside a String Array",
"input": "colors = [\"Red\" \"GREEN\" \"blue\"];\nmask = strcmpi(colors, \"green\")",
"output": "mask = 1×3 logical array\n 0 1 0"
},
{
"description": "Compare Character Array Rows Without Case Sensitivity",
"input": "animals = char(\"Cat\", \"DOG\", \"cat\");\ntf = strcmpi(animals, \"cAt\")",
"output": "tf = 3×1 logical array\n 1\n 0\n 1"
},
{
"description": "Compare Cell Arrays Of Character Vectors Case-Insensitively",
"input": "C1 = {'north', 'East', 'SOUTH'};\nC2 = {'NORTH', 'east', 'west'};\ntf = strcmpi(C1, C2)",
"output": "tf = 1×3 logical array\n 1 1 0"
},
{
"description": "Broadcast A String Scalar Against A Character Matrix",
"input": "patterns = char(\"alpha\", \"BETA\");\ntf = strcmpi(patterns, [\"ALPHA\" \"beta\"])",
"output": "tf = 2×2 logical array\n 1 0\n 0 1"
},
{
"description": "Handle Missing Strings In Case-Insensitive Comparisons",
"input": "values = [\"Active\" missing];\nmask = strcmpi(values, \"active\")",
"output": "mask = 1×2 logical array\n 1 0"
}
],
"faqs": [
{
"question": "Does `strcmpi` support string arrays, character arrays, and cell arrays?",
"answer": "Yes. All MATLAB-supported text containers are accepted, and mixed combinations are handled automatically with implicit expansion."
},
{
"question": "Is whitespace significant when comparing character arrays?",
"answer": "Yes. Trailing spaces or different lengths make rows unequal, just like `strcmp`. Use `strtrim` or `strip` if you need to ignore whitespace."
},
{
"question": "Do missing strings compare equal?",
"answer": "No. The `missing` sentinel compares unequal to all values, including another missing string scalar."
},
{
"question": "Can I compare complex numbers or numeric arrays with `strcmpi`?",
"answer": "No. Both arguments must contain text. Numeric inputs produce a descriptive MATLAB-style error."
},
{
"question": "How are GPU inputs handled?",
"answer": "They are gathered to the CPU automatically before comparison. Providers do not need to implement additional kernels for `strcmpi`."
},
{
"question": "What is returned when both inputs are scalars?",
"answer": "A logical scalar is returned (`true` or `false`). For non-scalar shapes, a logical array that mirrors the broadcast dimensions is produced."
},
{
"question": "What is `strcmpi` in MATLAB?",
"answer": "— `strcmpi(s1, s2)` compares two text values for equality while ignoring letter case. It returns `true` when the strings match case-insensitively and `false` otherwise. The `i` stands for *insensitive*. Use `strcmp` when you do want case to matter, and `strncmpi` when you only want to compare the first `n` characters."
},
{
"question": "How does `strcmpi` behave with cell arrays or string arrays?",
"answer": "— When one operand is a cell array or string array and the other is a scalar, `strcmpi` broadcasts the scalar elementwise and returns a logical array of the same shape. For example:\n\n```matlab\nstrcmpi({'apple','Banana','CHERRY'}, 'banana')\n% ans = 1x3 logical array\n% 0 1 0\n```\n\nWhen both operands are arrays of the same shape, they are compared element-by-element. This matches MATLAB's implicit-expansion rules."
},
{
"question": "Does `strcmpi` work across mixed char/string inputs?",
"answer": "— Yes. Character vectors (`'Hello'`), string scalars (`\"Hello\"`), and cells of character vectors all interoperate, so `strcmpi('hello', \"Hello\")` returns `true`. Note that `strcmpi` only tests **exact equality** (ignoring case). For case-insensitive *substring* matching, use `contains(str, pattern, 'IgnoreCase', true)` or `regexpi`."
}
],
"links": [
{
"label": "strcmp",
"url": "./strcmp"
},
{
"label": "contains",
"url": "./contains"
},
{
"label": "startswith",
"url": "./startswith"
},
{
"label": "endswith",
"url": "./endswith"
},
{
"label": "strip",
"url": "./strip"
},
{
"label": "char",
"url": "./char"
},
{
"label": "compose",
"url": "./compose"
},
{
"label": "num2str",
"url": "./num2str"
},
{
"label": "sprintf",
"url": "./sprintf"
},
{
"label": "str2double",
"url": "./str2double"
},
{
"label": "string.empty",
"url": "./string.empty"
},
{
"label": "string",
"url": "./string"
},
{
"label": "strings",
"url": "./strings"
},
{
"label": "strlength",
"url": "./strlength"
},
{
"label": "strncmp",
"url": "./strncmp"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/strings/core/strcmpi.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/strings/core/strcmpi.rs"
},
"gpu_residency": "You rarely need to call `gpuArray` manually. When inputs already live on the GPU, RunMat gathers them before calling `strcmpi`, then returns a logical result on the host. This matches MATLAB’s behaviour while keeping the runtime simple. Subsequent GPU-aware code can explicitly transfer results back if needed.",
"gpu_behavior": [
"`strcmpi` is registered as an acceleration sink. When either operand resides on the GPU, RunMat gathers both to host memory before comparing them. This keeps behaviour identical to MATLAB and avoids requiring backend-specific kernels. The logical result is produced on the CPU and never remains GPU-resident."
],
"syntax": {
"example": {
"description": "Syntax",
"input": "tf = strcmpi(s1, s2)"
},
"points": [
"`s1` and `s2` are the text values to compare. Accepted types: character vector (`'abc'`), character matrix (`char(...)`), string scalar or array (`\"abc\"`, `[\"a\" \"b\"]`), or cell array of character vectors (`{'a','b'}`). Types can be mixed — `strcmpi('hello', \"Hello\")` returns `true`.",
"When one operand is a scalar (a single string or `1×1` cell/string) and the other is an array/cell of strings, MATLAB broadcasts the scalar elementwise across the array. For same-shape arrays, comparison is elementwise.",
"Returns `tf`, a logical scalar when both inputs are scalars, or a logical array whose shape matches the broadcast result. `missing` string values always compare unequal, mirroring MATLAB.",
"For exact (case-sensitive) equality use `strcmp`. For case-insensitive *substring* matching (rather than full equality), use `contains(s, pattern, 'IgnoreCase', true)` or `regexpi`."
]
}
}