{
"title": "strncmp",
"category": "strings/core",
"keywords": [
"strncmp",
"string compare",
"prefix",
"text equality",
"case-sensitive"
],
"summary": "Compare text inputs for equality up to N leading characters with MATLAB-compatible broadcasting.",
"references": [
"https://www.mathworks.com/help/matlab/ref/strncmp.html"
],
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [],
"broadcasting": "matlab",
"notes": "Executes on the CPU. GPU-resident inputs are gathered automatically so prefix comparisons match MATLAB exactly."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 3,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::strings::core::strncmp::tests",
"integration": "builtins::strings::core::strncmp::tests::strncmp_char_array_rows"
},
"description": "`strncmp(A, B, N)` compares text values element-wise and returns logical `true` when the first `N` characters of the corresponding elements are identical. Comparisons are case-sensitive and respect MATLAB's implicit expansion rules across strings, character arrays, and cell arrays of character vectors.",
"behaviors": [
"**Accepted text types**: String scalars/arrays, character vectors or character arrays, and cell arrays of character vectors.",
"**Scalar `N` requirement**: The third argument must evaluate to a finite, nonnegative integer scalar. Numeric, logical, and scalar tensor/logical-array values are accepted when they convert cleanly.",
"**Implicit expansion**: Scalars expand to match the size of the other operand before comparison.",
"**Character arrays**: Rows are treated as independent character vectors. Each row is compared against the other operand and the result is returned as a column vector.",
"**Unicode-aware comparisons**: Prefixes are counted in MATLAB characters (Unicode scalar values), so multi-byte UTF-8 sequences are handled transparently.",
"**Prefix length semantics**: If `N` is `0`, every comparison evaluates to `true`. If either text element is shorter than `N`, it must match exactly up to the end of the shorter value and the longer value must also end within `N` characters to be considered equal.",
"**Missing strings**: Any comparison involving a missing string returns `false` unless `N == 0`.",
"**Result type**: Scalar comparisons return logical scalars. Array comparisons return logical arrays that follow MATLAB's column-major ordering."
],
"examples": [
{
"description": "Checking whether two strings share a prefix",
"input": "tf = strncmp(\"RunMat\", \"Runway\", 3)",
"output": "tf = logical\n 1"
},
{
"description": "Comparing string arrays with implicit expansion",
"input": "names = [\"north\" \"south\" \"east\"];\ntf = strncmp(names, \"no\", 2)",
"output": "tf = 1×3 logical array\n 1 0 0"
},
{
"description": "Comparing rows of a character array",
"input": "animals = char(\"cat\", \"camel\", \"cow\");\ntf = strncmp(animals, \"ca\", 2)",
"output": "tf = 3×1 logical array\n 1\n 1\n 0"
},
{
"description": "Comparing cell arrays element-wise",
"input": "C1 = {'red', 'green', 'blue'};\nC2 = {'rose', 'grey', 'black'};\ntf = strncmp(C1, C2, 2)",
"output": "tf = 1×3 logical array\n 1 0 0"
},
{
"description": "Handling zero-length comparisons",
"input": "tf = strncmp(\"alpha\", \"omega\", 0)",
"output": "tf = logical\n 1"
}
],
"faqs": [
{
"question": "What argument types does `strncmp` accept?",
"answer": "String arrays, character vectors/arrays, and cell arrays of character vectors. Mixed combinations are converted automatically. The third argument `N` must be a nonnegative integer scalar."
},
{
"question": "Is the comparison case-sensitive?",
"answer": "Yes. Use `strncmpi` if you need a case-insensitive prefix comparison."
},
{
"question": "What happens when `N` is zero?",
"answer": "The builtin returns `true` for every element because zero leading characters are compared."
},
{
"question": "How are shorter strings handled when `N` is larger than their length?",
"answer": "The shorter value must match the longer value exactly for its entire length, and the longer value must not have additional characters within the first `N` positions. Otherwise the comparison returns `false`."
},
{
"question": "How are missing string values treated?",
"answer": "Any comparison that involves a missing string returns `false`, except when `N` is zero (because no characters are compared)."
},
{
"question": "Does `strncmp` produce logical results?",
"answer": "Yes. Scalar comparisons yield logical scalars; array inputs produce logical arrays that follow MATLAB’s column-major ordering."
}
],
"links": [
{
"label": "strcmp",
"url": "./strcmp"
},
{
"label": "strcmpi",
"url": "./strcmpi"
},
{
"label": "contains",
"url": "./contains"
},
{
"label": "startswith",
"url": "./startswith"
},
{
"label": "strlength",
"url": "./strlength"
},
{
"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"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/strings/core/strncmp.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/strings/core/strncmp.rs"
},
"gpu_residency": "No. If you pass GPU-resident data, RunMat automatically gathers it to host memory before running `strncmp`. The builtin is an acceleration sink and always returns host logical outputs. Explicit `gpuArray` / `gather` calls are only required for compatibility with legacy MATLAB workflows.",
"gpu_behavior": [
"`strncmp` is registered as an acceleration **sink**. When any operand resides on the GPU, RunMat gathers all inputs back to host memory before performing the comparison so that the behaviour matches MATLAB exactly. The logical result is always returned on the host. Providers do not need to supply specialised kernels."
]
}