collection

functions

_at

@function _at($collection, $props...) { ... }

Description

Creates a list of elements corresponding to the given keys, or indexes, of $collection. Keys may be specified as individual arguments or as lists of keys.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$props...

The property names or indexes of elements to pick, specified individually or in lists.

Number... or String... or List—

Returns

List —

Returns the new list of picked elements.

Example

_at(('a', 'b', 'c'), (1, 3));
// => ('a', 'c')

_at(('fred', 'barney', 'pebbles'), 1, 3);
// => ('fred', 'pebbles')

_count-by

@function _count-by($collection, $iteratee: _identity, $this-arg: null) { ... }

Description

Creates a map composed of keys generated from the results of running each element of $collection through $iteratee. The corresponding value of each key is the number of times the key was returned by $iteratee. The $iteratee is bound to $this-arg and invoked with three arguments; (value, index|key, collection).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given map, else false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$iteratee

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Map —

Returns the composed aggregate map.

Example

$foo: _count-by((4.3, 6.1, 6.4), 'floor');
// => ( 4: 1, 6: 2 )

$foo: _count-by(('one', 'two', 'three'), 'str-length');
// => ( 3: 2, 5: 1 )

_every

@function _every($collection, $predicate: _identity, $this-arg: null) { ... }

Description

Checks if $predicate returns truthy for all elements of $collection. The predicate is bound to $this-arg and invoked with three arguments: (value, index|key, collection).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

Boolean —

Returns true if all elements pass the predicate check, else false.

Example

$foo: _every((true, 1, null, 'yes'), _is-boolean);
// => false

$users: (
  ( 'user': 'barney', 'active': false ),
  ( 'user': 'fred',   'active': false )
);

// using the `_matches` callback shorthand
$foo: _every($users, ( 'user': 'barney', 'active': false ));
// => false

// using the `_matches-property` callback shorthand
$foo: _every($users, 'active', false);
// => true

// using the `_property` callback shorthand
$foo: _every($users, 'active');
// => false

_max

@function _max($collection, $iteratee: null, $this-arg: null) { ... }

Description

Gets the maximum value of $collection. If $collection is empty or falsey -Infinity is returned. If an iteratee function is provided it is invoked for each value in $collection to generate the criterion by which the value is ranked. The $iteratee is bound to $this-arg and invoked with three arguments: (value, index, collection).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given map, else false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$iteratee

The function invoked per iteration.

Function or Map or Stringnull
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Any type —

Returns the maximum value.

Example

$foo: _max((4, 2, 8, 6));
// => 8

$foo: _max(());
// => -Infinity

$users: (
  ( 'user': 'barney', 'age': 36 ),
  ( 'user': 'fred',   'age': 40 )
);

// using the `_property` callback shorthand
$foo: _max($users, 'age');
// => ( 'user': 'fred', 'age': 40 );

_min

@function _min($collection, $iteratee: null, $this-arg: null) { ... }

Description

Gets the minimum value of $collection. If $collection is empty or falsey Infinity is returned. If an iteratee function is provided it is invoked for each value in $collection to generate the criterion by which the value is ranked. The $iteratee is bound to $this-arg and invoked with three arguments; (value, index, collection).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given map, else false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$iteratee

The function invoked per iteration.

Function or Map or Stringnull
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Any type —

Returns the minimum value.

Example

$foo: _min((4, 2, 8, 6));
// => 2

$foo: _min(());
// => Infinity

$users: (
  ( 'user': 'barney', 'age': 36 ),
  ( 'user': 'fred',   'age': 40 )
);

// using the `_property` callback shorthand
$foo: _min($users, 'age');
// => ( 'user': 'barney', 'age': 36 );

_filter

@function _filter($collection, $predicate: _identity, $this-arg: null) { ... }

Description

Iterates over elements of $collection, returning a list of all elements $predicate returns truthy for. The predicate is bound to $this-arg and invoked with three arguments; (value, index|key, collection).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

List —

Returns the new filtered list.

Example

    @function is-even($value, $args...) {
        @return $value % 2 == 0;
    }
    
    $foo: _filter((4, 5, 6), is-even);
    // => (4, 6)
    
    $users: (
      ( 'user': 'barney', 'age': 36, 'active': true ),
      ( 'user': 'fred',   'age': 40, 'active': false )
    );
    
    // using the `_matches` callback shorthand
    $foo: _pluck(_filter($users, ( 'age': 36, 'active': true )), 'user');
    // => ('barney',)
    
    // using the `_matches-property` callback shorthand
    $foo: _pluck(_filter($users, 'active', false), 'user');
    // => ('fred',)
    
    // using the `_property` callback shorthand
    $foo: _pluck(_filter($users, 'active'), 'user');
    // => ('barney',)

_find

@function _find($collection, $predicate: _identity, $this-arg: null) { ... }

Description

Iterates over elements of $collection, returning the first element $predicate returns truthy for. The predicate is bound to $this-arg and invoked with three arguments; (value, index|key, collection).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given map, else false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to search.

List or Map or String—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

Any type —

Returns the matched element, else null.

Example

    $users: (
      ( 'user': 'barney',  'age': 36', active': true ),
      ( 'user': 'fred',    'age': 40', active': false ),
      ( 'user': 'pebbles', 'age': 1',  active': false )
    );
    
    @function is-young($user, $args...) {
        @return _get($user, 'age') < 40;
    }
    
    $foo: _result(_find($users, is-young), 'user');
    // => 'barney'
    
    // using the `_matches` callback shorthand
    $foo: _result(_find($users, ( 'age': 1, 'active': true )), 'user');
    // => 'pebbles'
    
    // using the `_matches-property` callback shorthand
    $foo: _result(_find($users, 'active', false), 'user');
    // => 'fred'
    
    // using the `_property` callback shorthand
    $foo: _result(_find($users, 'active'), 'user');
    // => 'barney'

_find-last

@function _find-last($collection, $predicate: _identity, $this-arg: null) { ... }

Description

This method is like _find except that it iterates over elements of $collection from right to left.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to search.

List or Map or String—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

Any type —

Returns the matched element, else null.

Example

    @function is-odd($value, $args...) {
        @return $value % 2 == 1;
    }
    
    $foo: _find-last((1, 2, 3, 4), is-odd);
    // => 3

_find-where

@function _find-where($collection, $source) { ... }

Description

Performs a deep comparison between each element in $collection and the source map, returning the first element that has equivalent property values.

Note: This method supports comparing lists, booleans, numbers, maps, and strings. Maps are compared by their own, not inherited, enumerable properties. For comparing a single own or inherited property value see _matches-property.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to search.

List or Map or String—
$source

The map of property values to match.

Map—

Returns

Any type —

Returns the matched element, else null.

Example

$users: (
  ( 'user': 'barney', 'age': 36, 'active': true ),
  ( 'user': 'fred',   'age': 40, 'active': false )
);

$foo: _result(_find-where($users, ( 'age': 36, 'active': true )), 'user');
// => 'barney'

$foo: _result(_find-where($users, ( 'age': 40, 'active': false )), 'user');
// => 'fred'

_for-each

@function _for-each($collection, $iteratee: _identity, $this-arg: null) { ... }

Description

Iterates over elements of $collection invoking $iteratee for each element. The $iteratee is bound to $this-arg and invoked with three arguments; (value, index|key, collection). Iterator functions may exit iteration early by explicitly returning false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$iteratee

The function invoked per iteration.

Function_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

List or Map or String —

Returns $collection.

Example

// todo

_for-each-right

@function _for-each-right($collection, $iteratee: _identity, $this-arg: null) { ... }

Description

This method is like _for-each except that it iterates over elements of $collection from right to left.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$iteratee

The function invoked per iteration.

Function_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

List or Map or String —

Returns $collection.

Example

// todo

_group-by

@function _group-by($collection, $iteratee: _identity, $this-arg: null) { ... }

Description

Creates a map composed of keys generated from the results of running each element of $collection through $iteratee. The corresponding value of each key is a list of the elements responsible for generating the key. The $iteratee is bound to $this-arg and invoked with three arguments; (value, index|key, collection).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$iteratee

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Map —

Returns the composed aggregate object.

Example

$foo: _group-by((4.2, 6.1, 6.4), floor);
// => { '4': (4.2,), '6': (6.1, 6.4) }

_group-by-keys

@function _group-by-keys($collection) { ... }

Description

Creates a map composed of keys generated from the results of aggregating the values for each key in $collection into a list.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—

Returns

Map —

Returns the aggregate values from the keys of the items.

Example

$foo: (a: 1, b: 2);
$bar: (a: 3, b: 4, c: 5);

$result: _group-by-keys($foo $bar);
// => (a: (1, 3), b: (2, 4), c: (5,));

_includes

@function _includes($collection, $target: null, $from-index: 1) { ... }

Description

Checks if $value is in $collection. If $from-index is negative, it is used as the offset from the end of $collection.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to search.

List or Map or String—
$target

The value to search for.

Anynull
$from-index

The index to search from.

Number1

Returns

Boolean —

Returns true if a matching element is found, else false.

Example

$foo: _includes((1, 2, 3), 1);
// => true
$foo: _includes((1, 2, 3), 1, 2);
// => false
$foo: _includes(( 'user': 'fred', 'age': 40 ), 'fred');
// => true
$foo: _includes('pebbles', 'eb');
// => true

_index-by

@function _index-by($collection, $iteratee: _identity, $this-arg: null) { ... }

Description

Creates a map composed of keys generated from the results of running each element of $collection through $iteratee. The corresponding value of each key is the last element responsible for generating the key. The iteratee function is bound to $this-arg and invoked with three arguments; (value, index|key, collection).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$iteratee

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Map —

Returns the composed aggregate object.

Example

// todo

_invoke

@function _invoke($collection, $method-name, $args...) { ... }

Description

Invokes the method named by $method-name on each element in $collection, returning a list of the results of each invoked method. Any additional arguments are provided to each invoked method. If $method-name is a function it is invoked for, and $this bound to, each element in $collection.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$method-name

The name of the method to invoke or the function invoked per iteration.

Function or String—
$args...

The arguments to invoke the method with.

Any...—

Returns

List —

Returns the list of results.

Example

$foo: _invoke(((5, 1, 7), (3, 2, 1)), '_sort');
// => ((1, 5, 7), (1, 2, 3))
$foo: _invoke((123, 456), '_split', '');
// => (('1', '2', '3'), ('4', '5', '6'))

_map

@function _map($collection, $iteratee: _identity, $this-arg: null) { ... }

Description

Creates a list of values by running each element in $collection through $iteratee. The $iteratee is bound to $this-arg and invoked with three arguments; (value, index|key, collection).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Many lodash methods are guarded to work as interatees for methods like _every, _filter, _map, _map-values, _reject, and _some.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$iteratee

The function invoked per iteration. create a _property or _matches style callback respectively.

Function or Map or String_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

List —

Returns the new mapped list.

Example

    @function times-three($n, $args...) {
      @return $n * 3;
    }
    
    $foo: _map((1, 2), times-three);
    // => (3, 6)
    
    $foo: _map(( 'a': 1, 'b': 2 ), times-three);
    // => (3, 6)
    
    $users: (
      ( 'user': 'barney' ),
      ( 'user': 'fred' )
    );
    // using the `_property` callback shorthand
    $foo: _map($users, 'user');
    // => ('barney', 'fred')

_partition

@function _partition($collection, $predicate: _identity, $this-arg: null) { ... }

Description

Creates a list of elements split into two groups, the first of which contains elements $predicate returns truthy for, while the second of which contains elements $predicate returns falsey for.

The predicate is bound to $this-arg and invoked with three arguments; (value, index|key, collection).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element. If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

List —

Returns the list of grouped elements.

Example

$foo: _partition(1.3 1.4 2.1 2.2, floor);
// => ((1.3 1.4), (2.1 2.2))

_pluck

@function _pluck($collection, $key) { ... }

Description

Gets the value of $key from all elements in $collection.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$key

The key of the property to pluck.

String—

Returns

List —

Returns the property values.

Example

$users: (
  ( 'user': 'barney', 'age': 36 ),
  ( 'user': 'fred',   'age': 40 )
);
$foo: _pluck($users, 'user');
// => ('barney', 'fred')
$user-index: _index-by($users, 'user');
$foo: _pluck($user-index, 'age');
// => (36, 40)

_reduce

@function _reduce($collection, $iteratee: _identity, $accumulator: null, $this-arg: null) { ... }

Description

Reduces $collection to a value which is the accumulated result of running each element in $collection through $iteratee, where each successive invocation is supplied the return value of the previous. If $accumulator is not provided the first element of $collection is used as the initial value. The $iteratee is bound to $this-argand invoked with four arguments; (accumulator, value, index|key, collection).

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$iteratee

