feat(list): add functions.

Author: sciborrudnicki

src/lib/_list.add.function.scss

@@ -0,0 +1,34 @@
+// Sass.
+@use 'sass:list';
+
+// Completed
+// The `list.add()` function returns a copy of `$list` with `$value` and additional `$values`.
+// @param `$list` The list to add the `$value` and additional `$values` into.
+// @param `$separator` The separator `comma`, `space` or `slash` of the list. Default `auto`.
+// @param `$value` The value to add to the end of `$list`.
+// @arbitrary `$values...` Additional values to add into `$list`.
+// @returns Returns a copy of `$list` with `$value` and additional `$values` added to the end.
+@function add($list, $separator: auto, $value, $values...) {
+  @return list.join(
+    $list,
+    list.join(($value,), $values, list.separator($separator)),
+    $separator
+  );
+}
+
+// Examples.
+// @debug add(10px 20px, auto, 30px); // 10px 20px 30px
+// @debug add((red, green), auto, blue, space); // red, green, blue, space
+
+// additional values
+// @debug add((blue, red), auto, green, blue, red); // blue, red, green, blue, red
+// @debug add(10px 20px, auto, 30px 40px, 1px, 15px); // 10px 20px (30px 40px) 1px 15px
+// @debug add(10px, auto, 20px, 1em, 2rem); // 10px, 20px, 1em, 2rem
+// @debug add(10px 20px, auto, 30px 40px, 1px, 15px, (1px 2px 3px)); // 10px 20px (30px 40px) 1px 15px (1px 2px 3px)
+// @debug add((10px, 20px), auto, 30px 40px, 1px, 15px, (1px 2px 3px), (4px, 5px)); // 10px, 20px, 30px 40px, 1px, 15px, 1px 2px 3px, (4px, 5px)
+
+// add map
+// @debug add(1 2 3, auto, (a: 1, b: 2, c: 3),  (d: 4, e: 5)); // 1 2 3 (a: 1, b: 2, c: 3) (d: 4, e: 5)
+// @debug add((a: 1, b: 2), auto, (c: 3, d: 4), (e: 5, f: 6)); // a 1, b 2, (c: 3, d: 4), (e: 5, f: 6)
+// @debug add(1 2 3, auto, (a: 1, b: 2, c: 3), (d: 4, e: 5), (4, 5, 6), (7, 8, 9)); // 1 2 3 (a: 1, b: 2, c: 3) (d: 4, e: 5) (4, 5, 6) (7, 8, 9)
+// @debug add(1 2 3, auto, (a: 1, b: 2, c: 3), (d: 4, e: 5), 4, 5, 6, 7, 8, 9); // 1 2 3 (a: 1, b: 2, c: 3) (d: 4, e: 5) 4 5 6 7 8 9

src/lib/_list.append.function.scss

@@ -0,0 +1,51 @@
+// Sass.
+@use 'sass:list';
+@use 'sass:meta';
+
+// Completed
+// The modified `list.append()` function returns a copy of `$list` with `$val` and/or with added multiple `$values`.
+// The function is modified by adding arbitrary values to the end of the parameters to preserve the original functionality.
+// @param `$list` The list to append the `$val` and/or `$values` into.
+// @param `$val` The value to append to the end of `$list`.
+// @param `$separator` The separator `comma`, `space` or `slash` of the list. Default `auto`.
+// @arbitrary `$values...` Additional values to append into `$list`.
+// @returns Returns a copy of `$list` with `$val` and/or `$values` added to the end.
+@function append($list, $val, $separator: auto, $values...) {
+  @if not list.index(arglist list, meta.type-of($list)) {
+    @error "$list: #{$list} is not arglist or list";
+  }
+  @return list.join(
+    $list,
+    list.join(($val,), $values, list.separator($list)),
+    $separator
+  );
+}
+
+// Examples.
+// $-list1: (30px, 10px);
+// $-list2: (50px, 40px);
+
+// @debug append(10px 20px, 30px); // 10px 20px 30px
+// @debug append((red, green), blue, space); // red green blue
+
+// @debug list.join(((10px 20px),), ((30px, 10px), (50px, 40px)), $separator: comma);
+// @debug append(((10px 20px),), (30px, 10px), comma, (50px, 40px));
+
+// @debug list.join(((10px 20px),), ($-list1, $-list2), $separator: comma);
+// @debug append(((10px 20px),), $-list1, comma, $-list2);
+
+// @debug list.join(((10px 20px),), ((30px, 10px),), comma);
+// @debug list.append(((10px 20px),), (30px, 10px), comma);
+
+// additional values
+// @debug append((blue, red), green, auto, blue, red); // blue, red, green, blue, red
+// @debug append(10px 20px, 30px 40px, auto, 1px, 15px); // 10px 20px (30px 40px) 1px 15px
+// @debug append(10px, 20px, auto, 1em, 2rem); // 10px 20px 1em 2rem
+// @debug append(10px 20px, 30px 40px, auto, 1px, 15px, (1px 2px 3px)); // 10px 20px (30px 40px) 1px 15px (1px 2px 3px)
+// @debug append((10px, 20px), 30px 40px, auto, 1px, 15px, (1px 2px 3px), (4px, 5px)); // 10px, 20px, 30px 40px, 1px, 15px, 1px 2px 3px, (4px, 5px)
+
+// append map
+// @debug append(1 2 3, (a: 1, b: 2, c: 3), auto, (d: 4, e: 5)); // 1 2 3 (a: 1, b: 2, c: 3) (d: 4, e: 5)
+// @debug append((a: 1, b: 2), (c: 3, d: 4), auto, (e: 5, f: 6)); // a 1, b 2, (c: 3, d: 4), (e: 5, f: 6)
+// @debug append(1 2 3, (a: 1, b: 2, c: 3), auto, (d: 4, e: 5), (4, 5, 6), (7, 8, 9)); // 1 2 3 (a: 1, b: 2, c: 3) (d: 4, e: 5) (4, 5, 6) (7, 8, 9)
+// @debug append(1 2 3, (a: 1, b: 2, c: 3), auto, (d: 4, e: 5), 4, 5, 6, 7, 8, 9); // 1 2 3 (a: 1, b: 2, c: 3) (d: 4, e: 5) 4 5 6 7 8 9

