////
///
/// List Functions
/// ===========================================================================
///
/// Utility functions for list manipulation.
///
/// @group Functions
/// @author Scape Agency
/// @link https://scape.style
/// @since 0.1.0 initial release
/// @access public
///
////

// ============================================================================
// Use
// ============================================================================

@use "sass:list";
@use "sass:math";
@use "sass:meta";

// ============================================================================
// Functions
// ============================================================================

/// Get first item in a list
/// @param {List} $list - The list
/// @return {*} - First item
@function first($list) {
    @return list.nth($list, 1);
}

/// Get last item in a list
/// @param {List} $list - The list
/// @return {*} - Last item
@function last($list) {
    @return list.nth($list, list.length($list));
}

/// Reverse a list
/// @param {List} $list - List to reverse
/// @return {List} - Reversed list
@function reverse($list) {
    $result: ();

    @for $i from list.length($list) through 1 {
        $result: list.append($result, list.nth($list, $i));
    }

    @return $result;
}

/// Sum all values in a list
/// @param {List} $list - List of numbers
/// @return {Number} - Sum of values
@function sum($list) {
    $result: 0;

    @each $value in $list {
        @if meta.type-of($value) == "number" {
            $result: $result + $value;
        }
    }

    @return $result;
}

/// Calculate average of list values
/// @param {List} $list - List of numbers
/// @return {Number} - Average value
@function average($list) {
    @return math.div(sum($list), list.length($list));
}

/// Get minimum value in a list
/// @param {List} $list - List of numbers
/// @return {Number} - Minimum value
@function list-min($list) {
    $result: list.nth($list, 1);

    @each $value in $list {
        @if $value < $result {
            $result: $value;
        }
    }

    @return $result;
}

/// Get maximum value in a list
/// @param {List} $list - List of numbers
/// @return {Number} - Maximum value
@function list-max($list) {
    $result: list.nth($list, 1);

    @each $value in $list {
        @if $value > $result {
            $result: $value;
        }
    }

    @return $result;
}

/// Remove item at index from list
/// @param {List} $list - Original list
/// @param {Number} $index - Index to remove
/// @return {List} - List without item at index
@function remove-at($list, $index) {
    $result: ();

    @for $i from 1 through list.length($list) {
        @if $i != $index {
            $result: list.append($result, list.nth($list, $i));
        }
    }

    @return $result;
}

/// Insert item at index in list
/// @param {List} $list - Original list
/// @param {*} $item - Item to insert
/// @param {Number} $index - Index to insert at
/// @return {List} - List with inserted item
@function insert-at($list, $item, $index) {
    $result: ();

    @for $i from 1 through list.length($list) {
        @if $i == $index {
            $result: list.append($result, $item);
        }
        $result: list.append($result, list.nth($list, $i));
    }

    @if $index > list.length($list) {
        $result: list.append($result, $item);
    }

    @return $result;
}

/// Check if list contains a value
/// @param {List} $list - List to search
/// @param {*} $value - Value to find
/// @return {Boolean} - True if value exists in list
@function contains($list, $value) {
    @return list.index($list, $value) != null;
}

/// Remove duplicates from list
/// @param {List} $list - Original list
/// @return {List} - List with unique values
@function unique($list) {
    $result: ();

    @each $item in $list {
        @if not contains($result, $item) {
            $result: list.append($result, $item);
        }
    }

    @return $result;
}