The function invoked per iteration.

Function_identity
$accumulator

The initial value.

Anynull
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Any type —

Returns the accumulated value.

Example

// todo

_reduce-right

@function _reduce-right($collection, $iteratee: _identity, $accumulator: null, $this-arg: null) { ... }

Description

This method is like _reduce except that it iterates over elements of $collection from right to left.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$iteratee

The function invoked per iteration.

Function_identity
$accumulator

The initial value.

Anynull
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Any type —

Returns the accumulated value.

Example

// todo

_reject

@function _reject($collection, $predicate: _identity, $this-arg: null) { ... }

Description

The opposite of _filter; this method returns the elements of $collection that $predicate does not return truthy for.

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

List —

Returns the new filtered list.

Example

$foo: _reject((1, 2, 3, 4), is-even);
// => (1, 3)

$users: (
  ( 'user': 'barney', 'age': 36, 'active': false ),
  ( 'user': 'fred',   'age': 40, 'active': true )
);
// using the `_matches` callback shorthand
$foo: _pluck(_reject($users, ( 'age': 40, 'active': true )), 'user');
// => ('barney')

// using the `_matches-property` callback shorthand
$foo: _pluck(_reject($users, 'active', false), 'user');
// => ('fred')

// using the `_property` callback shorthand
$foo: _pluck(_reject($users, 'active'), 'user');
// => ('barney')

_sample

@function _sample($collection, $n: 1) { ... }

Description

Gets a random element or $n random elements from a collection.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to sample.

List or Map or String—
$n

The number of elements to sample.

Number1

Returns

Any type —

Returns the random sample(s).

Example

$foo: _sample((1, 2, 3, 4));
// => 2

$foo: _sample((1, 2, 3, 4), 2);
// => (3, 1)

_shuffle

@function _shuffle($collection) { ... }

Description

Creates a list of shuffled values, using a version of the Fisher-Yates shuffle. See Wikipedia for more details.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to shuffle.

List or Map or String—

Returns

List —

Returns the new shuffled list.

Example

$foo: _shuffle((1, 2, 3, 4));
// => (4, 1, 3, 2)

_size

@function _size($collection) { ... }

Description

