Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

format-quantity

Package Overview
Dependencies
Maintainers
1
Versions
21
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

format-quantity

Number formatter for imperial measurements with support for vulgar fractions

  • 2.1.0
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
774
increased by9.94%
Maintainers
1
Weekly downloads
 
Created
Source

format-quantity

npm workflow status codecov.io downloads MIT License

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".

Features:

  • To use vulgar fraction characters like "⅞", pass true as the second argument (see other options, like Roman numerals, 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.
  • The return value will be an empty string ("") if the first argument is 0 or "0", which is done to fit the primary use case of formatting recipe ingredient quantities.

For the inverse operation—converting a string to a number—check out numeric-quantity. It handles mixed numbers, vulgar fractions, comma/underscore separators, and Roman numerals.

If you're interested in parsing recipe ingredient strings, try parse-ingredient.

Usage

Installed

import { formatQuantity } from 'format-quantity';

formatQuantity(1.5); // "1 1/2"
formatQuantity(2.66); // "2 2/3"
formatQuantity(3.875, true); // "3⅞"

CDN

As an ES module:

<script type="module">
  import { formatQuantity } from 'https://cdn.jsdelivr.net/npm/format-quantity/+esm';

  console.log(formatQuantity(10.5)); // "10 1/2"
</script>

As UMD (all exports are properties of the global object FormatQuantity):

<script src="https://unpkg.com/format-quantity"></script>
<script>
  console.log(FormatQuantity.formatQuantity(10.5)); // "10 1/2"
</script>

Options

The second parameter to formatQuantity can be a boolean value or an options object.

vulgarFractions

TypeDefault
booleanfalse

Returns vulgar fractions when appropriate. This option has the same effect as passing a plain boolean value as the second parameter.

formatQuantity(3.875, { vulgarFractions: true }); // "3⅞"
// is the same as
formatQuantity(3.875, true); // "3⅞"

Note: formatQuantity supports sixteenths, but no vulgar fraction characters exist for that denomination. Therefore the vulgarFractions option has no effect if the fraction portion of the final string is an odd numerator over a denominator of 16.

fractionSlash

TypeDefault
booleanfalse

Uses the fraction slash character ("\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.

formatQuantity(3.875, { fractionSlash: true }); // "3 7⁄8"
formatQuantity(3.875, { fractionSlash: true, vulgarFractions: true }); // "3⅞"

tolerance

TypeDefault
number0.0075

This option determines how close the decimal portion of a number has to be to the actual quotient of a fraction to be considered a match. For example, consider the fraction 1⁄3: $1 \div 3 = 0.\overline{333}$, repeating forever. The number 0.333 (exactly 333 thousandths) is not equivalent to 1⁄3, but it's very close. So even though $0.333 \neq 1 \div 3$, both formatQuantity(0.333) and formatQuantity(1/3) will return "1/3".

A lower tolerance increases the likelihood that formatQuantity will return a decimal representation instead of a fraction or mixed number since the matching algorithm will be stricter. An higher tolerance increases the likelihood that formatQuantity will return a fraction or mixed number, but at the risk of arbitrarily matching an incorrect fraction simply because it gets evaluated first (the export fractionDecimalMatches defines the order of evaluation).

// Low tolerance - returns a decimal since 0.333 is not close enough to 1/3
formatQuantity(0.333, { tolerance: 0.00001 }); // "0.333"
// High tolerance - matches "1/3" even for 3/10
formatQuantity(0.3, { tolerance: 0.1 }); // "1/3"
// *Way* too high tolerance - incorrect result because thirds get evaluated before halves
formatQuantity(0.5, { tolerance: 0.5 }); // "1/3"

romanNumerals

TypeDefault
booleanfalse

Coerces the number into an integer using Math.floor, then formats the value as Roman numerals. The algorithm uses strict, modern rules, so the number must be between 1 and 3999 (inclusive).

When this option is true, all other options are ignored.

formatQuantity(1214, { romanNumerals: true }); // "MCCXIV"
formatQuantity(12.14, { romanNumerals: true, vulgarFractions: true }); // "XII"

Other exports

NameTypeDescription
defaultTolerancenumber0.0075
defaultOptionstypeObject representing the default options
fractionDecimalMatches[number, VulgarFraction | Sixteenth][]List of decimal values that are close enough to match the associated fraction (inputs are evaluated against the decimal values in the order of this array)
vulgarToAsciiMapobjectMap of vulgar fraction characters to their equivalent ASCII strings ("⅓" to "1/3", "⅞" to "7/8", etc.)
formatRomanNumeralsfunctionFormats a number as Roman numerals (used internally by formatQuantity when the romanNumerals option is true)
FormatQuantityOptionsinterfaceShape of formatQuantity's second parameter (if not a boolean value)
SimpleFractiontypeString template type for valid (positive, no division by zero) ASCII fraction strings with either one or two digits in the numerator and denominator each
VulgarFractiontypeThe set of vulgar fraction characters ("\u00bc", "\u00bd", "\u00be", and "\u2150" through "\u215e")
SixteenthtypeUnion type of all ASCII representations of odd-numbered sixteenth fractions less than one, ("1/16", "3/16", etc.)

Keywords

FAQs

Package last updated on 17 Jun 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc