string-dashes^1.4.6

No 3rd party dependencies. All dependencies and devDependencies, checked recursively, are Codsen packages.

Permalink to InstallationInstallation

Permalink to Quick TakeQuick Take

Permalink to ExamplesExamples

• An ambiguous hyphen is left alone
• Convert one em dash into an entity
• Disable the dash conversion
• Convert a letter range into an en dash
• Convert a number range into an en dash
• Convert a maths minus into an en dash
• Report the index offsets through a callback
• Supply the dash value separately

Idea

A hyphen (-) is not a dash. Typographically-correct English text uses three different characters:

This program finds hyphens and dashes which are in the wrong place and reports what to replace them with. It reads the surrounding characters to decide, so it does not need you to mark anything up.

This is a sibling of string-apostrophes; both are used by detergent.

Sources used in rules logic and unit tests:

• Oxford A–Z of Grammar and Punctuation 2nd Ed., 2009, ISBN 978–0199564675
• Butterick’s Practical Typography 2nd Ed., “Hyphens and dashes” chapter

The rules

The program applies three rules. In each, the character being evaluated is a hyphen, an en dash or an em dash.

1. Number range or A-Z range → en dash. A hyphen with a digit on each side (1880-1912) becomes an en dash. So does a hyphen between two standalone uppercase letters (A-Z).
2. Whitespace on both sides → em dash. A hyphen or en dash becomes —; an existing prose em dash stays unchanged. The exception is arithmetic: numeric or currency operands (1 - 2, $5 - $2, 5$ - 2$) receive an en dash for a hyphen, en dash, or em dash. This includes spaced em dashes such as 1 — 2 and any amount of whitespace.
3. Cut-off speech → em dash. A letter, then a hyphen, then a quote ("I was just abo-") becomes an em dash.

Anything the rules don’t recognise is left alone.

API — convertAll()

The main function convertAll() is imported like this:

It’s a function which takes two input arguments:

The Optional Options Object has the following shape:

Omitted or undefined conversion flags use their defaults. An explicit convertDashes: false disables conversion.

Use convertOne() to provide your own span or decoded symbol. convertAll() scans literal characters; it does not decode HTML entities automatically.

Here are all defaults in one place for copying:

The function will return a plain object:

For example:

import { convertAll } from "string-dashes";

console.log(
  convertAll("Dashes come in two sizes - the en dash and the em dash.", {
    convertEntities: true,
  }),
);
// => {
//      result: "Dashes come in two sizes — the en dash and the em dash.",
//      ranges: [[25, 26, "—"]],
//    }

API — convertOne()

The main function convertOne() is imported like this:

It’s a function which takes two input arguments:

The Obligatory Options Object has the following shape:

Pass an options object; null receives the required-options error. opts.from must be an integer from 0 to str.length - 1. opts.to defaults to from + 1. Backwards or out-of-bounds integer spans throw an error prefixed with string-dashes/convertOne().

Equal endpoints are valid: a supplied value can insert a dash without deleting source text. For example, convertOne("12", { from: 1, to: 1, value: "-" }) returns [[1, 1, "–"]].

The function returns ranges: an array of range arrays or null. Later you can use them in ranges-apply to process a string using those ranges (in other words, “to apply those ranges”).

import { convertOne } from "string-dashes";

console.log(
  convertOne("Dashes come in two sizes - the en dash and the em dash.", {
    from: 25,
    convertEntities: true,
  }),
);
// => [[25, 26, "—"]]

opts.value

Use opts.value when the character sits in the string encoded, or represented by something other than a literal -, – or —. You tell the program where the “symbol” starts (from) and ends (to), and what it stands for (value); the program then evaluates the surroundings as if a real dash were there:

import { convertOne } from "string-dashes";

console.log(
  convertOne("Dashes come in two sizes - the en dash.", {
    from: 25,
    to: 30,
    value: "-", // tell the program indexes 25-30 represent a hyphen
  }),
);
// => [[25, 30, "—"]]

The context scan begins after the complete supplied span, including when multiple spaces, tabs, or newlines separate it from the next operand:

import { convertOne } from "string-dashes";

convertOne("1 -  2", { from: 2, to: 7, value: "-" });
// => [[2, 7, "–"]]

That’s how detergent uses this package. convertEntities controls the encoding of replacements; it does not encode already-correct prose em dashes.

API — defaults

You can import defaults:

It's a plain object:

The main function calculates the options to be used by merging the options you passed with these defaults.

These defaults are applicable for both convertOne() and convertAll() functions.

API — version

You can import version:

API — types

This package is written in TypeScript and exports the following types:

import type { Opts, Range, Ranges } from "string-dashes";

Permalink to changelogChangelog