src/lib/_list.empty.function.scss

@@ -0,0 +1,20 @@
+// Sass.
+@use 'sass:list';
+
+// Completed
+// The `list.empty()` function returns the `bool` indicating whether the list is empty.
+// @param `$list` The list to check against its length.
+// @returns The returned value is a `bool` indicating whether the given `$list` is empty.
+@function empty($list) {
+  @return list.length($list) == 0;
+}
+
+// Alias name for `list.empty()`.
+@function is-empty($list) {
+  @return empty($list);
+}
+
+// Examples.
+// @debug empty(()); // true
+// @debug empty((1, )); // true
+// @debug empty((a: 1)); // false

src/lib/_list.extract-map.function.scss

@@ -0,0 +1,22 @@
+// Functions.
+@use 'get/get.map.function' as get-map;
+@use 'remove/remove.map.function' as remove-map;
+
+// Completed
+// The `list.extract-map()` gets and removes the map from `$list`.
+// @param `$list` A list from which the map is extracted.
+// @param `$occurrence` Extract `first`, `last` map or `all` maps.
+// @returns The returned value is a map with extracted from `$list` map(or multiple maps in list) in `map` key, and list without `map`.
+@function extract-map($list, $occurrence: first) {
+  @return (map: get-map.map($list, $occurrence), list: remove-map.map($list));
+}
+
+// Examples.
+// first map
+// @debug extract-map((a, b, (a: 1, b: 5), c, d)); // (map: (a: 1, b: 5), list: (a, b, c, d))
+
+// last map
+// @debug extract-map((a, b, (a: 1, b: 5), c, (c: 1, d: 1), d), last); // (map: (c: 1, d: 1), list: (a, b, c, d))
+
+// all maps
+// @debug extract-map((a, b, (a: 1, b: 5), c, (c: 1, d: 1), d), all); // (map: ((a: 1, b: 5), (c: 1, d: 1)), list: (a, b, c, d))

src/lib/_list.first.function.scss

@@ -0,0 +1,14 @@
+// Sass.
+@use 'sass:list';
+
+// Completed
+// The `list.first()` function returns the first element of `$list`.
+// @param `$list` The list to get the first element from.
+// @returns The returned value is the first element of `$list`.
+@function first($list) {
+  @return list.nth($list, 1);
+}
+
+// Examples.
+// @debug first(('a', 'b', c, d, 2, 4, 5, (a: 1))); // a
+// @debug first(((a: 1), 'b', c, d, 2, 4, 5, (a: 1))); // (a: 1)

src/lib/_list.flatten.function.scss

@@ -0,0 +1,30 @@
+// Sass.
+@use 'sass:list';
+@use 'sass:meta';
+
+// Completed
+// The `list.flatten()` function returns flattened list of `$list`, otherwise `null`.
+// @param `$list` The list to flatten.
+// @returns The returned value is flattened copy of `$list`, otherwise `null`.
+@function flatten($list) {
+  @if meta.type-of($list) == list {
+    $result: ();
+    @for $i from 1 through list.length($list) {
+      @if meta.type-of(list.nth($list, $i)) == list {
+        @each $element in list.nth($list, $i) {
+          $result: list.append($result, $element, list.separator($list));
+        }
+      } @else {
+        $result: list.append($result, list.nth($list, $i), list.separator($list));
+      }
+    }
+    @return $result;
+  }
+  @return null;
+}
+
+// Examples.
+// @debug flatten(('a', 'b', (5, 6), c, d, 2, 4, 5, (a: 1), (1, 2, 3) )); // "a", "b", 5, 6, c, d, 2, 4, 5, (a: 1), 1, 2, 3
+// @debug flatten(('a', 'b', (5, 6), (c, d, 2, 4), 5, (a: 1), (1, 2, 3) )); // "a", "b", 5, 6, c, d, 2, 4, 5, (a: 1), 1, 2, 3
+// @debug flatten(('a', (b: 1), 'b', (5, 6), c, d, 2, 4, 5, (a: 1), (1, 2, 3) )); // "a", (b: 1), "b", 5, 6, c, d, 2, 4, 5, (a: 1), 1, 2, 3
+// @debug flatten((b: 1)); // null

