Converts a string to a number, like an enhanced version of parseFloat. Returns NaN if the provided string does not resemble a number.
In addition to plain integers and decimals, numeric-quantity handles:
- Fractions and mixed numbers:
'1 2/3'→1.667,'1⅖'→1.4,'1 2⁄3'→1.667 - Separators:
'1,000'→1000,'1_000_000'→1000000 - Roman numerals (see option below):
'XIV'→14,'Ⅻ'→12 - Non-ASCII numerals: Arabic-Indic (
'٣'), Devanagari ('३'), Bengali, Thai, Fullwidth, and 70+ other Unicode digit scripts
For the inverse operation—converting a number to an imperial measurement—check out format-quantity.
For a more complete solution to parsing recipe ingredients, try parse-ingredient.
import { numericQuantity } from 'numeric-quantity';
console.log(numericQuantity('1 1/2')); // 1.5
console.log(numericQuantity('2 2/3')); // 2.667As an ES module:
<script type="module">
import { numericQuantity } from 'https://cdn.jsdelivr.net/npm/numeric-quantity/+esm';
console.log(numericQuantity('10½')); // 10.5
</script>As UMD (all exports are properties of the global object NumericQuantity):
<script src="https://unpkg.com/numeric-quantity"></script>
<script>
console.log(NumericQuantity.numericQuantity('xii', { romanNumerals: true })); // 12
</script>All options are passed as the second argument to numericQuantity (and isNumericQuantity).
Results are rounded to three decimal places by default. Use the round option to change this behavior.
numericQuantity('1/3'); // 0.333 (default: 3 decimal places)
numericQuantity('1/3', { round: 5 }); // 0.33333
numericQuantity('1/3', { round: false }); // 0.3333333333333333By default, strings with trailing non-numeric characters return NaN. Set allowTrailingInvalid: true to ignore trailing invalid characters, similar to parseFloat.
numericQuantity('100abc'); // NaN
numericQuantity('100abc', { allowTrailingInvalid: true }); // 100Parse Roman numerals (ASCII or Unicode) by setting romanNumerals: true. You can also use parseRomanNumerals directly.
numericQuantity('MCCXIV', { romanNumerals: true }); // 1214
numericQuantity('Ⅻ', { romanNumerals: true }); // 12
numericQuantity('xiv', { romanNumerals: true }); // 14 (case-insensitive)For European-style numbers where comma is the decimal separator, set decimalSeparator: ','.
numericQuantity('1,5'); // 15 (comma treated as thousands separator)
numericQuantity('1,5', { decimalSeparator: ',' }); // 1.5
numericQuantity('1.000,50', { decimalSeparator: ',' }); // 1000.5When parsing integers that exceed Number.MAX_SAFE_INTEGER or are less than Number.MIN_SAFE_INTEGER, set bigIntOnOverflow: true to return a bigint instead.
numericQuantity('9007199254740992'); // 9007199254740992 (loses precision)
numericQuantity('9007199254740992', { bigIntOnOverflow: true }); // 9007199254740992nParse percentage strings by setting the percentage option. Use 'decimal' (or true) to divide by 100, or 'number' to just strip the % symbol.
numericQuantity('50%'); // NaN
numericQuantity('50%', { percentage: true }); // 0.5
numericQuantity('50%', { percentage: 'decimal' }); // 0.5
numericQuantity('50%', { percentage: 'number' }); // 50
numericQuantity('1/2%', { percentage: true }); // 0.005Strip currency symbols from the start or end of the string by setting allowCurrency: true. Supports all Unicode currency symbols ($, €, £, ¥, ₹, ₽, ₿, ₩, etc.).
numericQuantity('$100'); // NaN
numericQuantity('$100', { allowCurrency: true }); // 100
numericQuantity('€1.000,50', { allowCurrency: true, decimalSeparator: ',' }); // 1000.5
numericQuantity('100€', { allowCurrency: true }); // 100
numericQuantity('-$50', { allowCurrency: true }); // -50Set verbose: true to return a detailed result object instead of just the numeric value. This is useful for understanding what was parsed and stripped.
numericQuantity('$50%', {
verbose: true,
allowCurrency: true,
percentage: true,
});
// {
// value: 0.5,
// input: '$50%',
// currencyPrefix: '$',
// percentageSuffix: true
// }
numericQuantity('100abc', {
verbose: true,
allowTrailingInvalid: true,
});
// {
// value: 100,
// input: '100abc',
// trailingInvalid: 'abc'
// }For fraction and mixed-number inputs, the result also includes parsed fraction components (always unsigned):
numericQuantity('1 2/3', { verbose: true });
// {
// value: 1.667,
// input: '1 2/3',
// whole: 1,
// numerator: 2,
// denominator: 3
// }
numericQuantity('½', { verbose: true });
// {
// value: 0.5,
// input: '½',
// numerator: 1,
// denominator: 2
// }The verbose result object has the following shape:
interface NumericQuantityVerboseResult {
value: number | bigint; // The parsed value (NaN if invalid)
input: string; // Original input string
currencyPrefix?: string; // Currency symbol(s) stripped from start
currencySuffix?: string; // Currency symbol(s) stripped from end
percentageSuffix?: boolean; // True if "%" was stripped
trailingInvalid?: string; // Characters ignored (if allowTrailingInvalid)
sign?: '-' | '+'; // Leading sign character, if present
whole?: number; // Whole part of a mixed fraction (e.g. 1 from "1 2/3")
numerator?: number; // Fraction numerator (e.g. 2 from "1 2/3")
denominator?: number; // Fraction denominator (e.g. 3 from "1 2/3")
}Returns true if the string can be parsed as a valid number, false otherwise. Accepts the same options as numericQuantity.
import { isNumericQuantity } from 'numeric-quantity';
isNumericQuantity('1 1/2'); // true
isNumericQuantity('abc'); // false
isNumericQuantity('XII', { romanNumerals: true }); // true
isNumericQuantity('$100', { allowCurrency: true }); // true
isNumericQuantity('50%', { percentage: true }); // trueParses a string of Roman numerals directly. Returns NaN for invalid input.
import { parseRomanNumerals } from 'numeric-quantity';
parseRomanNumerals('MCMXCIX'); // 1999
parseRomanNumerals('Ⅻ'); // 12
parseRomanNumerals('invalid'); // NaN