{"name":"numbers","intro":"Everything numeric that models get wrong for reasons that are not arithmetic: comparing `9.11` with `9.9` as decimals rather than version strings, rounding with a *stated* rule instead of whatever the language does, grouping digits the Indian way, and splitting an amount so the parts sum to the total exactly. Every value is parsed and computed as a `Decimal`, never a float, and inputs like `₹1.2 Cr`, `2.5k`, `(500)` and `12%` are understood.","when_to_use":["Comparing or ordering numbers that arrive as strings.","Rounding when the tie-breaking rule matters — invoices, tax, prices.","Formatting for a locale or a currency, including Indian lakh/crore grouping.","Splitting a total across parts or weights so the shares reconcile to the cent.","Reading messy human numbers, and spelling amounts out in words for documents."],"network":false,"related":"[`math`](/docs/tools/math) for the arithmetic itself · [`convert`](/docs/tools/convert) for units and currency conversion · [`collections`](/docs/tools/collections) `aggregate` for sums across records.","docs_url":"/docs/tools/numbers","modes":[{"name":"compare","purpose":"Order two or more numbers, exactly.","description":"Parses every value as a decimal and returns them sorted ascending and descending, the min and max, a readable `ordering` chain, and — for exactly two values — the relation, the difference and the percentage change. This is the `9.11 < 9.9` test: string comparison and version-number instinct both get it wrong.","parameters":[{"name":"values","type":"array","required":true,"doc":"Two or more values. Strings, numbers, `₹1.2 Cr`, `2.5k`, `12%`, `(500)`.","default":null},{"name":"a","type":"string \\| number \\| integer","required":false,"doc":"First value, as an alternative to `values`.","default":null},{"name":"b","type":"string \\| number \\| integer","required":false,"doc":"Second value, as an alternative to `values`.","default":null}],"examples":[{"mode":"compare","values":["9.11","9.9"]},{"mode":"compare","values":["1.2 Cr","₹15,00,000","2.5k","0.03 bn"]},{"mode":"compare","a":"1,250.50","b":"1,499.99"},{"mode":"compare","values":["nine point one","9.9"]}]},{"name":"round","purpose":"Round with an explicitly named rule.","description":"Rounds to decimal places, to significant figures (`significant`) or to a step (`nearest`, e.g. 0.05 for cash rounding). `rounding` names the tie-break: `half_up`, `half_even` (bankers'), `half_down`, `floor`, `ceil`, `truncate`. The default is `half_up` — and the response points out that Python's own `round()` is `half_even`, which is why 2.5 and 0.5 disagree between systems.","parameters":[{"name":"value","type":"string \\| number \\| integer","required":true,"doc":"The value to round.","default":null},{"name":"decimals","type":"integer","required":false,"doc":"Decimal places.","default":"0"},{"name":"significant","type":"integer","required":false,"doc":"Round to this many significant figures instead.","default":null},{"name":"nearest","type":"number","required":false,"doc":"Round to the nearest multiple of this.","default":null},{"name":"rounding","type":"string","required":false,"doc":"Tie-break rule.","default":"`half_up`"}],"examples":[{"mode":"round","value":123.456,"significant":2,"decimals":5},{"mode":"round","value":"2.5","decimals":0},{"mode":"round","value":"2.5","decimals":0,"rounding":"half_even"},{"mode":"round","value":"1234.5678","significant":3},{"mode":"round","value":"12.327","nearest":"0.05"},{"mode":"round","value":"2.5","rounding":"cosmic"},{"mode":"round","value":"2.5","significant":0},{"mode":"round","value":"2.5","nearest":0},{"mode":"round","value":"two and a half"}]},{"name":"format","purpose":"Present a number for a locale, currency or style.","description":"Groups digits the way a locale does — `12,34,567.89` for `en_IN`, `1.234.567,89` for `de_DE`, thin-space groups for `fr_FR` — and applies a `style`: `number`, `currency`, `percent` or `compact`. Compact notation follows the locale too: `1.2 Cr` for India, `12M` elsewhere. `accounting: true` wraps negatives in parentheses.","parameters":[{"name":"value","type":"string \\| number \\| integer","required":true,"doc":"The value to format.","default":null},{"name":"locale","type":"string","required":false,"doc":"`en_IN`, `en_US`, `de_DE`, `fr_FR`, `de_CH`, `ja_JP`…","default":"`en_US`"},{"name":"style","type":"string","required":false,"doc":"Presentation style.","default":"`number`"},{"name":"currency","type":"string","required":false,"doc":"ISO code, for `style: currency` or `compact`.","default":null},{"name":"decimals","type":"integer","required":false,"doc":"Decimal places.","default":"style-dependent"},{"name":"accounting","type":"boolean","required":false,"doc":"Show negatives in parentheses.","default":"`false`"}],"examples":[{"mode":"format","value":12345678.9,"locale":"en_IN"},{"mode":"format","value":12345678.9,"locale":"de_DE"},{"mode":"format","value":"1234567.891","locale":"en_IN","style":"currency","currency":"INR"},{"mode":"format","value":12345678,"locale":"en_IN","style":"compact","currency":"INR"},{"mode":"format","value":"-0.0725","style":"percent","accounting":true},{"mode":"format","value":1234.5,"locale":"xx_YY"},{"mode":"format","value":"lots"}]},{"name":"allocate","purpose":"Split a total so the parts sum exactly to it.","description":"Divides a total into parts whose shares add up to the total exactly — no missing cent, no extra one. Split equally with `parts`, or proportionally with `weights` (a list, or a `{label: weight}` map) or `percentages`. Leftover minor units go to the largest fractional remainders by default; `method: first` or `last` puts them all in one place instead. Each item reports its exact unrounded share and whether it was adjusted, so the arithmetic is auditable. `parts` is capped at 10 000.","parameters":[{"name":"total","type":"string \\| number \\| integer","required":true,"doc":"The amount to divide.","default":null},{"name":"parts","type":"integer","required":false,"doc":"Split equally into this many parts.","default":null},{"name":"weights","type":"array \\| object","required":false,"doc":"Proportional weights, or a `{label: weight}` map.","default":null},{"name":"percentages","type":"array","required":false,"doc":"Weights that must sum to 100.","default":null},{"name":"labels","type":"string[]","required":false,"doc":"Names for the parts.","default":null},{"name":"decimals","type":"integer","required":false,"doc":"Minor-unit precision.","default":"2"},{"name":"method","type":"string","required":false,"doc":"Where leftover units go.","default":"`largest_remainder`"}],"examples":[{"mode":"allocate","total":100,"parts":1000000},{"mode":"allocate","total":100,"parts":3},{"mode":"allocate","total":"10000","weights":{"alice":3,"bob":2,"carol":1}},{"mode":"allocate","total":"1250.75","percentages":[50,30,20],"labels":["rent","food","savings"]},{"mode":"allocate","total":100,"parts":3,"method":"first"},{"mode":"allocate","total":100,"percentages":[50,30,10]},{"mode":"allocate","total":100},{"mode":"allocate","total":100,"weights":[1,2,3],"labels":["a","b"]},{"mode":"allocate","total":100,"weights":[3,-1]},{"mode":"allocate","total":100,"weights":[0,0]},{"mode":"allocate","total":100,"parts":3,"method":"random"}]},{"name":"sequence","purpose":"Generate a numeric sequence and its sum.","description":"Builds a sequence and returns its terms, count, sum and last term — all as exact decimals. `kind` selects the family: `arithmetic`, `geometric`, `range`, `fibonacci`, `primes`, `squares`. Arithmetic sequences take either `n` or an `end`; sequences are capped at 10 000 terms, and separately at 1 000 digits in the largest term — `geometric` with ratio 2 and n 10 000 ends at 2^10000, which is refused with `too_large`.","parameters":[{"name":"kind","type":"string","required":false,"doc":"`arithmetic`, `geometric`, `range`, `fibonacci`, `primes`, `squares`.","default":"`arithmetic`"},{"name":"start","type":"string \\| number \\| integer","required":false,"doc":"First term.","default":"0 (1 for geometric)"},{"name":"step","type":"string \\| number \\| integer","required":false,"doc":"Common difference, for `arithmetic` and `range`.","default":"1"},{"name":"ratio","type":"string \\| number \\| integer","required":false,"doc":"Common ratio, for `geometric`.","default":"2"},{"name":"end","type":"string \\| number \\| integer","required":false,"doc":"Last value, for `arithmetic` and `range`.","default":null},{"name":"n","type":"integer","required":false,"doc":"Number of terms, 1..10000.","default":null}],"examples":[{"mode":"sequence","kind":"geometric","start":2,"ratio":2,"n":10000},{"mode":"sequence","kind":"arithmetic","start":100,"step":25,"n":6},{"mode":"sequence","kind":"range","start":"0","end":"2","step":"0.5"},{"mode":"sequence","kind":"fibonacci","n":12},{"mode":"sequence","kind":"geometric","start":"1000","ratio":"1.08","n":5},{"mode":"sequence","kind":"harmonic","n":5},{"mode":"sequence","kind":"arithmetic","start":1,"step":0,"end":10},{"mode":"sequence","kind":"fibonacci","n":20000}]},{"name":"parse","purpose":"Read a messy human number into a decimal.","description":"Turns written numbers into decimals and says how it read them. Currency symbols, Indian and international digit grouping, magnitude suffixes (`k`, `M`, `bn`, `L`, `Cr`), trailing percent signs and accounting parentheses are all understood, and each interpretation lands in `assumptions`. Pass `values` to parse a batch in one call.","parameters":[{"name":"value","type":"string \\| number \\| integer","required":false,"doc":"One value to parse.","default":null},{"name":"values","type":"array","required":false,"doc":"Several values; the result becomes a list.","default":null}],"examples":[{"mode":"parse","value":"₹1.2 Cr"},{"mode":"parse","values":["(500)","12%","1,23,456.78","2.5k","1234,56"]},{"mode":"parse","value":"twelve"},{"mode":"parse","value":"1,23.45.6"},{"mode":"parse","value":"5 zillion"}]},{"name":"to_words","purpose":"Spell an amount out in words.","description":"Writes a number in words, in the international system (thousand / million / billion) or the Indian one (thousand / lakh / crore). With `currency` the output becomes the cheque-and-invoice form — “Rupees … only”, with the minor units named — and the rounding of those minor units is stated in `assumptions`.","parameters":[{"name":"value","type":"string \\| number \\| integer","required":true,"doc":"The amount.","default":null},{"name":"system","type":"string","required":false,"doc":"Numbering system.","default":"`international`"},{"name":"currency","type":"string","required":false,"doc":"ISO code; switches to the currency phrasing.","default":null},{"name":"suffix_only","type":"boolean","required":false,"doc":"Append “only”, as invoices do.","default":"`true`"}],"examples":[{"mode":"to_words","value":1234567,"system":"international"},{"mode":"to_words","value":1234567,"system":"indian"},{"mode":"to_words","value":"125430.75","system":"indian","currency":"INR"},{"mode":"to_words","value":"-42.5"},{"mode":"to_words","value":1234,"system":"roman"},{"mode":"to_words","value":"a lot"}]},{"name":"semver","purpose":"Order version strings the SemVer way.","description":"Compares or sorts version strings as versions, not decimals — `1.10` is newer than `1.9`. Precedence follows SemVer 2.0: major, minor, patch numerically; a release above every pre-release of it; pre-release identifiers left to right, numeric ones numerically and before alphanumeric ones, a shorter prefix first. Build metadata (`+…`) is returned but never decides the order. A leading `v` and a missing minor or patch are tolerated and recorded in `assumptions`.","parameters":[{"name":"values","type":"array","required":false,"doc":"Two or more version strings.","default":null},{"name":"a","type":"string \\| number \\| integer","required":false,"doc":"First version, with `b`; gives a `relation`.","default":null},{"name":"b","type":"string \\| number \\| integer","required":false,"doc":"Second version.","default":null}],"examples":[{"mode":"semver","a":"1.9","b":"1.10"},{"mode":"semver","values":["1.0.0","1.0.0-rc.1","1.0.0-beta.11","1.0.0-beta.2","1.0.0-alpha"]},{"mode":"semver","values":["v2.1.0+build.7","2.1.0+build.9","2.0.9"]},{"mode":"semver","values":["1.2.3","latest"]}]}]}