src/lib/_list.index.function.scss

@@ -0,0 +1,38 @@
+// Sass.
+@use "sass:list";
+@use "sass:meta";
+
+// Completed
+// The `list.index()` function returns the index and/or indexes of the given `$values`.
+// @param `$list` The list from which indexes of the given values are retrieved.
+// @param `$value` The single value to find in the given list and return its index.
+// @arbitrary `$values...` Multiple values to find their indexes in the given list.
+// @returns The returned value is an index or list of indexes of the given values.
+@function index($list, $value, $values...) {
+  @if not list.index(arglist list, meta.type-of($list)) {
+    @error "$list: #{$list} is not arglist or list";
+  }
+  $result: ();
+  @each $value in list.join(($value,), $values, comma) {
+    $result: list.index($list, $value)
+      and list.append($result, list.index($list, $value), comma)
+      or $result;
+  }
+  @return list.length($result) > 0
+    and (list.length($result) == 1 and list.nth($result, 1) or $result)
+    or null;
+}
+
+// Examples.
+// @debug index(1px solid red, 1px); // 1
+// @debug index(1px solid red, solid); // 2
+// @debug index(1px solid red, dashed); // null
+
+// bool
+// @debug index(1px false solid red, false); // 2
+
+// null
+// @debug index(1px false solid null red, null); // 4
+
+// list
+// @debug index((1px solid) 'red' (12px, 14px) 'green', (1px solid), (12px, 14px)); // 1, 3

src/lib/_list.insert-nth.function.scss

@@ -0,0 +1,25 @@
+// Sass.
+@use 'sass:list';
+
+// Completed
+// The `list.insert-nth()` function returns the `$list` with `$value` inserted into index `$n`.
+// @param `$list` The list to insert `$value` at index `$n`.
+// @param `$n` The index `$n` under which `$value` is inserted.
+// @param `$value` The value to insert at `$n` index.
+// @return The return value is the list with the inserted `$value` at the `$n` index.
+@function insert-nth($list, $n, $value) {
+  $result: ();
+  @for $i from 1 through list.length($list) {
+    @if $n == $i {
+      $result: list.append($result, $value, list.separator($list));
+    }
+
+    $result: list.append($result, list.nth($list, $i), list.separator($list));
+  }
+  @return $result;
+}
+
+// Examples.
+// @debug insert-nth(('a', 'b', 'd', 'e', 'f', 'g'), 3 , 'c'); // "a", "b", "c", "d", "e", "f", "g"
+// @debug insert-nth('a' 'b' 'd' 'e' 'f' 'g', 3, 'c'); // "a" "b" "c" "d" "e" "f" "g"
+// @debug insert-nth(('a' 1) ('b' 2) ('d' 4) ('e' 5) ('f' 6) ('g' 7), 3, ('c' 3)); // ("a" 1) ("b" 2) ("c" 3) ("d" 4) ("e" 5) ("f" 6) ("g" 7)

src/lib/_list.invert.function.scss

@@ -0,0 +1,19 @@
+// Sass.
+@use 'sass:list';
+
+// Completed
+// The `list.invert()` function invert `$list` elements.
+// @param `$list` The list to invert elements.
+// @returns The returned value is a copy of `$list` with inverted elements.
+@function invert($list) {
+  $inverted: ();
+  @for $i from list.length($list) through 1 {
+    $inverted: list.append($inverted, list.nth($list, $i), list.separator($list));
+  }
+  @return $inverted;
+}
+
+// Examples.
+// $-list: ('a', 'b', c, d, 2, 4, 5, (a: 1));
+
+// @debug invert($-list);

src/lib/_list.is-length.function.scss

@@ -0,0 +1,18 @@
+// Sass.
+@use "sass:list";
+
+// Completed
+// The `list.is-length()` function checks whether `$list` length is equal to `$length`.
+// @param `$list` The list to check it is of `$length`.
+// @returns The returned value is `bool` indicating whether `$list` length is equal to `$length`.
+@function is-length($list, $length) {
+  @return $length and list.length($list) == $length;
+}
+
+// Alias name.
+@function of-length($list, $length) {
+  @return is-length($list, $length);
+}
+
+// Examples.
+// @debug of-length((a, b, c), 4); // false