@charset 'UTF-8';

////
/// Flavor SCSS Types String
/// @group types-string
/// @author blackmirror1980
////

/// Checks if a value is a string value.
///
/// @access public
/// @param {string} $s - the value to check
/// @return {boolean} - true if is a string
@function is-string($s) {
  @return is-defined($s) and type-of($s)==string;
}

/// Converts something to a string
///
/// @access public
/// @param {any} $a - the value to convert
/// @return {string} - the converted string
@function to-string($a) {
  @return inspect($a);
}

/// Returns the number of characters in a string.
/// <br><br><u>Note: aliases the native str-length method</u>
///
/// @link https://sass-lang.com/documentation/Sass/Script/Functions.html#str_length-instance_method SassLang str-length docs
/// @access public
/// @param {string} $s - the string to count
/// @return {integer} - the string length
@function string-length($s) {
  @return str-length($s);
}

/// Returns the position index of the first occurrence of string needle in string haystack
/// <br><br><u>Note: aliases the native str-index method</u>
///
/// @link https://sass-lang.com/documentation/Sass/Script/Functions.html#str_index-instance_method SassLang str-index docs
/// @access public
/// @param {string} $h - the haystack
/// @param {string} $n - the needle
/// @return {integer} - the string index position of the needle
@function string-index($h, $n) {
  @return str-index($h, $n);
}

/// Inserts string $i in string $s at $p position
/// <br><br><u>Note: aliases the native str-insert method</u>
///
/// @link https://sass-lang.com/documentation/Sass/Script/Functions.html#str_insert-instance_method SassLang str-insert docs
/// @access public
/// @param {string} $s - the string to modify
/// @param {string} $i - the string to insert into
/// @param {number} $p - the position index to use for insertion
/// @return {string} - the new string
@function string-insert($s, $i, $p) {
  @return str-insert($s, $i, $p);
}

/// Extracts a sub string from a string between from & to position indexes,
/// <br>if to position index is not specified (null), will be between from & the end of the string
/// <br><br><u>Note: aliases the native str-slice method</u>
///
/// @link https://sass-lang.com/documentation/Sass/Script/Functions.html#str_slice-instance_method SassLang str-slice docs
/// @access public
/// @param {string} $s - the string
/// @param {string} $from [1] - the from position index
/// @param {string} $to [-1] - the to position index
/// @return {string} - the sub string needle
@function string-slice($s, $from: 1, $to: -1) {
  @return str-slice($s, $from, $to);
}

/// Checks if a string starts with another string.
///
/// @access public
/// @param {string} $h - the haystack
/// @param {string} $n - the needle
/// @requires {function} is-string
/// @requires {function} string-length
/// @requires {function} string-slice
/// @return {boolean} - true if the string starts with the needle
@function string-starts-with($h, $n) {
  @if is-string($h) and is-string($n) {
    @return string-slice($h, 1, string-length($n))==$n;
  }

  @warn '`haystack: #{$h}` and `needle: #{$n}` are not valid strings';
  @return false;
}

/// Checks if a string contains another string.
///
/// @access public
/// @param {string} $h - the haystack
/// @param {string} $n - the needle
/// @requires {function} is-string
/// @requires {function} string-index
/// @return {boolean} - true if the string contains the needle
@function string-contains($h, $n) {
  @if is-string($h) and is-string($n) {
    @return string-index($h, $n) > 0;
  }

  @warn '`haystack: #{$h}` and `needle: #{$n}` are not valid strings';
  @return false;
}

/// Checks if a string ends with another string.
///
/// @access public
/// @param {string} $h - the haystack
/// @param {string} $n - the needle
/// @requires {function} is-string
/// @requires {function} string-length
/// @requires {function} string-slice
/// @return {boolean} - true if the string ends with the needle
@function string-ends-with($h, $n) {
  @if is-string($h) and is-string($n) {
    $h-length: string-length($h);
    $n-length: string-length($n);

    @return string-slice($h, $h-length - $n-length + 1)==$n;
  }

  @warn '`haystack: #{$h}` and `needle: #{$n}` are not valid strings';
  @return false;
}

/// Splits a string in an array/list using the specified separator
///
/// @access public
/// @param {string} $s - the string to split
/// @param {string} $sep ['.'] - the separator
/// @requires {function} array-concat
/// @requires {function} string-index
/// @requires {function} string-slice
/// @return {list | array} - the splitted array
@function string-split($s, $sep: '.') {
  $split: ();

  $i: string-index($s, $sep);

  @while $i!=null {
    $item: string-slice($s, 1, $i - 1);
    $split: array-concat($split, $item);
    $s: string-slice($s, $i + string-length($sep));
    $i: string-index($s, $sep);
  }

  $split: array-concat($split, $s);

  @return $split;
}

/// Replaces all the occurrencies of a string inside another string with the specified value
///
/// @access public
/// @param {string} $h - the haystack
/// @param {string} $n - the needle
/// @param {string} $r [''] - the string to use for replacement
/// @requires {function} string-slice
/// @return {string} - the updated string
@function string-replace($h, $n, $r: '') {
  $i: string-index($h, $n);

  @if $i {
    @return string-slice($h, 1, $i - 1) + $r + string-replace(string-slice($h, $i + string-length($n)), $n, $r);
  }

  @return $h;
}