Sass/SCSS Missing Functions

_missing-functions.scss

///
// Sass/SCSS missing functions.
//
// @author Davey Jacobson <daveyjake21 [at] geemail [dot] com>
//
// @version 1.2.2
//
// @since 1.0.0 - Initial commit.
// @since 1.1.0 - Added str-replace().
// @since 1.1.5 - Added is-list().
// @since 1.2.0 - Added empty().
// @since 1.2.2 - Optimized parse-args().
///

///
// Check if variable is empty like PHP's `empty` function.
//
// @since 1.2.0
//
// @param {mixed} $variable Variable to check.
//
// @return {bool} True if empty. False if not.
///
@function empty( $variable ) {
    $conditions: (
        $variable == '',
        $variable == (),
        $variable == '()',
        $variable == null,
        $variable == 'null',
        $variable == false,
        $variable == 'false',
        $variable == undefined,
        $variable == 'undefined',
        $variable == 0,
        $variable == '0'
    );

    $total: 0;

    @each $condition in $conditions {
        @if not $condition {
            $total: $total + 1;
        }
    }

    @if $total > 0 {
        @return false;
    }

    @return true;
}

///
// Split a string into a list of strings.
//
// @since 1.0.0
//
// @author danielpchen
// @link https://gist.github.com/danielpchen/3677421ea15dcf2579ff
//
// @param {string} $string    The string to split.
// @param {string} $delimiter What to split string by.
//
// @return {list} The list built from the string.
///
@function explode( $string, $delimiter ) {
    $result: ();

    @if $delimiter == '' {
        @for $i from 1 through str-length( $string ) {
            $result: append( $result, str-slice( $string, $i, $i ) );
        }

        @return $result;
    }

    $exploding: true;

    @while $exploding {
        $d-index: str-index( $string, $delimiter );

        @if $d-index {
            @if $d-index > 1 {
                $result: append( $result, str-slice( $string, 1, $d-index - 1 ) );
                $string: str-slice( $string, $d-index + str-length( $delimiter ) );

            } @else if $d-index == 1 {
                $string: str-slice( $string, 1, $d-index + str-length( $delimiter ) );

            } @else {
                $result: append( $result, $string );
                $exploding: false;
            }
        } @else {
            $result: append( $result, $string );
            $exploding: false;
        }
    }

    @return $result;
}

///
// Join list of elements to form a single string, like PHP's `implode` function.
//
// @since 1.0.0
//
// @param {list}   $pieces The list of strings to implode.
// @param {string} $glue   The "glue" between elements in the result string.
//
// @return {string} The result string.
///
@function implode( $pieces, $glue: '' ) {
    $result: '';

    @for $i from 1 through length( $pieces ) {
        $piece: nth( $pieces, $i );

        @if type-of( $piece ) == 'list' {
            $result: unquote( '#{$result}#{$glue}#{implode( $piece, $glue )}' );
        } @else {
            $result: unquote( '#{$result}#{$glue}#{$piece}' );
        }
    }

    @if $result != null {
        $result: str-slice( $result, str-length( $glue ) + 1, -1 );
    }

    @return $result;
}

///
// An alias for index() that acts like PHP's `in_array` function for lists.
//
// @since 1.0.0
// @since 1.1.6 Removed quotes from `string` and `number`.
//
// @param {string|number} $needle   Value to look for.
// @param {list}          $haystack List to look in.
//
// @return bool True if $needle is found in $haystack. False if not.
///
@function in-list( $needle, $haystack ) {
    @if type-of( $needle ) != string and type-of( $needle ) != number {
        @error "The in-list() `$needle` parameter is a #{type-of( $needle )}. It MUST be a string or number.";
        @return false;
    }
    @else if is-list( $haystack ) == false {
        @error "The in-list() `$haystack` parameter is a #{type-of( $haystack )}. It MUST be a list.";
        @return false;
    }

    @return index( $haystack, $needle );
}

///
// Check if variable is a list.
//
// @since 1.1.5
// @since 1.1.6 Removed quotes from values.
//
// @param {mixed} $variable Anything to check.
//
// @return {bool} True if list. False if not.
///
@function is-list( $variable ) {
    // Just in case a list is surrounded by quotes.
    @if type-of( $variable ) == string {
        $variable: unquote( $variable );
    }

    @return type-of( $variable ) == list;
}

///
// Fetch nested keys.
//
// @since 1.0.0
//
// @link https://www.sitepoint.com/extra-map-functions-sass/
//
// @param {map}  $map  Map to traverse.
// @param {list} $keys Keys to fetch from map.
//
// @return {mixed} The desired value of the nested key.
///
@function map-deep-get( $map, $keys... ) {
    @each $key in $keys {
        $map: map-get( $map, $key );
    }

    @return $map;
}

///
// Inspired by the WordPress `wp_parse_args` function.
//
// @since 1.0.0
// @since 1.2.2 Because `$args` contains what we want, we're merging
//              what's untouched in `$defaults`.
//
// @param {map} $args     Custom parameter-value pairs for a function or mixin.
// @param {map} $defaults Default parameter-values pairs for a function or mixin.
// 
// @return {map} The parsed map with new values overwriting defaults.
///
@function parse-args( $args, $defaults ) {
    @each $key, $val in $defaults {
        @if map-has-key( $args, $key ) == false {
            $args: map-merge( $args, ( $key: $val ) );
        }
    }

    @return $args;
}

///
// Replace substring with another string like PHP's `str_replace`.
//
// @author Kitty Giraudel
// @link https://css-tricks.com/snippets/sass/str-replace-function/
//
// @since 1.1.0
//
// @param {string} $string  The initial string.
// @param {string} $search  Substring to replace.
// @param {string} $replace The replacement string.
//
// @return {string} The final modified string.
///
@function str-replace( $string, $search, $replace: '' ) {
    $index: str-index( $string, $search );

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

    @return $string;
}