Gets the size of $collection by returning length($collection) for lists or maps, orstr-length($collection)` for strings.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to inspect.

List or Map or String—

Returns

Number —

Returns the size of $collection.

Example

$foo: _size((1, 2, 3));
// => 3

$foo: _size(( 'a': 1, 'b': 2 ));
// => 2

$foo: _size('pebbles');
// => 7

_some

@function _some($collection, $predicate: _identity, $this-arg: null) { ... }

Description

Checks if $predicate returns truthy for any element of $collection. The function returns as soon as it finds a passing value and does not iterate over the entire collection. The predicate is bound to $this-arg and invoked with three arguments; (value, index|key, collection).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

Boolean —

Returns true if any element passes the predicate check, else false.

Example

$foo: _some((null, 0, 'yes', false), _is-boolean);
// => true

$users: (
  ( 'user': 'barney', 'active': true ),
  ( 'user': 'fred',   'active': false )
);
// using the `_matches` callback shorthand

$foo: _some($users, ( 'user': 'barney', 'active': false ));
// => false

// using the `_matches-property` callback shorthand
$foo: _some($users, 'active', false);
// => true

// using the `_property` callback shorthand
$foo: _some($users, 'active');
// => true

_sort-by

@function _sort-by($collection, $iteratee: _identity, $this-arg: null) { ... }

Description

Creates a list of elements, sorted in ascending order by the results of running each element in a collection through $iteratee. This method performs a stable sort, that is, it preserves the original sort order of equal elements.

The $iteratee is bound to $this-arg and invoked with three arguments; (value, index|key, collection).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$iteratee

The function invoked per iteration. If a property name or a map is provided it is used to create a _property or _matches style callback respectively.

List or Function or Map or String_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

List —

Returns the new sorted list.

Example

$users: (
  ( 'user': 'fred' ),
  ( 'user': 'pebbles' ),
  ( 'user': 'barney' )
);
// using the `_property` callback shorthand
$foo: _pluck(_sort-by($users, 'user'), 'user');
// => ('barney', 'fred', 'pebbles')

_sort-by-all

@function _sort-by-all($collection, $props) { ... }

Description

This method is like _sort-by except that it sorts by property names instead of an iteratee function.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

List or Map or String—
$props

The property names to sort by, specified as individual property names or lists of property names.

String... or List(string)—

Returns

List —

Returns the new sorted list.

Example

$users: (
  ( 'user': 'barney', 'age': 36 ),
  ( 'user': 'fred',   'age': 40 ),
  ( 'user': 'barney', 'age': 26 ),
  ( 'user': 'fred',   'age': 30 )
);
$foo: _map(_sort-by-all($users, ('user', 'age')), _values);
// => (('barney', 26), ('barney', 36), ('fred', 30), ('fred', 40))

_where

@function _where($collection, $source) { ... }

Description

Performs a deep comparison between each element in $collection and the source map, returning a list of all elements that have equivalent property values.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to search.

List or Map or String—
$source

The map of property values to match.

Map—

Returns

List —

Returns the new filtered list.

Example

$users: (
  ( 'user': 'barney', 'age': 36, 'active': false, 'pets': ('hoppy',) ),
  ( 'user': 'fred',   'age': 40, 'active': true, 'pets': ('baby puss', 'dino') )
);
$foo: _pluck(_where($users, ( 'age': 36, 'active': false )), 'user');
// => ('barney',)
$foo: _pluck(_where($users, ( 'pets': ('dino',) )), 'user');
// => ('fred',)

function

functions

_after

@function _after($n, $func) { ... }

Description

The opposite of _before; this method creates a function that invokes $function once it is called $n or more times.

Parameters

NameDescriptionTypeDefault value
$n

The number of calls before $function is invoked.

Number—
$func

The function to restrict.

Function—

Returns

Function —

Returns the new restricted function.

Example

    @function warn-overuse() {
        @warn 'You are using this mixin too many times.';
    }

    $warn-overuse: _after(3, warn-overuse);

    @mixin my-mixin() {
        // ...
        $overuse: _exec($warn-overuse);
    }

    @each $selector in '.one', '.two', '.three', '.four' {
        @include my-mixin();
    }

_ary

@function _ary($func, $n: 1) { ... }

Description

Creates a function that accepts up to $n arguments ignoring any additional arguments.

Parameters

NameDescriptionTypeDefault value
$func

The function to cap arguments for.

Function—
$n

The arity cap.

Number1

Returns

Function —

Returns the new function.

Example

$foo: _map(('6', '8', '10'), _ary(_parse-int, 1));
// => (6, 8, 10)

_before

@function _before($n, $func) { ... }

Description

Creates a function that invokes $function, with the _this binding and arguments of the created function, while it is called less than $n times. Subsequent calls to the created function return the result of the last $function invocation.

Parameters

NameDescriptionTypeDefault value
$n

The number of calls at which $function is no longer invoked.

Number—
$func

The function to restrict.

Function—

Returns

Function —

Returns the new restricted function.

Example

    @function limit-mixin() { @return true; }

    $limit-mixin: _before(5, 'limit-mixin');

    @mixin my-mixin() {
        @if _exec($limit-mixin) {
            // ... include mixin
        } @else {
            @extend %placeholder; // extend after mixin used 4 times
        }
    }

_bind

@function _bind($func, $this-arg: null, $args...) { ... }

Description

Creates a function that invokes $func with the _this binding of $this-arg and prepends any additional _bind arguments to those provided to the bound function.

Parameters

NameDescriptionTypeDefault value
$func

The function to bind.

Function—
$this-arg

The _this binding of $func.

Anynull
$args...

The arguments to be partially applied.

Any...—

Returns

Function —

Returns the new bound function.

Example

    @function greet($greeting, $punctuation) {
        @return $greeting + ' ' + _this('user') + $punctuation;
    }
   
    $map: ('user': 'fred');
   
    $bound: _bind('greet', $map, 'hi');
   
    $result: _exec($bound, '!');
    // => 'hi fred!'

_exec

@function _exec($function, $args...) { ... }

Description

Dynamically calls a standard Sass function, similar to call($function, $args...), with the ability to call scoped functions, such as those returned from Sassdash functions like _bind(), _callback(), etc., that otherwise can't be called via call().

Parameters

NameDescriptionTypeDefault value
$function

The function/Sassdash callback to call.

Function—
$args...

The arguments to apply to the function.

Any...—

Returns

Any type —

Returns the result of calling $function with the given $args....

Example

$is-primary: _callback(('color': $color-primary));

$theme: (
    'name': 'sassdash-theme',
    'color': $color-primary
);

$foo: _exec($is-primary, $theme);
// => true

_flow

@function _flow($funcs) { ... }

Description

Creates a function that returns the result of invoking the provided functions with the _this binding of the created function, where each successive invocation is supplied the return value of the previous.

Parameters

NameDescriptionTypeDefault value
$funcs

Functions to invoke.

Function...—

Returns

Function —

Returns the new function.

Example

    @function add($x, $y) {
      @return $x + $y;
    }
    
    @function square($n) {
      @return $n * $n;
    }
    
    $addSquare: _flow(add, square);

    $foo: _exec($addSquare, 1, 2);
    // => 9

_flow-right

@function _flow-right($funcs...) { ... }

Description

This method is like _flow except that it creates a function that invokes the provided functions from right to left.

Parameters

NameDescriptionTypeDefault value
$funcs...

Functions to invoke.

Function...—

Returns

Function —

Returns the new function.

Example

    @function add($x, $y) {
      @return $x + $y;
    }
    
    @function square($n) {
      @return $n * $n;
    }
    
    $addSquare: _flow-right(square, add);
    $foo: _exec($addSquare, 1, 2);
    // => 9

_memoize

@function _memoize($func, $resolver: _identity) { ... }

Description

Creates a function that memoizes the result of $func. If $resolver is provided, it determines the cache key for storing the result based on the arguments provided to the memoized function. By default, the first argument provided to the memoized function is coerced to a string and used as the cache key. The $func is invoked with the _this binding of the memoized function.

Parameters

NameDescriptionTypeDefault value
$func

The function to have its output memoized.

Function—
$resolver

The function to resolve the cache key.

Function_identity

Returns

Function —

Returns the new memoizing function.

Example

$uppercase: _memoize(to-upper-case);

$foo: _exec($uppercase, 'fred');
// => 'FRED'

// modifying the result cache
$mod: _memo(to-upper-case, 'fred', 'BARNEY');
$foo: _exec($uppercase, 'fred');
// => 'BARNEY'

// using a `$resolver`
  @function greet($name) {
    @return 'Hello, ' + $name;
  }
  
  $greet-memoized: _memoize(greet, to-upper-case);
  
  $foo: _exec($greet-memoized, 'Fred');
  // => 'Hello, Fred'
  
  $foo: _exec($greet-memoized, 'FRED');
  // => 'Hello, Fred' (since 'Fred' and 'FRED' resolve to 'FRED');

_memo

@function _memo($context, $key: undefined, $value: undefined) { ... }

Description

Gets or sets a memo in the Sassdash memo cache, based on the $context where the memo is being queried from (usually a function).

Parameters

NameDescriptionTypeDefault value
$context

The memo context.

String or Function—
$key

The memo key to get or set.

Anyundefined
$value

The value to set the key in the memo context to, if provided.

Anyundefined

Returns

Any type —

Returns memo map if only context is provided, memo value if context and key are provided, and sets the memo and returns true if context, key, and value are provided.

Example

// todo

_negate

@function _negate($predicate) { ... }

Description

Creates a function that negates the result of the predicate $function. The $function predicate is invoked with the _this binding and arguments of the created function.

Parameters

NameDescriptionTypeDefault value
$predicate

The predicate to negate.

Function—

Returns

Function —

Returns the new function.

Example

    @function is-even($n, $args...) {
        @return $n % 2 == 0;
    }
    
    $foo: _filter((1, 2, 3, 4, 5, 6), _negate(is-even));
    // => (1, 3, 5)

_once

@function _once($func) { ... }

Description

Creates a function that is restricted to invoking $function once. Repeat calls to the function return the value of the first call. The $function is invoked with the _this binding of the created function.

Parameters

NameDescriptionTypeDefault value
$func

The function to restrict.

Function—

Returns

Function —

Returns the new restricted function.

Example

$lighten-once: _once(lighten);
$color: _exec($lighten-once, green, 10%);

color: $color; // lightened green

$color: _exec($lighten-once, blue, 20%);

color: $color; // null

_partial

@function _partial($func, $args...) { ... }

Description

Creates a function that invokes $function with partial arguments prepended to those provided to the new function. This method is like _bind except it does not alter the _this binding.

Parameters

NameDescriptionTypeDefault value
$func

The function to partially apply arguments to.

Function—
$args...

The arguments to be partially applied.

Any...—

Returns

Function —

Returns the new partially applied function.

Example

    @function greet($greeting, $name) {
        @return $greeting + ' ' + $name;
    }
    
    $say-hello-to: _partial(greet, 'hello');
    
    $foo: _exec($say-hello-to, 'fred');
    // => 'hello fred'

_partial-right

@function _partial-right($func, $args...) { ... }

Description

This method is like _partial except that partially applied arguments are appended to those provided to the new function.

Parameters

NameDescriptionTypeDefault value
$func

The function to partially apply arguments to.

Function—
$args...

The arguments to be partially applied.

Any...—

Returns

Function —

Returns the new partially applied function.

Example

    @function greet($greeting, $name) {
        @return $greeting + ' ' + $name;
    }
    
    $greet-with: _partial-right(greet, 'fred');
    
    $foo: _exec($greet-with, 'hi');
    // => 'hi fred'

lang

functions

_lt

@function _lt($value, $other) { ... }

Description

Checks if $value is less than $other.

Parameters

NameDescriptionTypeDefault value
$value

The value to compare.

Number or String—
$other

The other value to compare.

Number or String—

Returns

Bool —

Returns true if $value is less than $other, else false.

Example

$foo: _lt(1, 3);
// => true

$foo: _lt(3, 1);
// => false

$foo: _lt(3, 3);
// => false

$foo: _lt('abc', 'def');
// => true

$foo: _lt('def', 'abc');
// => false
 
$foo: _lt('def', 'def');
// => false

_lte

@function _lte($value, $other) { ... }

Description

Checks if $value is less than or equal to $other.

Parameters

NameDescriptionTypeDefault value
$value

The value to compare.

Number or String—
$other

The other value to compare.

Number or String—

Returns

Bool —

Returns true if $value is less than or equal to $other, else false.

Example

$foo: _lte(1, 3);
// => true

$foo: _lte(3, 1);
// => false

$foo: _lte(3, 3);
// => true

$foo: _lte('abc', 'def');
// => true

$foo: _lte('def', 'abc');
// => false

$foo: _lte('def', 'def');
// => true

_gt

@function _gt($value, $other) { ... }

Description

Checks if $value is greater than $other.

Parameters

NameDescriptionTypeDefault value
$value

The value to compare.

Number or String—
$other

The other value to compare.

Number or String—

Returns

Bool —

Returns true if $value is greater than $other, else false.

Example

$foo: _gt(1, 3);
// => false

$foo: _gt(3, 1);
// => true

$foo: _gt(3, 3);
// => false

$foo: _gt('abc', 'def');
// => false

$foo: _gt('def', 'abc');
// => true

$foo: _gt('def', 'def');
// => false

_gte

@function _gte($value, $other) { ... }

Description

Checks if $value is greater than or equal to $other.

Parameters

NameDescriptionTypeDefault value
$value

The value to compare.

Number or String—
$other

The other value to compare.

Number or String—

Returns

Bool —

Returns true if $value is greater than or equal to $other, else false.

Example

$foo: _gte(1, 3);
// => false

$foo: _gte(3, 1);
// => true

$foo: _gte(3, 3);
// => true

$foo: _gte('abc', 'def');
// => false

$foo: _gte('def', 'abc');
// => true

$foo: _gte('def', 'def');
// => true

_is-empty

@function _is-empty($value) { ... }

Description

Checks if a value is empty.

Parameters

NameDescriptionTypeDefault value
$value

The value to inspect.

List or Map or String—

Returns

Boolean —

Returns true if $value is empty, else false.

Example

$foo: _is-empty(null);
// => true

$foo: _is-empty(true);
// => true

$foo: _is-empty(1);
// => true

$foo: _is-empty((1, 2, 3));
// => false

$foo: _is-empty(( 'a': 1 ));
// => false

_is-equal

@function _is-equal($value, $other, $customizer: null, $this-arg: null) { ... }

Description

Performs a deep comparison between two values to determine if they are equivalent. If $customizer is provided it is invoked to compare values. If $customizer returns undefined comparisons are handled by the method instead. The $customizer is bound to $this-arg and invoked with three arguments; (value, other, (index|key)).

Parameters

NameDescriptionTypeDefault value
$value

The value to compare.

Any—
$other

The other value to compare.

Any—
$customizer

The function to customize comparing values.

Functionnull
$this-arg

The _this binding of $customizer.

Anynull

Returns

Boolean —

Returns true if the values are equivalent, else false.

Example

    $object: ( 'user': 'fred' );
    $other: ( 'user': 'fred' );
    $foo: _is-equal($object, $other);
    // => true
    
    // using a customizer callback
    // todo

_is-match

@function _is-match($map, $source, $customizer: null, $this-arg: null) { ... }

Description

Performs a deep comparison between $map and source to determine if $map contains equivalent property values. If $customizer is provided it is invoked to compare values. If $customizer returns undefined comparisons are handled by the method instead. The $customizer is bound to $this-arg and invoked with three arguments; (value, other, index|key).

Parameters

NameDescriptionTypeDefault value
$map

The map to inspect.

Map—
$source

The map of property values to match.

Map—
$customizer

The function to customize comparing values.

Functionnull
$this-arg

The _this binding of $customizer.

Anynull

Returns

Boolean —

Returns true if $map is a match, else false.

Example

$map: ( 'user': 'fred', 'age': 40 );

_is-match($map, ( 'age': 40 ));
// => true

_is-match($map, ( 'age': 36 ));
// => false

// using a customizer callback
// todo

_is-arglist

@function _is-arglist($value) { ... }

Description

Checks if $value is an Arglist.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is an Arglist, else false.

Example

    @function get-args($args...) {
        @return $args;
    }
    
    $foo: _is-arglist(get-args(1, 2, 3));
    // => true
    
    $foo: _is-arglist((1, 2, 3));
    // => false

_is-list

@function _is-list($value) { ... }

Description

Checks if $value is a List.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is a List, else false.

Example

    
$foo: _is-list(1 2 3);
// => true

$foo: _is-list((1, 2, 3));
// => true

_is-boolean

@function _is-boolean($value) { ... }

Description

Checks if $value is a Boolean.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is a Boolean, else false.

Example

    
$foo: _is-boolean(false);
// => true

$foo: _is-boolean(1 + 1 == 2);
// => true

$foo: _is-boolean(null);
// => false

_is-function

@function _is-function($value) { ... }

Description

Checks if $value is a standard Sass Function or a Sassdash callback Function.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is a Function, else false.

Example

    
$foo: _is-function('lighten');
// => true

$foo: _is-function(_partial('lighten', #C0FF33));
// => true

$foo: _is-function('not-a-function');
// => false

_is-null

@function _is-null($value) { ... }

Description

Checks if $value is null.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is null, else false.

Example

    
$foo: _is-null(null);
// => true

$foo: _is-null(map-get(('a': 1), 'b'));
// => true

$foo: _is-null(false);
// => false

_is-number

@function _is-number($value) { ... }

Description

Checks if $value is a Number.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is a Number, else false.

Example

    
$foo: _is-number(30);
// => true

$foo: _is-number('30');
// => false

_is-integer

@function _is-integer($value) { ... }

Description

Checks if $value is an integer number.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is an integer number, else false.

Example

    
$foo: _is-integer(31);
// => true

$foo: _is-integer('31');
// => false

$foo: _is-integer(31.25);
// => false

_is-map

@function _is-map($value) { ... }

Description

Checks if $value is a Map.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is a Map, else false.

Example

    
$foo: _is-map(('a': 1));
// => true

$foo: _is-map(('a', 1));
// => false

_is-plain-map

@function _is-plain-map($value) { ... }

Description

Checks if $value is a plain Map, not from a constructor.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is a plain Map, else false.

Example

// todo

_is-string

@function _is-string($value) { ... }

Description

Checks if $value is a String.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is a String, else false.

Example

    
$foo: _is-string('hello');
// => true

$foo: _is-string(hello);
// => true

$foo: _is-string(31);
// => false

_is-undefined

@function _is-undefined($value) { ... }

Description

Checks if $value is the Sassdash undefined value. Using undefined ($__undefined__) can be useful in distinguishing between null and undefined values.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is undefined, else false.

Example

// todo

_is-iterable

@function _is-iterable($value) { ... }

Description

Checks if $value is iterable. A value in Sassdash is considered iterable if it contains a distinct set of elements and acts as a container for these elements - i.e. a Map, List, Arglist, or String.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is iterable, else false.

Example

    
$foo: _is-iterable('hello');
// => true

$foo: _is-iterable(1 2 3 4);
// => true

$foo: _is-iterable(('a': 1, 'b': 2));
// => true

$foo: _is-iterable(1234);
// => false

_is-map-like

@function _is-map-like($value) { ... }

Description

Checks if $value is similar to a Map, in that it has (implicit or explicit) keys bijectively paired with values. In Sassdash, a Map, List, or Arglist can be considered map-like.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is similar to a Map, else false.

Example

    
$foo: _is-map-like(1 2 3 4);
// => true

$foo: _is-map-like(('a': 1, 'b': 2));
// => true

$foo: _is-map-like('1234');
// => false

_is-list-like

@function _is-list-like($value) { ... }

Description

Checks if $value is a List or Arglist.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is a List or Arglist, else false.

Example

    
$foo: _is-list-like((1, 2));
// => true

_is-color

@function _is-color($value) { ... }

Description

Checks if $value is a Color.

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if $value is a Color, else false.

Example

    
$foo: _is-color($C0FF33);
// => true

$foo: _is-color(green);
// => true

$foo: _is-color('green');
// => false

_is-time

@function _is-time($value) { ... }

Description

Checks if $value is a Time value (i.e. seconds or milliseconds).

Parameters

NameDescriptionTypeDefault value
$value

The value to check.

Any—

Returns

Boolean —

Returns true if unit of numerical $value is 's' or 'ms', else false.

Example

$foo: _is-time(13s);
// => true

$foo: _is-time(0.3ms);
// => true

$foo: _is-time('13s');
// => false

_to-list

@function _to-list($value) { ... }

Description

Converts $value to a list.

Parameters

NameDescriptionTypeDefault value
$value

The value to convert.

Any—

Returns

List —

Returns the converted list.

Example

$map: ('a': 1, 'b': 2, 'c': 3);

$foo: _to-list($map);
// => 1, 2, 3

_to-string

@function _to-string($value) { ... }

Description

Converts $value to a string.

Parameters

NameDescriptionTypeDefault value
$value

The value to convert.

Any—

Returns

String —

Returns the converted string.

Example

$foo: _to-string(123);
// => '123'

_to-map

@function _to-map($value) { ... }

Description

Converts $value to a map.

If the value is a list, the map keys represent the list indexes and the values represent the corresponding list values.

If the value is a string, the string is first coerced to a list, with with each index representing the index of each character in the string.

If the value is not list-like, an empty map is returned.

Parameters

NameDescriptionTypeDefault value
$value

The value to convert.

Any—

Returns

Map —

Returns the converted map.

Example

$list: 100, 200, 300;
$string: 'abc';
$number: 3;

$foo: _to-map($list);
// => (1: 100, 2: 200, 3: 300);

$foo: _to-map($string)
// => (1: 'a', 2: 'b', 3: 'c')

$foo: _to-map($number)
// => ()

list

functions

_chunk

@function _chunk($list, $size: 1) { ... }

Description

Creates a list of elements split into groups the length of $size. If $collection can't be split evenly, the final chunk will be the remaining elements.

Parameters

NameDescriptionTypeDefault value
$list

The list to process.

List—
$size

The length of each chunk.

Number1

Returns

List —

Returns the new list containing chunks.

Example

$foo: _chunk(('a', 'b', 'c', 'd'), 2);
// => (('a', 'b'), ('c', 'd'))

$foo: _chunk(('a', 'b', 'c', 'd'), 3);
// => (('a', 'b', 'c'), ('d',))

_compact

@function _compact($list) { ... }

Description

Creates a list with all falsey values removed. The values false, null, 0, and "" are considered falsey.

Parameters

NameDescriptionTypeDefault value
$list

The list to compact.

List—

Returns

List —

Returns the new list of filtered values.

Example

$foo: _compact((0, 1, false, 2, '', 3));
// => (1, 2, 3)

_concat

@function _concat($source, $args...) { ... }

Description

Returns a new list comprised of the $source list joined with the list(s) and/or value(s) provided as arguments.

The separator of the returned list will be the same as the separator of the $source list.

Parameters

NameDescriptionTypeDefault value
$source

The initial list

List—
$args...

Lists and/or values to concatenate into the source list.

List... or *...—

Returns

List —

Returns a new list of concatenated lists/values.

Example

$foo: _concat(1 2, 3 4);
// => (1 2 3 4)

$foo: _concat(1 2, 3, 4);
// => (1 2 3 4)

_difference

@function _difference($list, $values...) { ... }

Description

Creates a list excluding all values of the provided lists.

Parameters

NameDescriptionTypeDefault value
$list

The list to inspect.

List—
$values...

The lists of values to exclude.

List...—

Returns

List —

Returns the new list of filtered values.

Example

$foo: _difference((1, 2, 3), (4, 2));
// => (1, 3)

_drop

@function _drop($list, $n: 1) { ... }

Description

Creates a slice of $list with $n elements dropped from the beginning.

Parameters

NameDescriptionTypeDefault value
$list

The list to query.

List—
$n

The number of elements to drop.

Number1

Returns

List —

Returns the slice of $list.

Example

$foo: _drop((1, 2, 3));
// => (2, 3)

$foo: _drop((1, 2, 3), 2);
// => (3,)

$foo: _drop((1, 2, 3), 5);
// => ()

$foo: _drop((1, 2, 3), 0);
// => (1, 2, 3)

_drop-right

@function _drop-right($list, $n: 1) { ... }

Description

Creates a slice of $list with $n elements dropped from the end.

Parameters

NameDescriptionTypeDefault value
$list

The list to query.

List—
$n

The number of elements to drop.

Number1

Returns

List —

Returns the slice of $list.

Example

$foo: _drop-right((1, 2, 3));
// => (1, 2)

$foo: _drop-right((1, 2, 3), 2);
// => (1,)

$foo: _drop-right((1, 2, 3), 5);
// => ()

$foo: _drop-right((1, 2, 3), 0);
// => (1, 2, 3)

_drop-right-while

@function _drop-right-while($list, $predicate: _identity, $this-arg: null) { ... }

Description

Creates a slice of $list excluding elements dropped from the end. Elements are dropped until $predicate returns falsey. The predicate is bound to $this-arg and invoked with three arguments; (value, index, list).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element. If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that match the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$list

The list to query.

List—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

List —

Returns the slice of $list.

Example

    @function greater-than-two($value, $args...) {
        @return $value > 2;
    }
    
    $foo: _drop-right-while((1, 2, 3, 4), greater-than-two);
    // => (1, 2)
    
    $users: (
      ( 'user': 'barney',  'active': true ),
      ( 'user': 'fred',    'active': false ),
      ( 'user': 'pebbles', 'active': false )
    );
    
    // using the `_matches` callback shorthand
    $foo: _pluck(_drop-right-while($users, ( 'user': 'pebbles', 'active': false )), 'user');
    // => ('barney', 'fred')
    
    // using the `_matches-property` callback shorthand
    $foo: _pluck(_drop-right-while($users, 'active', false), 'user');
    // => ('barney')
    
    // using the `_property` callback shorthand
    $foo: _pluck(_drop-right-while($users, 'active'), 'user');
    // => ('barney', 'fred', 'pebbles')

_drop-while

@function _drop-while($list, $predicate: _identity, $this-arg: null) { ... }

Description

Creates a slice of $list excluding elements dropped from the beginning. Elements are dropped until $predicate returns falsey. The predicate is bound to $this-arg and invoked with three arguments; (value, index, list). If a property name is provided for $predicate the created _property style callback returns the property value of the given element. If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false. If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$list

The list to query.

List—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

List —

Returns the slice of $list.

Example

    @function less-than-three($value, $args...) {
        @return $value < 3;
    }
    
    $foo: _drop-while((1, 2, 3, 4), less-than-three);
    // => (3, 4)
    
    $users: (
      ( 'user': 'barney',  'active': false ),
      ( 'user': 'fred',    'active': false ),
      ( 'user': 'pebbles', 'active': true )
    );
    
    // using the `_matches` callback shorthand
    $foo: _pluck(_drop-while($users, ( 'user': 'barney', 'active': false )), 'user');
    // => ('fred', 'pebbles')
    
    // using the `_matches-property` callback shorthand
    $foo: _pluck(_drop-while($users, 'active', false), 'user');
    // => ('pebbles')
    
    // using the `_property` callback shorthand
    $foo: _pluck(_drop-while($users, 'active'), 'user');
    // => ('barney', 'fred', 'pebbles')

_fill

@function _fill($list, $value: null, $start: 1, $end: length($list)) { ... }

Description

Fills elements of $list with $value from $start up to, but not including, $end. Returns new list.

Parameters

NameDescriptionTypeDefault value
$list

The list to fill.

List—
$value

The value to fill $list with.

Anynull
$start

The start position.

Number1
$end

The end position.

Numberlength($list)

Returns

List —

Returns new list with filled values.

Example

$list: 1 2 3;

$foo: _fill($list, 'a');
// => 'a' 'a' 'a'

$foo: _fill($list, 'a', 2);
// => 1 'a' 'a'

_find-index

@function _find-index($list, $predicate: _identity, $this-arg: null) { ... }

Description

This method is like _find except that it returns the index of the first element $predicate returns truthy for, instead of the element itself.

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given map, else false.

Parameters

NameDescriptionTypeDefault value
$list

The list to search.

List—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

Number —

Returns the index of the found element, else -1.

Example

    $users: (
      ( 'user': 'barney',  'active': false ),
      ( 'user': 'fred',    'active': false ),
      ( 'user': 'pebbles', 'active': true )
    );
    
    @function is-barney($user, $args...) {
        @return _get($user, 'user') == 'barney';
    }
        
    $foo: _find-index($users, is-barney);
    // => 1
    
    // using the `_matches` callback shorthand
    $foo: _find-index($users, ( 'user': 'fred', 'active': false ));
    // => 2
    // using the `_matches-property` callback shorthand
    $foo: _find-index($users, 'active', false);
    // => 1
    
    // using the `_property` callback shorthand
    $foo: _find-index($users, 'active');
    // => 3

_find-last-index

@function _find-last-index($list, $predicate: _identity, $this-arg: null) { ... }

Description

This method is like _find-index except that it iterates over elements of $collection from right to left.

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given map, else false.

Parameters

NameDescriptionTypeDefault value
$list

The list to search.

List—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

Number —

Returns the index of the found element, else -1.

Example

    $users: (
      ( 'user': 'barney',  'active': true ),
      ( 'user': 'fred',    'active': false ),
      ( 'user': 'pebbles', 'active': false )
    );

    @function is-pebbles($chr, $args...) {
        @return _get($chr, 'user') == 'pebbles';
    }

    $foo: _find-last-index($users, is-pebbles);
    // => 3
    
    // using the `_matches` callback shorthand
    $foo: _find-last-index($users, ( 'user': 'barney', 'active': true ));
    // => 1
    
    // using the `_matches-property` callback shorthand
    $foo: _find-last-index($users, 'active', false);
    // => 2
    
    // using the `_property` callback shorthand
    $foo: _find-last-index($users, 'active');
    // => 1

_first

@function _first($list) { ... }

Description

Gets the first element of $list.

Parameters

NameDescriptionTypeDefault value
$list

The list to query.

List—

Returns

Any type —

Returns the first element of $list.

Example

$foo: _first((1, 2, 3));
// => 1

$foo: _first(());
// => null

_flatten

@function _flatten($list, $is-deep: false) { ... }

Description

Flattens a nested list. If $is-deep is true the list is recursively flattened, otherwise it is only flattened a single level.

Parameters

NameDescriptionTypeDefault value
$list

The list to flatten.

List—
$is-deep

Specify a deep flatten.

Booleanfalse

Returns

List —

Returns the new flattened list.

Example

$foo: _flatten((1, (2, 3, (4,))));
// => (1, 2, 3, (4,));

// using `$is-deep`
$foo: _flatten((1, (2, 3, (4,))), true);
// => (1, 2, 3, 4);

_flatten-deep

@function _flatten-deep($list) { ... }

Description

Recursively flattens a nested list.

Parameters

NameDescriptionTypeDefault value
$list

The list to recursively flatten.

List—

Returns

List —

Returns the new flattened list.

Example

$foo: _flatten-deep((1, (2, 3, (4,))));
// => (1, 2, 3, 4);

_index-of

@function _index-of($list, $value, $from-index: 1) { ... }

Description

Gets the index at which the first occurrence of $value is found in $list. If $from-index is negative, it is used as the offset from the end of $list. If $list is sorted providing true for $from-index performs a faster binary search.

Parameters

NameDescriptionTypeDefault value
$list

The list to search.

List—
$value

The value to search for.

Any—
$from-index

The index to search from or true to perform a binary search on a sorted list.

Boolean or Number1

Returns

Number —

Returns the index of the matched value, else -1.

Example

$foo: _index-of((1, 2, 1, 2), 2);
// => 2

// using `$from-index`
$foo: _index-of((1, 2, 1, 2), 2, 3);
// => 4

// performing a binary search
$foo: _index-of((1, 1, 2, 2), 3, true);
// => 3

_last-index-of

@function _last-index-of($list, $value, $from-index: length($list)) { ... }

Description

This method is like _index-of except that it iterates over elements of $list from right to left.

Parameters

NameDescriptionTypeDefault value
$list

The list to search.

List—
$value

The value to search for.

Any—
$from-index

The index to search from or true to perform a binary search on a sorted list.

Boolean or Numberlength($list)

Returns

Number —

Returns the index of the matched value, else -1.

Example

$foo: _last-index-of((1, 2, 1, 2), 2);
// => 4

// using `$from-index`
$foo: _last-index-of((1, 2, 1, 2), 2, 2);
// => 2

// performing a binary search
$foo: _last-index-of((1, 1, 2, 2), 2, true);
// => 4

_initial

@function _initial($list) { ... }

Description

Gets all but the last element of $list.

Parameters

NameDescriptionTypeDefault value
$list

The list to query.

List—

Returns

List —

Returns the slice of $list.

Example

_initial((1, 2, 3));
// => (1, 2)

_intersection

@function _intersection($lists...) { ... }

Description

Creates a list of unique values in all provided lists for equality comparisons.

Parameters

NameDescriptionTypeDefault value
$lists...

The lists to inspect.

List...—

Returns

List —

Returns the new list of shared values.

Example

$foo: _intersection((1, 2), (4, 2), (2, 1));
// => (2,)

_join

@function _join($list, $separator: '') { ... }

Description

Joins a single list into a string, similar to the native JavaScript Array.prototype.join().

NOTE: This is not the same as the native Sass join() function.

Parameters

NameDescriptionTypeDefault value
$list

The list containing elements to join.

List—
$separator

The string separator.

String''

Returns

String —

Returns the joined list as a string.

Example

$foo: _join('a' 'b' 'c', '--');
// => 'a--b--c'

_last

@function _last($list) { ... }

Description

Gets the last element of $list.

Parameters

NameDescriptionTypeDefault value
$list

The list to query.

List—

Returns

Any type —

Returns the last element of $list.

Example

$foo: _last((1, 2, 3));
// => 3

_pull

@function _pull($list, $values...) { ... }

Description

Removes all provided values from $list, and returns a new list without the provided values. Does not mutate original list.

Parameters

NameDescriptionTypeDefault value
$list

The source list.

List—
$values...

The values to remove.

Any...—

Returns

List —

Returns new $list with removed values.

Example

$list: (1, 2, 3, 1, 2, 3);
$foo: _pull(list, 2, 3);
// => (1, 1)

_push

@function _push($list, $items...) { ... }

Description

Adds one or more elements to the end of a $list and returns a new list with appended items.

Similar to native Sass join(), with the exception that no $separator is specified and arguments after the first one are treated as elements to be appended to $list.

Parameters

NameDescriptionTypeDefault value
$list

The target list.

List—
$items...

The items to append to $list.

Any...—

Returns

List —

Returns list with appended items.

Example

// todo

_rest

@function _rest($list) { ... }

Description

Gets all but the first element of $list.

Parameters

NameDescriptionTypeDefault value
$list

The list to query.

List—

Returns

List —

Returns the slice of $list.

Example

$foo: _rest((1, 2, 3));
// => (2, 3)

_reverse

@function _reverse($value) { ... }

Description

Reverses a $list or $string. The first element/character of the list/string becomes the last, and vice versa.

Parameters

NameDescriptionTypeDefault value
$value

The value to reverse.

List or String—

Returns

List or String —

Returns reversed $value.

Example

$foo: _reverse(1 2 3);
// => 3 2 1

$foo: _reverse('abc');
// => 'cba'

_str-reverse

@function _str-reverse($string) { ... }

Description

Reverses a $string. The first character of the string becomes the last, and vice versa.

Parameters

NameDescriptionTypeDefault value
$string

The string to reverse.

String—

Returns

String —

Returns reversed $string.

Example

$foo: _str-reverse('abc');
// => 'cba'

_slice

@function _slice($list, $start: 0, $end: length($list)) { ... }

Description

Creates a slice of $list from $start up to, but not including, $end.

Parameters

NameDescriptionTypeDefault value
$list

The list to slice.

List—
$start

The start position.

Number0
$end

The end position.

Numberlength($list)

Returns

List —

Returns the slice of $list.

Example

// todo

_sort

@function _sort($list, $predicate: 'asc') { ... }

Description

Sorts elements of a list by $predicate and returns a new list with the sorted elements.

Parameters

NameDescriptionTypeDefault value
$list

The list to sort.

List—
$predicate

The predicate used for comparison.

Function or String'asc'

Returns

List —

Returns sorted list.

Example

$foo: _sort(3 1 4 2 6 5 8 7 9);
// => 1 2 3 4 5 6 7 8 9

$foo: _sort(3 1 4 2 6 5 8 7 9, 'desc');
// => 9 8 7 6 5 4 3 2 1

_sorted-index

@function _sorted-index($list, $value, $iteratee: _identity, $this-arg: NULL) { ... }

Description

Uses a binary search to determine the lowest index at which $value should be inserted into $list in order to maintain its sort order. If an iteratee function is provided it is invoked for $value and each element of $list to compute their sort ranking. The iteratee is bound to $this-arg and invoked with one argument; (value).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$list

The sorted list to inspect.

List—
$value

The value to evaluate.

Any—
$iteratee

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $iteratee.

AnyNULL

Returns

Number —

Returns the index at which $value should be inserted into $list.

Example

$foo: _sorted-index((30, 50), 40);
// => 2

$foo: _sorted-index((4, 4, 5, 5), 5);
// => 3

$dict: { 'data': { 'thirty': 30, 'forty': 40, 'fifty': 50 } };

// using the `_property` callback shorthand
$foo: _sorted-index((( 'x': 30 ), ( 'x': 50 )), ( 'x': 40 ), 'x');
// => 2

_sorted-last-index

@function _sorted-last-index($list, $value, $iteratee: _identity, $this-arg: null) { ... }

Description

This method is like _sorted-index except that it returns the highest index at which $value should be inserted into $list in order to maintain its sort order.

Parameters

NameDescriptionTypeDefault value
$list

The sorted list to inspect.

List—
$value

The value to evaluate.

Any—
$iteratee

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Number —

Returns the index at which $value should be inserted into $list.

Example

$foo: _sorted-last-index((4, 4, 5, 5), 5);
// => 5

_splice

@function _splice($list, $start, $delete-count: 1, $items...) { ... }

Description

Removes items from a $list and adds new items in their place. Similar to the native JavaScript splice() function.

Parameters

NameDescriptionTypeDefault value
$list

List to splice.

List—
$start

Index to start changing the list.

Number—
$delete-count

Number of list items to remove.

Number1
$items...

Items to add to the lsit.

Any...—

Example

$margin: 10px 3px 5px 20px;

$margin: _splice($margin, 2, 2, 15px);
// => 10px 15px 20px

_take

@function _take($list, $n: 1) { ... }

Description

Creates a slice of $list with $n elements taken from the beginning.

Parameters

NameDescriptionTypeDefault value
$list

The list to query.

List—
$n

The number of elements to take.

Number1

Returns

List —

Returns the slice of $list.

Example

$foo: _take((1, 2, 3));
// => (1,)
$foo: _take((1, 2, 3), 2);
// => (1, 2)
$foo: _take((1, 2, 3), 5);
// => (1, 2, 3)
$foo: _take((1, 2, 3), 0);
// => ()

_take-right

@function _take-right($list, $n: 1) { ... }

Description

Creates a slice of $list with $n elements taken from the end.

Parameters

NameDescriptionTypeDefault value
$list

The list to query.

List—
$n

The number of elements to take.

Number1

Returns

List —

Returns the slice of $list.

Example

$foo: _take-right((1, 2, 3));
// => (3,)
$foo: _take-right((1, 2, 3), 2);
// => (2, 3)
$foo: _take-right((1, 2, 3), 5);
// => (1, 2, 3)
$foo: _take-right((1, 2, 3), 0);
// => ()

_take-right-while

@function _take-right-while($list, $predicate: _identity, $this-arg: null) { ... }

Description

Creates a slice of $list with elements taken from the end. Elements are taken until $predicate returns falsey. The predicate is bound to $this-arg and invoked with three arguments; (value, index, list).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$list

The list to query.

List—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

List —

Returns the slice of $list.

Example

$users: (
  ( 'user': 'barney',  'active': true ),
  ( 'user': 'fred',    'active': false ),
  ( 'user': 'pebbles', 'active': false )
);

// using the `_matches` callback shorthand
$foo: _pluck(_take-right-while($users, ( 'user': 'pebbles', 'active': false )), 'user');
// => ('pebbles',)

// using the `_matches-property` callback shorthand
$foo: _pluck(_take-right-while($users, 'active', false), 'user');
// => ('fred', 'pebbles')

// using the `_property` callback shorthand
$foo: _pluck(_take-right-while($users, 'active'), 'user');
// => ()

_take-while

@function _take-while($list, $predicate: _identity, $this-arg: null) { ... }

Description

Creates a slice of $list with elements taken from the beginning. Elements are taken until $predicate returns falsey. The predicate is bound to $this-arg and invoked with three arguments; (value, index, list).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$list

The list to query.

List—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

List —

Returns the slice of $list.

Example

$users: (
  ( 'user': 'barney',  'active': false ),
  ( 'user': 'fred',    'active': false ),
  ( 'user': 'pebbles', 'active': true )
);
// using the `_matches` callback shorthand
$foo: _pluck(_take-while($users, ( 'user': 'barney', 'active': false )), 'user');
// => ('barney',)

// using the `_matches-property` callback shorthand
$foo: _pluck(_take-while($users, 'active', false), 'user');
// => ('barney', 'fred')

// using the `_property` callback shorthand
$foo: _pluck(_take-while($users, 'active'), 'user');
// => ()

_union

@function _union($lists...) { ... }

Description

Creates a list of unique values, in order.

Parameters

NameDescriptionTypeDefault value
$lists...

The lists to inspect.

List...—

Returns

List —

Returns the new list of combined values.

Example

$foo: _union((1, 2), (4, 2), (2, 1));
// => (1, 2, 4)

_uniq

@function _uniq($list, $iteratee: _identity, $this-arg: null) { ... }

Description

Creates a duplicate-value-free version of a list.

If an iteratee function is provided it is invoked for each value in the list to generate the criterion by which uniqueness is computed. The $iteratee is bound to $this-arg and invoked with three arguments; (value, index, list).

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given object, else false.

Parameters

NameDescriptionTypeDefault value
$list

The list to inspect.

List—
$iteratee

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

List —

Returns the new duplicate-value-free list.

Example

$foo: _uniq((1, 2, 1));
// => (1, 2)

// using an iteratee function
$foo: _uniq((1, 2.5, 1.5, 2), floor);
// => (1, 2.5)

// using the `_property` callback shorthand
$foo: _uniq((( 'x': 1 ), ( 'x': 2 ), ( 'x': 1 )), 'x');
// => (( 'x': 1 ), ( 'x': 2 ))

_unzip

@function _unzip($list) { ... }

Description

This method is like _zip except that it accepts a list of grouped elements and creates a list regrouping the elements to their pre-_zip configuration.

Parameters

NameDescriptionTypeDefault value
$list

The list of grouped elements to process.

List—

Returns

List —

Returns the new list of regrouped elements.

Example

$zipped: _zip(('fred', 'barney'), (30, 40), (true, false));
// => (('fred', 30, true), ('barney', 40, false))

$unzipped: _unzip($zipped);
// => (('fred', 'barney'), (30, 40), (true, false))

_without

@function _without($list, $values...) { ... }

Description

Creates a list excluding all provided values.

Parameters

NameDescriptionTypeDefault value
$list

The list to filter.

List—
$values...

The values to exclude.

Any...—

Returns

List —

Returns the new list of filtered values.

Example

$foo: _without((1, 2, 1, 3), 1, 2);
// => (3,)

_xor

@function _xor($lists) { ... }

Description

Creates a list that is the symmetric difference of the provided lists. See Wikipedia for more details.

Parameters

NameDescriptionTypeDefault value
$lists

The lists to inspect.

List...—

Returns

List —

Returns the new list of values.

Example

$foo: _xor((1, 2), (4, 2));
// => (1, 4)

_zip

@function _zip($lists...) { ... }

Description

Creates a list of grouped elements, the first of which contains the first elements of the given lists, the second of which contains the second elements of the given lists, and so on.

Parameters

NameDescriptionTypeDefault value
$lists...

The lists to process.

List...—

Returns

List —

Returns the new list of grouped elements.

Example

$foo: _zip(('fred', 'barney'), (30, 40), (true, false));
// => (('fred', 30, true), ('barney', 40, false))

_zip-map

@function _zip-map($props, $values: ()) { ... }

Description

Creates a map composed from lists of property names and values. Provide either a single two dimensional list, e.g. (($key1, $value1), ($key2, $value2)) or two lists, one of property names and one of corresponding values.

Parameters

NameDescriptionTypeDefault value
$props

The property names.

List—
$values

The property values.

List()

Returns

Map —

Returns the new map.

Example

$foo: _zip-map(('fred', 'barney'), (30, 40));
// => ( 'fred': 30, 'barney': 40 )

map

functions

_assign

@function _assign($map, $sources..., $customizer: false, $this-arg: null) { ... }

Description

Assigns own enumerable properties of source map(s) to the destination map. Subsequent sources overwrite property assignments of previous sources. If $customizer is provided it is invoked to produce the assigned values. The $customizer is bound to $this-arg and invoked with five arguments; ($map-value, $map-value, $key, $map, $source).

Parameters

NameDescriptionTypeDefault value
$map

The destination map.

Map—
$sources...

The source maps.

Map...—
$customizer

The function to customize assigning values.

Functionfalse
$this-arg

The _this binding of $customizer.

Anynull

Returns

Map —

Returns map.

Example

_assign(( 'user': 'barney' ), ( 'age': 40 ), ( 'user': 'fred' ));
// => ( 'user': 'fred', 'age': 40 )

// using a customizer callback
$defaults: _partial-right(_assign, _either);
_exec($defaults, (( 'user': 'barney' ), ( 'age': 36 ), ( 'user': 'fred' )));
// => ( 'user': 'barney', 'age': 36 )

_create

@function _create($prototype, $properties: null) { ... }

Description

Creates a map that inherits from the given $prototype map. If a $properties map is provided its own enumerable properties are assigned to the created map.

Parameters

NameDescriptionTypeDefault value
$prototype

The map to inherit from.

Map—
$properties

The properties to assign to the map.

Mapnull

Returns

Map —

Returns the new map.

Example

// todo

_defaults

@function _defaults($map, $source...) { ... }

Description

Assigns own enumerable properties of source map(s) to the destination map for all undefined destination properties. Once a property is set, additional defaults of the same property are ignored.

Parameters

NameDescriptionTypeDefault value
$map

The destination map.

Map—
$source...

The source maps.

Map...—

Returns

Map —

Returns $map with defaults.

Example

$foo: _defaults(( 'user': 'barney' ), ( 'age': 36 ), ( 'user': 'fred' ));
// => ( 'user': 'barney', 'age': 36 )

_find-key

@function _find-key($map, $predicate: _identity, $this-arg: null) { ... }

Description

This method is like _find-index except that it returns the key of the first element $predicate returns truthy for, instead of the element itself.

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given map, else false.

Parameters

NameDescriptionTypeDefault value
$map

The map to search.

Map—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

String or Null —

Returns the key of the matched element, else null.

Example

    $users: (
      'barney':  ( 'age': 36, 'active': true ),
      'fred':    ( 'age': 40, 'active': false ),
      'pebbles': ( 'age': 1,  'active': true )
    );

    @function under-40($chr, $args...) {
        @return _get($chr, 'age') < 40;
    }
    
    $foo: _find-key($users, under-40)
    // => 'barney'
    
    // using the `_matches` callback shorthand
    $foo: _find-key($users, ( 'age': 1, 'active': true ));
    // => 'pebbles'
    
    // using the `_matches-property` callback shorthand
    $foo: _find-key($users, 'active', false);
    // => 'fred'
    
    // using the `_property` callback shorthand
    $foo: _find-key($users, 'active');
    // => 'barney'

_find-last-key

@function _find-last-key($map, $predicate: _identity, $this-arg: null) { ... }

Description

This method is like _find-key except that it iterates over elements of a collection in the opposite order.

If a property name is provided for $predicate the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $predicate the created _matches style callback returns true for elements that have the properties of the given map, else false.

Parameters

NameDescriptionTypeDefault value
$map

The map to search.

Map—
$predicate

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

String or Null —

Returns the key of the matched element, else null.

Example

    $users: (
      'barney':  ( 'age': 36, 'active': true ),
      'fred':    ( 'age': 40, 'active': false ),
      'pebbles': ( 'age': 1,  'active': true )
    );

    @function is-young($chr, $args...) {
        @return _get($chr, 'age') < 40;
    }

    $foo: _find-last-key($users, _is-young);
    // => returns `pebbles` assuming `_find-key` returns `barney`
    
    // using the `_matches` callback shorthand
    $foo: _find-last-key($users, ( 'age': 36, 'active': true ));
    // => 'barney'
    
    // using the `_matches-property` callback shorthand
    $foo: _find-last-key($users, 'active', false);
    // => 'fred'
    
    // using the `_property` callback shorthand
    $foo: _find-last-key($users, 'active');
    // => 'pebbles'

_for-in

@function _for-in($map, $iteratee: _identity, $this-arg: null) { ... }

Description

Iterates over own and inherited enumerable properties of a map invoking $iteratee for each property. The $iteratee is bound to $this-arg and invoked with three arguments; (value, key, map). Iterator functions may exit iteration early by explicitly returning false.

Parameters

NameDescriptionTypeDefault value
$map

The map to iterate over.

Map—
$iteratee

The function invoked per iteration.

Function_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Map —

Returns new map.

Example

// todo

_for-in-right

@function _for-in-right($map, $iteratee: _identity, $this-arg: null) { ... }

Description

This method is like _for-in except that it iterates over properties of $map in the opposite order.

Parameters

NameDescriptionTypeDefault value
$map

The map to iterate over.

Map—
$iteratee

The function invoked per iteration.

Function_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Map —

Returns new map.

Example

// todo

_for-own

@function _for-own($map, $iteratee: _identity, $this-arg: null) { ... }

Description

Iterates over own enumerable properties of a map invoking $iteratee for each property. The $iteratee is bound to $this-arg and invoked with three arguments; (value, key, map). Iterator functions may exit iteration early by explicitly returning false.

Parameters

NameDescriptionTypeDefault value
$map

The map to iterate over.

Map—
$iteratee

The function invoked per iteration.

Function_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Map —

Returns new map.

Example

// todo

_for-own-right

@function _for-own-right($map, $iteratee: _identity, $this-arg: null) { ... }

Description

This method is like _for-own except that it iterates over properties of $map in the opposite order.

Parameters

NameDescriptionTypeDefault value
$map

The map to iterate over.

Map—
$iteratee

The function invoked per iteration.

Function_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Map —

Returns map.

Example

// todo

_functions

@function _functions($map) { ... }

Description

Creates a list of function property names from all enumerable properties, own and inherited, of $map.

Parameters

NameDescriptionTypeDefault value
$map

The map to inspect.

Map—

Returns

List —

Returns the new list of property names.

Example

$map: ('a': '_after', 'b': 'lighten', 'c': 'blah');

$foo: _functions($map);
// => ('a', 'b')

_has

@function _has($map, $key) { ... }

Description

Checks if $key exists as a direct property of $map instead of an inherited property. Similar to Sass map-has-key function.

Parameters

NameDescriptionTypeDefault value
$map

The map to inspect.

Map—
$key

The key to check.

String—

Returns

Boolean —

Returns true if $key is a direct property, else false.

Example

$map: ( 'a': 1, 'b': 2, 'c': 3 );
$foo: _has($map, 'b');
// => true

_invert

@function _invert($map, $multi-value: false) { ... }

Description

Creates a map composed of the inverted keys and values of $map. If $map contains duplicate values, subsequent values overwrite property assignments of previous values unless multiValue is true.

Parameters

NameDescriptionTypeDefault value
$map

The map to invert.

Map—
$multi-value

Allow multiple values per key.

Booleanfalse

Returns

Map —

Returns the new inverted map.

Example

$map: ( 'a': 1, 'b': 2, 'c': 1 );
$foo: _invert($map);
// => ( '1': 'c', '2': 'b' )

// with `$multi-value`
$foo: _invert($map, true);
// => ( '1': ('a', 'c'), '2': ('b',) )

_keys

@function _keys($map) { ... }

Description

Creates a list of the own enumerable keys of $map.

Parameters

NameDescriptionTypeDefault value
$map

The map to inspect.

Map—

Returns

List —

Returns the list of keys.

Example

// todo

_keys-in

@function _keys-in($map) { ... }

Description

Creates a list of the own and inherited enumerable keys of map. Note: Non-map values are coerced to maps.

Parameters

NameDescriptionTypeDefault value
$map

The map to inspect.

Map—

Returns

List —

Returns the list of keys.

Example

// todo

_map-values

@function _map-values($map, $iteratee: _identity, $this-arg: null) { ... }

Description

Creates a map with the same keys as $map and values generated by running each own enumerable property of $map through $iteratee. The iteratee function is bound to $this-arg and invoked with three arguments; (value, key, map).

If a property name is provided for $iteratee the created _property style callback returns the property value of the given element.

If a value is also provided for $this-arg the created _matches-property style callback returns true for elements that have a matching property value, else false.

If a map is provided for $iteratee the created _matches style callback returns true for elements that have the properties of the given map, else false.

Parameters

NameDescriptionTypeDefault value
$map

The map to iterate over.

Map—
$iteratee

The function invoked per iteration.

Function or Map or String_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

Map —

Returns the new mapped map.

Example

    @function times-three($n, $args...) {
        @return $n * 3;
    }
    
    $foo: _map-values(( 'a': 1, 'b': 2 ), times-three);
    // => ( 'a': 3, 'b': 6 )
    
    $users: (
      'fred':    ( 'user': 'fred',    'age': 40 ),
      'pebbles': ( 'user': 'pebbles', 'age': 1 )
    );
    // using the `_property` callback shorthand
    $foo: _map-values($users, 'age');
    // => ( 'fred': 40, 'pebbles': 1 )

_merge

@function _merge($map, $source..., $customizer: null, $this-arg: null) { ... }

Description

Recursively merges own enumerable properties of the source map(s), that don't resolve to undefined into the destination map. Subsequent sources overwrite property assignments of previous sources. If $customizer is provided, it is invoked to produce the merged values of the destination and source properties. If $customizer returns undefined merging is handled by the method instead. The $customizer is bound to $this-arg and invoked with five arguments; (source-value, other-value, key, map, source).

Parameters

NameDescriptionTypeDefault value
$map

The destination map.

Map—
$source...

The source maps.

Map...—
$customizer

The function to customize merging properties.

Functionnull
$this-arg

The _this binding of $customizer.

Anynull

Returns

Map —

Returns map.

Example

$users: (
  'data': (( 'user': 'barney' ), ( 'user': 'fred' ))
);
$ages: (
  'data': (( 'age': 36 ), ( 'age': 40 ))
);
$foo: _merge($users, ages);
// => ( 'data': (( 'user': 'barney', 'age': 36 ), ( 'user': 'fred', 'age': 40 )) )

// using a customizer callback
// todo

_omit

@function _omit($map, $predicate, $this-arg: null) { ... }

Description

The opposite of _pick; this method creates a map composed of the own and inherited enumerable properties of $map that are not omitted.

Property names may be specified as individual arguments or as lists of property names. If $predicate is provided it is invoked for each property of $map omitting the properties $predicate returns truthy for. The predicate is bound to $this-arg and invoked with three arguments; (value, key, map).

Parameters

NameDescriptionTypeDefault value
$map

The source map.

Map—
$predicate

The function invoked per iteration or property names to omit, specified as individual property names or lists of property names.

Function or String... or List—
$this-arg

The _this binding of $predicate.

Anynull

Returns

Map —

Returns the new map.

Example

$map: ( 'user': 'fred', 'age': 40 );
$foo: _omit($map, 'age');
// => ( 'user': 'fred' )
$foo: _omit($map, _is-number);
// => ( 'user': 'fred' )

_pairs

@function _pairs($map) { ... }

Description

Creates a two dimensional list of the key-value pairs for $map, e.g. (($key1, $value1), ($key2, $value2)).

Parameters

NameDescriptionTypeDefault value
$map

The map to inspect.

Map—

Returns

List —

Returns the new list of key-value pairs.

Example

$foo: _pairs(( 'barney': 36, 'fred': 40 ));
// => (('barney', 36), ('fred', 40))

_pick

@function _pick($map, $predicate: _identity, $this-arg: null) { ... }

Description

Creates a map composed of the picked $map properties. Property names may be specified as individual arguments or as lists of property names. If $predicate is provided it is invoked for each property of $map picking the properties $predicate returns truthy for. The predicate is bound to $this-arg and invoked with three arguments; (value, key, map).

Parameters

NameDescriptionTypeDefault value
$map

The source map.

Map—
$predicate

The function invoked per iteration or property names to pick, specified as individual property names or lists of property names.

Function or String or List(string)_identity
$this-arg

The _this binding of $predicate.

Anynull

Returns

Map —

Returns the new map.

Example

$map: ( 'user': 'fred', 'age': 40 );
$foo: _pick($map, 'user');
// => ( 'user': 'fred' )
$foo: _pick($map, _is-string);
// => ( 'user': 'fred' )

_result

@function _result($map, $key, $default-value) { ... }

Description

Resolves the value of property $key on $map. If the value of key is a function it is invoked with the _this binding of $map and its result is returned, else the property value is returned. If the property value is undefined or null the $default-value is used in its place.

Parameters

NameDescriptionTypeDefault value
$map

The $map to query.

Map—
$key

The key of the property to resolve.

String—
$default-value

The value returned if the property value resolves to undefined or null.

Any—

Returns

Any type —

Returns the resolved value.

Example

$map: ( 'user': 'fred', 'age': _constant(40) );
$foo: _result($map, 'user');
// => 'fred'
$foo: _result($map, 'age');
// => 40
$foo: _result($map, 'status', 'busy');
// => 'busy'
$foo: _result($map, 'status', _constant('busy'));
// => 'busy'

_values

@function _values($map) { ... }

Description

Creates a list of the own enumerable property values of $map.

Parameters

NameDescriptionTypeDefault value
$map

The map to query.

Map—

Returns

List —

Returns the list of property values.

Example

// todo

_values-in

@function _values-in($map) { ... }

Description

Creates a list of the own and inherited enumerable property values of $map.

Parameters

NameDescriptionTypeDefault value
$map

The map to query.

Map—

Returns

List —

Returns the list of property values.

Example

// todo

mixins

_declare

@mixin _declare($declarations: ()) { ... }

Description

Includes a declaration block for the current selector from a map.

Parameters

NameDescriptionTypeDefault value
$declarations

The declaration map.

Map()

Output

The declarations as CSS property-value pairs.

Example

.foo {
    $foo-declarations: ('height': 50px, 'padding': 1rem 5rem);
    
    @include _declare($foo-declarations);
}

// Output CSS:
.foo {
    height: 50px;
    padding: 1rem 5rem;
}

_rules

@mixin _rules($rules: ()) { ... }

Description

Includes a ruleset for each selector-declarations pair in the map.

Parameters

NameDescriptionTypeDefault value
$rules

The rules map.

Map()

Output

The rulesets for each selector key.

Example

    $test-rules: (
        '.foo': (
            'height': 50px,
            'padding': 1rem 5rem
        ),
        '.bar .baz': (
            'width': 50px,
            'margin': 2rem 6rem
        )
    );
    
    @include _rules($test-rules);
    
    // Output CSS:
    .foo {
        height: 50px;
        padding: 1rem 5rem;
    }
    
    .bar .baz {
        width: 50px;
        margin: 2rem 6rem;
    }

math

functions

_add

@function _add($augend, $addend) { ... }

Description

Adds two numbers.

Parameters

NameDescriptionTypeDefault value
$augend

The first number to add.

Number—
$addend

The second number to add.

Number—

Returns

Number —

Returns the sum.

Example

$foo: _add(6, 4);
// => 10

_sum

@function _sum($collection) { ... }

Description

Gets the sum of the values in $collection.

Parameters

NameDescriptionTypeDefault value
$collection

The collection to iterate over.

Array or Object or String—

Returns

Number —

Returns the sum.

Example

$foo: _sum(4 6 2);
// => 12

$foo: _sum(('a': 4, 'b': 6, 'c': 2));
// => 12

number

functions

_parse-int

@function _parse-int($string, $radix) { ... }

Description

Parses a string argument and returns an integer of the specified radix (the base in mathematical numerical systems).

Similar to native JavaScript parseInt() function.

Parameters

NameDescriptionTypeDefault value
$string

The value to parse. If string is not a string, then it is converted to one. Leading whitespace in the string is ignored.

String—
$radix

An integer between 2 and 36 that represents the radix (the base in mathematical numeral systems) of the above mentioned string.

Number—

Returns

Number —

Returns the string converted to an integer, or null.

Example

$foo: _parse-int('10');
// => 10

$foo: _parse-int('#000020');
// => 32

$foo: _parse-int('    123');
// => 123

_rand

@function _rand($min: 0, $max: 1, $floating: false) { ... }

Description

Produces a random number between $min and $max (inclusive). If only one argument is provided a number between 0 and the given number is returned.

If floating is true, or either $min or $max are floats, a floating-point number is returned instead of an integer.

NOTE: This is not equivalent to the native Sass random() function.

Parameters

NameDescriptionTypeDefault value
$min

The minimum possible value.

Number0
$max

The maximum possible value.

Number1
$floating

Specify returning a floating-point number.

Booleanfalse

Returns

Number —

Returns the random number.

Example

$foo: _random(0, 5);
// => an integer between 0 and 5
$foo: _random(5);
// => also an integer between 0 and 5
$foo: _random(5, true);
// => a floating-point number between 0 and 5
$foo: _random(1.2, 5.2);
// => a floating-point number between 1.2 and 5.2

string

functions

_camel-case

@function _camel-case($string: '') { ... }

Description

Converts $string to camel case. See Wikipedia for more details.

Parameters

NameDescriptionTypeDefault value
$string

The string to convert.

String''

Returns

String —

Returns the camel cased string.

Example

$foo: _camel-case('Foo Bar');
// => 'fooBar'
$foo: _camel-case('--foo-bar');
// => 'fooBar'
$foo: _camel-case('__foo_bar__');
// => 'fooBar'

_capitalize

@function _capitalize($string: '') { ... }

Description

Capitalizes the first character of $string.

Parameters

NameDescriptionTypeDefault value
$string

The string to capitalize.

String''

Returns

String —

Returns the capitalized string.

Example

$foo: _capitalize('fred');
// => 'Fred'

_kebab-case

@function _kebab-case($string: '') { ... }

Description

Converts $string to kebab case. See Wikipedia for more details.

Parameters

NameDescriptionTypeDefault value
$string

The string to convert.

String''

Returns

String —

Returns the kebab cased string.

Example

$foo: _kebab-case('Foo Bar');
// => 'foo-bar'
$foo: _kebab-case('fooBar');
// => 'foo-bar'
$foo: _kebab-case('__foo_bar__');
// => 'foo-bar'

_snake-case

@function _snake-case($string: '') { ... }

Description

Converts $string to snake case. See Wikipedia for more details.

Parameters

NameDescriptionTypeDefault value
$string

The string to convert.

String''

Returns

String —

Returns the snake cased string.

Example

$foo: _snake-case('Foo Bar');
// => 'foo_bar'
$foo: _snake-case('fooBar');
// => 'foo_bar'
$foo: _snake-case('--foo-bar');
// => 'foo_bar'

_start-case

@function _start-case($string: '') { ... }

Description

Converts $string to start case. See Wikipedia for more details.

Parameters

NameDescriptionTypeDefault value
$string

The string to convert.

String''

Returns

String —

Returns the start cased string.

Example

$foo: _start-case('--foo-bar');
// => 'Foo Bar'
$foo: _start-case('fooBar');
// => 'Foo Bar'
$foo: _start-case('__foo_bar__');
// => 'Foo Bar'

_str-concat

@function _str-concat($source: '', $args...) { ... }

Description

Combines the text of two or more strings and returns a new string.

Parameters

NameDescriptionTypeDefault value
$source

Source string

String''
$args...

Other strings to concatenate

String... or *...—

Returns

String —

Returns a new string of concatenated strings

Example

$foo: _concat('Hello', ' ', 'World');
// => 'Hello World'

_encode

@function _encode($string) { ... }

Description

Converts a $string to a URL encoding representation by converting certain characters to their 2-digit hexadecimal equivalent, preceded by a "%" sign.

Parameters

NameDescriptionTypeDefault value
$string

The string to encode.

String—

Returns

String —

Returns the encoded string.

Example

$foo: _encode('Hello world');
// => 'Hello%20world'

_ends-with

@function _ends-with($string: '', $target, $position: str-length($string)) { ... }

Description

Checks if $string ends with the given target string.

Parameters

NameDescriptionTypeDefault value
$string

The string to search.

String''
$target

The string to search for.

String—
$position

The position to search from.

Numberstr-length($string)

Returns

Boolean —

Returns true if $string ends with $target, else false.

Example

$foo: _ends-with('abc', 'c');
// => true

$foo: _ends-with('abc', 'b');
// => false

$foo: _ends-with('abc', 'b', 2);
// => true

_ends-with-any

@function _ends-with-any($string: '', $targets: (), $position: str-length($string)) { ... }

Description

Checks if $string ends with any of the strings in $targets list.

Parameters

NameDescriptionTypeDefault value
$string

The string to search.

String''
$targets

The list of strings to search for.

String()
$position

The position to search from.

Numberstr-length($string)

Returns

Boolean —

Returns true if $string ends with any of the strings in $targets, else false.

Example

$foo: _ends-with-any('abc', 'a' 'c');
// => true

$foo: _ends-with-any('abc', 'a' 'b');
// => false

$foo: _ends-with-any('abc', 'a' 'b', 2);
// => true

_escape

@function _escape($string: '') { ... }

Description

Converts the characters "&", "<", ">", '"', "'", and '', in$string` to their corresponding HTML entities. Note: No other characters are escaped.

