sort ()

Sorts the items of a list in place. The default sort order is ascending, built upon converting the items into strings, then comparing their sequences of UTF-16 code units values.

Read more on comparison logic for a detailed explanation on sorting methods.

Parameters

$list

The list to sort.

Type

List

$compare

The function that defines the sort order. The first parameter is the first item for comparison. The second parameter is the second item for comparison. The third parameter is for centering numeric values. The returned value must be a number.

Type

Function

Default

list.compare-string()

$center

For numeric comparison, the value indicating the center (zero) position between positive and negative values.

Type

Number | auto

Default

auto

$separator

The type of separator to be used by the sorted list.

Type

space | comma | slash | auto

Default

auto

Return Value

List

The sorted list.

Example

@use '@sass-fairy/list';

// 1. Sorting as strings
$list: 'Three' 'Two' 'Five' 'Six' 'Four' 'One';

@debug list.sort($list);
  // 'Five' 'Four' 'One' 'Six' 'Three' 'Two'

@debug list.sort($list, list.compare-string());
  // 'Five' 'Four' 'One' 'Six' 'Three' 'Two'

@debug list.sort($list, list.compare-string-desc());
  // 'Two' 'Three' 'Six' 'One' 'Four' 'Five'

// 2. Sorting as numbers (Automatic)
$unsorted: 6mm 2px 4em 20mm -9mm 2cm 25px 1.25cm -4px 1 -3cm;

$sorted: list.sort($unsorted, list.compare-numeric());

@debug $sorted;
  // -3cm -9mm -4px 2px 1 4em 6mm 25px 1.25cm 2cm 20mm

@debug list.sort($sorted, list.compare-numeric());
  // -3cm -9mm -4px 2px 6mm 25px 1 1.25cm 20mm 2cm 4em

// 3. Sorting as numbers (Certain)
$sorted: list.sort($unsorted, list.compare-numeric(), 0cm);

@debug $sorted;
  // -3cm -9mm -4px 2px 6mm 25px 1 1.25cm 20mm 2cm 4em

@debug list.sort($sorted, list.compare-numeric(), 0mm);
  // -3cm -9mm -4px 2px 1 4em 6mm 25px 1.25cm 2cm 20mm

@debug list.sort($sorted, list.compare-numeric(), 0);
  // -9mm -4px -3cm 1 1.25cm 2cm 2px 4em 6mm 20mm 25px