Functions and Built-in Function Reference

// Simple calculation function
@function strip-unit($number) {
  @if type-of($number) == 'number' and not unitless($number) {
    @return $number / ($number * 0 + 1);
  }
  @return $number;
}

// Usage
$value: strip-unit(16px);  // Returns: 16

// Function with multiple parameters
@function calculate-rem($size, $base: 16px) {
  $rem: $size / $base;
  @return #{$rem}rem;
}

// Usage
font-size: calculate-rem(24px);       // 1.5rem
font-size: calculate-rem(20px, 10px); // 2rem

// Conditional return
@function contrast-color($color) {
  @if (lightness($color) > 50%) {
    @return #000;
  } @else {
    @return #fff;
  }
}

.button {
  background: #3498db;
  color: contrast-color(#3498db);  // Returns: #fff
}

// Variadic arguments
@function sum($numbers...) {
  $total: 0;
  @each $num in $numbers {
    $total: $total + $num;
  }
  @return $total;
}

$result: sum(1, 2, 3, 4, 5);  // 15

// Named arguments for clarity
@function responsive-size(
  $min-size,
  $max-size,
  $min-viewport: 320px,
  $max-viewport: 1200px
) {
  $slope: ($max-size - $min-size) / ($max-viewport - $min-viewport);
  $intercept: $min-size - $slope * $min-viewport;
  @return calc(#{$intercept} + #{$slope * 100vw});
}

// Call with named args
font-size: responsive-size(
  $min-size: 14px,
  $max-size: 18px
);

// Guard clauses with early return
@function safe-divide($dividend, $divisor) {
  @if $divisor == 0 {
    @warn "Cannot divide by zero";
    @return null;
  }
  @return $dividend / $divisor;
}

// Return different types
@function get-spacing($key) {
  $spacing: (small: 8px, medium: 16px, large: 24px);
  
  @if map-has-key($spacing, $key) {
    @return map-get($spacing, $key);  // Returns number
  }
  @return null;  // Returns null if not found
}

$primary: #3498db;

// Lightness adjustments
.light-bg {
  background: lighten($primary, 30%);  // #a8d5f2
}

.dark-bg {
  background: darken($primary, 20%);   // #1f5d87
}

// Color mixing
$brand-gradient: mix(#3498db, #9b59b6, 50%);

.gradient {
  background: linear-gradient(
    to right,
    #3498db,
    $brand-gradient,
    #9b59b6
  );
}

// Saturation
.vibrant {
  color: saturate($primary, 40%);      // More vivid
}

.muted {
  color: desaturate($primary, 40%);    // Less vivid
}

// Complementary color scheme
$accent: complement($primary);         // Opposite on color wheel

.scheme {
  background: $primary;
  color: $accent;
}

// Transparency
$overlay: transparentize(#000, 0.5);   // rgba(0, 0, 0, 0.5)

.modal-backdrop {
  background: $overlay;
}

// Advanced: Color palette generator
@function generate-palette($base-color) {
  @return (
    base: $base-color,
    light: lighten($base-color, 15%),
    lighter: lighten($base-color, 30%),
    dark: darken($base-color, 15%),
    darker: darken($base-color, 30%),
    complement: complement($base-color)
  );
}

$blue-palette: generate-palette(#3498db);

// Responsive grid calculation
@function grid-width($cols, $total: 12) {
  $percent: ($cols / $total) * 100%;
  @return floor($percent * 100) / 100;  // Round to 2 decimals
}

.col-4 {
  width: grid-width(4);  // 33.33%
}

// Clamp value between min and max
@function clamp($value, $min, $max) {
  @return max($min, min($value, $max));
}

$size: clamp(20px, 10px, 30px);  // Returns: 20px

// Aspect ratio calculation
@function aspect-ratio-padding($width, $height) {
  @return percentage($height / $width);
}

.video-16-9 {
  padding-bottom: aspect-ratio-padding(16, 9);  // 56.25%
}

// Random color generator
@function random-color() {
  @return rgb(random(255), random(255), random(255));
}

.random-bg {
  background: random-color();
}

// Spacing scale with rounding
$base-spacing: 8px;

@function spacing($multiplier) {
  @return round($base-spacing * $multiplier);
}

.mt-1 { margin-top: spacing(1); }    // 8px
.mt-2 { margin-top: spacing(2); }    // 16px
.mt-3 { margin-top: spacing(3); }    // 24px

// Ensure non-negative values
@function positive($value) {
  @return max(0, $value);
}

.safe-margin {
  margin: positive(-10px);  // 0px (prevents negative)
}

// Font family management
$font-stack: (Helvetica, Arial, sans-serif);

@function get-font-stack($fonts) {
  $stack: '';
  @each $font in $fonts {
    @if str-index($font, ' ') {
      $stack: $stack + quote($font) + ', ';
    } @else {
      $stack: $stack + $font + ', ';
    }
  }
  @return unquote(str-slice($stack, 1, -3));
}

.text {
  font-family: get-font-stack($font-stack);
}

// String replacement function
@function str-replace($string, $search, $replace: '') {
  $index: str-index($string, $search);
  
  @if $index {
    $before: str-slice($string, 1, $index - 1);
    $after: str-slice($string, $index + str-length($search));
    @return $before + $replace + $after;
  }
  
  @return $string;
}

$url: "assets/images/icon.png";
$new-url: str-replace($url, "assets", "public");
// Result: "public/images/icon.png"

// Class name generator
@function bem-class($block, $element: null, $modifier: null) {
  $class: $block;
  
  @if $element {
    $class: $class + '__' + $element;
  }
  
  @if $modifier {
    $class: $class + '--' + $modifier;
  }
  
  @return unquote('.' + $class);
}

// Usage
#{bem-class('card', 'header', 'large')} {
  font-size: 2rem;
}
// Generates: .card__header--large { }

// Unique ID for animations
@function unique-animation-name($base) {
  @return unquote($base + '-' + unique-id());
}

$anim-name: unique-animation-name('slide');

@keyframes #{$anim-name} {
  from { opacity: 0; }
  to { opacity: 1; }
}

// Robust unit conversion
@function convert-to-rem($value, $base: 16px) {
  // Type validation
  @if type-of($value) != 'number' {
    @warn "#{$value} is not a number";
    @return $value;
  }
  
  // Check if already unitless or rem
  @if unitless($value) {
    @return #{$value}rem;
  }
  
  @if unit($value) == 'rem' {
    @return $value;
  }
  
  @if unit($value) == 'px' {
    @return $value / $base * 1rem;
  }
  
  @warn "Cannot convert #{unit($value)} to rem";
  @return $value;
}

.text {
  font-size: convert-to-rem(18px);      // 1.125rem
  padding: convert-to-rem(16);          // 16rem
  margin: convert-to-rem(1.5rem);       // 1.5rem
}

// Polymorphic spacing function
@function spacing($value) {
  @if type-of($value) == 'number' {
    @return $value * 8px;
  }
  
  @if type-of($value) == 'string' {
    $map: (xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px);
    @if map-has-key($map, $value) {
      @return map-get($map, $value);
    }
  }
  
  @warn "Invalid spacing value: #{$value}";
  @return 0;
}

.component {
  margin: spacing(2);       // 16px (number)
  padding: spacing('lg');   // 24px (string)
}

// Conditional mixin application
@mixin apply-if-exists($mixin-name, $args...) {
  @if mixin-exists($mixin-name) {
    @include #{$mixin-name}($args...);
  } @else {
    @warn "Mixin #{$mixin-name} does not exist";
  }
}

// Safe variable getter
@function get-var($name, $fallback: null) {
  @if global-variable-exists($name) {
    @return #{$name};
  }
  @return $fallback;
}

// Type guard for lists
@function safe-nth($list, $index, $default: null) {
  @if type-of($list) != 'list' {
    @return $default;
  }
  
  @if $index <= length($list) and $index > 0 {
    @return nth($list, $index);
  }
  
  @return $default;
}

$colors: red, blue, green;
$color: safe-nth($colors, 5, black);  // Returns: black (fallback)