Parameters

NameDescriptionTypeDefault value
$string

The string to escape.

String''

Returns

String —

Returns the escaped string.

Example

$foo: _escape('fred, barney, & pebbles');
// => 'fred, barney, & pebbles'

_pad

@function _pad($string: '', $length: 0, $chars: ' ') { ... }

Description

Pads $string on the left and right sides if it is shorter then the given padding length. The $chars string may be truncated if the number of padding characters can't be evenly divided by the padding length.

Parameters

NameDescriptionTypeDefault value
$string

The string to pad.

String''
$length

The padding length.

Number0
$chars

The string used as padding.

String' '

Returns

String —

Returns the padded string.

Example

$foo: _pad('abc', 8);
// => '  abc   '
$foo: _pad('abc', 8, '_-');
// => '_-abc_-_'
$foo: _pad('abc', 3);
// => 'abc'

_pad-left

@function _pad-left($string: '', $length: 0, $chars: ' ') { ... }

Description

Pads $string on the left side if it is shorter then the given padding length. The $chars string may be truncated if the number of padding characters exceeds the padding length.

Parameters

NameDescriptionTypeDefault value
$string

The string to pad.

String''
$length

The padding length.

Number0
$chars

The string used as padding.

String' '

Returns

String —

Returns the padded string.

