Useful Sass list functions

SassMeister-input.scss

// ----
// libsass (v3.2.5)
// ----

// ----------------------------------------------------------------------------------
// Checks if the list contains the specified value.
// Param: {list} $list - list to search.
// Param: $search-item - value to search the $list for.
// Returns: {boolean} true if the $search-item was found and false otherwise. 
// ----------------------------------------------------------------------------------
@function contains($list, $search-item) {
  
  @if type-of($list) != list {
    @error "contains(): expects parameter of type list";
    @return false;
  }
  
  $result: false;
  @each $item in $list {
    @if $item == $search-item {
      $result: true;
    }
  }
  
  @return $result;
}

// ----------------------------------------------------------------------------------
// Prepends item to the list.
// Param: {list} $list - list to prepend to.
// Param: $prepend-item - item to prepend to the $list.
// Returns: {list}  A new list with $prepend-item prepended.
// ----------------------------------------------------------------------------------
@function prepend($list, $prepend-item) {
  
  @if type_of($list) != list {
    @error "prepend(): expects parameter of type list.";
    @return false;
  }
  
  @return join(($prepend-item), $list);
}

// ----------------------------------------------------------------------------------
// Grabs the portion of the list between $start & $end. 
// Inspired by JavaScript Array.prototype.slice method.
// Param: {list} $list - list from which to grab the portion. 
// Param: {number} [$start]- start index in the list. Negative values will offset 
//                  from the end of the list. 
// Param: {number} or {boolean} [$end] - end index. Setting this to false will 
//        set this to the last index in the list.
// Param: {string} [$separator] - Seaparator for the list.
// Returns: {list} a portion of the $list between $start & $end.
// ----------------------------------------------------------------------------------
@function slice($list, $start: 1, $end: false, $separator: space) {

  // We only want numbers for start & end indexes
  @if type_of($start) != number {
    @error "slice(): 'start' parameter must of type number.";
    @return false;
  }
  
  @if abs($start) > length($list) {
    @error "slice(): 'start' index is out of bounds.";
    @return false;
  }

  @if type_of($end) != number {
    $end: length($list);
  }
  @else if $end > length($list) {
    @error "slice(): 'end' index is out of bounds.";
    @return false;
  }
  
  // Negative start index will serve as an offset from the end of the list
  @if $start < 0 {
    $start: length($list) + $start + 1;
  }
  
  // Same goes for the end index
  @if $end < 0 {
    $end: length($list) + $end;    
  }
  
  // Finally, test for out of boundary index
  @if $start > $end {
    @error "slice(): 'start' cannot be > 'end'";
    @return false;
  }  
  
  // Create and return the sliced list
  $new-list: ();
  @for $i from $start through $end {
    $new-list: append($new-list, nth($list, $i));
  }
  
  @return join((), $new-list, $separator);
}

// ----------------------------------------------------------------------------------
// Retrieves the first item in the list
// Param: $list - list from which to grab the first item.
// Returns: First item in the list.
// ----------------------------------------------------------------------------------
@function first($list) {
  
  @if (type_of($list) != list) {
    @error("first(): Parameter must be of type list");
    @return false;
  }
  
  @return nth($list, 1);
}

// ----------------------------------------------------------------------------------
// Retrieves the last item in the list
// Param: $list - list from which to grab the last item.
// Returns: Last item in the list.
// ----------------------------------------------------------------------------------
@function last($list) {
  
  @if type_of($list) != list {
    @error("last(): Parameter must be of type list");
    @return false;
  }
  
  @return nth($list, length($list));
}

// ----------------------------------------------------------------------------------
// Reverses the order of items in the list.
// Param: $list - list to reverse.
// Returns: {list} reversed $list.
// ----------------------------------------------------------------------------------
@function reverse($list) {
  
  @if (type_of($list) != list) {
    @error("reverse(): Parameter must be of type list");
    @return false;
  }
  
  $result: ();
  
  @for $i from 1 through length($list) {
    $result: append($result, first(slice($list, -$i)));
  }
  
  @return $result;
}