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

/// Takes a String and separates it into a List.
///
/// @param {String} $string - The initial string.
/// @param {String} $delimiter - The separator found in `$string` that is
/// used to subdivide the string into list values.
/// @param {String} $separator [comma] - The separator that will be used between
/// values in the new list. Must be either `space`, `comma` or `slash`. You may
/// also pass the string-wrapped characters themselves to this parameter, such
/// as: `' '`, `','`, `', '`, `'/'`. or `' / '`.
///
/// @return {List} The converted list.
///
/// @access public
/// @group Utilities
///
/// @throw List passsed to str-to-list warning.
/// @throw Invalid $string type passed, not a string.
/// @throw Invalid $delimiter type passed, not a string.
/// @throw Invalid $separator value passed, not a valid separator.
@function str-to-list($string, $delimiter: ' ', $separator: comma) {
  @if meta.type-of($string) == 'list' {
    @warn 'You passed a list value to the [ str-to-list() ] function.' +
        'Returning original list of #{$string}';

    @return $string;
  }

  @if meta.type-of($string) != 'string' {
    @error 'Invalid $string type passed to the [ str-to-list() ] function. ' +
        'You passed `#{meta.inspect($string)}`, which is of type: '
        '`#{meta.type-of($string)}`.';
  }

  @if meta.type-of($delimiter) != 'string' {
    @error 'Invalid $delimiter type passed to the [ str-to-list() ] ' +
        'function. You passed `#{meta.inspect($delimiter)}`, which is ' +
        'of type: `#{meta.type-of($delimiter)}`. This value must be ' +
        'of type string.';
  }

  @if $delimiter == 'comma' {
    $delimiter: ',';
  } @else if $delimiter == 'space' {
    $delimiter: ' ';
  } @else if $delimiter == 'slash' {
    $delimiter: '/';
  } @else if $delimiter == 'backslash' {
    $delimiter: '\\';
  } @else if $delimiter == 'hyphen' {
    $delimiter: '-';
  }

  @if $separator == comma or $separator == ',' or $separator == ', ' {
    $separator: comma;
  } @else if $separator == space or $separator == ' ' {
    $separator: space;
  } @else if $separator == slash or $separator == '/' or $separator == ' / ' {
    $separator: slash;
  } @else {
    @error 'Invalid $separator value passed to the [ str-to-list() ] ' +
        'function. You passed `#{meta.inspect($separator)}`, which is ' +
        'not a valid separator for lists. You must choose either `comma`, ' +
        '`space`, or `slash` for the $separator parameter.';
  }

  $list: ();
  $index: string.index($string, $delimiter);

  @while $index {
    // Extract the substring from the start to the found separator index
    $item: string.slice($string, 1, $index - 1);

    // Append the item to the list
    $list: list.append($list, $item, $separator);

    // Remove the processed item and separator from the string
    $string: string.slice($string, $index + string.length($delimiter));

    // Find the next separator in the remaining string
    $index: string.index($string, $delimiter);
  }

  // Check if there is any remaining string to add as the last item
  @if string.length($string) > 0 {
    $list: list.append($list, $string, $separator);
  }

  @return $list;
}

/// Takes a String and separates it into a List.
///
/// @param {String} $string - The initial string.
/// @param {String} $delimiter - The separator found in `$string` that is
/// used to subdivide the string into list values.
/// @param {String} $separator [comma] - The separator that will be used between
/// values in the new list. Must be either `space`, `comma` or `slash`. You may
/// also pass the string-wrapped characters themselves to this parameter, such
/// as: `' '`, `','`, `', '`, `'/'`. or `' / '`.
///
/// @return {List} The converted list.
///
/// @access public
/// @group Utilities
/// @require {function} str-to-list
///
/// @throw List passsed to str-to-list warning.
/// @throw Invalid $string type passed, not a string.
/// @throw Invalid $delimiter type passed, not a string.
/// @throw Invalid $separator value passed, not a valid separator.
///
/// @alias str-to-list
@function string-to-list($string, $delimiter: ' ', $separator: comma) {
  @return str-to-list($string, $delimiter, $separator);
}

/// Takes a String and separates it into a List.
///
/// @param {String} $string - The initial string.
/// @param {String} $delimiter - The separator found in `$string` that is
/// used to subdivide the string into list values.
/// @param {String} $separator [comma] - The separator that will be used between
/// values in the new list. Must be either `space`, `comma` or `slash`. You may
/// also pass the string-wrapped characters themselves to this parameter, such
/// as: `' '`, `','`, `', '`, `'/'`. or `' / '`.
///
/// @return {List} The converted list.
///
/// @access public
/// @group Utilities
/// @require {function} str-to-list
///
/// @throw List passsed to str-to-list warning.
/// @throw Invalid $string type passed, not a string.
/// @throw Invalid $delimiter type passed, not a string.
/// @throw Invalid $separator value passed, not a valid separator.
///
/// @alias str-to-list
@function string-to-list($string, $delimiter: ' ', $separator: comma) {
  @return str-to-list($string, $delimiter, $separator);
}

/// Takes a String and separates it into a List.
///
/// @param {String} $string - The initial string.
/// @param {String} $delimiter - The separator found in `$string` that is
/// used to subdivide the string into list values.
/// @param {String} $separator [comma] - The separator that will be used between
/// values in the new list. Must be either `space`, `comma` or `slash`. You may
/// also pass the string-wrapped characters themselves to this parameter, such
/// as: `' '`, `','`, `', '`, `'/'`. or `' / '`.
///
/// @return {List} The converted list.
///
/// @access public
/// @group Utilities
/// @require {function} str-to-list
///
/// @throw List passsed to str-to-list warning.
/// @throw Invalid $string type passed, not a string.
/// @throw Invalid $delimiter type passed, not a string.
/// @throw Invalid $separator value passed, not a valid separator.
///
/// @alias str-to-list
@function explode-string($string, $delimiter: ' ', $separator: comma) {
  @return str-to-list($string, $delimiter, $separator);
}