Example

$foo: _pad-left('abc', 6);
// => '   abc'
$foo: _pad-left('abc', 6, '_-');
// => '_-_abc'
$foo: _pad-left('abc', 3);
// => 'abc'

_pad-right

@function _pad-right($string: '', $length: 0, $chars: ' ') { ... }

Description

Pads $string on the right side if it is shorter then the given padding length. The $chars string may be truncated if the number of padding characters exceeds the padding length.

Parameters

NameDescriptionTypeDefault value
$string

The string to pad.

String''
$length

The padding length.

Number0
$chars

The string used as padding.

String' '

Returns

String —

Returns the padded string.

Example

$foo: _pad-right('abc', 6);
// => 'abc   '
$foo: _pad-right('abc', 6, '_-');
// => 'abc_-_'
$foo: _pad-right('abc', 3);
// => 'abc'

_repeat

@function _repeat($string: '', $n: 0) { ... }

Description

Repeats the given string $n times.

Parameters

NameDescriptionTypeDefault value
$string

The string to repeat.

String''
$n

The number of times to repeat the string.

Number0

Returns

String —

Returns the repeated string.

Example

 _repeat('*', 3);
// => '***'
 _repeat('abc', 2);
// => 'abcabc'
 _repeat('abc', 0);
// => ''

