@thejaredwilcurt/csslop 0.0.49 → 0.0.51

package/src/value/math-expression.js

@@ -1,1156 +0,0 @@
-/**
- * @file Reads the arithmetic a CSS math function states and resolves it into the value it works out to, whenever every operand of it is a number already known at minification time.
- */
-
-import {
-  convertAbsoluteLengthToPx,
-  formatResolvedNumber
-} from './shared.js';
-
-/**
- * The unit a plain number is totalled under. A number carries no unit, and the
- * empty string is the unit it does not carry.
- *
- * @type {string}
- */
-const UNITLESS = '';
-
-/**
- * The unit a percentage is totalled under. A percentage is only resolved
- * against its basis once the element is laid out, so it is totalled as a unit
- * of its own rather than as the number it is written from.
- *
- * @type {string}
- */
-const PERCENTAGE = '%';
-
-/**
- * The numeric constants a calculation may name instead of writing out, as the
- * keywords section of the CSS Values specification defines them:
- * https://drafts.csswg.org/css-values/#calc-keywords.
- *
- * @type {Map<string, number>}
- */
-const NUMERIC_CONSTANTS = new Map([
-  ['e', Math.E],
-  ['infinity', Infinity],
-  ['nan', NaN],
-  ['pi', Math.PI]
-]);
-
-/**
- * How each rounding strategy of `round()` turns the number of intervals it is
- * given into the whole number of them it keeps.
- *
- * @type {Map<string, function(number): number>}
- */
-const ROUNDING_STRATEGIES = new Map([
-  ['nearest', Math.round],
-  ['up', Math.ceil],
-  ['down', Math.floor],
-  ['to-zero', Math.trunc]
-]);
-
-/**
- * The deepest a calculation may nest one set of parentheses inside another
- * before the evaluator gives up on it. Every level of nesting is a level of
- * recursion, and a stylesheet states nothing at a depth anywhere near this.
- *
- * @type {number}
- */
-const MAXIMUM_NESTING_DEPTH = 32;
-
-/**
- * Creates the totals of a value that states a single quantity, holding the
- * number it is written from under the unit it is written with. An absolute
- * length is held as the pixels it measures, since every length stating the
- * same measurement then totals under the same unit.
- *
- * @param  {number}  number                   The number the quantity is written from.
- * @param  {string}  unit                     The unit the quantity is written with, or the empty string when it is a plain number.
- * @param  {boolean} preserveWrittenQuantity  Whether to retain the original spelling for a standalone quantity.
- * @return {Map}                              The unit totals the quantity states.
- */
-function createUnitTotals (number, unit, preserveWrittenQuantity = false) {
-  const lowercasedUnit = unit.toLowerCase();
-  const pixels = convertAbsoluteLengthToPx(number, lowercasedUnit);
-  let totals;
-  if (pixels === null) {
-    totals = new Map([[lowercasedUnit, number]]);
-  } else {
-    totals = new Map([['px', pixels]]);
-  }
-  if (preserveWrittenQuantity) {
-    totals.writtenQuantity = {
-      number,
-      unit: lowercasedUnit,
-      canonicalUnit: pixels === null ? lowercasedUnit : 'px',
-      canonicalNumber: pixels === null ? number : pixels
-    };
-  }
-  return totals;
-}
-
-/**
- * Reports whether a value states a plain number, which is what an operand has
- * to be to scale or divide the quantity it is written against.
- *
- * @param  {Map}     value  The unit totals the value holds.
- * @return {boolean}        Whether the value states a plain number.
- */
-function isPlainNumber (value) {
-  return value.size === 1 && value.has(UNITLESS);
-}
-
-/**
- * Reads a value as the single quantity it states, which is what a function
- * comparing its arguments needs each of them to be. A value totalling more
- * than one unit is only resolved once its units are resolved against the
- * element, so it states no single number to read.
- *
- * @param  {Map}         value  The unit totals the value holds.
- * @return {object|null}        The number and the unit the value states, or null when it states more than one quantity.
- */
-function readSingleQuantity (value) {
-  if (value.size !== 1) {
-    return null;
-  }
-  const [[unit, number]] = [...value];
-  return { number, unit };
-}
-
-/**
- * Scales every quantity a value states by a plain number, which is how a
- * multiplication and a division are worked out.
- *
- * @param  {Map}    value   The unit totals the value holds.
- * @param  {number} factor  The number every total is scaled by.
- * @return {Map}            The scaled unit totals.
- */
-function scaleUnitTotals (value, factor) {
-  const scaled = new Map();
-  for (const [unit, coefficient] of value) {
-    scaled.set(unit, coefficient * factor);
-  }
-  return scaled;
-}
-
-/**
- * Adds one value to another, totalling the quantities they state under the
- * units they are written with. A sum of a plain number and a quantity carrying
- * a unit states nothing a stylesheet can hold, so such a sum has no total to
- * give.
- *
- * @param  {Map}      left   The unit totals the value on the left holds.
- * @param  {Map}      right  The unit totals the value on the right holds.
- * @param  {number}   sign   The direction the right value is added in: 1 to add it, -1 to subtract it.
- * @return {Map|null}        The totals of the sum, or null when the two cannot be added.
- */
-function addUnitTotals (left, right, sign) {
-  const totals = new Map(left);
-  for (const [unit, coefficient] of right) {
-    totals.set(unit, (totals.get(unit) || 0) + (coefficient * sign));
-  }
-  const addsNumberToQuantity = totals.has(UNITLESS) && totals.size > 1;
-  if (addsNumberToQuantity) {
-    return null;
-  }
-  return totals;
-}
-
-/**
- * Multiplies two values, which CSS only allows when one of them is a plain
- * number: the product of two quantities carrying units measures an area or a
- * rate, and no CSS property takes one.
- *
- * @param  {Map}      left   The unit totals the value on the left holds.
- * @param  {Map}      right  The unit totals the value on the right holds.
- * @return {Map|null}        The totals of the product, or null when neither side is a plain number.
- */
-function multiplyUnitTotals (left, right) {
-  if (isPlainNumber(right)) {
-    return scaleUnitTotals(left, right.get(UNITLESS));
-  }
-  if (isPlainNumber(left)) {
-    return scaleUnitTotals(right, left.get(UNITLESS));
-  }
-  const leftQuantity = readSingleQuantity(left);
-  const rightQuantity = readSingleQuantity(right);
-  if (leftQuantity && rightQuantity) {
-    if (leftQuantity.unit.startsWith('reciprocal:') && leftQuantity.unit.slice('reciprocal:'.length) === rightQuantity.unit) {
-      return createUnitTotals(leftQuantity.number * rightQuantity.number, UNITLESS);
-    }
-    if (rightQuantity.unit.startsWith('reciprocal:') && rightQuantity.unit.slice('reciprocal:'.length) === leftQuantity.unit) {
-      return createUnitTotals(leftQuantity.number * rightQuantity.number, UNITLESS);
-    }
-  }
-  return null;
-}
-
-/**
- * Divides a value by another, which CSS only allows when the divisor is a
- * plain number. A division by zero resolves to an infinity that no property
- * takes, so it is left for the stylesheet to state as written.
- *
- * @param  {Map}      left   The unit totals of the value being divided.
- * @param  {Map}      right  The unit totals of the value dividing it.
- * @return {Map|null}        The totals of the quotient, or null when the division cannot be worked out.
- */
-function divideUnitTotals (left, right) {
-  if (isPlainNumber(right)) {
-    const divisor = right.get(UNITLESS);
-    if (divisor === 0) {
-      return null;
-    }
-    return scaleUnitTotals(left, 1 / divisor);
-  }
-  const dividendQuantity = readSingleQuantity(left);
-  const divisorQuantity = readSingleQuantity(right);
-  if (!dividendQuantity || !divisorQuantity || divisorQuantity.number === 0) {
-    return null;
-  }
-  if (dividendQuantity.unit === divisorQuantity.unit) {
-    return createUnitTotals(dividendQuantity.number / divisorQuantity.number, UNITLESS);
-  }
-  if (dividendQuantity.unit === UNITLESS) {
-    return createUnitTotals(
-      dividendQuantity.number / divisorQuantity.number,
-      'reciprocal:' + divisorQuantity.unit
-    );
-  }
-  return null;
-}
-
-/**
- * Matches a CSS number where the scanner stands: the digits it is written
- * from, together with the fraction and the exponent it may be written with.
- * A sign is left to the parser, which tells the sign of a number from an
- * operator by whether whitespace stands between the two.
- *
- * @type {RegExp}
- */
-const NUMBER_AT_INDEX = /(?:\d+\.\d+|\.\d+|\d+)(?:e[+-]?\d+)?/iy;
-
-/**
- * Matches a CSS identifier where the scanner stands: a name of letters,
- * digits, underscores, and hyphens that does not begin with a digit. A numeric
- * constant, a function name, and a keyword argument are all written as
- * identifiers.
- *
- * @type {RegExp}
- */
-const IDENTIFIER_AT_INDEX = /[a-z_][a-z0-9_-]*/iy;
-
-/**
- * Matches the unit written against a number where the scanner stands. Every
- * CSS unit is named in letters alone, so a name holding anything else is a
- * token of its own that a number cannot carry.
- *
- * @type {RegExp}
- */
-const UNIT_AT_INDEX = /[a-z]+/iy;
-
-/**
- * The characters CSS counts as whitespace, which separates the tokens of a
- * calculation and tells an operator apart from the sign of a number.
- *
- * @type {Set<string>}
- */
-const WHITESPACE_CHARACTERS = new Set([' ', '\t', '\n', '\r', '\f']);
-
-/**
- * The characters that punctuate a calculation, and the kind of token each of
- * them stands for.
- *
- * @type {Map<string, string>}
- */
-const PUNCTUATION_TOKEN_TYPES = new Map([
-  ['(', 'open'],
-  [')', 'close'],
-  [',', 'comma']
-]);
-
-/**
- * The arithmetic operators a calculation is written with.
- *
- * @type {Set<string>}
- */
-const OPERATOR_CHARACTERS = new Set(['+', '-', '*', '/']);
-
-/**
- * Reads the unit written directly against the number that ends at the given
- * index, which is a percent sign or an identifier naming the unit. A number
- * with nothing written against it carries no unit.
- *
- * @param  {string} text   The math function being tokenized.
- * @param  {number} index  The index just past the number's digits.
- * @return {object}        The unit read and the index just past it.
- */
-function readUnitAtIndex (text, index) {
-  if (text[index] === PERCENTAGE) {
-    return { unit: PERCENTAGE, nextIndex: index + 1 };
-  }
-  UNIT_AT_INDEX.lastIndex = index;
-  const unitMatch = UNIT_AT_INDEX.exec(text);
-  if (!unitMatch) {
-    return { unit: UNITLESS, nextIndex: index };
-  }
-  return { unit: unitMatch[0], nextIndex: index + unitMatch[0].length };
-}
-
-/**
- * Splits a math function into the tokens it is written from: its numbers with
- * the units they carry, its identifiers, its function names, its operators,
- * and its punctuation. Each token records whether whitespace precedes it,
- * since that is what tells the sign of a number from an operator.
- *
- * @param  {string}     text  The math function as it is written.
- * @return {Array|null}       The tokens of the math function, or null when it holds a character no calculation is written with.
- */
-function tokenizeMathExpression (text) {
-  const tokens = [];
-  let index = 0;
-  let precededBySpace = false;
-
-  while (index < text.length) {
-    const character = text[index];
-
-    if (WHITESPACE_CHARACTERS.has(character)) {
-      precededBySpace = true;
-      index++;
-      continue;
-    }
-
-    NUMBER_AT_INDEX.lastIndex = index;
-    const numberMatch = NUMBER_AT_INDEX.exec(text);
-    if (numberMatch) {
-      const { unit, nextIndex } = readUnitAtIndex(text, index + numberMatch[0].length);
-      tokens.push({
-        type: 'number',
-        number: Number(numberMatch[0]),
-        unit,
-        precededBySpace
-      });
-      index = nextIndex;
-      precededBySpace = false;
-      continue;
-    }
-
-    if (OPERATOR_CHARACTERS.has(character) || PUNCTUATION_TOKEN_TYPES.has(character)) {
-      tokens.push({
-        type: PUNCTUATION_TOKEN_TYPES.get(character) || 'operator',
-        operator: character,
-        precededBySpace
-      });
-      index++;
-      precededBySpace = false;
-      continue;
-    }
-
-    IDENTIFIER_AT_INDEX.lastIndex = index;
-    const identifierMatch = IDENTIFIER_AT_INDEX.exec(text);
-    if (!identifierMatch) {
-      return null;
-    }
-    index = index + identifierMatch[0].length;
-    // A name written directly against an opening parenthesis calls a function
-    const callsFunction = text[index] === '(';
-    if (callsFunction) {
-      index++;
-    }
-    tokens.push({
-      type: callsFunction ? 'function' : 'identifier',
-      name: identifierMatch[0].toLowerCase(),
-      precededBySpace
-    });
-    precededBySpace = false;
-  }
-
-  return tokens;
-}
-
-/**
- * @typedef  {object} ExpressionReader
- * @property {Array}  tokens            The tokens of the math function, in the order they are written.
- * @property {number} index             The token the parser reads next.
- * @property {number} depth             How many sets of parentheses the parser is reading inside of.
- */
-
-/**
- * Reads the token the parser stands on, or one of the tokens after it.
- *
- * @param  {ExpressionReader} reader  The token reader.
- * @param  {number}           offset  How many tokens past the current one to read.
- * @return {object|undefined}         The token read, or undefined past the end of the expression.
- */
-function peekToken (reader, offset = 0) {
-  return reader.tokens[reader.index + offset];
-}
-
-/**
- * Reports whether the parser stands on an operator that adds or subtracts what
- * follows it from what precedes it. A sign written directly against its number
- * is part of that number rather than an operator, so a value written with one
- * sits against the value before it with no operator between them, which is not
- * a calculation any browser reads.
- *
- * @param  {ExpressionReader} reader  The token reader.
- * @return {boolean}                  Whether an addition or a subtraction follows.
- */
-function readsAdditiveOperator (reader) {
-  const token = peekToken(reader);
-  const isAdditive = token?.type === 'operator' && (token.operator === '+' || token.operator === '-');
-  if (!isAdditive) {
-    return false;
-  }
-  const operandToken = peekToken(reader, 1);
-  const signsItsNumber = operandToken?.type === 'number' && !operandToken.precededBySpace;
-  return !signsItsNumber;
-}
-
-/**
- * Reads a sum: the terms a calculation adds together, in the order they are
- * written.
- *
- * @param  {ExpressionReader} reader  The token reader.
- * @return {Map|null}                 The unit totals the sum states, or null when it cannot be resolved.
- */
-function parseSum (reader) {
-  let value = parseProduct(reader);
-  if (!value) {
-    return null;
-  }
-  while (readsAdditiveOperator(reader)) {
-    const subtracts = peekToken(reader).operator === '-';
-    reader.index++;
-    const term = parseProduct(reader);
-    if (!term) {
-      return null;
-    }
-    value = addUnitTotals(value, term, subtracts ? -1 : 1);
-    if (!value) {
-      return null;
-    }
-  }
-  return value;
-}
-
-/**
- * Reads a product: the operands a calculation multiplies and divides, which
- * bind more tightly than the terms of a sum do.
- *
- * @param  {ExpressionReader} reader  The token reader.
- * @return {Map|null}                 The unit totals the product states, or null when it cannot be resolved.
- */
-function parseProduct (reader) {
-  let value = parseOperand(reader);
-  if (!value) {
-    return null;
-  }
-  let token = peekToken(reader);
-  while (token?.type === 'operator' && (token.operator === '*' || token.operator === '/')) {
-    reader.index++;
-    const operand = parseOperand(reader);
-    if (!operand) {
-      return null;
-    }
-    if (token.operator === '*') {
-      value = multiplyUnitTotals(value, operand);
-    } else {
-      value = divideUnitTotals(value, operand);
-    }
-    if (!value) {
-      return null;
-    }
-    token = peekToken(reader);
-  }
-  return value;
-}
-
-/**
- * Reads the number a sign is written against, which is the only place a
- * calculation states a sign: CSS has no operator that negates what follows it,
- * so a sign standing apart from its number, or a second sign written in front
- * of the first, is not a calculation any browser reads.
- *
- * @param  {ExpressionReader} reader  The token reader.
- * @return {Map|null}                 The unit totals the signed number states, or null when the sign signs nothing.
- */
-function parseSignedNumber (reader) {
-  const signToken = peekToken(reader);
-  const signedToken = peekToken(reader, 1);
-  const signsItsValue = (
-    (signedToken?.type === 'number' || signedToken?.type === 'identifier') &&
-    !signedToken.precededBySpace
-  );
-  if (!signsItsValue) {
-    return null;
-  }
-  reader.index++;
-  const value = parseOperand(reader);
-  if (!value) {
-    return null;
-  }
-  if (signToken.operator === '-') {
-    return scaleUnitTotals(value, -1);
-  }
-  return value;
-}
-
-/**
- * Reads a single operand: a signed number, a number, a numeric constant, a
- * parenthesized sum, or another math function.
- *
- * @param  {ExpressionReader} reader  The token reader.
- * @return {Map|null}                 The unit totals the operand states, or null when it cannot be resolved.
- */
-function parseOperand (reader) {
-  const token = peekToken(reader);
-  if (!token) {
-    return null;
-  }
-  if (token.type === 'operator' && (token.operator === '+' || token.operator === '-')) {
-    return parseSignedNumber(reader);
-  }
-  if (token.type === 'number') {
-    reader.index++;
-    return createUnitTotals(token.number, token.unit, true);
-  }
-  if (token.type === 'identifier') {
-    reader.index++;
-    const constant = NUMERIC_CONSTANTS.get(token.name);
-    if (constant === undefined) {
-      return null;
-    }
-    return createUnitTotals(constant, UNITLESS);
-  }
-  if (token.type === 'function') {
-    reader.index++;
-    return parseMathFunction(reader, token.name);
-  }
-  if (token.type === 'open') {
-    reader.index++;
-    return parseGroup(reader);
-  }
-  return null;
-}
-
-/**
- * Reads a sum written inside parentheses, which is read as one operand of the
- * calculation around it.
- *
- * @param  {ExpressionReader} reader  The token reader.
- * @return {Map|null}                 The unit totals the group states, or null when it cannot be resolved.
- */
-function parseGroup (reader) {
-  if (reader.depth >= MAXIMUM_NESTING_DEPTH) {
-    return null;
-  }
-  reader.depth++;
-  const value = parseSum(reader);
-  reader.depth--;
-  if (!value || peekToken(reader)?.type !== 'close') {
-    return null;
-  }
-  reader.index++;
-  return value;
-}
-
-/**
- * Reads one argument of a math function, which is either a sum or a lone
- * keyword such as the rounding strategy of `round()` or the open end of a
- * `clamp()` range.
- *
- * @param  {ExpressionReader} reader  The token reader.
- * @return {object|null}              The argument read, or null when it cannot be resolved.
- */
-function parseFunctionArgument (reader) {
-  const token = peekToken(reader);
-  const followingToken = peekToken(reader, 1);
-  const standsAlone = followingToken?.type === 'comma' || followingToken?.type === 'close';
-  const isKeyword = token?.type === 'identifier' && standsAlone && !NUMERIC_CONSTANTS.has(token.name);
-  if (isKeyword) {
-    reader.index++;
-    return { keyword: token.name, value: null };
-  }
-  const value = parseSum(reader);
-  if (!value) {
-    return null;
-  }
-  return { keyword: null, value };
-}
-
-/**
- * Reads the comma-separated arguments a math function is called with, up to
- * the parenthesis that closes the call.
- *
- * @param  {ExpressionReader} reader  The token reader.
- * @return {Array|null}               The arguments read, or null when the call cannot be resolved.
- */
-function parseFunctionArguments (reader) {
-  const argumentList = [];
-  while (reader.index < reader.tokens.length) {
-    const argument = parseFunctionArgument(reader);
-    if (!argument) {
-      return null;
-    }
-    argumentList.push(argument);
-    const token = peekToken(reader);
-    if (token?.type === 'close') {
-      reader.index++;
-      return argumentList;
-    }
-    if (token?.type !== 'comma') {
-      return null;
-    }
-    reader.index++;
-  }
-  return null;
-}
-
-/**
- * Reads the arguments of a math function and works out the value the function
- * resolves to.
- *
- * @param  {ExpressionReader} reader  The token reader.
- * @param  {string}           name    The lowercased name of the function being called.
- * @return {Map|null}                 The unit totals the function resolves to, or null when it cannot be resolved.
- */
-function parseMathFunction (reader, name) {
-  const resolveFunction = MATH_FUNCTION_EVALUATORS.get(name);
-  if (!resolveFunction || reader.depth >= MAXIMUM_NESTING_DEPTH) {
-    return null;
-  }
-  reader.depth++;
-  const argumentList = parseFunctionArguments(reader);
-  reader.depth--;
-  if (!argumentList) {
-    return null;
-  }
-  return resolveFunction(argumentList);
-}
-
-/**
- * Reads the arguments of a function as the numbers of one shared unit, which
- * is what a function comparing or rounding its arguments needs them to be.
- * Arguments carrying different units are only comparable once they are
- * resolved against the element, which is long after minification.
- *
- * @param  {Array}       argumentList  The arguments the function was called with.
- * @return {object|null}               The shared unit and the numbers the arguments state, or null when they do not share one.
- */
-function readComparableArguments (argumentList) {
-  const numbers = [];
-  let sharedUnit = null;
-  for (const argument of argumentList) {
-    if (!argument.value) {
-      return null;
-    }
-    const quantity = readSingleQuantity(argument.value);
-    if (!quantity) {
-      return null;
-    }
-    if (sharedUnit !== null && quantity.unit !== sharedUnit) {
-      return null;
-    }
-    sharedUnit = quantity.unit;
-    numbers.push(quantity.number);
-  }
-  if (!numbers.length) {
-    return null;
-  }
-  return { numbers, unit: sharedUnit };
-}
-
-/**
- * Reads the single value argument a function takes, which no keyword may
- * stand in for.
- *
- * @param  {Array}    argumentList  The arguments the function was called with.
- * @return {Map|null}               The unit totals of the lone argument, or null when the function was called with anything else.
- */
-function readLoneArgument (argumentList) {
-  if (argumentList.length !== 1) {
-    return null;
-  }
-  return argumentList[0].value;
-}
-
-/**
- * Resolves `calc()`, which states the value its one argument works out to.
- *
- * @param  {Array}    argumentList  The arguments the function was called with.
- * @return {Map|null}               The unit totals the calculation states, or null when it cannot be resolved.
- */
-function evaluateCalculation (argumentList) {
-  return readLoneArgument(argumentList);
-}
-
-/**
- * Resolves `min()`, which states the smallest of the values it compares.
- *
- * @param  {Array}    argumentList  The arguments the function was called with.
- * @return {Map|null}               The unit totals of the smallest argument, or null when the arguments are not comparable.
- */
-function evaluateMinimum (argumentList) {
-  const comparable = readComparableArguments(argumentList);
-  if (!comparable) {
-    return null;
-  }
-  const winningIndex = comparable.numbers.indexOf(Math.min(...comparable.numbers));
-  return argumentList[winningIndex].value;
-}
-
-/**
- * Resolves `max()`, which states the largest of the values it compares.
- *
- * @param  {Array}    argumentList  The arguments the function was called with.
- * @return {Map|null}               The unit totals of the largest argument, or null when the arguments are not comparable.
- */
-function evaluateMaximum (argumentList) {
-  const comparable = readComparableArguments(argumentList);
-  if (!comparable) {
-    return null;
-  }
-  const winningIndex = comparable.numbers.indexOf(Math.max(...comparable.numbers));
-  return argumentList[winningIndex].value;
-}
-
-/**
- * Reports whether an end of a `clamp()` range is left open, which the `none`
- * keyword does, leaving that end to bound nothing.
- *
- * @param  {object}  argument  The argument written at that end of the range.
- * @return {boolean}           Whether that end of the range is open.
- */
-function boundsNothing (argument) {
-  return argument.keyword === 'none';
-}
-
-/**
- * Resolves `clamp()`, which holds its preferred value inside the range its
- * other two arguments bound. The smallest value wins a range written back to
- * front, since the preferred value is held below the maximum before it is
- * held above the minimum.
- *
- * @param  {Array}    argumentList  The arguments the function was called with.
- * @return {Map|null}               The unit totals of the clamped value, or null when the arguments are not comparable.
- */
-function evaluateClamp (argumentList) {
-  if (argumentList.length !== 3) {
-    return null;
-  }
-  const [lowerBound, preferred, upperBound] = argumentList;
-  const boundedArguments = argumentList.filter((argument) => {
-    return !boundsNothing(argument);
-  });
-  const comparable = readComparableArguments(boundedArguments);
-  if (!comparable || !preferred.value) {
-    return null;
-  }
-  let clamped = readSingleQuantity(preferred.value).number;
-  if (!boundsNothing(upperBound)) {
-    clamped = Math.min(clamped, readSingleQuantity(upperBound.value).number);
-  }
-  if (!boundsNothing(lowerBound)) {
-    clamped = Math.max(clamped, readSingleQuantity(lowerBound.value).number);
-  }
-  return createUnitTotals(clamped, comparable.unit);
-}
-
-/**
- * Resolves `abs()`, which states its argument's distance from zero.
- *
- * @param  {Array}    argumentList  The arguments the function was called with.
- * @return {Map|null}               The unit totals of the absolute value, or null when the argument states more than one quantity.
- */
-function evaluateAbsolute (argumentList) {
-  const comparable = readComparableArguments(argumentList);
-  if (!comparable || comparable.numbers.length !== 1) {
-    return null;
-  }
-  return createUnitTotals(Math.abs(comparable.numbers[0]), comparable.unit);
-}
-
-/**
- * Resolves `sign()`, which states which side of zero its argument lies on as
- * a plain number.
- *
- * @param  {Array}    argumentList  The arguments the function was called with.
- * @return {Map|null}               The unit totals of the sign, or null when the argument states more than one quantity.
- */
-function evaluateSign (argumentList) {
-  const comparable = readComparableArguments(argumentList);
-  if (!comparable || comparable.numbers.length !== 1) {
-    return null;
-  }
-  return createUnitTotals(Math.sign(comparable.numbers[0]), UNITLESS);
-}
-
-/**
- * Resolves `hypot()`, which states the length of the vector its arguments
- * measure the sides of.
- *
- * @param  {Array}    argumentList  The arguments the function was called with.
- * @return {Map|null}               The unit totals of the hypotenuse, or null when the arguments are not comparable.
- */
-function evaluateHypotenuse (argumentList) {
-  const comparable = readComparableArguments(argumentList);
-  if (!comparable) {
-    return null;
-  }
-  return createUnitTotals(Math.hypot(...comparable.numbers), comparable.unit);
-}
-
-/**
- * Reads the two comparable numbers a function divides one of by the other,
- * refusing a divisor of zero, which no division resolves against.
- *
- * @param  {Array}       argumentList  The arguments the function was called with.
- * @return {object|null}               The shared unit with the dividend and the divisor, or null when the arguments cannot be divided.
- */
-function readDivisionArguments (argumentList) {
-  const comparable = readComparableArguments(argumentList);
-  if (!comparable || comparable.numbers.length !== 2 || comparable.numbers[1] === 0) {
-    return null;
-  }
-  return {
-    dividend: comparable.numbers[0],
-    divisor: comparable.numbers[1],
-    unit: comparable.unit
-  };
-}
-
-/**
- * Resolves `mod()`, which states what is left of its first argument after
- * taking out whole multiples of its second, carrying the sign of the divisor.
- *
- * @param  {Array}    argumentList  The arguments the function was called with.
- * @return {Map|null}               The unit totals of the modulus, or null when the arguments cannot be divided.
- */
-function evaluateModulus (argumentList) {
-  const division = readDivisionArguments(argumentList);
-  if (!division) {
-    return null;
-  }
-  const { dividend, divisor, unit } = division;
-  return createUnitTotals(((dividend % divisor) + divisor) % divisor, unit);
-}
-
-/**
- * Resolves `rem()`, which states what is left of its first argument after
- * taking out whole multiples of its second, carrying the sign of the dividend.
- *
- * @param  {Array}    argumentList  The arguments the function was called with.
- * @return {Map|null}               The unit totals of the remainder, or null when the arguments cannot be divided.
- */
-function evaluateRemainder (argumentList) {
-  const division = readDivisionArguments(argumentList);
-  if (!division) {
-    return null;
-  }
-  const { dividend, divisor, unit } = division;
-  return createUnitTotals(dividend % divisor, unit);
-}
-
-/**
- * Resolves `round()`, which states the multiple of its rounding interval that
- * the strategy it is given rounds its value to. A call written without a
- * strategy rounds to the nearest multiple.
- *
- * @param  {Array}    argumentList  The arguments the function was called with.
- * @return {Map|null}               The unit totals of the rounded value, or null when the arguments cannot be rounded.
- */
-function evaluateRound (argumentList) {
-  let strategyName = 'nearest';
-  let valueArguments = argumentList;
-  if (argumentList.length === 3) {
-    strategyName = argumentList[0].keyword;
-    valueArguments = argumentList.slice(1);
-  }
-  const roundIntervals = ROUNDING_STRATEGIES.get(strategyName);
-  const division = readDivisionArguments(valueArguments);
-  if (!roundIntervals || !division) {
-    return null;
-  }
-  const { dividend, divisor, unit } = division;
-  return createUnitTotals(roundIntervals(dividend / divisor) * divisor, unit);
-}
-
-/**
- * How each math function resolves the arguments it is called with. The
- * functions listed here are the ones whose arguments are arithmetic, so that
- * `*` and `/` between them are operators rather than characters of some other
- * syntax.
- *
- * @type {Map<string, function(Array): (Map|null)>}
- */
-const MATH_FUNCTION_EVALUATORS = new Map([
-  ['abs', evaluateAbsolute],
-  ['calc', evaluateCalculation],
-  ['clamp', evaluateClamp],
-  ['hypot', evaluateHypotenuse],
-  ['max', evaluateMaximum],
-  ['min', evaluateMinimum],
-  ['mod', evaluateModulus],
-  ['rem', evaluateRemainder],
-  ['round', evaluateRound],
-  ['sign', evaluateSign]
-]);
-
-/**
- * The names of the functions whose arguments are a math expression.
- *
- * @type {Set<string>}
- */
-const MATH_FUNCTION_NAMES = new Set(MATH_FUNCTION_EVALUATORS.keys());
-
-/**
- * The smallest total a term is written with. A term totalling less than this
- * is the rounding error binary floating point arithmetic leaves behind rather
- * than a quantity the stylesheet states.
- *
- * @type {number}
- */
-const NEGLIGIBLE_TOTAL = 1e-12;
-
-/**
- * The unit each kind of quantity is canonically stated in, and how much of
- * that unit one of the unit written measures. Absolute lengths are absent
- * because every length is already totalled in the pixels it measures.
- *
- * @type {Map<string, {unit: string, perUnit: number}>}
- */
-const CANONICAL_UNITS = new Map([
-  ['s', { unit: 's', perUnit: 1 }],
-  ['ms', { unit: 's', perUnit: 1 / 1000 }],
-  ['deg', { unit: 'deg', perUnit: 1 }],
-  ['grad', { unit: 'deg', perUnit: 360 / 400 }],
-  ['rad', { unit: 'deg', perUnit: 180 / Math.PI }],
-  ['turn', { unit: 'deg', perUnit: 360 }],
-  ['hz', { unit: 'hz', perUnit: 1 }],
-  ['khz', { unit: 'hz', perUnit: 1000 }],
-  ['dppx', { unit: 'dppx', perUnit: 1 }],
-  ['x', { unit: 'dppx', perUnit: 1 }],
-  ['dpi', { unit: 'dppx', perUnit: 1 / 96 }],
-  ['dpcm', { unit: 'dppx', perUnit: 2.54 / 96 }]
-]);
-
-/**
- * Counts how many units of each kind of quantity a calculation totalled, so
- * that the kinds it states in more than one unit can be told from the ones it
- * states in a single unit.
- *
- * @param  {Map} totals  The unit totals the calculation resolved to.
- * @return {Map}         How many units each canonical unit was totalled from.
- */
-function countUnitsByKind (totals) {
-  const counts = new Map();
-  for (const unit of totals.keys()) {
-    const conversion = CANONICAL_UNITS.get(unit);
-    if (!conversion) {
-      continue;
-    }
-    counts.set(conversion.unit, (counts.get(conversion.unit) || 0) + 1);
-  }
-  return counts;
-}
-
-/**
- * Restates the totals of every kind of quantity a calculation measured in two
- * units of, so that terms measuring the same thing are totalled together
- * (`calc(1s - 200ms)` comes to `.8s`). A kind measured in a single unit keeps
- * that unit: restating `2ms` as `.002s` measures the same time in more
- * characters than it was written with.
- *
- * @param  {Map} totals  The unit totals the calculation resolved to.
- * @return {Map}         The totals, with each kind of quantity stated in one unit.
- */
-function mergeUnitsOfSameKind (totals) {
-  const unitCounts = countUnitsByKind(totals);
-  const measuredInSeveralUnits = [...unitCounts.values()].some((count) => {
-    return count > 1;
-  });
-  if (!measuredInSeveralUnits) {
-    return totals;
-  }
-  const merged = new Map();
-  for (const [unit, total] of totals) {
-    const conversion = CANONICAL_UNITS.get(unit);
-    const restatesUnit = conversion && unitCounts.get(conversion.unit) > 1;
-    const mergedUnit = restatesUnit ? conversion.unit : unit;
-    const mergedTotal = restatesUnit ? total * conversion.perUnit : total;
-    merged.set(mergedUnit, (merged.get(mergedUnit) || 0) + mergedTotal);
-  }
-  return merged;
-}
-
-/**
- * Collects the terms a resolved calculation is written from, leaving out the
- * ones that totalled to nothing. A unit is totalled from where it is first
- * written, so the terms keep the order the calculation states them in, which
- * is both the order the author chose and one fewer difference between what
- * was written and what is written back out.
- *
- * @param  {Map}   totals  The unit totals the calculation resolved to.
- * @return {Array}         The terms to write, each holding its unit and its total.
- */
-function collectOutputTerms (totals) {
-  const terms = [];
-  for (const [unit, total] of totals) {
-    if (Math.abs(total) < NEGLIGIBLE_TOTAL) {
-      continue;
-    }
-    terms.push({ total, unit });
-  }
-  return leadWithAddedTerm(terms);
-}
-
-/**
- * Moves an added term to the front of a calculation that a subtracted one
- * leads. Every term but the first is written after the operator adding or
- * subtracting it, so a term written first states its own sign, and the minus
- * sign of a subtracted one is a character the sum saves by being led by a
- * term that is added instead.
- *
- * @param  {Array} terms  The terms to write, in the order the calculation states them.
- * @return {Array}        The same terms, led by one that is added whenever any of them is.
- */
-function leadWithAddedTerm (terms) {
-  if (!terms.length || terms[0].total > 0) {
-    return terms;
-  }
-  const leadingIndex = terms.findIndex((term) => {
-    return term.total > 0;
-  });
-  if (leadingIndex === -1) {
-    return terms;
-  }
-  const reordered = [...terms];
-  const [addedTerm] = reordered.splice(leadingIndex, 1);
-  reordered.unshift(addedTerm);
-  return reordered;
-}
-
-/**
- * Reports whether writing only the terms collected would drop a percentage the
- * calculation was written with. A percentage that cancels out still ties the
- * value to the basis the percentage is resolved against, so a calculation
- * keeping other terms cannot be written without it.
- *
- * @param  {Map}     totals       The unit totals the calculation resolved to.
- * @param  {Array}   outputTerms  The terms that would be written.
- * @return {boolean}              Whether a percentage the calculation states would be lost.
- */
-function dropsPercentageBasis (totals, outputTerms) {
-  if (!totals.has(PERCENTAGE) || !outputTerms.length) {
-    return false;
-  }
-  return !outputTerms.some((term) => {
-    return term.unit === PERCENTAGE;
-  });
-}
-
-/**
- * Writes the total of a term as the number a stylesheet states it with. A
- * total that no written number states faithfully — one that is infinite, one
- * beyond the integers a double holds exactly, and one that rounds away to
- * nothing — has no number to be written as.
- *
- * @param  {number}      total  The total the term resolved to.
- * @return {string|null}        The number as it is written into the stylesheet, or null when it cannot be written.
- */
-function writeTermNumber (total) {
-  if (!Number.isFinite(total) || Math.abs(total) > Number.MAX_SAFE_INTEGER) {
-    return null;
-  }
-  const written = formatResolvedNumber(total);
-  const roundsAwayToNothing = total !== 0 && parseFloat(written) === 0;
-  if (roundsAwayToNothing) {
-    return null;
-  }
-  return written;
-}
-
-/**
- * Writes the unit totals a calculation resolved to as the shortest value
- * stating them: the lone quantity they came to, or, when units that only
- * resolve against the element are left over, a `calc()` summing what remains.
- *
- * @param  {Map}         totals  The unit totals the calculation resolved to.
- * @return {string|null}         The value the calculation resolved to, or null when it cannot be written faithfully.
- */
-function formatUnitTotals (totals) {
-  const writtenQuantity = totals.writtenQuantity;
-  if (
-    writtenQuantity &&
-    totals.size === 1 &&
-    totals.has(writtenQuantity.canonicalUnit) &&
-    totals.get(writtenQuantity.canonicalUnit) === writtenQuantity.canonicalNumber
-  ) {
-    return formatResolvedNumber(writtenQuantity.number) + writtenQuantity.unit;
-  }
-  const mergedTotals = mergeUnitsOfSameKind(totals);
-  const hasUnrepresentableReciprocalUnit = [...mergedTotals.keys()].some((unit) => {
-    return unit.startsWith('reciprocal:');
-  });
-  if (hasUnrepresentableReciprocalUnit) {
-    return null;
-  }
-  const outputTerms = collectOutputTerms(mergedTotals);
-  if (dropsPercentageBasis(mergedTotals, outputTerms)) {
-    return null;
-  }
-  if (!outputTerms.length) {
-    return '0';
-  }
-  const [leadingTerm, ...trailingTerms] = outputTerms;
-  const leadingNumber = writeTermNumber(leadingTerm.total);
-  if (leadingNumber === null) {
-    return null;
-  }
-  let written = leadingNumber + leadingTerm.unit;
-  for (const term of trailingTerms) {
-    const number = writeTermNumber(Math.abs(term.total));
-    if (number === null) {
-      return null;
-    }
-    // Both operators have to be surrounded by whitespace to be read as one
-    written = written + (term.total < 0 ? ' - ' : ' + ') + number + term.unit;
-  }
-  if (trailingTerms.length) {
-    return 'calc(' + written + ')';
-  }
-  return written;
-}
-
-/**
- * Resolves a CSS math function into the value its arithmetic works out to.
- * A function whose operands are not all known at minification time — one
- * referencing a custom property, an environment variable, or an element the
- * value is only resolved against once the page is laid out — states a value
- * that cannot be worked out here, and so resolves to nothing.
- *
- * @param  {string}      mathFunction  The math function as it is written, such as `calc(10 / 2)` or `min(10px, 20px)`.
- * @return {string|null}               The value the math function states, or null when it cannot be resolved.
- */
-function simplifyCalc (mathFunction) {
-  const tokens = tokenizeMathExpression(mathFunction);
-  if (!tokens) {
-    return null;
-  }
-  const reader = { tokens, index: 0, depth: 0 };
-  const totals = parseSum(reader);
-  // A token left unread means the expression states more than the arithmetic
-  // that was resolved, so what was resolved is not the whole of its value
-  if (!totals || reader.index !== tokens.length) {
-    return null;
-  }
-  return formatUnitTotals(totals);
-}
-
-export {
-  formatUnitTotals,
-  MATH_FUNCTION_NAMES,
-  simplifyCalc
-};