Accoutrement 4.0.5

Sass Utilities

We use a number of Sass utilities to help manage strings, maps, and lists. As more functions are added to the Sass core, we hope to be able to remove some or all of these over time.

Sass Lists

Utility functions that extend the Sass core modules, to help with advanced list manipulation.

@function remove-nth()

Remove any item (1-indexed) from a list.

This function has a list- prefix added by default (e.g. list-remove-nth()) unless it’s imported directly. However, it’s available in all Accoutrement maps as 'remove-nth'.

Since 4.0.0:

  • NEW: Now also available to use directly, without private prefix

Parameters & Return

$list: (list)

The original list to be edited

$index: (number)

The 1-indexed item to remove from the list

@return (list)

The original list, with item removed

@error

$index must be a non-zero integer

@error

$index is too large for the list length

Example

scss 
$map: (
  'main-start': ['nav-end' 'main-start' 'footer-start'],
  'small-start': '#main-start' ('remove-nth': 1),
);
/*! #{meta.inspect(tools.get($map, 'small-start'))} */
css compiled 
/*! ["main-start" "footer-start"] */

Requires

@function template() [private]

@function error() [private]

Used By

@function normalize-token() [private]

@function next-alias() [private]

@function lookup-alias() [private]

Sass Maps

Utility functions that extend the Sass core modules, to help with advanced map manipulation.

These functions have a map- prefix added by default (e.g. map-multi-merge()) unless they are imported directly.

@function multi-merge()

Merge multiple maps into a single map, in case you want to define tokens in smaller groups – such as brand-colors, text-colors, etc. – before merging them into a single map.

Since 4.0.0:

  • NEW: Initial release

Parameters & Return

$maps: (maps...)

Pass any number of maps to be merged.

@return (map)

The merged map of easings.

Requires

@function check() [private]

@function error() [private]

Used By

@mixin add-changes()

@mixin add-easing()

@mixin add-times()

@mixin add-colors()

@mixin add-ratios()

@mixin add-sizes()

Sass Strings

Utility function(s) that extend the Sass core modules, to help with advanced string manipulation.

@function replace()

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

This function has a str- prefix added by default (e.g. str-replace()) unless it’s imported directly. However, it’s available in all Accoutrement maps as either 'replace' or 'str-replace'.

Since 4.0.0:

  • BREAKING: Renamed from _a_str-replace to replace
  • NEW: Available for direct usage

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: '' (*)

A new sub-string to replace the old

$all: false (boolean)

If true, replace all instances of $old in $string

@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'),
);
/*! #{tools.get($map, 'large-text')} */
css compiled 
/*! calc(1em + 3vw) */

Requires

@function error() [private]

@function template() [private]

@function force() [private]

Used By

@function next-alias() [private]

@function interpolate()

@function ident()

@function interpolate()

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

This function has a str- prefix added by default (e.g. str-interpolate()) unless it’s imported directly. However, it’s available in all Accoutrement maps as either 'interpolate', 'str-interpolate', or '%s'.

Since 4.0.0:

  • BREAKING: Renamed from _a_interpolate to interpolate
  • NEW: Available for direct usage

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),
);
/*! #{tools.get($map, 'responsive')} */
css compiled 
/*! calc(16px + 0.5vw) */

Requires

@function check() [private]

@function error() [private]

@function replace()

@function split()

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

This function has a str- prefix added by default (e.g. str-split()) unless it’s imported directly. However, it’s available in all Accoutrement maps as either 'str-split' or 'split'.

Since 4.0.0:

  • BREAKING: Renamed from _a_split to split
  • NEW: Available for direct usage

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': ' '),
);
/*! #{tools.get($map, 'list')} */
css compiled 
/*! hello world */

Requires

@function force() [private]

Used By

@function font-get-variants() [private]

@function font-stack() [private]

@function variant-name() [private]

@function next-alias() [private]

@function lookup-alias() [private]

@function trim()

Trims whitespace from the start and end of a string.

This function has a str- prefix added by default (e.g. str-trim()) unless it’s imported directly. However, it’s available in all Accoutrement maps as either 'str-trim' or 'trim'.

Since 4.0.0:

  • BREAKING: Renamed from _a_trim to trim
  • NEW: Available for direct usage

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),
);
/*! #{tools.get($map, 'trim')} */
css compiled 
/*! hello world */

Requires

@function check() [private]

@function error() [private]

Used By

@function font-stack() [private]