@use 'sass:meta';
@use 'sass:string';

/// Replace `$search` with `$replace` in `$string`.
///
/// @param {String} $string - The initial string.
/// @param {String} $search - The substring to replace.
/// @param {String} $replace [''] - The new value that replaces `$search`. If
/// nothing is passed here, or an empty string is passed, $search is removed
/// from the string.
///
/// @return {String} The updated string.
///
/// @access public
/// @group Utilities
///
/// @throw Invalid data type error for $string, $search, or $replace.
@function str-replace($string, $search, $replace: '') {
  @if meta.type-of($string) != 'string' or
      meta.type-of($search) != 'string' or
      meta.type-of($replace) != 'string'
  {
    @error 'Invalid data type passed to [ str-replace() ] function. All ' +
        'parameters passed to this function must be strings.';
  }

  $index: string.index($string, $search);

  @if $index {
    @return (
      string.slice($string, 1, $index - 1) + $replace +
        str-replace(
          string.slice($string, $index + string.length($search)),
          $search,
          $replace
        )
    );
  }

  @return $string;
}

/// Replace `$search` with `$replace` in `$string`.
///
/// @param {String} $string - The initial string.
/// @param {String} $search - The substring to replace.
/// @param {String} $replace [''] - The new value that replaces `$search`. If
/// nothing is passed here, or an empty string is passed, $search is removed
/// from the string.
///
/// @return {String} The updated string.
///
/// @access public
/// @group Utilities
/// @require {function} str-replace
///
/// @throw Invalid data type error for $string, $search, or $replace.
///
/// @alias str-replace
@function string-replace($string, $search, $replace: '') {
  @return str-replace($string, $search, $replace);
}

/// Replace `$search` with `$replace` in `$string`.
///
/// @param {String} $string - The initial string.
/// @param {String} $search - The substring to replace.
/// @param {String} $replace [''] - The new value that replaces `$search`. If
/// nothing is passed here, or an empty string is passed, $search is removed
/// from the string.
///
/// @return {String} The updated string.
///
/// @access public
/// @group Utilities
/// @require {function} str-replace
///
/// @throw Invalid data type error for $string, $search, or $replace.
///
/// @alias str-replace
@function update-str($string, $search, $replace: '') {
  @return str-replace($string, $search, $replace);
}

/// Replace `$search` with `$replace` in `$string`.
///
/// @param {String} $string - The initial string.
/// @param {String} $search - The substring to replace.
/// @param {String} $replace [''] - The new value that replaces `$search`. If
/// nothing is passed here, or an empty string is passed, $search is removed
/// from the string.
///
/// @return {String} The updated string.
///
/// @access public
/// @group Utilities
/// @require {function} str-replace
///
/// @throw Invalid data type error for $string, $search, or $replace.
///
/// @alias str-replace
@function update-string($string, $search, $replace: '') {
  @return str-replace($string, $search, $replace);
}