Accoutrement 2.1.1

String functions

Functions for basic Sass-string manipulation. While these functions are defined with private prefixes, they are registered without the prefix for map-access.

@function str-replace()

Replace a substring inside a larger string, or replace the entirety of the string.

This function is prefixed outside maps & should not be used directly, but is available in all accoutrement maps under the 'str-replace' alias.

Since 1.0.0:

  • NEW: Improved handling of non-string values, allows you to replace a number within a string, for example

Parameters & Return

$string: (string | list)

The original string (or list of strings) to edit

$old: (*)

A sub-string to replace

$new: null (*)

A new sub-string to replace the old

$replace-all: false (boolean)

A new sub-string to replace the old

@return (string)

Original string, with substring replaced

Example

scss
// sass treats calc() as a string,
// so we can use string-functions to manipulate calc values…
$map: (
  'text-size': calc(1em + 1vw),
  'large-text': '#text-size' ('str-replace': '1vw' '3vw'),
);
/*! #{get-token($map, 'large-text')} */
css compiled
/*! calc(1em + 3vw) */

Requires

@function _a_list-template() [private]

@function interpolate()

Return a string with interpolated values replacing %s placeholders in a format string.

This function is prefixed outside maps & should not be used directly, but is available in all accoutrement maps under the 'interpolate' or '%s' aliases.

Parameters & Return

$string: (string)

The original string to be edited

$values...: (*)

New strings, to replace the %s format strings

@return (string)

Original string, with %s format strings replaced

@error

Too many interpolation values given for the string

Example

scss
// sass treats calc() as a string,
// so we can use string-functions to manipulate calc values…
$map: (
  'root': 16px,
  'responsive': calc(%s + %s) ('%s': #root 0.5vw),
);
/*! #{get-token($map, 'responsive')} */
css compiled
/*! calc(16px + 0.5vw) */

Requires

@function _a_type-check() [private]

@function _a_error() [private]

@function str-split()

Splits a string into a list of strings, using the same logic as JavaScript’s split() meathod.

This function is prefixed outside maps & should not be used directly, but is available in all accoutrement maps under the 'str-split' or 'split' aliases.

Since 1.0.0:

  • NEW: Aliased as str-split

Parameters & Return

$string: (string)

The original string to be split

  • Empty strings will be returned as a list of one empty string

$separator: null (*)

The string will be split on any instance of the separator, and the separators will be removed

  • Null or unfound separators will return a single-item list with the original string
  • Empty-string ('') separators will return a list of all characters in the original string
  • Non-string separators will be converted to strings before splitting

$limit: null (integer | null)

Maximum length of the returned list

@return (list)

Space-delimited list of string-slices from the original string

Example

scss
$map: (
  'list': 'hello world' ('split': ' '),
);
/*! #{get-token($map, 'list')} */
css compiled
/*! hello world */

@function str-trim()

Trims whitespace from the start and end of a string.

This function is prefixed outside maps & should not be used directly, but is available in all accoutrement maps under the 'str-trim' or 'trim' aliases.

Since 1.0.0:

  • NEW: Strips whitespace
  • NEW: Aliased as str-trim

Parameters & Return

$string: (string)

The original string to be trimmed

@return (string)

Trimmed string

Example

scss
$map: (
  // null value is needed for single-argument functions…
  'trim': '  hello world     ' ('trim': null),
);
/*! #{get-token($map, 'trim')} */
css compiled
/*! hello world */

Requires

@function _a_type-check() [private]