20 KiB
| title |
|---|
| sass:math |
{% render 'doc_snippets/built-in-module-status' %}
Variables
{% function 'math.$e' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
The closest 64-bit floating point approximation of the mathematical constant e.
{% codeExample 'math-e', false %} @debug math.$e; // 2.7182818285 === @debug math.$e // 2.7182818285 {% endcodeExample %} {% endfunction %}
{% function 'math.$epsilon' %} {% compatibility 'dart: "1.55.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
The difference between 1 and the smallest 64-bit floating point number greater than 1 according to floating-point comparisons. Because of Sass numbers' 10 digits of precision, in many cases this will appear to be 0. {% endfunction %}
{% function 'math.$max-number' %} {% compatibility 'dart: "1.55.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
The maximum finite number that can be represented as a 64-bit floating point number.
{% codeExample 'math-max-number', false %} @debug math.$max-number; // 179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 === @debug math.$max-number // 179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 {% endcodeExample %} {% endfunction %}
{% function 'math.$max-safe-integer' %} {% compatibility 'dart: "1.55.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
The maximum integer n such that both n and n + 1 can be precisely
represented as a 64-bit floating-point number.
{% codeExample 'math-max-safe-integer', false %} @debug math.$max-safe-integer; // 9007199254740991 === @debug math.$max-safe-integer // 9007199254740991 {% endcodeExample %} {% endfunction %}
{% function 'math.$min-number' %} {% compatibility 'dart: "1.55.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
The smallest positive number that can be represented as a 64-bit floating point number. Because of Sass numbers' 10 digits of precision, in many cases this will appear to be 0. {% endfunction %}
{% function 'math.$min-safe-integer' %} {% compatibility 'dart: "1.55.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
The minimum integer n such that both n and n - 1 can be precisely
represented as a 64-bit floating-point number.
{% codeExample 'math-min-safe-integer', false %} @debug math.$min-safe-integer; // -9007199254740991 === @debug math.$min-safe-integer // -9007199254740991 {% endcodeExample %} {% endfunction %}
{% function 'math.$pi' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
The closest 64-bit floating point approximation of the mathematical constant π.
{% codeExample 'math-pi', false %} @debug math.$pi; // 3.1415926536 === @debug math.$pi // 3.1415926536 {% endcodeExample %} {% endfunction %}
Bounding Functions
{% function 'math.ceil($number)', 'ceil($number)', 'returns:number' %}
Rounds $number up to the next highest whole number.
{% codeExample 'math-ceil', false %} @debug math.ceil(4); // 4 @debug math.ceil(4.2); // 5 @debug math.ceil(4.9); // 5 === @debug math.ceil(4) // 4 @debug math.ceil(4.2) // 5 @debug math.ceil(4.9) // 5 {% endcodeExample %} {% endfunction %}
{% function 'math.clamp($min, $number, $max)', 'returns:number' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Restricts $number to the range between $min and $max. If $number is
less than $min this returns $min, and if it's greater than $max this
returns $max.
$min, $number, and $max must have compatible units, or all be unitless.
{% codeExample 'math-clamp', false %} @debug math.clamp(-1, 0, 1); // 0 @debug math.clamp(1px, -1px, 10px); // 1px @debug math.clamp(-1in, 1cm, 10mm); // 10mm === @debug math.clamp(-1, 0, 1) // 0 @debug math.clamp(1px, -1px, 10px) // 1px @debug math.clamp(-1in, 1cm, 10mm) // 10mm {% endcodeExample %} {% endfunction %}
{% function 'math.floor($number)', 'floor($number)', 'returns:number' %}
Rounds $number down to the next lowest whole number.
{% codeExample 'math-floor', false %} @debug math.floor(4); // 4 @debug math.floor(4.2); // 4 @debug math.floor(4.9); // 4 === @debug math.floor(4) // 4 @debug math.floor(4.2) // 4 @debug math.floor(4.9) // 4 {% endcodeExample %} {% endfunction %}
{% function 'math.max($number...)', 'max($number...)', 'returns:number' %} Returns the highest of one or more numbers.
{% codeExample 'math-max', false %} @debug math.max(1px, 4px); // 4px
$widths: 50px, 30px, 100px;
@debug math.max($widths...); // 100px
===
@debug math.max(1px, 4px) // 4px
$widths: 50px, 30px, 100px
@debug math.max($widths...) // 100px
{% endcodeExample %} {% endfunction %}
{% function 'math.min($number...)', 'min($number...)', 'returns:number' %} Returns the lowest of one or more numbers.
{% codeExample 'math-min', false %} @debug math.min(1px, 4px); // 1px
$widths: 50px, 30px, 100px;
@debug math.min($widths...); // 30px
===
@debug math.min(1px, 4px) // 1px
$widths: 50px, 30px, 100px
@debug math.min($widths...) // 30px
{% endcodeExample %} {% endfunction %}
{% function 'math.round($number)', 'round($number)', 'returns:number' %}
Rounds $number to the nearest whole number.
{% codeExample 'math-round', false %} @debug math.round(4); // 4 @debug math.round(4.2); // 4 @debug math.round(4.9); // 5 === @debug math.round(4) // 4 @debug math.round(4.2) // 4 @debug math.round(4.9) // 5 {% endcodeExample %} {% endfunction %}
Distance Functions
{% function 'math.abs($number)', 'abs($number)', 'returns:number' %}
Returns the absolute value of $number. If $number is negative, this
returns -$number, and if $number is positive, it returns $number as-is.
{% codeExample 'math-abs', false %} @debug math.abs(10px); // 10px @debug math.abs(-10px); // 10px === @debug math.abs(10px) // 10px @debug math.abs(-10px) // 10px {% endcodeExample %} {% endfunction %}
{% function 'math.hypot($number...)', 'returns:number' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Returns the length of the n-dimensional vector that has components equal
to each $number. For example, for three numbers a, b, and c, this
returns the square root of a² + b² + c².
The numbers must either all have compatible units, or all be unitless. And since the numbers' units may differ, the output takes the unit of the first number.
{% codeExample 'math-hypot', false %} @debug math.hypot(3, 4); // 5
$lengths: 1in, 10cm, 50px;
@debug math.hypot($lengths...); // 4.0952775683in
===
@debug math.hypot(3, 4) // 5
$lengths: 1in, 10cm, 50px
@debug math.hypot($lengths...) // 4.0952775683in
{% endcodeExample %} {% endfunction %}
Exponential Functions
{% function 'math.log($number, $base: null)', 'returns:number' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Returns the logarithm of $number with respect to $base. If $base is
null, the natural log is calculated.
$number and $base must be unitless.
{% codeExample 'math-log', false %} @debug math.log(10); // 2.302585093 @debug math.log(10, 10); // 1 === @debug math.log(10) // 2.302585093 @debug math.log(10, 10) // 1 {% endcodeExample %} {% endfunction %}
{% function 'math.pow($base, $exponent)', 'returns:number' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Raises $base to the power of $exponent.
$base and $exponent must be unitless.
{% codeExample 'math-pow', false %} @debug math.pow(10, 2); // 100 @debug math.pow(100, math.div(1, 3)); // 4.6415888336 @debug math.pow(5, -2); // 0.04 === @debug math.pow(10, 2) // 100 @debug math.pow(100, math.div(1, 3)) // 4.6415888336 @debug math.pow(5, -2) // 0.04 {% endcodeExample %} {% endfunction %}
{% function 'math.sqrt($number)', 'returns:number' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Returns the square root of $number.
$number must be unitless.
{% codeExample 'math-sqrt', false %} @debug math.sqrt(100); // 10 @debug math.sqrt(math.div(1, 3)); // 0.5773502692 @debug math.sqrt(-1); // NaN === @debug math.sqrt(100) // 10 @debug math.sqrt(math.div(1, 3)) // 0.5773502692 @debug math.sqrt(-1) // NaN {% endcodeExample %} {% endfunction %}
Trigonometric Functions
{% function 'math.cos($number)', 'returns:number' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Returns the cosine of $number.
$number must be an angle (its units must be compatible with deg) or
unitless. If $number has no units, it is assumed to be in rad.
{% codeExample 'math-cos', false %} @debug math.cos(100deg); // -0.1736481777 @debug math.cos(1rad); // 0.5403023059 @debug math.cos(1); // 0.5403023059 === @debug math.cos(100deg) // -0.1736481777 @debug math.cos(1rad) // 0.5403023059 @debug math.cos(1) // 0.5403023059 {% endcodeExample %} {% endfunction %}
{% function 'math.sin($number)', 'returns:number' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Returns the sine of $number.
$number must be an angle (its units must be compatible with deg) or
unitless. If $number has no units, it is assumed to be in rad.
{% codeExample 'math-sin', false %} @debug math.sin(100deg); // 0.984807753 @debug math.sin(1rad); // 0.8414709848 @debug math.sin(1); // 0.8414709848 === @debug math.sin(100deg) // 0.984807753 @debug math.sin(1rad) // 0.8414709848 @debug math.sin(1) // 0.8414709848 {% endcodeExample %} {% endfunction %}
{% function 'math.tan($number)', 'returns:number' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Returns the tangent of $number.
$number must be an angle (its units must be compatible with deg) or
unitless. If $number has no units, it is assumed to be in rad.
{% codeExample 'math-tan', false %} @debug math.tan(100deg); // -5.6712818196 @debug math.tan(1rad); // 1.5574077247 @debug math.tan(1); // 1.5574077247 === @debug math.tan(100deg) // -5.6712818196 @debug math.tan(1rad) // 1.5574077247 @debug math.tan(1) // 1.5574077247 {% endcodeExample %} {% endfunction %}
{% function 'math.acos($number)', 'returns:number' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Returns the arccosine of $number in deg.
$number must be unitless.
{% codeExample 'math-acos', false %} @debug math.acos(0.5); // 60deg @debug math.acos(2); // NaNdeg === @debug math.acos(0.5) // 60deg @debug math.acos(2) // NaNdeg {% endcodeExample %} {% endfunction %}
{% function 'math.asin($number)', 'returns:number' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Returns the arcsine of $number in deg.
$number must be unitless.
{% codeExample 'math-asin', false %} @debug math.asin(0.5); // 30deg @debug math.asin(2); // NaNdeg === @debug math.asin(0.5) // 30deg @debug math.asin(2) // NaNdeg {% endcodeExample %} {% endfunction %}
{% function 'math.atan($number)', 'returns:number' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Returns the arctangent of $number in deg.
$number must be unitless.
{% codeExample 'math-atan', false %} @debug math.atan(10); // 84.2894068625deg === @debug math.atan(10) // 84.2894068625deg {% endcodeExample %} {% endfunction %}
{% function 'math.atan2($y, $x)', 'returns:number' %} {% compatibility 'dart: "1.25.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Returns the 2-argument arctangent of $y and $x in deg.
$y and $x must have compatible units or be unitless.
{% funFact %}
math.atan2($y, $x) is distinct from atan(math.div($y, $x)) because it
preserves the quadrant of the point in question. For example, math.atan2(1, -1) corresponds to the point (-1, 1) and returns 135deg. In contrast,
math.atan(math.div(1, -1)) and math.atan(math.div(-1, 1)) resolve first
to atan(-1), so both return -45deg.
{% endfunFact %}
{% codeExample 'math-atan2', false %} @debug math.atan2(-1, 1); // 135deg === @debug math.atan2(-1, 1) // 135deg {% endcodeExample %} {% endfunction %}
Unit Functions
{% function 'math.compatible($number1, $number2)', 'comparable($number1, $number2)', 'returns:boolean' %}
Returns whether $number1 and $number2 have compatible units.
If this returns true, $number1 and $number2 can safely be added,
subtracted, and compared. Otherwise, doing so will produce errors.
{% headsUp %}
The global name of this function is
comparable, but when it was added to the
sass:math module the name was changed to
compatible to more clearly convey what the
function does.
{% endheadsUp %}
{% codeExample 'math-compatible', false %} @debug math.compatible(2px, 1px); // true @debug math.compatible(100px, 3em); // false @debug math.compatible(10cm, 3mm); // true === @debug math.compatible(2px, 1px) // true @debug math.compatible(100px, 3em) // false @debug math.compatible(10cm, 3mm) // true {% endcodeExample %} {% endfunction %}
{% function 'math.is-unitless($number)', 'unitless($number)', 'returns:boolean' %}
Returns whether $number has no units.
{% codeExample 'math-is-unitless', false %} @debug math.is-unitless(100); // true @debug math.is-unitless(100px); // false === @debug math.is-unitless(100) // true @debug math.is-unitless(100px) // false {% endcodeExample %} {% endfunction %}
{% function 'math.unit($number)', 'unit($number)', 'returns:quoted string' %}
Returns a string representation of $number's units.
{% headsUp %} This function is intended for debugging; its output format is not guaranteed to be consistent across Sass versions or implementations. {% endheadsUp %}
{% codeExample 'math-unitless', false %} @debug math.unit(100); // "" @debug math.unit(100px); // "px" @debug math.unit(5px * 10px); // "pxpx" @debug math.unit(math.div(5px, 1s)); // "px/s" === @debug math.unit(100) // "" @debug math.unit(100px) // "px" @debug math.unit(5px * 10px) // "pxpx" @debug math.unit(math.div(5px, 1s)) // "px/s" {% endcodeExample %} {% endfunction %}
Other Functions
{% function 'math.div($number1, $number2)', 'returns:number' %} {% compatibility 'dart: "1.33.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}
Returns the result of dividing $number1 by $number2.
Any units shared by both numbers will be canceled out. Units in $number1
that aren't in $number2 will end up in the return value's numerator, and
units in $number2 that aren't in $number1 will end up in its denominator.
{% headsUp %}
For backwards-compatibility purposes, this returns the exact same result
as [the deprecated / operator], including concatenating two strings with a
/ character between them. However, this behavior will be removed
eventually and shouldn't be used in new stylesheets.
[the deprecated `/` operator]: /documentation/breaking-changes/slash-div
{% endheadsUp %}
{% codeExample 'math-div', false %} @debug math.div(1, 2); // 0.5 @debug math.div(100px, 5px); // 20 @debug math.div(100px, 5); // 20px @debug math.div(100px, 5s); // 20px/s === @debug math.div(1, 2) // 0.5 @debug math.div(100px, 5px) // 20 @debug math.div(100px, 5) // 20px @debug math.div(100px, 5s) // 20px/s {% endcodeExample %} {% endfunction %}
{% function 'math.percentage($number)', 'percentage($number)', 'returns:number' %}
Converts a unitless $number (usually a decimal between 0 and 1) to a
percentage.
{% funFact %}
This function is identical to $number * 100%.
{% endfunFact %}
{% codeExample 'math-percentage', false %} @debug math.percentage(0.2); // 20% @debug math.percentage(math.div(100px, 50px)); // 200% === @debug math.percentage(0.2) // 20% @debug math.percentage(math.div(100px, 50px)) // 200% {% endcodeExample %} {% endfunction %}
{% function 'math.random($limit: null)', 'random($limit: null)', 'returns:number' %}
If $limit is null, returns a random decimal number between 0 and 1.
{% codeExample 'math-random', false %} @debug math.random(); // 0.2821251858 @debug math.random(); // 0.6221325814 === @debug math.random() // 0.2821251858 @debug math.random() // 0.6221325814 {% endcodeExample %}
If $limit is a number greater than or equal to 1, returns a random whole
number between 1 and $limit.
{% headsUp %}
random() ignores units in $limit. [This behavior is deprecated] and
random($limit) will return a random integer with the same units as the
$limit argument.
[This behavior is deprecated]: /documentation/breaking-changes/function-units
{% codeExample 'math-random-warning', false %}
@debug math.random(100px); // 42
===
@debug math.random(100px) // 42
{% endcodeExample %}
{% endheadsUp %}
{% codeExample 'math-random-limit', false %} @debug math.random(10); // 4 @debug math.random(10000); // 5373 === @debug math.random(10) // 4 @debug math.random(10000) // 5373 {% endcodeExample %} {% endfunction %}