@use 'sass:list';
@use 'sass:map';
@use 'sass:math';
@use 'is-true' as *;
@use 'list-purge' as *;
@use 'to-list' as *;

/// Replaces `$old-value` with `$new-value` in `$list`.
///
/// @param {List} $list - The list to update.
/// @param {*} $old-value - The old value to replace in `$list`.
/// @param {*} $new-value - The new value that is replacing the `$old-value`.
///
/// @return {List} The new, updated list.
///
/// @access public
/// @group Utilities
/// @require {function} is-true
/// @require {function} purge-list
/// @require {function} to-list
@function list-update($list, $old-value, $new-value) {
  $running: true;

  @while $running {
    $index: list.index($list, $old-value);

    @if not $index {
      $running: false;
    } @else {
      $list: list.set-nth($list, $index, $new-value);
    }
  }

  $list: if(is-true($new-value), $list, purge-list($list));

  @return to-list($list);
}

/// Replaces `$old-value` with `$new-value` in `$list`.
///
/// @param {List} $list - The list to update.
/// @param {*} $old-value - The old value to replace in `$list`.
/// @param {*} $new-value - The new value that is replacing the `$old-value`.
///
/// @return {List} The new, updated list.
///
/// @access public
/// @group Utilities
/// @require {function} list-update
///
/// @alias list-update
@function list-replace($list, $old-value, $new-value) {
  @return list-update($list, $old-value, $new-value);
}

/// Replaces `$old-value` with `$new-value` in `$list`.
///
/// @param {List} $list - The list to update.
/// @param {*} $old-value - The old value to replace in `$list`.
/// @param {*} $new-value - The new value that is replacing the `$old-value`.
///
/// @return {List} The new, updated list.
///
/// @access public
/// @group Utilities
/// @require {function} list-update
///
/// @alias list-update
@function update-list($list, $old-value, $new-value) {
  @return list-update($list, $old-value, $new-value);
}