# Natural compare

`natural-compare` · version 1.0.0 · Text · free, no key needed

Compare two strings by deterministic natural order, treating ASCII digit runs numerically; returns -1, 0, or 1.

**Use when you need to: compare two filenames naturally · does file2 sort before file10 · natural string comparator.**

## Decide before calling

Read the [versioned contract](/v1/tools/natural-compare/versions/1.0.0) and the supported scope below. Reuse `natural-compare@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `natural-compare@1.0.0` for compare two filenames naturally. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- compare two filenames naturally
- does file2 sort before file10
- natural string comparator
- compare text with embedded numbers
- human friendly string comparison
- case insensitive natural compare
- compare numeric chunks in strings
- natural order leading zero comparison

## Not supported

- locale-aware collation or full Unicode Collation Algorithm
- non-ASCII numeric digits, signed numbers, decimals, or scientific notation
- Unicode normalization

## Behavior

- Maximal ASCII digit runs compare by exact numeric value using significant length and digits, never binary floating point.
- Equal numeric values use leading_zeros: shorter_first by default, longer_first, or ignore.
- case_fold defaults false; true folds ASCII A-Z only, with original code points as the deterministic secondary tie-break.
- Non-digits compare by Unicode code point. This is not full UCA collation and does not normalize text.
- Every success returns standard_version "ComputeFirst R92 natural order algorithm 1.0.0".

## Input

- `left` (string, required): max length 1024
- `right` (string, required): max length 1024
- `case_fold` (boolean, optional)
- `leading_zeros` (one of "shorter_first", "longer_first", "ignore", optional)

## Output

- `comparison` (integer, required): min -1; max 1
- `standard_version` (constant "ComputeFirst R92 natural order algorithm 1.0.0", required)

## Limits

- max input bytes: 2048
- max string bytes: 1024
- max iterations: 4096
- max output bytes: 128

## Example

Request input:

```json
{
  "left": "file2",
  "right": "file10"
}
```

Response:

```json
{
  "result": {
    "comparison": -1,
    "standard_version": "ComputeFirst R92 natural order algorithm 1.0.0"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "natural-compare",
  "version": "1.0.0",
  "input": {
    "left": "file2",
    "right": "file10"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/natural-compare/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"left":"file2","right":"file10"}'
```

The machine-readable contract is at [/v1/tools/natural-compare/versions/1.0.0](/v1/tools/natural-compare/versions/1.0.0).

### CLI

```sh
node cli.mjs run natural-compare 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Natural sort strings](/tools/natural-sort-strings): Sort strings by natural order (file2 before file10); returns the ordered strings and standard version.
- [Text shingle similarity](/tools/text-shingle-similarity): Exact shingle-set resemblance (Jaccard) and containment of two texts, with counts and shared shingles.
- [Bleu smoothing compute](/tools/bleu-smoothing-compute): Apply none or Chen-Cherry smoothing 1-3 to BLEU match/total counts; return smoothed counts, BP and BLEU.
- [Chrf plus plus compute](/tools/chrf-plus-plus-compute): Compute exact chrF++ (character 6-grams plus word 1-2-grams, Popovic 2017) with the word tokens it scored.
- [Citation anchor check](/tools/citation-anchor-check): Check a quote anchor (exact text plus prefix/suffix) matches exactly one place in a supplied source version.
- [Jaro similarity compute](/tools/jaro-similarity-compute): Compute Jaro similarity with a deterministic match window and exact reduced rational audit fields.