_replace

@function _replace($string, $target, $replacement: '') { ... }

Description

Replaces all instances of a $target substring in a $string with a $replacement string.

Parameters

NameDescriptionTypeDefault value
$string

The source string.

String—
$target

The substring to replace.

String—
$replacement

The replacement string.

String''

Returns

String —

Returns new string with replacements.

Example

$foo: _replace('abcde', 'bcd', '---');
// => 'a---e'

_split

@function _split($string, $delimiter: null) { ... }

Description

Splits a string from indexes of $delimiter to a list.

Parameters

NameDescriptionTypeDefault value
$string

String to split.

String—
$delimiter

Characters to use for separating the $string.

Stringnull

Returns

List —

Returns list of substrings from split $string.

Example

$foo: _split('a--b--c--d--e', '--');
// => 'a' 'b' 'c' 'd' 'e'

_starts-with

@function _starts-with($string: '', $target, $position: 1) { ... }

Description

Checks if $string starts with the given target string.

Parameters

NameDescriptionTypeDefault value
$string

The string to search.

String''
$target

The string to search for.

String—
$position

The position to search from.

Number1

Returns

Boolean —

Returns true if $string starts with $target, else false.

Example

$foo: _starts-with('abc', 'a');
// => true

$foo: _starts-with('abc', 'b');
// => false

