@geronimus/text

Contains utility functions for working with text values.

Usage

import { member_name } from "@geronimus/text";

or

const { member_name } = require( "@geronimus/text" );

Module Members

Character

Contains collections of constants describing various classifications of special characters.

Contants

Character.Control object

An object containing constants for each non-printable contol character.

Character.ControlSet Set[ string ]

A Set containing all non-printable control characters.

Character.LineEnd object

An object containing constants for each line-terminating character.

Character.LineEndSet Set[ string ]

A Set containing all non-printable control characters.

Character.Space object

An object containing constants for each spacing character.

Character.SpaceSet Set[ string ]

A Set containing all spacing characters.

escape( chars, inText, escapeChar )

Returns the inText argument, with every character in the chars argument escaped.

By default, this function uses JavaScript's escape character, the backslash (\). However, you can provide another character value to the escapeChar parameter to use that character instead.

The original use case for this function was printing text representations of values that may need to contain string literals, where internal double-quotes (") or other characters may need to be escaped.

Parameters

chars string | Array[ string ]

The characters to escape. You can pass a single-character string, or an array of single-character strings.

inText string

The text containing the characters to be escaped.

escapeChar string (Optional)

If you don't provide this argument, the default value of the backslash (\) will be used. Otherwise, you can provide an alternate value to be used as an escape character.

firstOccurrence( substrings, text )

Returns the index of the first occurrence of one of the substrings within the text.

The returned index is that of the logical character, and not of the byte. So be careful with strings containing multi-byte characters.

Parameters

substrings string | Array[ string ]

You can pass a single string, or an array of strings. These are the values that we are looking for in the text.

text string

The text to search for an occurrence of one of the substrings.

Return value

If the substring is not found within the text - or if the text or all of the substrings are the empty string - then the return value is: -1;

Otherwise, the return value is the index of the character within the text.

However, note that if the text contains any multi-byte characters, the returned value is the index of the logical character, and not of the byte - which is what you would get from String.prototype.indexOf().

head( text )

A function to help you safely iterate over a text value as a sequence of characters.

It returns the first character in the text value, irrespective of how many bytes it contains.

Parameters

text string

The text whose first character you wish to return.

Return value

If the text contains at least one character, it returns the first character.

Otherwise, it returns the empty string value.

Examples

head( "head" ); // => "h"
head( "🚕 🛵" ); // => "🚕"
head( "" ); // => ""

tail( text )

A function to help you safely iterate over a text value as a sequence of characters.

It returns the string of all characters following the first, irrespective of how many bytes the the characters contain.

Parameters

text string

The text for which you wish to return all characters except the first.

Return value

string

If the text contains at least two characters, it returns the string of all characters except the first.

Otherwise, it returns the empty string value.

Examples

tail( "tail" ); // => "ail"
tail( "🚕 🛵" ); // => " 🛵"
tail( "a" ); // => ""