Module Sass::Script::Functions
In: lib/sass/script/functions.rb

@comment

  YARD can't handle some multiline tags, and we need really long tags for function declarations.
  rubocop:disable LineLength

Methods in this module are accessible from the SassScript context. For example, you can write

    $color: hsl(120deg, 100%, 50%)

and it will call {Functions#hsl}.

The following functions are provided:

*Note: These functions are described in more detail below.*

## RGB Functions

\{rgb rgb($red, $green, $blue)} : Creates a {Sass::Script::Value::Color Color} from red, green, and blue

  values.

\{rgba rgba($red, $green, $blue, $alpha)} : Creates a {Sass::Script::Value::Color Color} from red, green, blue, and

  alpha values.

\{red red($color)} : Gets the red component of a color.

\{green green($color)} : Gets the green component of a color.

\{blue blue($color)} : Gets the blue component of a color.

\{mix mix($color1, $color2, \[$weight\])} : Mixes two colors together.

## HSL Functions

\{hsl hsl($hue, $saturation, $lightness)} : Creates a {Sass::Script::Value::Color Color} from hue, saturation, and

  lightness values.

\{hsla hsla($hue, $saturation, $lightness, $alpha)} : Creates a {Sass::Script::Value::Color Color} from hue, saturation,

  lightness, and alpha values.

\{hue hue($color)} : Gets the hue component of a color.

\{saturation saturation($color)} : Gets the saturation component of a color.

\{lightness lightness($color)} : Gets the lightness component of a color.

\{adjust_hue adjust-hue($color, $degrees)} : Changes the hue of a color.

\{lighten lighten($color, $amount)} : Makes a color lighter.

\{darken darken($color, $amount)} : Makes a color darker.

\{saturate saturate($color, $amount)} : Makes a color more saturated.

\{desaturate desaturate($color, $amount)} : Makes a color less saturated.

\{grayscale grayscale($color)} : Converts a color to grayscale.

\{complement complement($color)} : Returns the complement of a color.

\{invert invert($color)} : Returns the inverse of a color.

## Opacity Functions

\{alpha alpha($color)} / \{opacity opacity($color)} : Gets the alpha component (opacity) of a color.

\{rgba rgba($color, $alpha)} : Changes the alpha component for a color.

\{opacify opacify($color, $amount)} / \{fade_in fade-in($color, $amount)} : Makes a color more opaque.

\{transparentize transparentize($color, $amount)} / \{fade_out fade-out($color, $amount)} : Makes a color more transparent.

## Other Color Functions

\{adjust_color adjust-color($color, \[$red\], \[$green\], \[$blue\], \[$hue\], \[$saturation\], \[$lightness\], \[$alpha\])} : Increases or decreases one or more components of a color.

\{scale_color scale-color($color, \[$red\], \[$green\], \[$blue\], \[$saturation\], \[$lightness\], \[$alpha\])} : Fluidly scales one or more properties of a color.

\{change_color change-color($color, \[$red\], \[$green\], \[$blue\], \[$hue\], \[$saturation\], \[$lightness\], \[$alpha\])} : Changes one or more properties of a color.

\{ie_hex_str ie-hex-str($color)} : Converts a color into the format understood by IE filters.

## String Functions

\{unquote unquote($string)} : Removes quotes from a string.

\{quote quote($string)} : Adds quotes to a string.

\{str_length str-length($string)} : Returns the number of characters in a string.

\{str_insert str-insert($string, $insert, $index)} : Inserts `$insert` into `$string` at `$index`.

\{str_index str-index($string, $substring)} : Returns the index of the first occurrence of `$substring` in `$string`.

\{str_slice str-slice($string, $start-at, [$end-at])} : Extracts a substring from `$string`.

\{to_upper_case to-upper-case($string)} : Converts a string to upper case.

\{to_lower_case to-lower-case($string)} : Converts a string to lower case.

## Number Functions

\{percentage percentage($number)} : Converts a unitless number to a percentage.

\{round round($number)} : Rounds a number to the nearest whole number.

\{ceil ceil($number)} : Rounds a number up to the next whole number.

\{floor floor($number)} : Rounds a number down to the previous whole number.

\{abs abs($number)} : Returns the absolute value of a number.

\{min min($numbers…)\} : Finds the minimum of several numbers.

\{max max($numbers…)\} : Finds the maximum of several numbers.

\{random random([$limit])\} : Returns a random number.

## List Functions {list-functions}

Lists in Sass are immutable; all list functions return a new list rather than updating the existing list in-place.

All list functions work for maps as well, treating them as lists of pairs.

\{length length($list)} : Returns the length of a list.

\{nth nth($list, $n)} : Returns a specific item in a list.

\{set-nth set-nth($list, $n, $value)} : Replaces the nth item in a list.

\{join join($list1, $list2, \[$separator\])} : Joins together two lists into one.

\{append append($list1, $val, \[$separator\])} : Appends a single value onto the end of a list.

\{zip zip($lists…)} : Combines several lists into a single multidimensional list.

\{index index($list, $value)} : Returns the position of a value within a list.

\{list_separator list-separator($list)} : Returns the separator of a list.

## Map Functions {map-functions}

Maps in Sass are immutable; all map functions return a new map rather than updating the existing map in-place.

\{map_get map-get($map, $key)} : Returns the value in a map associated with a given key.

\{map_merge map-merge($map1, $map2)} : Merges two maps together into a new map.

\{map_remove map-remove($map, $keys…)} : Returns a new map with keys removed.

\{map_keys map-keys($map)} : Returns a list of all keys in a map.

\{map_values map-values($map)} : Returns a list of all values in a map.

\{map_has_key map-has-key($map, $key)} : Returns whether a map has a value associated with a given key.

\{keywords keywords($args)} : Returns the keywords passed to a function that takes variable arguments.

## Selector Functions

Selector functions are very liberal in the formats they support for selector arguments. They can take a plain string, a list of lists as returned by `&` or anything in between:

  • A plain string, such as `".foo .bar, .baz .bang"`.
  • A space-separated list of strings such as `(".foo" ".bar")`.
  • A comma-separated list of strings such as `(".foo .bar", ".baz .bang")`.
  • A comma-separated list of space-separated lists of strings such as `((".foo" ".bar"), (".baz" ".bang"))`.

In general, selector functions allow placeholder selectors (`%foo`) but disallow parent-reference selectors (`&`).

\{selector_nest selector-nest($selectors…)} : Nests selector beneath one another like they would be nested in the

  stylesheet.

\{selector_append selector-append($selectors…)} : Appends selectors to one another without spaces in between.

\{selector_extend selector-extend($selector, $extendee, $extender)} : Extends `$extendee` with `$extender` within `$selector`.

\{selector_replace selector-replace($selector, $original, $replacement)} : Replaces `$original` with `$replacement` within `$selector`.

\{selector_unify selector-unify($selector1, $selector2)} : Unifies two selectors to produce a selector that matches

  elements matched by both.

\{is_superselector is-superselector($super, $sub)} : Returns whether `$super` matches all the elements `$sub` does, and

  possibly more.

\{simple_selectors simple-selectors($selector)} : Returns the simple selectors that comprise a compound selector.

\{selector_parse selector-parse($selector)} : Parses a selector into the format returned by `&`.

## Introspection Functions

\{feature_exists feature-exists($feature)} : Returns whether a feature exists in the current Sass runtime.

\{variable_exists variable-exists($name)} : Returns whether a variable with the given name exists in the current scope.

\{global_variable_exists global-variable-exists($name)} : Returns whether a variable with the given name exists in the global scope.

\{function_exists function-exists($name)} : Returns whether a function with the given name exists.

\{mixin_exists mixin-exists($name)} : Returns whether a mixin with the given name exists.

\{inspect inspect($value)} : Returns the string representation of a value as it would be represented in Sass.

\{type_of type-of($value)} : Returns the type of a value.

\{unit unit($number)} : Returns the unit(s) associated with a number.

\{unitless unitless($number)} : Returns whether a number has units.

\{comparable comparable($number1, $number2)} : Returns whether two numbers can be added, subtracted, or compared.

\{call call($name, $args…)} : Dynamically calls a Sass function.

## Miscellaneous Functions

\{if if($condition, $if-true, $if-false)} : Returns one of two values, depending on whether or not `$condition` is

  true.

\{unique_id unique-id()} : Returns a unique CSS identifier.

## Adding Custom Functions

New Sass functions can be added by adding Ruby methods to this module. For example:

    module Sass::Script::Functions
      def reverse(string)
        assert_type string, :String
        Sass::Script::Value::String.new(string.value.reverse)
      end
      declare :reverse, [:string]
    end

Calling {declare} tells Sass the argument names for your function. If omitted, the function will still work, but will not be able to accept keyword arguments. {declare} can also allow your function to take arbitrary keyword arguments.

There are a few things to keep in mind when modifying this module. First of all, the arguments passed are {Value} objects. Value objects are also expected to be returned. This means that Ruby values must be unwrapped and wrapped.

Most Value objects support the {Value::Base#value value} accessor for getting their Ruby values. Color objects, though, must be accessed using {Sass::Script::Value::Color#rgb rgb}, {Sass::Script::Value::Color#red red}, {Sass::Script::Value::Color#blue green}, or {Sass::Script::Value::Color#blue blue}.

Second, making Ruby functions accessible from Sass introduces the temptation to do things like database access within stylesheets. This is generally a bad idea; since Sass files are by default only compiled once, dynamic code is not a great fit.

If you really, really need to compile Sass on each request, first make sure you have adequate caching set up. Then you can use {Sass::Engine} to render the code, using the {file:SASS_REFERENCE.md#custom-option `options` parameter} to pass in data that {EvaluationContext#options can be accessed} from your Sass functions.

Within one of the functions in this module, methods of {EvaluationContext} can be used.

### Caveats

When creating new {Value} objects within functions, be aware that it‘s not safe to call {Value::Base#to_s to_s} (or other methods that use the string representation) on those objects without first setting {Tree::Node#options= the options attribute}.

@comment

  rubocop:enable LineLength
  rubocop:disable ModuleLength

Methods

Classes and Modules

Class Sass::Script::Functions::EvaluationContext

Constants

Signature = Struct.new(:args, :delayed_args, :var_args, :var_kwargs, :deprecated)   A class representing a Sass function signature.

@attr args [Array<String>] The names of the arguments to the function. @attr delayed_args [Array<String>] The names of the arguments whose evaluation should be

  delayed.

@attr var_args [Boolean] Whether the function takes a variable number of arguments. @attr var_kwargs [Boolean] Whether the function takes an arbitrary set of keyword arguments.

External Aliases

public_method_defined? -> callable?
  Returns whether user function with a given name exists.

@param function_name [String] @return [Boolean]

Public Class methods

Declare a Sass signature for a Ruby-defined function. This includes the names of the arguments, whether the function takes a variable number of arguments, and whether the function takes an arbitrary set of keyword arguments.

It‘s not necessary to declare a signature for a function. However, without a signature it won‘t support keyword arguments.

A single function can have multiple signatures declared as long as each one takes a different number of arguments. It‘s also possible to declare multiple signatures that all take the same number of arguments, but none of them but the first will be used unless the user uses keyword arguments.

@example

  declare :rgba, [:hex, :alpha]
  declare :rgba, [:red, :green, :blue, :alpha]
  declare :accepts_anything, [], :var_args => true, :var_kwargs => true
  declare :some_func, [:foo, :bar, :baz], :var_kwargs => true

@param method_name [Symbol] The name of the method

  whose signature is being declared.

@param args [Array<Symbol>] The names of the arguments for the function signature. @option options :var_args [Boolean] (false)

  Whether the function accepts a variable number of (unnamed) arguments
  in addition to the named arguments.

@option options :var_kwargs [Boolean] (false)

  Whether the function accepts other keyword arguments
  in addition to those in `:args`.
  If this is true, the Ruby function will be passed a hash from strings
  to {Value}s as the last argument.
  In addition, if this is true and `:var_args` is not,
  Sass will ensure that the last argument passed is a hash.

Get Sass‘s internal random number generator.

@return [Random]

Sets the random seed used by Sass‘s internal random number generator.

This can be used to ensure consistent random number sequences which allows for consistent results when testing, etc.

@param seed [Integer] @return [Integer] The same seed.

Determine the correct signature for the number of arguments passed in for a given function. If no signatures match, the first signature is returned for error messaging.

@param method_name [Symbol] The name of the Ruby function to be called. @param arg_arity [Integer] The number of unnamed arguments the function was passed. @param kwarg_arity [Integer] The number of keyword arguments the function was passed.

@return [{Symbol => Object}, nil]

  The signature options for the matching signature,
  or nil if no signatures are declared for this function. See {declare}.

Public Instance methods

Returns the absolute value of a number.

@example

  abs(10px) => 10px
  abs(-10px) => 10px

@overload abs($number)

  @param $number [Sass::Script::Value::Number]

@return [Sass::Script::Value::Number] @raise [ArgumentError] if `$number` isn‘t a number

Increases or decreases one or more properties of a color. This can change the red, green, blue, hue, saturation, value, and alpha properties. The properties are specified as keyword arguments, and are added to or subtracted from the color‘s current value for that property.

All properties are optional. You can‘t specify both RGB properties (`$red`, `$green`, `$blue`) and HSL properties (`$hue`, `$saturation`, `$value`) at the same time.

@example

  adjust-color(#102030, $blue: 5) => #102035
  adjust-color(#102030, $red: -5, $blue: 5) => #0b2035
  adjust-color(hsl(25, 100%, 80%), $lightness: -30%, $alpha: -0.4) => hsla(25, 100%, 50%, 0.6)

@overload adjust_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])

  @param $color [Sass::Script::Value::Color]
  @param $red [Sass::Script::Value::Number] The adjustment to make on the
    red component, between -255 and 255 inclusive
  @param $green [Sass::Script::Value::Number] The adjustment to make on the
    green component, between -255 and 255 inclusive
  @param $blue [Sass::Script::Value::Number] The adjustment to make on the
    blue component, between -255 and 255 inclusive
  @param $hue [Sass::Script::Value::Number] The adjustment to make on the
    hue component, in degrees
  @param $saturation [Sass::Script::Value::Number] The adjustment to make on
    the saturation component, between `-100%` and `100%` inclusive
  @param $lightness [Sass::Script::Value::Number] The adjustment to make on
    the lightness component, between `-100%` and `100%` inclusive
  @param $alpha [Sass::Script::Value::Number] The adjustment to make on the
    alpha component, between -1 and 1 inclusive

@return [Sass::Script::Value::Color] @raise [ArgumentError] if any parameter is the wrong type or out-of

  bounds, or if RGB properties and HSL properties are adjusted at the
  same time

Changes the hue of a color. Takes a color and a number of degrees (usually between `-360deg` and `360deg`), and returns a color with the hue rotated along the color wheel by that amount.

@example

  adjust-hue(hsl(120, 30%, 90%), 60deg) => hsl(180, 30%, 90%)
  adjust-hue(hsl(120, 30%, 90%), -60deg) => hsl(60, 30%, 90%)
  adjust-hue(#811, 45deg) => #886a11

@overload adjust_hue($color, $degrees)

  @param $color [Sass::Script::Value::Color]
  @param $degrees [Sass::Script::Value::Number] The number of degrees to
    rotate the hue

@return [Sass::Script::Value::Color] @raise [ArgumentError] if either parameter is the wrong type

Returns the alpha component (opacity) of a color. This is 1 unless otherwise specified.

This function also supports the proprietary Microsoft `alpha(opacity=20)` syntax as a special case.

@overload alpha($color)

  @param $color [Sass::Script::Value::Color]

@return [Sass::Script::Value::Number] The alpha component, between 0 and 1 @raise [ArgumentError] if `$color` isn‘t a color

Appends a single value onto the end of a list.

Unless the `$separator` argument is passed, if the list had only one item, the resulting list will be space-separated.

Like all list functions, `append()` returns a new list rather than modifying its argument in place.

@example

  append(10px 20px, 30px) => 10px 20px 30px
  append((blue, red), green) => blue, red, green
  append(10px 20px, 30px 40px) => 10px 20px (30px 40px)
  append(10px, 20px, comma) => 10px, 20px
  append((blue, red), green, space) => blue red green

@overload append($list, $val, $separator: auto)

  @param $list [Sass::Script::Value::Base]
  @param $val [Sass::Script::Value::Base]
  @param $separator [Sass::Script::Value::String] The list separator to use.
    If this is `comma` or `space`, that separator will be used. If this is
    `auto` (the default), the separator is determined as explained above.

@return [Sass::Script::Value::List]

Gets the blue component of a color. Calculated from HSL where necessary via [this algorithm][hsl-to-rgb].

[hsl-to-rgb]: www.w3.org/TR/css3-color/#hsl-color

@overload blue($color)

  @param $color [Sass::Script::Value::Color]

@return [Sass::Script::Value::Number] The blue component, between 0 and

  255 inclusive

@raise [ArgumentError] if `$color` isn‘t a color

Dynamically calls a function. This can call user-defined functions, built-in functions, or plain CSS functions. It will pass along all arguments, including keyword arguments, to the called function.

@example

  call(rgb, 10, 100, 255) => #0a64ff
  call(scale-color, #0a64ff, $lightness: -10%) => #0058ef

  $fn: nth;
  call($fn, (a b c), 2) => b

@overload call($name, $args…)

  @param $name [String] The name of the function to call.

Rounds a number up to the next whole number.

@example

  ceil(10.4px) => 11px
  ceil(10.6px) => 11px

@overload ceil($number)

  @param $number [Sass::Script::Value::Number]

@return [Sass::Script::Value::Number] @raise [ArgumentError] if `$number` isn‘t a number

Changes one or more properties of a color. This can change the red, green, blue, hue, saturation, value, and alpha properties. The properties are specified as keyword arguments, and replace the color‘s current value for that property.

All properties are optional. You can‘t specify both RGB properties (`$red`, `$green`, `$blue`) and HSL properties (`$hue`, `$saturation`, `$value`) at the same time.

@example

  change-color(#102030, $blue: 5) => #102005
  change-color(#102030, $red: 120, $blue: 5) => #782005
  change-color(hsl(25, 100%, 80%), $lightness: 40%, $alpha: 0.8) => hsla(25, 100%, 40%, 0.8)

@overload change_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])

  @param $color [Sass::Script::Value::Color]
  @param $red [Sass::Script::Value::Number] The new red component for the
    color, within 0 and 255 inclusive
  @param $green [Sass::Script::Value::Number] The new green component for
    the color, within 0 and 255 inclusive
  @param $blue [Sass::Script::Value::Number] The new blue component for the
    color, within 0 and 255 inclusive
  @param $hue [Sass::Script::Value::Number] The new hue component for the
    color, in degrees
  @param $saturation [Sass::Script::Value::Number] The new saturation
    component for the color, between `0%` and `100%` inclusive
  @param $lightness [Sass::Script::Value::Number] The new lightness
    component for the color, within `0%` and `100%` inclusive
  @param $alpha [Sass::Script::Value::Number] The new alpha component for
    the color, within 0 and 1 inclusive

@return [Sass::Script::Value::Color] @raise [ArgumentError] if any parameter is the wrong type or out-of

  bounds, or if RGB properties and HSL properties are adjusted at the
  same time

Returns whether two numbers can added, subtracted, or compared.

@example

  comparable(2px, 1px) => true
  comparable(100px, 3em) => false
  comparable(10cm, 3mm) => true

@overload comparable($number1, $number2)

  @param $number1 [Sass::Script::Value::Number]
  @param $number2 [Sass::Script::Value::Number]

@return [Sass::Script::Value::Bool] @raise [ArgumentError] if either parameter is the wrong type

Returns the complement of a color. This is identical to `adjust-hue(color, 180deg)`.

@see adjust_hue adjust-hue @overload complement($color)

  @param $color [Sass::Script::Value::Color]

@return [Sass::Script::Value::Color] @raise [ArgumentError] if `$color` isn‘t a color

This function only exists as a workaround for IE7‘s [`content: counter` bug](jes.st/2013/ie7s-css-breaking-content-counter-bug/). It works identically to any other plain-CSS function, except it avoids adding spaces between the argument commas.

@example

  counter(item, ".") => counter(item,".")

@overload counter($args…) @return [Sass::Script::Value::String]

This function only exists as a workaround for IE7‘s [`content: counter` bug](jes.st/2013/ie7s-css-breaking-content-counter-bug/). It works identically to any other plain-CSS function, except it avoids adding spaces between the argument commas.

@example

  counters(item, ".") => counters(item,".")

@overload counters($args…) @return [Sass::Script::Value::String]

Makes a color darker. Takes a color and a number between 0% and 100%, and returns a color with the lightness decreased by that amount.

@see lighten @example

  darken(hsl(25, 100%, 80%), 30%) => hsl(25, 100%, 50%)
  darken(#800, 20%) => #200

@overload darken($color, $amount)

  @param $color [Sass::Script::Value::Color]
  @param $amount [Sass::Script::Value::Number] The amount to decrease the
    lightness by, between `0%` and `100%`

@return [Sass::Script::Value::Color] @raise [ArgumentError] if `$amount` is out of bounds, or either parameter

  is the wrong type

Makes a color less saturated. Takes a color and a number between 0% and 100%, and returns a color with the saturation decreased by that value.

@see saturate @example

  desaturate(hsl(120, 30%, 90%), 20%) => hsl(120, 10%, 90%)
  desaturate(#855, 20%) => #726b6b

@overload desaturate($color, $amount)

  @param $color [Sass::Script::Value::Color]
  @param $amount [Sass::Script::Value::Number] The amount to decrease the
    saturation by, between `0%` and `100%`

@return [Sass::Script::Value::Color] @raise [ArgumentError] if `$amount` is out of bounds, or either parameter

  is the wrong type
fade_in(color, amount)

Alias for opacify

fade_out(color, amount)

Alias for transparentize

Returns whether a feature exists in the current Sass runtime.

The following features are supported:

  • `global-variable-shadowing` indicates that a local variable will shadow a global variable unless `!global` is used.
  • `extend-selector-pseudoclass` indicates that `@extend` will reach into selector pseudoclasses like `:not`.
  • `units-level-3` indicates full support for unit arithmetic using units defined in the [Values and Units Level 3][] spec.

[Values and Units Level 3]: www.w3.org/TR/css3-values/

  • `at-error` indicates that the Sass `@error` directive is supported.

@example

  feature-exists(some-feature-that-exists) => true
  feature-exists(what-is-this-i-dont-know) => false

@overload feature_exists($feature)

  @param $feature [Sass::Script::Value::String] The name of the feature

@return [Sass::Script::Value::Bool] Whether the feature is supported in this version of Sass @raise [ArgumentError] if `$feature` isn‘t a string

Rounds a number down to the previous whole number.

@example

  floor(10.4px) => 10px
  floor(10.6px) => 10px

@overload floor($number)

  @param $number [Sass::Script::Value::Number]

@return [Sass::Script::Value::Number] @raise [ArgumentError] if `$number` isn‘t a number

Check whether a function with the given name exists.

@example

  function-exists(lighten) => true

  @function myfunc { @return "something"; }
  function-exists(myfunc) => true

@overload function_exists($name)

  @param name [Sass::Script::Value::String] The name of the function to
    check.

@return [Sass::Script::Value::Bool] Whether the function is defined.

Check whether a variable with the given name exists in the global scope (at the top level of the file).

@example

  $a-false-value: false;
  global-variable-exists(a-false-value) => true
  global-variable-exists(a-null-value) => true

  .foo {
    $some-var: false;
    @if global-variable-exists(some-var) { /* false, doesn't run */ }
  }

@overload global_variable_exists($name)

  @param $name [Sass::Script::Value::String] The name of the variable to
    check. The name should not include the `$`.

@return [Sass::Script::Value::Bool] Whether the variable is defined in

  the global scope.

Converts a color to grayscale. This is identical to `desaturate(color, 100%)`.

@see desaturate @overload grayscale($color)

  @param $color [Sass::Script::Value::Color]

@return [Sass::Script::Value::Color] @raise [ArgumentError] if `$color` isn‘t a color

Gets the green component of a color. Calculated from HSL where necessary via [this algorithm][hsl-to-rgb].

[hsl-to-rgb]: www.w3.org/TR/css3-color/#hsl-color

@overload green($color)

  @param $color [Sass::Script::Value::Color]

@return [Sass::Script::Value::Number] The green component, between 0 and

  255 inclusive

@raise [ArgumentError] if `$color` isn‘t a color

Creates a {Sass::Script::Value::Color Color} from hue, saturation, and lightness values. Uses the algorithm from the [CSS3 spec][].

[CSS3 spec]: www.w3.org/TR/css3-color/#hsl-color

@see hsla @overload hsl($hue, $saturation, $lightness)

  @param $hue [Sass::Script::Value::Number] The hue of the color. Should be
    between 0 and 360 degrees, inclusive
  @param $saturation [Sass::Script::Value::Number] The saturation of the
    color. Must be between `0%` and `100%`, inclusive
  @param $lightness [Sass::Script::Value::Number] The lightness of the
    color. Must be between `0%` and `100%`, inclusive

@return [Sass::Script::Value::Color] @raise [ArgumentError] if `$saturation` or `$lightness` are out of bounds

  or any parameter is the wrong type

Creates a {Sass::Script::Value::Color Color} from hue, saturation, lightness, and alpha values. Uses the algorithm from the [CSS3 spec][].

[CSS3 spec]: www.w3.org/TR/css3-color/#hsl-color

@see hsl @overload hsla($hue, $saturation, $lightness, $alpha)

  @param $hue [Sass::Script::Value::Number] The hue of the color. Should be
    between 0 and 360 degrees, inclusive
  @param $saturation [Sass::Script::Value::Number] The saturation of the
    color. Must be between `0%` and `100%`, inclusive
  @param $lightness [Sass::Script::Value::Number] The lightness of the
    color. Must be between `0%` and `100%`, inclusive
  @param $alpha [Sass::Script::Value::Number] The opacity of the color. Must
    be between 0 and 1, inclusive

@return [Sass::Script::Value::Color] @raise [ArgumentError] if `$saturation`, `$lightness`, or `$alpha` are out

  of bounds or any parameter is the wrong type

Returns the hue component of a color. See [the CSS3 HSL specification][hsl]. Calculated from RGB where necessary via [this algorithm][rgb-to-hsl].

[hsl]: en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV [rgb-to-hsl]: en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV

@overload hue($color)

  @param $color [Sass::Script::Value::Color]

@return [Sass::Script::Value::Number] The hue component, between 0deg and

  360deg

@raise [ArgumentError] if `$color` isn‘t a color

Converts a color into the format understood by IE filters.

@example

  ie-hex-str(#abc) => #FFAABBCC
  ie-hex-str(#3322BB) => #FF3322BB
  ie-hex-str(rgba(0, 255, 0, 0.5)) => #8000FF00

@overload ie_hex_str($color)

  @param $color [Sass::Script::Value::Color]

@return [Sass::Script::Value::String] The IE-formatted string

  representation of the color

@raise [ArgumentError] if `$color` isn‘t a color

Returns one of two values, depending on whether or not `$condition` is true. Just like in `@if`, all values other than `false` and `null` are considered to be true.

@example

  if(true, 1px, 2px) => 1px
  if(false, 1px, 2px) => 2px

@overload if($condition, $if-true, $if-false)

  @param $condition [Sass::Script::Value::Base] Whether the `$if-true` or
    `$if-false` will be returned
  @param $if-true [Sass::Script::Tree::Node]
  @param $if-false [Sass::Script::Tree::Node]

@return [Sass::Script::Value::Base] `$if-true` or `$if-false`

Returns the position of a value within a list. If the value isn‘t found, returns `null` instead.

Note that unlike some languages, the first item in a Sass list is number 1, the second number 2, and so forth.

This can return the position of a pair in a map as well.

@example

  index(1px solid red, solid) => 2
  index(1px solid red, dashed) => null
  index((width: 10px, height: 20px), (height 20px)) => 2

@overload index($list, $value)

  @param $list [Sass::Script::Value::Base]
  @param $value [Sass::Script::Value::Base]

@return [Sass::Script::Value::Number, Sass::Script::Value::Null] The

  1-based index of `$value` in `$list`, or `null`

Return a string containing the value as its Sass representation.

@overload inspect($value)

  @param $value [Sass::Script::Value::Base] The value to inspect.

@return [Sass::Script::Value::String] A representation of the value as

  it would be written in Sass.

Returns the inverse (negative) of a color. The red, green, and blue values are inverted, while the opacity is left alone.

@overload invert($color)

  @param $color [Sass::Script::Value::Color]

@return [Sass::Script::Value::Color] @raise [ArgumentError] if `$color` isn‘t a color

Returns whether `$super` is a superselector of `$sub`. This means that `$super` matches all the elements that `$sub` matches, as well as possibly additional elements. In general, simpler selectors tend to be superselectors of more complex oned.

@example

  is-superselector(".foo", ".foo.bar") => true
  is-superselector(".foo.bar", ".foo") => false
  is-superselector(".bar", ".foo .bar") => true
  is-superselector(".foo .bar", ".bar") => false

@overload is_superselector($super, $sub)

  @param $super [Sass::Script::Value::String, Sass::Script::Value::List]
    The potential superselector. This can be either a string, a list of
    strings, or a list of lists of strings as returned by `&`.
  @param $sub [Sass::Script::Value::String, Sass::Script::Value::List]
    The potential subselector. This can be either a string, a list of
    strings, or a list of lists of strings as returned by `&`.
  @return [Sass::Script::Value::Bool]
    Whether `$selector1` is a superselector of `$selector2`.

Joins together two lists into one.

Unless `$separator` is passed, if one list is comma-separated and one is space-separated, the first parameter‘s separator is used for the resulting list. If both lists have fewer than two items, spaces are used for the resulting list.

Like all list functions, `join()` returns a new list rather than modifying its arguments in place.

@example

  join(10px 20px, 30px 40px) => 10px 20px 30px 40px
  join((blue, red), (#abc, #def)) => blue, red, #abc, #def
  join(10px, 20px) => 10px 20px
  join(10px, 20px, comma) => 10px, 20px
  join((blue, red), (#abc, #def), space) => blue red #abc #def

@overload join($list1, $list2, $separator: auto)

  @param $list1 [Sass::Script::Value::Base]
  @param $list2 [Sass::Script::Value::Base]
  @param $separator [Sass::Script::Value::String] The list separator to use.
    If this is `comma` or `space`, that separator will be used. If this is
    `auto` (the default), the separator is determined as explained above.

@return [Sass::Script::Value::List]

Returns the map of named arguments passed to a function or mixin that takes a variable argument list. The argument names are strings, and they do not contain the leading `$`.

@example

  @mixin foo($args...) {
    @debug keywords($args); //=> (arg1: val, arg2: val)
  }

  @include foo($arg1: val, $arg2: val);

@overload keywords($args)

  @param $args [Sass::Script::Value::ArgList]

@return [Sass::Script::Value::Map] @raise [ArgumentError] if `$args` isn‘t a variable argument list

Return the length of a list.

This can return the number of pairs in a map as well.

@example

  length(10px) => 1
  length(10px 20px 30px) => 3
  length((width: 10px, height: 20px)) => 2

@overload length($list)

  @param $list [Sass::Script::Value::Base]

@return [Sass::Script::Value::Number]

Makes a color lighter. Takes a color and a number between `0%` and `100%`, and returns a color with the lightness increased by that amount.

@see darken @example

  lighten(hsl(0, 0%, 0%), 30%) => hsl(0, 0, 30)
  lighten(#800, 20%) => #e00

@overload lighten($color, $amount)

  @param $color [Sass::Script::Value::Color]
  @param $amount [Sass::Script::Value::Number] The amount to increase the
    lightness by, between `0%` and `100%`

@return [Sass::Script::Value::Color] @raise [ArgumentError] if `$amount` is out of bounds, or either parameter

  is the wrong type

Returns the lightness component of a color. See [the CSS3 HSL specification][hsl]. Calculated from RGB where necessary via [this algorithm][rgb-to-hsl].

[hsl]: en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV [rgb-to-hsl]: en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV

@overload lightness($color)

  @param $color [Sass::Script::Value::Color]

@return [Sass::Script::Value::Number] The lightness component, between 0%

  and 100%

@raise [ArgumentError] if `$color` isn‘t a color

Returns the separator of a list. If the list doesn‘t have a separator due to having fewer than two elements, returns `space`.

@example

  list-separator(1px 2px 3px) => space
  list-separator(1px, 2px, 3px) => comma
  list-separator('foo') => space

@overload list_separator($list)

  @param $list [Sass::Script::Value::Base]

@return [Sass::Script::Value::String] `comma` or `space`

Returns the value in a map associated with the given key. If the map doesn‘t have such a key, returns `null`.

@example

  map-get(("foo": 1, "bar": 2), "foo") => 1
  map-get(("foo": 1, "bar": 2), "bar") => 2
  map-get(("foo": 1, "bar": 2), "baz") => null

@overload map_get($map, $key)

  @param $map [Sass::Script::Value::Map]
  @param $key [Sass::Script::Value::Base]

@return [Sass::Script::Value::Base] The value indexed by `$key`, or `null`

  if the map doesn't contain the given key

@raise [ArgumentError] if `$map` is not a map

Returns whether a map has a value associated with a given key.

@example

  map-has-key(("foo": 1, "bar": 2), "foo") => true
  map-has-key(("foo": 1, "bar": 2), "baz") => false

@overload map_has_key($map, $key)

  @param $map [Sass::Script::Value::Map]
  @param $key [Sass::Script::Value::Base]

@return [Sass::Script::Value::Bool] @raise [ArgumentError] if `$map` is not a map

Returns a list of all keys in a map.

@example

  map-keys(("foo": 1, "bar": 2)) => "foo", "bar"

@overload map_keys($map)

  @param $map [Map]

@return [List] the list of keys, comma-separated @raise [ArgumentError] if `$map` is not a map

Merges two maps together into a new map. Keys in `$map2` will take precedence over keys in `$map1`.

This is the best way to add new values to a map.

All keys in the returned map that also appear in `$map1` will have the same order as in `$map1`. New keys from `$map2` will be placed at the end of the map.

Like all map functions, `map-merge()` returns a new map rather than modifying its arguments in place.

@example

  map-merge(("foo": 1), ("bar": 2)) => ("foo": 1, "bar": 2)
  map-merge(("foo": 1, "bar": 2), ("bar": 3)) => ("foo": 1, "bar": 3)

@overload map_merge($map1, $map2)

  @param $map1 [Sass::Script::Value::Map]
  @param $map2 [Sass::Script::Value::Map]

@return [Sass::Script::Value::Map] @raise [ArgumentError] if either parameter is not a map

Returns a new map with keys removed.

Like all map functions, `map-merge()` returns a new map rather than modifying its arguments in place.

@example

  map-remove(("foo": 1, "bar": 2), "bar") => ("foo": 1)
  map-remove(("foo": 1, "bar": 2, "baz": 3), "bar", "baz") => ("foo": 1)
  map-remove(("foo": 1, "bar": 2), "baz") => ("foo": 1, "bar": 2)

@overload map_remove($map, $keys…)

  @param $map  [Sass::Script::Value::Map]
  @param $keys [[Sass::Script::Value::Base]]

@return [Sass::Script::Value::Map] @raise [ArgumentError] if `$map` is not a map

Returns a list of all values in a map. This list may include duplicate values, if multiple keys have the same value.

@example

  map-values(("foo": 1, "bar": 2)) => 1, 2
  map-values(("foo": 1, "bar": 2, "baz": 1)) => 1, 2, 1

@overload map_values($map)

  @param $map [Map]

@return [List] the list of values, comma-separated @raise [ArgumentError] if `$map` is not a map

Finds the maximum of several numbers. This function takes any number of arguments.

@example

  max(1px, 4px) => 4px
  max(5em, 3em, 4em) => 5em

@overload max($numbers…)

  @param $numbers [[Sass::Script::Value::Number]]

@return [Sass::Script::Value::Number] @raise [ArgumentError] if any argument isn‘t a number, or if not all of

  the arguments have comparable units

Finds the minimum of several numbers. This function takes any number of arguments.

@example

  min(1px, 4px) => 1px
  min(5em, 3em, 4em) => 3em

@overload min($numbers…)

  @param $numbers [[Sass::Script::Value::Number]]

@return [Sass::Script::Value::Number] @raise [ArgumentError] if any argument isn‘t a number, or if not all of

  the arguments have comparable units

Mixes two colors together. Specifically, takes the average of each of the RGB components, optionally weighted by the given percentage. The opacity of the colors is also considered when weighting the components.

The weight specifies the amount of the first color that should be included in the returned color. The default, `50%`, means that half the first color and half the second color should be used. `25%` means that a quarter of the first color and three quarters of the second color should be used.

@example

  mix(#f00, #00f) => #7f007f
  mix(#f00, #00f, 25%) => #3f00bf
  mix(rgba(255, 0, 0, 0.5), #00f) => rgba(63, 0, 191, 0.75)

@overload mix($color1, $color2, $weight: 50%)

  @param $color1 [Sass::Script::Value::Color]
  @param $color2 [Sass::Script::Value::Color]
  @param $weight [Sass::Script::Value::Number] The relative weight of each
    color. Closer to `100%` gives more weight to `$color1`, closer to `0%`
    gives more weight to `$color2`

@return [Sass::Script::Value::Color] @raise [ArgumentError] if `$weight` is out of bounds or any parameter is

  the wrong type

Check whether a mixin with the given name exists.

@example

  mixin-exists(nonexistent) => false

  @mixin red-text { color: red; }
  mixin-exists(red-text) => true

@overload mixin_exists($name)

  @param name [Sass::Script::Value::String] The name of the mixin to
    check.

@return [Sass::Script::Value::Bool] Whether the mixin is defined.

Gets the nth item in a list.

Note that unlike some languages, the first item in a Sass list is number 1, the second number 2, and so forth.

This can return the nth pair in a map as well.

Negative index values address elements in reverse order, starting with the last element in the list.

@example

  nth(10px 20px 30px, 1) => 10px
  nth((Helvetica, Arial, sans-serif), 3) => sans-serif
  nth((width: 10px, length: 20px), 2) => length, 20px

@overload nth($list, $n)

  @param $list [Sass::Script::Value::Base]
  @param $n [Sass::Script::Value::Number] The index of the item to get.
    Negative indices count from the end of the list.

@return [Sass::Script::Value::Base] @raise [ArgumentError] if `$n` isn‘t an integer between 1 and the length

  of `$list`

Makes a color more opaque. Takes a color and a number between 0 and 1, and returns a color with the opacity increased by that amount.

@see transparentize @example

  opacify(rgba(0, 0, 0, 0.5), 0.1) => rgba(0, 0, 0, 0.6)
  opacify(rgba(0, 0, 17, 0.8), 0.2) => #001

@overload opacify($color, $amount)

  @param $color [Sass::Script::Value::Color]
  @param $amount [Sass::Script::Value::Number] The amount to increase the
    opacity by, between 0 and 1

@return [Sass::Script::Value::Color] @raise [ArgumentError] if `$amount` is out of bounds, or either parameter

  is the wrong type

Returns the alpha component (opacity) of a color. This is 1 unless otherwise specified.

@overload opacity($color)

  @param $color [Sass::Script::Value::Color]

@return [Sass::Script::Value::Number] The alpha component, between 0 and 1 @raise [ArgumentError] if `$color` isn‘t a color

Converts a unitless number to a percentage.

@example

  percentage(0.2) => 20%
  percentage(100px / 50px) => 200%

@overload percentage($number)

  @param $number [Sass::Script::Value::Number]

@return [Sass::Script::Value::Number] @raise [ArgumentError] if `$number` isn‘t a unitless number

Add quotes to a string if the string isn‘t quoted, or returns the same string if it is.

@see unquote @example

  quote("foo") => "foo"
  quote(foo) => "foo"

@overload quote($string)

  @param $string [Sass::Script::Value::String]

@return [Sass::Script::Value::String] @raise [ArgumentError] if `$string` isn‘t a string

@overload random()

  Return a decimal between 0 and 1, inclusive of 0 but not 1.
  @return [Sass::Script::Value::Number] A decimal value.

@overload random($limit)

  Return an integer between 1 and `$limit`, inclusive of both 1 and `$limit`.
  @param $limit [Sass::Script::Value::Number] The maximum of the random integer to be
    returned, a positive integer.
  @return [Sass::Script::Value::Number] An integer.
  @raise [ArgumentError] if the `$limit` is not 1 or greater

Gets the red component of a color. Calculated from HSL where necessary via [this algorithm][hsl-to-rgb].

[hsl-to-rgb]: www.w3.org/TR/css3-color/#hsl-color

@overload red($color)

  @param $color [Sass::Script::Value::Color]

@return [Sass::Script::Value::Number] The red component, between 0 and 255

  inclusive

@raise [ArgumentError] if `$color` isn‘t a color

Creates a {Sass::Script::Value::Color Color} object from red, green, and blue values.

@see rgba @overload rgb($red, $green, $blue)

  @param $red [Sass::Script::Value::Number] The amount of red in the color.
    Must be between 0 and 255 inclusive, or between `0%` and `100%`
    inclusive
  @param $green [Sass::Script::Value::Number] The amount of green in the
    color. Must be between 0 and 255 inclusive, or between `0%` and `100%`
    inclusive
  @param $blue [Sass::Script::Value::Number] The amount of blue in the
    color. Must be between 0 and 255 inclusive, or between `0%` and `100%`
    inclusive

@return [Sass::Script::Value::Color] @raise [ArgumentError] if any parameter is the wrong type or out of bounds

Creates a {Sass::Script::Value::Color Color} from red, green, blue, and alpha values. @see rgb

@overload rgba($red, $green, $blue, $alpha)

  @param $red [Sass::Script::Value::Number] The amount of red in the
    color. Must be between 0 and 255 inclusive or 0% and 100% inclusive
  @param $green [Sass::Script::Value::Number] The amount of green in the
    color. Must be between 0 and 255 inclusive or 0% and 100% inclusive
  @param $blue [Sass::Script::Value::Number] The amount of blue in the
    color. Must be between 0 and 255 inclusive or 0% and 100% inclusive
  @param $alpha [Sass::Script::Value::Number] The opacity of the color.
    Must be between 0 and 1 inclusive
  @return [Sass::Script::Value::Color]
  @raise [ArgumentError] if any parameter is the wrong type or out of
    bounds

@overload rgba($color, $alpha)

  Sets the opacity of an existing color.

  @example
    rgba(#102030, 0.5) => rgba(16, 32, 48, 0.5)
    rgba(blue, 0.2)    => rgba(0, 0, 255, 0.2)

  @param $color [Sass::Script::Value::Color] The color whose opacity will
    be changed.
  @param $alpha [Sass::Script::Value::Number] The new opacity of the
    color. Must be between 0 and 1 inclusive
  @return [Sass::Script::Value::Color]
  @raise [ArgumentError] if `$alpha` is out of bounds or either parameter
    is the wrong type

Rounds a number to the nearest whole number.

@example

  round(10.4px) => 10px
  round(10.6px) => 11px

@overload round($number)

  @param $number [Sass::Script::Value::Number]

@return [Sass::Script::Value::Number] @raise [ArgumentError] if `$number` isn‘t a number

Makes a color more saturated. Takes a color and a number between 0% and 100%, and returns a color with the saturation increased by that amount.

@see desaturate @example

  saturate(hsl(120, 30%, 90%), 20%) => hsl(120, 50%, 90%)
  saturate(#855, 20%) => #9e3f3f

@overload saturate($color, $amount)

  @param $color [Sass::Script::Value::Color]
  @param $amount [Sass::Script::Value::Number] The amount to increase the
    saturation by, between `0%` and `100%`

@return [Sass::Script::Value::Color] @raise [ArgumentError] if `$amount` is out of bounds, or either parameter

  is the wrong type

Returns the saturation component of a color. See [the CSS3 HSL specification][hsl]. Calculated from RGB where necessary via [this algorithm][rgb-to-hsl].

[hsl]: en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV [rgb-to-hsl]: en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV

@overload saturation($color)

  @param $color [Sass::Script::Value::Color]

@return [Sass::Script::Value::Number] The saturation component, between 0%

  and 100%

@raise [ArgumentError] if `$color` isn‘t a color

Fluidly scales one or more properties of a color. Unlike \{adjust_color adjust-color}, which changes a color‘s properties by fixed amounts, \{scale_color scale-color} fluidly changes them based on how high or low they already are. That means that lightening an already-light color with \{scale_color scale-color} won‘t change the lightness much, but lightening a dark color by the same amount will change it more dramatically. This has the benefit of making `scale-color($color, …)` have a similar effect regardless of what `$color` is.

For example, the lightness of a color can be anywhere between `0%` and `100%`. If `scale-color($color, $lightness: 40%)` is called, the resulting color‘s lightness will be 40% of the way between its original lightness and 100. If `scale-color($color, $lightness: -40%)` is called instead, the lightness will be 40% of the way between the original and 0.

This can change the red, green, blue, saturation, value, and alpha properties. The properties are specified as keyword arguments. All arguments should be percentages between `0%` and `100%`.

All properties are optional. You can‘t specify both RGB properties (`$red`, `$green`, `$blue`) and HSL properties (`$saturation`, `$value`) at the same time.

@example

  scale-color(hsl(120, 70%, 80%), $lightness: 50%) => hsl(120, 70%, 90%)
  scale-color(rgb(200, 150%, 170%), $green: -40%, $blue: 70%) => rgb(200, 90, 229)
  scale-color(hsl(200, 70%, 80%), $saturation: -90%, $alpha: -30%) => hsla(200, 7%, 80%, 0.7)

@overload scale_color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha])

  @param $color [Sass::Script::Value::Color]
  @param $red [Sass::Script::Value::Number]
  @param $green [Sass::Script::Value::Number]
  @param $blue [Sass::Script::Value::Number]
  @param $saturation [Sass::Script::Value::Number]
  @param $lightness [Sass::Script::Value::Number]
  @param $alpha [Sass::Script::Value::Number]

@return [Sass::Script::Value::Color] @raise [ArgumentError] if any parameter is the wrong type or out-of

  bounds, or if RGB properties and HSL properties are adjusted at the
  same time

Return a new selector with all selectors in `$selectors` appended one another as though they had been nested in the stylesheet as `$selector1 { &$selector2 { … } }`.

@example

  selector-append(".foo", ".bar", ".baz") => .foo.bar.baz
  selector-append(".a .foo", ".b .bar") => "a .foo.b .bar"
  selector-append(".foo", "-suffix") => ".foo-suffix"

@overload selector_append($selectors…)

  @param $selectors [[Sass::Script::Value::String, Sass::Script::Value::List]]
    The selectors to append. At least one selector must be passed. Each of
    these can be either a string, a list of strings, or a list of lists of
    strings as returned by `&`.
  @return [Sass::Script::Value::List]
    A list of lists of strings representing the result of appending
    `$selectors`. This is in the same format as a selector returned by
    `&`.
  @raise [ArgumentError] if a selector could not be appended.

Returns a new version of `$selector` with `$extendee` extended with `$extender`. This works just like the result of

    $selector { ... }
    $extender { @extend $extendee }

@example

  selector-extend(".a .b", ".b", ".foo .bar") => .a .b, .a .foo .bar, .foo .a .bar

@overload selector_extend($selector, $extendee, $extender)

  @param $selector [Sass::Script::Value::String, Sass::Script::Value::List]
    The selector within which `$extendee` is extended with
    `$extender`. This can be either a string, a list of strings,
    or a list of lists of strings as returned by `&`.
  @param $extendee [Sass::Script::Value::String, Sass::Script::Value::List]
    The selector being extended. This can be either a string, a
    list of strings, or a list of lists of strings as returned
    by `&`.
  @param $extender [Sass::Script::Value::String, Sass::Script::Value::List]
    The selector being injected into `$selector`. This can be
    either a string, a list of strings, or a list of lists of
    strings as returned by `&`.
  @return [Sass::Script::Value::List]
    A list of lists of strings representing the result of the
    extension. This is in the same format as a selector returned
    by `&`.
  @raise [ArgumentError] if the extension fails

Return a new selector with all selectors in `$selectors` nested beneath one another as though they had been nested in the stylesheet as `$selector1 { $selector2 { … } }`.

Unlike most selector functions, `selector-nest` allows the parent selector `&` to be used in any selector but the first.

@example

  selector-nest(".foo", ".bar", ".baz") => .foo .bar .baz
  selector-nest(".a .foo", ".b .bar") => .a .foo .b .bar
  selector-nest(".foo", "&.bar") => .foo.bar

@overload selector_nest($selectors…)

  @param $selectors [[Sass::Script::Value::String, Sass::Script::Value::List]]
    The selectors to nest. At least one selector must be passed. Each of
    these can be either a string, a list of strings, or a list of lists of
    strings as returned by `&`.
  @return [Sass::Script::Value::List]
    A list of lists of strings representing the result of nesting
    `$selectors`. This is in the same format as a selector returned by
    `&`.

Parses a user-provided selector into a list of lists of strings as returned by `&`.

@example

  selector-parse(".foo .bar, .baz .bang") => ('.foo' '.bar', '.baz' '.bang')

@overload selector_parse($selector)

  @param $selector [Sass::Script::Value::String, Sass::Script::Value::List]
    The selector to parse. This can be either a string, a list of
    strings, or a list of lists of strings as returned by `&`.
  @return [Sass::Script::Value::List]
    A list of lists of strings representing `$selector`. This is
    in the same format as a selector returned by `&`.

Replaces all instances of `$original` with `$replacement` in `$selector`

This works by using `@extend` and throwing away the original selector. This means that it can be used to do very advanced replacements; see the examples below.

@example

  selector-replace(".foo .bar", ".bar", ".baz") => ".foo .baz"
  selector-replace(".foo.bar.baz", ".foo.baz", ".qux") => ".bar.qux"

@overload selector_replace($selector, $original, $replacement)

  @param $selector [Sass::Script::Value::String, Sass::Script::Value::List]
    The selector within which `$original` is replaced with
    `$replacement`. This can be either a string, a list of
    strings, or a list of lists of strings as returned by `&`.
  @param $original [Sass::Script::Value::String, Sass::Script::Value::List]
    The selector being replaced. This can be either a string, a
    list of strings, or a list of lists of strings as returned
    by `&`.
  @param $replacement [Sass::Script::Value::String, Sass::Script::Value::List]
    The selector that `$original` is being replaced with. This
    can be either a string, a list of strings, or a list of
    lists of strings as returned by `&`.
  @return [Sass::Script::Value::List]
    A list of lists of strings representing the result of the
    extension. This is in the same format as a selector returned
    by `&`.
  @raise [ArgumentError] if the replacement fails

Unifies two selectors into a single selector that matches only elements matched by both input selectors. Returns `null` if there is no such selector.

Like the selector unification done for `@extend`, this doesn‘t guarantee that the output selector will match all elements matched by both input selectors. For example, if `.a .b` is unified with `.x .y`, `.a .x .b.y, .x .a .b.y` will be returned, but `.a.x .b.y` will not. This avoids exponential output size while matching all elements that are likely to exist in practice.

@example

  selector-unify(".a", ".b") => .a.b
  selector-unify(".a .b", ".x .y") => .a .x .b.y, .x .a .b.y
  selector-unify(".a.b", ".b.c") => .a.b.c
  selector-unify("#a", "#b") => null

@overload selector_unify($selector1, $selector2)

  @param $selector1 [Sass::Script::Value::String, Sass::Script::Value::List]
    The first selector to be unified. This can be either a
    string, a list of strings, or a list of lists of strings as
    returned by `&`.
  @param $selector2 [Sass::Script::Value::String, Sass::Script::Value::List]
    The second selector to be unified. This can be either a
    string, a list of strings, or a list of lists of strings as
    returned by `&`.
  @return [Sass::Script::Value::List, Sass::Script::Value::Null]
    A list of lists of strings representing the result of the
    unification, or null if no unification exists. This is in
    the same format as a selector returned by `&`.

Return a new list, based on the list provided, but with the nth element changed to the value given.

Note that unlike some languages, the first item in a Sass list is number 1, the second number 2, and so forth.

Negative index values address elements in reverse order, starting with the last element in the list.

@example

  set-nth($list: 10px 20px 30px, $n: 2, $value: -20px) => 10px -20px 30px

@overload set-nth($list, $n, $value)

  @param $list [Sass::Script::Value::Base] The list that will be copied, having the element
    at index `$n` changed.
  @param $n [Sass::Script::Value::Number] The index of the item to set.
    Negative indices count from the end of the list.
  @param $value [Sass::Script::Value::Base] The new value at index `$n`.

@return [Sass::Script::Value::List] @raise [ArgumentError] if `$n` isn‘t an integer between 1 and the length

  of `$list`

Returns the [simple selectors](dev.w3.org/csswg/selectors4/#simple) that comprise the compound selector `$selector`.

Note that `$selector` **must be** a [compound selector](dev.w3.org/csswg/selectors4/#compound). That means it cannot contain commas or spaces. It also means that unlike other selector functions, this takes only strings, not lists.

@example

  simple-selectors(".foo.bar") => ".foo", ".bar"
  simple-selectors(".foo.bar.baz") => ".foo", ".bar", ".baz"

@overload simple_selectors($selector)

  @param $selector [Sass::Script::Value::String]
    The compound selector whose simple selectors will be extracted.
  @return [Sass::Script::Value::List]
    A list of simple selectors in the compound selector.

Returns the index of the first occurrence of `$substring` in `$string`. If there is no such occurrence, returns `null`.

Note that unlike some languages, the first character in a Sass string is number 1, the second number 2, and so forth.

@example

  str-index(abcd, a)  => 1
  str-index(abcd, ab) => 1
  str-index(abcd, X)  => null
  str-index(abcd, c)  => 3

@overload str_index($string, $substring)

  @param $string [Sass::Script::Value::String]
  @param $substring [Sass::Script::Value::String]

@return [Sass::Script::Value::Number, Sass::Script::Value::Null] @raise [ArgumentError] if any parameter is the wrong type

Inserts `$insert` into `$string` at `$index`.

Note that unlike some languages, the first character in a Sass string is number 1, the second number 2, and so forth.

@example

  str-insert("abcd", "X", 1) => "Xabcd"
  str-insert("abcd", "X", 4) => "abcXd"
  str-insert("abcd", "X", 5) => "abcdX"

@overload str_insert($string, $insert, $index)

  @param $string [Sass::Script::Value::String]
  @param $insert [Sass::Script::Value::String]
  @param $index [Sass::Script::Value::Number] The position at which
    `$insert` will be inserted. Negative indices count from the end of
    `$string`. An index that's outside the bounds of the string will insert
    `$insert` at the front or back of the string

@return [Sass::Script::Value::String] The result string. This will be

  quoted if and only if `$string` was quoted

@raise [ArgumentError] if any parameter is the wrong type

Returns the number of characters in a string.

@example

  str-length("foo") => 3

@overload str_length($string)

  @param $string [Sass::Script::Value::String]

@return [Sass::Script::Value::Number] @raise [ArgumentError] if `$string` isn‘t a string

Extracts a substring from `$string`. The substring will begin at index `$start-at` and ends at index `$end-at`.

Note that unlike some languages, the first character in a Sass string is number 1, the second number 2, and so forth.

@example

 str-slice("abcd", 2, 3)   => "bc"
 str-slice("abcd", 2)      => "bcd"
 str-slice("abcd", -3, -2) => "bc"
 str-slice("abcd", 2, -2)  => "bc"

@overload str_slice($string, $start-at, $end-at: -1)

  @param $start-at [Sass::Script::Value::Number] The index of the first
    character of the substring. If this is negative, it counts from the end
    of `$string`
  @param $end-at [Sass::Script::Value::Number] The index of the last
    character of the substring. If this is negative, it counts from the end
    of `$string`. Defaults to -1
  @return [Sass::Script::Value::String] The substring. This will be quoted
    if and only if `$string` was quoted

@raise [ArgumentError] if any parameter is the wrong type

Convert a string to lower case,

@example

  to-lower-case(ABCD) => abcd

@overload to_lower_case($string)

  @param $string [Sass::Script::Value::String]

@return [Sass::Script::Value::String] @raise [ArgumentError] if `$string` isn‘t a string

Converts a string to upper case.

@example

  to-upper-case(abcd) => ABCD

@overload to_upper_case($string)

  @param $string [Sass::Script::Value::String]

@return [Sass::Script::Value::String] @raise [ArgumentError] if `$string` isn‘t a string

Makes a color more transparent. Takes a color and a number between 0 and 1, and returns a color with the opacity decreased by that amount.

@see opacify @example

  transparentize(rgba(0, 0, 0, 0.5), 0.1) => rgba(0, 0, 0, 0.4)
  transparentize(rgba(0, 0, 0, 0.8), 0.2) => rgba(0, 0, 0, 0.6)

@overload transparentize($color, $amount)

  @param $color [Sass::Script::Value::Color]
  @param $amount [Sass::Script::Value::Number] The amount to decrease the
    opacity by, between 0 and 1

@return [Sass::Script::Value::Color] @raise [ArgumentError] if `$amount` is out of bounds, or either parameter

  is the wrong type

Returns the type of a value.

@example

  type-of(100px)  => number
  type-of(asdf)   => string
  type-of("asdf") => string
  type-of(true)   => bool
  type-of(#fff)   => color
  type-of(blue)   => color
  type-of(null)   => null

@overload type_of($value)

  @param $value [Sass::Script::Value::Base] The value to inspect

@return [Sass::Script::Value::String] The unquoted string name of the

  value's type

Returns a unique CSS identifier. The identifier is returned as an unquoted string. The identifier returned is only guaranteed to be unique within the scope of a single Sass run.

@overload unique_id() @return [Sass::Script::Value::String]

Returns the unit(s) associated with a number. Complex units are sorted in alphabetical order by numerator and denominator.

@example

  unit(100) => ""
  unit(100px) => "px"
  unit(3em) => "em"
  unit(10px * 5em) => "em*px"
  unit(10px * 5em / 30cm / 1rem) => "em*px/cm*rem"

@overload unit($number)

  @param $number [Sass::Script::Value::Number]

@return [Sass::Script::Value::String] The unit(s) of the number, as a

  quoted string

@raise [ArgumentError] if `$number` isn‘t a number

Returns whether a number has units.

@example

  unitless(100) => true
  unitless(100px) => false

@overload unitless($number)

  @param $number [Sass::Script::Value::Number]

@return [Sass::Script::Value::Bool] @raise [ArgumentError] if `$number` isn‘t a number

Removes quotes from a string. If the string is already unquoted, this will return it unmodified.

@see quote @example

  unquote("foo") => foo
  unquote(foo) => foo

@overload unquote($string)

  @param $string [Sass::Script::Value::String]

@return [Sass::Script::Value::String] @raise [ArgumentError] if `$string` isn‘t a string

Check whether a variable with the given name exists in the current scope or in the global scope.

@example

  $a-false-value: false;
  variable-exists(a-false-value) => true
  variable-exists(a-null-value) => true

  variable-exists(nonexistent) => false

@overload variable_exists($name)

  @param $name [Sass::Script::Value::String] The name of the variable to
    check. The name should not include the `$`.

@return [Sass::Script::Value::Bool] Whether the variable is defined in

  the current scope.

Combines several lists into a single multidimensional list. The nth value of the resulting list is a space separated list of the source lists’ nth values.

The length of the resulting list is the length of the shortest list.

@example

  zip(1px 1px 3px, solid dashed solid, red green blue)
  => 1px solid red, 1px dashed green, 3px solid blue

@overload zip($lists…)

  @param $lists [[Sass::Script::Value::Base]]

@return [Sass::Script::Value::List]

[Validate]