$foo: _starts-with('abc', 'b', 1);
// => true

_starts-with-any

@function _starts-with-any($string: '', $targets: (), $position: 1) { ... }

Description

Checks if $string starts with any of the strings in $targets list.

Parameters

NameDescriptionTypeDefault value
$string

The string to search.

String''
$targets

The list of strings to search for.

String()
$position

The position to search from.

Number1

Returns

Boolean —

Returns true if $string starts with any of the strings in $targets, else false.

Example

$foo: _starts-with-any('abc', 'a' 'b');
// => true
$foo: _starts-with-any('abc', 'b' 'c');
// => false
$foo: _starts-with-any('abc', 'b' 'c', 1);
// => true

_trim

@function _trim($string: '', $chars: ' ') { ... }

Description

Removes leading and trailing whitespace or specified characters from $string.

Parameters

NameDescriptionTypeDefault value
$string

The string to trim.

String''
$chars

The characters to trim.

String' '

Returns

String —

Returns the trimmed string.

Example

$foo: _trim('  abc  ');
// => 'abc'
$foo: _trim('-_-abc-_-', '_-');
// => 'abc'
$foo: _map(('  foo  ', '  bar  '), _trim);
// => ('foo', 'bar')

_trim-left

@function _trim-left($string: '', $chars: whitespace) { ... }

Description

Removes leading whitespace or specified characters from $string.

Parameters

NameDescriptionTypeDefault value
$string

The string to trim.

String''
$chars

The characters to trim.

Stringwhitespace

Returns

String —

Returns the trimmed string.

Example

 _trim-left('  abc  ');
// => 'abc  '
 _trim-left('-_-abc-_-', '_-');
// => 'abc-_-'

_trim-right

@function _trim-right($string: '', $chars: ' ') { ... }

Description

Removes trailing whitespace or specified characters from $string.

Parameters

NameDescriptionTypeDefault value
$string

The string to trim.

String''
$chars

The characters to trim.

String' '

Returns

String —

Returns the trimmed string.

Example

$foo: _trim-right('  abc  ');
// => '  abc'
$foo: _trim-right('-_-abc-_-', '_-');
// => '-_-abc'

_trunc

@function _trunc($string: '', $options: null, $length: 30, $omission: '...', $separator: null) { ... }

Description

Truncates $string if it is longer than the given maximum string length. The last characters of the truncated string are replaced with the omission string which defaults to "...".

Parameters

NameDescriptionTypeDefault value
$string

The string to truncate.

String''
$options

The options object or maximum string length.

