format-quantity 3.0.0 → 3.1.0

package/README.md

@@ -1,8 +1,8 @@
 [![npm][badge-npm]](https://www.npmjs.com/package/format-quantity)
 ![workflow status](https://github.com/jakeboone02/format-quantity/actions/workflows/main.yml/badge.svg)
 [![codecov.io](https://codecov.io/github/jakeboone02/format-quantity/coverage.svg?branch=main)](https://codecov.io/github/jakeboone02/format-quantity?branch=main)
-[![downloads](https://img.shields.io/npm/dm/format-quantity.svg)](http://npm-stat.com/charts.html?package=format-quantity&from=2015-08-01)
-[![MIT License](https://img.shields.io/npm/l/format-quantity.svg)](http://opensource.org/licenses/MIT)
+[![downloads](https://img.shields.io/npm/dm/format-quantity.svg)](https://npm-stat.com/charts.html?package=format-quantity&from=2015-08-01)
+[![MIT License](https://img.shields.io/npm/l/format-quantity.svg)](https://opensource.org/licenses/MIT)
 
 Formats a number (or string that appears to be a number) as one would see it written in imperial measurements, e.g. "1 1/2" instead of "1.5".
 
@@ -11,7 +11,8 @@ Formats a number (or string that appears to be a number) as one would see it wri
 Features:
 
 - To use vulgar fraction characters like "⅞", pass `true` as the second argument. Other options like Roman numerals are described below.
-- The return value will be `null` if the first argument is neither a number nor a string that evaluates to a number using `parseFloat`.
+- String inputs are parsed with [`numeric-quantity`](https://www.npmjs.com/package/numeric-quantity), so mixed numbers (`"1 1/2"`), vulgar fractions (`"½"`), bare fractions (`"1/3"`), and comma/underscore-separated numbers (`"1,000"`) are all accepted in addition to plain decimal strings.
+- The return value will be `null` if the first argument is not a recognized numeric format.
 - The return value will be an empty string (`""`) if the first argument is `0` or `"0"`, which fits the primary use case of formatting recipe ingredient quantities.
 
 > _For the inverse operation—converting a string to a `number`—check out [numeric-quantity](https://www.npmjs.com/package/numeric-quantity). It handles mixed numbers, vulgar fractions, comma/underscore separators, and Roman numerals._
@@ -77,13 +78,27 @@ Note: `formatQuantity` supports sixteenths, but no vulgar fraction characters ex
 | --------- | ------: |
 | `boolean` | `false` |
 
-Uses the [fraction slash character](<https://en.wikipedia.org/wiki/Slash_(punctuation)#Fractions>) (`"\u2044"`) to separate the numerator and denominator instead of the regular "solidus" slash (`"\u002f"`). This option is ignored if the `vulgarFractions` option is also `true`.
+Uses the [fraction slash character](<https://en.wikipedia.org/wiki/Slash_(punctuation)#Fractions>) (`"\u2044"`) to separate the numerator and denominator instead of the regular "solidus" slash (`"\u002f"`), with Unicode superscript numerator and subscript denominator digits. This option is ignored if the `vulgarFractions` option is also `true`.
 
 ```js
-formatQuantity(3.875, { fractionSlash: true }); // "3 7⁄8"
+formatQuantity(3.875, { fractionSlash: true }); // "3 ⁷⁄₈"
 formatQuantity(3.875, { fractionSlash: true, vulgarFractions: true }); // "3⅞"
 ```
 
+### `separator`
+
+| Type     | Default |
+| -------- | ------: |
+| `string` |     N/A |
+
+Overrides the string placed between the whole number and the fraction. When not specified, the default is `" "` (a space) for ASCII and fraction-slash fractions, and `""` (no space) for vulgar fractions. Common alternatives include a hyphen (`"-"`) and a no-break space (`"\u00a0"`).
+
+```js
+formatQuantity(1.5, { separator: '-' }); // "1-1/2"
+formatQuantity(1.5, { separator: ' ', vulgarFractions: true }); // "1 ½"
+formatQuantity(1.5, { separator: '\u00a0' }); // "1\u00a01/2" (no-break space)
+```
+
 ### `tolerance`
 
 | Type     |  Default |

package/dist/cjs/format-quantity.cjs.development.d.ts

@@ -1,113 +1,107 @@
+//#region src/types.d.ts
 interface FormatQuantityOptions {
-    /**
-     * Output vulgar fractions, like "½" instead of "1/2", when appropriate.
-     * Overrides the `fractionSlash` option.
-     */
-    vulgarFractions?: boolean;
-    /**
-     * Amount by which a number can deviate from the calculated quotient to be
-     * considered a match. For example, 0.66 is close enough to 2 ÷ 3 (which
-     * is 0.66666... repeating) to be considered equivalent so the function
-     * will return "2/3". The smaller this number, the higher the likelihood that
-     * the function will return a decimal instead of a fraction or mixed number.
-     *
-     * @default 0.0075
-     */
-    tolerance?: number;
-    /**
-     * Output the fraction slash character (⁄) instead of the "solidus"
-     * slash (/) for fractions. Results appear like "1⁄2" instead of "1/2".
-     * Overridden by the `vulgarFractions` option.
-     */
-    fractionSlash?: boolean;
-    /**
-     * Output in Roman numerals. Provided value must be between 1 and 3999, inclusive.
-     * Decimal values will be ignored (`Math.floor` is used to remove them). Overrides
-     * all other options.
-     */
-    romanNumerals?: boolean;
+  /**
+  * Output vulgar fractions, like "½" instead of "1/2", when appropriate.
+  * Overrides the `fractionSlash` option.
+  */
+  vulgarFractions?: boolean;
+  /**
+  * Amount by which a number can deviate from the calculated quotient to be
+  * considered a match. For example, 0.66 is close enough to 2 ÷ 3 (which
+  * is 0.66666... repeating) to be considered equivalent so the function
+  * will return "2/3". The smaller this number, the higher the likelihood that
+  * the function will return a decimal instead of a fraction or mixed number.
+  *
+  * @default 0.0075
+  */
+  tolerance?: number;
+  /**
+  * Output the fraction slash character (⁄) instead of the "solidus"
+  * slash (/) for fractions. Results appear like "1⁄2" instead of "1/2".
+  * Overridden by the `vulgarFractions` option.
+  */
+  fractionSlash?: boolean;
+  /**
+  * Output in Roman numerals. Provided value must be between 1 and 3999, inclusive.
+  * Decimal values will be ignored (`Math.floor` is used to remove them). Overrides
+  * all other options.
+  */
+  romanNumerals?: boolean;
+  /**
+  * String to place between the whole number and fraction parts. When not specified,
+  * defaults to `" "` for ASCII and fraction-slash fractions, and `""` for vulgar
+  * fractions (preserving the standard typographic convention of no space before
+  * vulgar fraction characters).
+  */
+  separator?: string;
 }
 /**
- * Function signature of {@link formatQuantity}.
- */
+* {@link FormatQuantityOptions} with all properties resolved to their
+* default values, except {@link FormatQuantityOptions.separator | separator}
+* which remains optional so that unset vs explicitly-set can be distinguished.
+*/
+type ResolvedFormatQuantityOptions = Required<Omit<FormatQuantityOptions, "separator">> & Pick<FormatQuantityOptions, "separator">;
+/**
+* Function signature of {@link formatQuantity}.
+*/
 interface FormatQuantity {
-    (qty: string | number, options?: boolean | FormatQuantityOptions): string | null;
+  (qty: string | number, options?: boolean | FormatQuantityOptions): string | null;
 }
 /** Any numeric character. */
-type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
 /** Any numeric character except '0'. */
-type NonZeroDigit = Exclude<Digit, '0'>;
+type NonZeroDigit = Exclude<Digit, "0">;
 /**
- * Fraction string with either one or two numeric characters in both the
- * numerator and denominator (but not two characters in the numerator while
- * the denominator only has one).
- */
+* Fraction string with either one or two numeric characters in both the
+* numerator and denominator (but not two characters in the numerator while
+* the denominator only has one).
+*/
 type SimpleFraction = `${NonZeroDigit}/${NonZeroDigit}` | `${NonZeroDigit}/${NonZeroDigit}${Digit}` | `${NonZeroDigit}${Digit}/${NonZeroDigit}${Digit}`;
 /**
- * Odd numerator sixteenth fraction strings.
- */
-type Sixteenth = `${'1' | '3' | '5' | '7' | '9' | '11' | '13' | '15'}/16`;
+* Odd numerator sixteenth fraction strings.
+*/
+type Sixteenth = `${"1" | "3" | "5" | "7" | "9" | "11" | "13" | "15"}/16`;
 /**
- * Unicode vulgar fraction code points.
- */
-type VulgarFraction = '¼' | '½' | '¾' | '⅐' | '⅑' | '⅒' | '⅓' | '⅔' | '⅕' | '⅖' | '⅗' | '⅘' | '⅙' | '⅚' | '⅛' | '⅜' | '⅝' | '⅞';
+* Unicode vulgar fraction code points.
+*/
+type VulgarFraction = "¼" | "½" | "¾" | "⅐" | "⅑" | "⅒" | "⅓" | "⅔" | "⅕" | "⅖" | "⅗" | "⅘" | "⅙" | "⅚" | "⅛" | "⅜" | "⅝" | "⅞";
 /** @hidden */
-type FormatQuantityTests = Record<string, ([Parameters<FormatQuantity>[0], ReturnType<FormatQuantity>] | [
-    Parameters<FormatQuantity>[0],
-    ReturnType<FormatQuantity>,
-    Parameters<FormatQuantity>[1]
-])[]>;
-
-/**
- * Formats a number (or string that appears to be a number)
- * as one would see it written in imperial measurements, e.g.
- * "1 1/2" instead of "1.5". To use vulgar fraction characters
- * like "½", pass `true` as the second argument. For other options
- * see {@link FormatQuantityOptions}.
- */
-declare const formatQuantity: FormatQuantity;
-
+type FormatQuantityTests = Record<string, ([Parameters<FormatQuantity>[0], ReturnType<FormatQuantity>] | [Parameters<FormatQuantity>[0], ReturnType<FormatQuantity>, Parameters<FormatQuantity>[1]])[]>;
+//#endregion
+//#region src/constants.d.ts
 /**
- * Default tolerance used by {@link formatQuantity} when determining if a number
- * is close enough to a fraction value to be considered equivalent.
- */
+* Default tolerance used by {@link formatQuantity} when determining if a number
+* is close enough to a fraction value to be considered equivalent.
+*/
 declare const defaultTolerance: 0.0075;
 /**
- * Default options for {@link formatQuantity}.
- */
-declare const defaultOptions: {
-    readonly vulgarFractions: false;
-    readonly tolerance: 0.0075;
-    readonly fractionSlash: false;
-    readonly romanNumerals: false;
-};
+* Default options for {@link formatQuantity}.
+*/
+declare const defaultOptions: ResolvedFormatQuantityOptions;
 /**
- * Map of vulgar fractions to their traditional ASCII equivalents.
- */
-declare const vulgarToAsciiMap: {
-    readonly '\u00BC': "1/4";
-    readonly '\u00BD': "1/2";
-    readonly '\u00BE': "3/4";
-    readonly '\u2150': "1/7";
-    readonly '\u2151': "1/9";
-    readonly '\u2152': "1/10";
-    readonly '\u2153': "1/3";
-    readonly '\u2154': "2/3";
-    readonly '\u2155': "1/5";
-    readonly '\u2156': "2/5";
-    readonly '\u2157': "3/5";
-    readonly '\u2158': "4/5";
-    readonly '\u2159': "1/6";
-    readonly '\u215A': "5/6";
-    readonly '\u215B': "1/8";
-    readonly '\u215C': "3/8";
-    readonly '\u215D': "5/8";
-    readonly '\u215E': "7/8";
-};
+* Map of vulgar fractions to their traditional ASCII equivalents.
+*/
+declare const vulgarToAsciiMap: Record<VulgarFraction, SimpleFraction>;
 /**
- * Map of "close enough" decimal values to the {@link VulgarFraction} or
- * {@link Sixteenth} fraction string matches.
- */
-declare const fractionDecimalMatches: ([number, "⅓"] | [number, "⅔"] | [number, "⅕"] | [number, "⅖"] | [number, "⅗"] | [number, "⅘"] | [number, "⅙"] | [number, "⅚"] | [number, "⅐"] | [number, "⅑"] | [number, "⅒"] | [number, "⅛"] | [number, "¼"] | [number, "⅜"] | [number, "½"] | [number, "⅝"] | [number, "¾"] | [number, "⅞"] | [number, "1/16"] | [number, "3/16"] | [number, "5/16"] | [number, "7/16"] | [number, "9/16"] | [number, "11/16"] | [number, "13/16"] | [number, "15/16"])[];
-
-export { type Digit, type FormatQuantity, type FormatQuantityOptions, type FormatQuantityTests, type NonZeroDigit, type SimpleFraction, type Sixteenth, type VulgarFraction, defaultOptions, defaultTolerance, formatQuantity, fractionDecimalMatches, vulgarToAsciiMap };
+* Map of "close enough" decimal values to the {@link VulgarFraction} or
+* {@link Sixteenth} fraction string matches.
+*/
+declare const fractionDecimalMatches: [number, VulgarFraction | Sixteenth][];
+//#endregion
+//#region src/formatQuantity.d.ts
+/**
+* Formats a number as Roman numerals. The number must be between
+* 1 and 3999, inclusive.
+*/
+declare const formatRomanNumerals: (qty: number) => string | null;
+/**
+* Formats a number (or string that appears to be a number)
+* as one would see it written in imperial measurements, e.g.
+* "1 1/2" instead of "1.5". To use vulgar fraction characters
+* like "½", pass `true` as the second argument. For other options
+* see {@link FormatQuantityOptions}.
+*/
+declare const formatQuantity: FormatQuantity;
+//#endregion
+export { Digit, FormatQuantity, FormatQuantityOptions, FormatQuantityTests, NonZeroDigit, ResolvedFormatQuantityOptions, SimpleFraction, Sixteenth, VulgarFraction, defaultOptions, defaultTolerance, formatQuantity, formatRomanNumerals, fractionDecimalMatches, vulgarToAsciiMap };
+//# sourceMappingURL=format-quantity.cjs.development.d.ts.map

package/dist/cjs/format-quantity.cjs.development.js

@@ -1,188 +1,195 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var src_exports = {};
-__export(src_exports, {
-  defaultOptions: () => defaultOptions,
-  defaultTolerance: () => defaultTolerance,
-  formatQuantity: () => formatQuantity,
-  fractionDecimalMatches: () => fractionDecimalMatches,
-  vulgarToAsciiMap: () => vulgarToAsciiMap
-});
-module.exports = __toCommonJS(src_exports);
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let numeric_quantity = require("numeric-quantity");
 
-// src/constants.ts
-var defaultTolerance = 75e-4;
-var defaultOptions = {
-  vulgarFractions: false,
-  tolerance: defaultTolerance,
-  fractionSlash: false,
-  romanNumerals: false
+//#region src/constants.ts
+/**
+* Default tolerance used by {@link formatQuantity} when determining if a number
+* is close enough to a fraction value to be considered equivalent.
+*/
+const defaultTolerance = .0075;
+/**
+* Default options for {@link formatQuantity}.
+*/
+const defaultOptions = {
+	vulgarFractions: false,
+	tolerance: defaultTolerance,
+	fractionSlash: false,
+	romanNumerals: false
 };
-var vulgarToAsciiMap = {
-  "\xBC": "1/4",
-  "\xBD": "1/2",
-  "\xBE": "3/4",
-  "\u2150": "1/7",
-  "\u2151": "1/9",
-  "\u2152": "1/10",
-  "\u2153": "1/3",
-  "\u2154": "2/3",
-  "\u2155": "1/5",
-  "\u2156": "2/5",
-  "\u2157": "3/5",
-  "\u2158": "4/5",
-  "\u2159": "1/6",
-  "\u215A": "5/6",
-  "\u215B": "1/8",
-  "\u215C": "3/8",
-  "\u215D": "5/8",
-  "\u215E": "7/8"
+/**
+* Map of vulgar fractions to their traditional ASCII equivalents.
+*/
+const vulgarToAsciiMap = {
+	"¼": "1/4",
+	"½": "1/2",
+	"¾": "3/4",
+	"⅐": "1/7",
+	"⅑": "1/9",
+	"⅒": "1/10",
+	"⅓": "1/3",
+	"⅔": "2/3",
+	"⅕": "1/5",
+	"⅖": "2/5",
+	"⅗": "3/5",
+	"⅘": "4/5",
+	"⅙": "1/6",
+	"⅚": "5/6",
+	"⅛": "1/8",
+	"⅜": "3/8",
+	"⅝": "5/8",
+	"⅞": "7/8"
 };
-var fractionDecimalMatches = [
-  [0.33, "\u2153"],
-  [0.66, "\u2154"],
-  [0.2, "\u2155"],
-  [0.4, "\u2156"],
-  [0.6, "\u2157"],
-  [0.8, "\u2158"],
-  [0.166, "\u2159"],
-  [0.833, "\u215A"],
-  [0.143, "\u2150"],
-  [0.111, "\u2151"],
-  [0.1, "\u2152"],
-  [0.125, "\u215B"],
-  [0.25, "\xBC"],
-  [0.375, "\u215C"],
-  [0.5, "\xBD"],
-  [0.625, "\u215D"],
-  [0.75, "\xBE"],
-  [0.875, "\u215E"],
-  [0.0625, "1/16"],
-  [0.1875, "3/16"],
-  [0.3125, "5/16"],
-  [0.4375, "7/16"],
-  [0.5625, "9/16"],
-  [0.6875, "11/16"],
-  [0.8125, "13/16"],
-  [0.9375, "15/16"]
+/**
+* Map of "close enough" decimal values to the {@link VulgarFraction} or
+* {@link Sixteenth} fraction string matches.
+*/
+const fractionDecimalMatches = [
+	[.33, "⅓"],
+	[.66, "⅔"],
+	[.2, "⅕"],
+	[.4, "⅖"],
+	[.6, "⅗"],
+	[.8, "⅘"],
+	[.166, "⅙"],
+	[.833, "⅚"],
+	[.143, "⅐"],
+	[.111, "⅑"],
+	[.1, "⅒"],
+	[.125, "⅛"],
+	[.25, "¼"],
+	[.375, "⅜"],
+	[.5, "½"],
+	[.625, "⅝"],
+	[.75, "¾"],
+	[.875, "⅞"],
+	[.0625, "1/16"],
+	[.1875, "3/16"],
+	[.3125, "5/16"],
+	[.4375, "7/16"],
+	[.5625, "9/16"],
+	[.6875, "11/16"],
+	[.8125, "13/16"],
+	[.9375, "15/16"]
 ];
 
-// src/formatQuantity.ts
-var closeEnough = (n1, n2, tolerance) => Math.abs(n1 - n2) < tolerance;
-var getFraction = (vulgarFractionOrSixteenth, { fractionSlash, vulgarFractions }) => {
-  if (vulgarFractions) {
-    return vulgarFractionOrSixteenth;
-  }
-  const plainFraction = vulgarToAsciiMap[vulgarFractionOrSixteenth] ?? vulgarFractionOrSixteenth;
-  if (fractionSlash) {
-    return plainFraction.replace("/", "\u2044");
-  }
-  return plainFraction;
+//#endregion
+//#region src/formatQuantity.ts
+/**
+* Determines if two numbers are close enough to consider
+* them equal for the purposes of this package.
+*/
+const closeEnough = (n1, n2, tolerance) => Math.abs(n1 - n2) < tolerance;
+const superscriptDigits = "⁰¹²³⁴⁵⁶⁷⁸⁹";
+const subscriptDigits = "₀₁₂₃₄₅₆₇₈₉";
+const toSuperscript = (s) => {
+	let r = "";
+	for (let i = 0; i < s.length; i++) r += superscriptDigits[+s[i]];
+	return r;
 };
-var normalizeOptions = (options) => ({
-  ...defaultOptions,
-  ...typeof options === "boolean" ? { vulgarFractions: options } : options
+const toSubscript = (s) => {
+	let r = "";
+	for (let i = 0; i < s.length; i++) r += subscriptDigits[+s[i]];
+	return r;
+};
+/**
+* Applies the `vulgarFractions` or `fractionSlash` options as necessary.
+*/
+const getFraction = (vulgarFractionOrSixteenth, { fractionSlash, vulgarFractions }) => {
+	if (vulgarFractions) return vulgarFractionOrSixteenth;
+	const plainFraction = vulgarToAsciiMap[vulgarFractionOrSixteenth] ?? vulgarFractionOrSixteenth;
+	if (fractionSlash) {
+		const [num, den] = plainFraction.split("/");
+		return `${toSuperscript(num)}⁄${toSubscript(den)}`;
+	}
+	return plainFraction;
+};
+/**
+* Merges options object with default options, converting boolean to object if necessary.
+*/
+const normalizeOptions = (options) => ({
+	...defaultOptions,
+	...typeof options === "boolean" ? { vulgarFractions: options } : options
 });
-var romanNumeralValueKey = [
-  "",
-  "C",
-  "CC",
-  "CCC",
-  "CD",
-  "D",
-  "DC",
-  "DCC",
-  "DCCC",
-  "CM",
-  "",
-  "X",
-  "XX",
-  "XXX",
-  "XL",
-  "L",
-  "LX",
-  "LXX",
-  "LXXX",
-  "XC",
-  "",
-  "I",
-  "II",
-  "III",
-  "IV",
-  "V",
-  "VI",
-  "VII",
-  "VIII",
-  "IX"
+const romanNumeralValueKey = [
+	"",
+	"C",
+	"CC",
+	"CCC",
+	"CD",
+	"D",
+	"DC",
+	"DCC",
+	"DCCC",
+	"CM",
+	"",
+	"X",
+	"XX",
+	"XXX",
+	"XL",
+	"L",
+	"LX",
+	"LXX",
+	"LXXX",
+	"XC",
+	"",
+	"I",
+	"II",
+	"III",
+	"IV",
+	"V",
+	"VI",
+	"VII",
+	"VIII",
+	"IX"
 ];
-var formatRomanNumerals = (qty) => {
-  if (typeof qty !== "number" || isNaN(qty)) {
-    return null;
-  }
-  if (qty < 1 || qty >= 4e3) {
-    return "";
-  }
-  const floored = Math.floor(qty);
-  const digits = `${floored}`.split("");
-  let roman = "";
-  let i = 3;
-  while (i--) {
-    roman = `${romanNumeralValueKey[+digits.pop() + i * 10] || ""}${roman}`;
-  }
-  return `${Array(+digits.join("") + 1).join("M")}${roman}`;
+/**
+* Formats a number as Roman numerals. The number must be between
+* 1 and 3999, inclusive.
+*/
+const formatRomanNumerals = (qty) => {
+	if (typeof qty !== "number" || isNaN(qty)) return null;
+	if (qty < 1 || qty >= 4e3) return "";
+	const digits = `${Math.floor(qty)}`.split("");
+	let roman = "";
+	let i = 3;
+	while (i--) roman = `${romanNumeralValueKey[+digits.pop() + i * 10] || ""}${roman}`;
+	return `${Array(+digits.join("") + 1).join("M")}${roman}`;
 };
-var formatQuantity = (qty, options = defaultOptions) => {
-  const qtyAsNumber = typeof qty === "string" ? parseFloat(qty) : qty;
-  if (isNaN(qtyAsNumber) || qtyAsNumber === null) {
-    return null;
-  }
-  if (qtyAsNumber === 0) {
-    return "";
-  }
-  const opts = normalizeOptions(options ?? defaultOptions);
-  if (opts.romanNumerals) {
-    return formatRomanNumerals(qtyAsNumber);
-  }
-  const absoluteValue = Math.abs(qtyAsNumber);
-  const flooredAbsVal = Math.floor(absoluteValue);
-  const flooredAbsValStr = `${qtyAsNumber < 0 ? "-" : ""}${flooredAbsVal === 0 ? "" : `${flooredAbsVal} `}`;
-  const decimalValue = absoluteValue - flooredAbsVal;
-  if (decimalValue === 0) {
-    return `${qtyAsNumber}`;
-  }
-  for (const [num, vf] of fractionDecimalMatches) {
-    if (closeEnough(decimalValue, num, opts.tolerance)) {
-      const fraction = getFraction(vf, opts);
-      const int = fraction in vulgarToAsciiMap ? flooredAbsValStr.trim() : flooredAbsValStr;
-      return `${int}${fraction}`;
-    }
-  }
-  return `${qtyAsNumber}`;
+/**
+* Formats a number (or string that appears to be a number)
+* as one would see it written in imperial measurements, e.g.
+* "1 1/2" instead of "1.5". To use vulgar fraction characters
+* like "½", pass `true` as the second argument. For other options
+* see {@link FormatQuantityOptions}.
+*/
+const formatQuantity = (qty, options = defaultOptions) => {
+	const qtyAsNumber = typeof qty === "string" ? (0, numeric_quantity.numericQuantity)(qty, {
+		round: false,
+		allowTrailingInvalid: true
+	}) : qty;
+	if (isNaN(qtyAsNumber) || qtyAsNumber === null) return null;
+	if (qtyAsNumber === 0) return "";
+	const opts = normalizeOptions(options ?? defaultOptions);
+	if (opts.romanNumerals) return formatRomanNumerals(qtyAsNumber);
+	const absoluteValue = Math.abs(qtyAsNumber);
+	const flooredAbsVal = Math.floor(absoluteValue);
+	const sign = qtyAsNumber < 0 ? "-" : "";
+	const wholeStr = flooredAbsVal === 0 ? "" : `${flooredAbsVal}`;
+	const decimalValue = absoluteValue - flooredAbsVal;
+	if (decimalValue === 0) return `${qtyAsNumber}`;
+	for (const [num, vf] of fractionDecimalMatches) if (closeEnough(decimalValue, num, opts.tolerance)) {
+		const fraction = getFraction(vf, opts);
+		const isVulgar = fraction in vulgarToAsciiMap;
+		return `${sign}${wholeStr}${wholeStr ? opts.separator ?? (isVulgar ? "" : " ") : ""}${fraction}`;
+	}
+	return `${qtyAsNumber}`;
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  defaultOptions,
-  defaultTolerance,
-  formatQuantity,
-  fractionDecimalMatches,
-  vulgarToAsciiMap
-});
+
+//#endregion
+exports.defaultOptions = defaultOptions;
+exports.defaultTolerance = defaultTolerance;
+exports.formatQuantity = formatQuantity;
+exports.formatRomanNumerals = formatRomanNumerals;
+exports.fractionDecimalMatches = fractionDecimalMatches;
+exports.vulgarToAsciiMap = vulgarToAsciiMap;
 //# sourceMappingURL=format-quantity.cjs.development.js.map