Map or Numbernull
$length

The maximum string length.

Number30
$omission

The string to indicate text is omitted.

String'...'
$separator

The separator pattern to truncate to.

Stringnull

Returns

String —

Returns the truncated string.

Example

$foo: _trunc('hi-diddly-ho there, neighborino');
// => 'hi-diddly-ho there, neighbo...'

$foo: _trunc('hi-diddly-ho there, neighborino', 24);
// => 'hi-diddly-ho there, n...'

$foo: _trunc('hi-diddly-ho there, neighborino',
  $length: 24,
  $separator: ' '
);
// => 'hi-diddly-ho there,...'

$foo: _trunc('hi-diddly-ho there, neighborino', 
  $omission: ' (...)'
);
// => 'hi-diddly-ho there, neig (...)'

_unescape

@function _unescape($string: '') { ... }

Description

The inverse of _escape; this method converts the HTML entities &amp;, &lt;, &gt;, &quot;, &#39;, and &#96; in string to their corresponding characters. Note: No other HTML entities are unescaped.

Parameters

NameDescriptionTypeDefault value
$string

The string to unescape.

String''

Returns

String —

Returns the unescaped string.

Example

$foo: _unescape('fred, barney, & pebbles');
// => 'fred, barney, & pebbles'

_words

@function _words($string: '') { ... }

Description

Splits $string into a list of its words.

Parameters

NameDescriptionTypeDefault value
$string

The string to inspect.

String''

Returns

List —

Returns the words of $string.

Example

$foo: _words('fred, barney, & pebbles');
// => ('fred', 'barney', 'pebbles')

_char-at

@function _char-at($string, $index: 1) { ... }

Description

Gets the character at $index of a string.

Parameters

NameDescriptionTypeDefault value
$string

Source string.

String—
$index

Character index in string.

Number1

Returns

Number —

Returns character at string index, or null if index is not in string.

Example

$foo: _char-at('coffee', 4);
// => 'f'

_char-code-at

@function _char-code-at($string, $index: 1) { ... }

Description

Gets the ASCII char code of a character at $index of a string.

Parameters

NameDescriptionTypeDefault value
$string

Source string.

String—
$index

Character index in string.

Number1

Returns

Number —

Returns char code of character at given string index.

Example

$foo: _char-code-at('beach', 3);
// => 97

_get-char-code

@function _get-char-code($char) { ... }

Description

Gets the ASCII char code of a given character.

Parameters

NameDescriptionTypeDefault value
$char

Source character.

String—

Returns

Number —

Returns char code of given character.

Example

$foo: _get-char-code('a');
// => 97

utility

functions

_callback

@function _callback($func: _identity, $this-arg: null) { ... }

Description

Creates a function that invokes $function with the _this binding of $this-arg and arguments of the created function.

If $function is a property name the created callback returns the property value for a given element.

If $function is a map the created callback returns true for elements that contain the equivalent map properties, otherwise it returns false.

If $function is a list the created callback returns the result of the function (first item of the list) right-partially applied with the rest of the list items, called with the value as the first argument (see example).

Parameters

NameDescriptionTypeDefault value
$func

The value to convert to a callback.

Any_identity
$this-arg

The _this binding of $function.

Anynull

Returns

Function —

Returns the callback.

Example

    $fully-lighten: _callback(lighten 100%);
    $lightened-color: _exec($fully-lighten, black);
    // => white

_constant

@function _constant($value) { ... }

Description

Creates a function that returns $value.

Parameters

NameDescriptionTypeDefault value
$value

The value to return from the new function.

Any—

Returns

Function —

Returns the new function.

Example

$map: ( 'user': 'fred' );
$getter: _constant($map);

$foo: _exec($getter) === $map;
// => true

_debug

@function _debug($value) { ... }

Description

Debugs a $value using @debug and returns the same value.

Parameters

NameDescriptionTypeDefault value
$value

The value to be debugged.

Any—

Returns

Any type —

Returns the value after it is debugged.

Example

$list: 'one' 'two' 'three';

$list: _map($list, _debug);
// DEBUG: one
// DEBUG: two
// DEBUG: three
// => 'one' 'two' 'three'

_either

@function _either($this, $that: null, $predicate: 'is-truthy') { ... }

Description

Returns initial $this value unless the $predicate applied to $this is falsey; in which case, $that is returned.

The $predicate argument can be any type of supported Sassdash callback.

Parameters

NameDescriptionTypeDefault value
$this

The target preferred value

Any—
$that

The fallback value, in case $this is falsey.

Anynull
$predicate

The predicate to check $this against

Function'is-truthy'

Returns

Any type —

$this or $that

Example

$button-bg-color: false;

$foo: _either($button-bg-color, #C0FFEE);
// => #C0FFEE

$foo: _either($button-bg-color, #C0FFEE, _is-color);
// => #C0FFEE

$button-bg-color: green;

$foo: _either($button-bg-color, #C0FFEE);
// => green

// Usage with "shifted argument" callback
$foo: _either('abcde', 'xyz', str-index 'abc');
// => 'abcde'

$foo: _either('hijkl', 'xyz', str-index 'abc');
// => 'xyz'

_identity

@function _identity($value: null) { ... }

Description

This method returns the first argument provided to it.

Parameters

NameDescriptionTypeDefault value
$value

Any value.

Anynull

Returns

Any type —

Returns $value.

Example

$map: ( 'user': 'fred' );
$foo: _identity($map) == $map;
// => true

_matches

@function _matches($source) { ... }

Description

Creates a function which performs a deep comparison between a given map and source, returning true if the given map has equivalent property values, else false.

Parameters

NameDescriptionTypeDefault value
$source

The map of property values to match.

Map—

Returns

Function —

Returns the new function.

Example

$users: (
  ( 'user': 'barney', 'age': 36, 'active': true ),
  ( 'user': 'fred',   'age': 40, 'active': false )
);
$foo: _filter($users, _matches(( 'age': 40, 'active': false )));
// => (( 'user': 'fred', 'age': 40, 'active': false ),)

_noop

@function _noop() { ... }

Description

A no-operation function which returns null regardless of the arguments it receives.

Parameters

None.

Example

$map: ( 'user': 'fred' );
$foo: _noop($map) == null;
// => true

_property

@function _property($key) { ... }

Description

Creates a function which returns the property value of $key on a given map.

Parameters

NameDescriptionTypeDefault value
$key

The key of the property to get.

String—

Returns

Function —

Returns the new function.

Example

$users: (
  ( 'user': 'fred' ),
  ( 'user': 'barney' )
);

$get-name: _property('user');

$foo: _map($users, $get-name);
// => ('fred', barney')

$foo: _pluck(_sort-by($users, $get-name), 'user');
// => ('barney', 'fred')

_property-of

@function _property-of($map) { ... }

Description

The inverse of _property; this method creates a function which returns the property value of a given key on $map.

Parameters

NameDescriptionTypeDefault value
$map

The map to inspect.

Map—

Returns

Function —

Returns the new function.

Example

$map: ( 'a': 3, 'b': 1, 'c': 2 );
$foo: _map(('a', 'c'), _property-of($map));
// => (3, 2)
$foo: _sort-by(('a', 'b', 'c'), _property-of($map));
// => ('b', 'c', 'a')

_range

@function _range($start: 0, $end, $step: 1) { ... }

Description

Creates a list of numbers (positive and/or negative) progressing from $start up to, but not including, $end. If $end is not specified it defaults to $start with $start becoming 0. If $start is less than $end a zero-length range is created unless a negative $step is specified.

Parameters

NameDescriptionTypeDefault value
$start

The start of the range.

Number0
$end

The end of the range.

Number—
$step

The value to increment or decrement by.

Number1

Returns

List —

Returns the new list of numbers.

Example

$foo: _range(4);
// => (0, 1, 2, 3)
$foo: _range(1, 5);
// => (1, 2, 3, 4)
$foo: _range(0, 20, 5);
// => (0, 5, 10, 15)
$foo: _range(0, -4, -1);
// => (0, -1, -2, -3)
$foo: _range(1, 4, 0);
// => (1, 1, 1)
$foo: _range(0);
// => ()

_times

@function _times($n: 0, $iteratee: _identity, $this-arg: null) { ... }

Description

Invokes the iteratee function $n times, returning a list of the results of each invocation. The $iteratee is bound to $this-arg and invoked with one argument; (index).

Parameters

NameDescriptionTypeDefault value
$n

The number of times to invoke $iteratee.

Number0
$iteratee

The function invoked per iteration.

Function_identity
$this-arg

The _this binding of $iteratee.

Anynull

Returns

List —

Returns the list of results.

Example

$dice-rolls: _times(3, _partial(_random, 1, 6, false));
// => (3, 6, 4)

_unique-id

@function _unique-id($prefix: '') { ... }

Description

Generates a unique ID. If $prefix is provided, the ID is appended to it.

This is similar to the native Sass unique-id() function, with the added prefix ability.

Parameters

NameDescriptionTypeDefault value
$prefix

The value to prefix the ID with.

String''

Returns

String —

Returns the unique ID.

Example

$foo: _unique-id('color_');
// => 'color_xxx' where xxx is a unique-id()

$foo: _unique-id();
// => 'xxx' where xxx is a unique-id()

_

@function _($value, $function-calls...) { ... }

Description

Allows pseudo "chaining" of $value by sequentially invoking function calls as arguments on $value.

Each argument after $value is a $function-call which can be:

  • A single function name
  • A list, containing the function name followed by the arguments to apply to the function after the $value has been applied as the first argument.

Parameters

NameDescriptionTypeDefault value
$value

The initial value.

Any—
$function-calls...

The function calls to apply to value.

Function... or List...—

Returns

Any type —

Returns new value with "chained" function calls applied.

Example

$list: ('a' 'b' 'c', 'd' 'e' 'f', 'g' 'h' 'i');

$foo: _($list
    _map _join,             // _map($list, _join);
    _reduce _str-concat,    // _reduce($list, _str-concat);
    _concat 'jkl',          // _concat($list, 'jkl');
    _join ' -- ');          // _join($list, ' -- ');
// => 'abcdefghi -- jkl';

_get

@function _get($value, $keys) { ... }

Description

Gets the value of a source $value from the specified key, or list of keys for deep map retrieval, or null if any of the keys are undefined.

If $value is list-like, indexes are used as keys.

Parameters

NameDescriptionTypeDefault value
$value

Source value.

Map or List or String or Arglist—
$keys

Single key or list of keys for value retrieval

* or List—

Returns

Any type —

Returns the retrieved value.

Example

$palette: (
    'primary': (
        'default': red,
        'dark': darken(red, 10%)
    )
);

$color-primary: _get($palette, 'primary' 'default');
// => red

$color-dark: _get($palette, 'primary.dark');
// => #CC0000

_set

@function _set($value, $keys) { ... }

Description

Sets the value of a source $value at the specified key, or list of keys for deep map setting.

If $value is list-like, indexes are used as keys.

Parameters

NameDescriptionTypeDefault value
$value

Source value.

Map or List or String or Arglist—
$keys

Single key or list of keys for value setting

* or List—

Returns

Any type —

Returns a new $value with the set value.

Example

$palette: (
    'primary': (
        'default': red,
        'dark': darken(red, 10%)
    )
);

$palette: _set($palette, 'primary' 'default', blue);
// => (
//     'primary': (
//         'default': blue,
//         'dark': darken(red, 10%)
//     )
// );

_static-get

@function _static-get($keys) { ... }

Description

Gets the specified static variable. Uses _get() syntax.

Parameters

NameDescriptionTypeDefault value
$keys

Single key or list of keys for static value retrieval.

String or List—

Returns

Any type —

Returns the retrieved static value.

Example

    @include _static-set('global-padding', 1rem);
    
    .foo {
        padding: _static-get('global-padding');
        // => 1rem
    }

See

_static-set

@function _static-set($keys) { ... }

Description

Sets the specified static variable. Uses _set() syntax.

Parameters

NameDescriptionTypeDefault value
$keys

Single key or list of keys for static value setting.

String or List—

Returns

Any type —

Returns the updated static value.

Example

    $global-padding: _static-set('global-padding', 1rem);
    
    .foo {
        padding: _static-get('global-padding');
        // => 1rem
    }

Used by

See

mixins

_static-set

@mixin _static-set($keys) { ... }

Description

Sets the specified static variable. Uses _set() syntax.

Parameters

NameDescriptionTypeDefault value
$keys

Single key or list of keys for static value setting.

String or List—

Example

    @include _static-set('global-padding', 1rem);
    
    .foo {
        padding: _static-get('global-padding');
        // => 1rem
    }

Requires

See