mirror of
https://github.com/danog/sass-site.git
synced 2024-12-12 09:29:58 +01:00
25d33be440
* document random($limit) behavior whe $limit has units * add breaking change section for random-with-units * add random-with-units link to sidenav
565 lines
16 KiB
Plaintext
565 lines
16 KiB
Plaintext
---
|
|
title: sass:math
|
|
---
|
|
|
|
<%= partial '../snippets/built-in-module-status' %>
|
|
|
|
## Variables
|
|
|
|
<% function 'math.$e' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
Equal to the value of the [mathematical constant *e*][].
|
|
|
|
[mathematical constant *e*]: https://en.wikipedia.org/wiki/E_(mathematical_constant)
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.$e; // 2.7182818285
|
|
===
|
|
@debug math.$e // 2.7182818285
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.$pi' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
Equal to the value of the [mathematical constant *π*][].
|
|
|
|
[mathematical constant *π*]: https://en.wikipedia.org/wiki/Pi
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.$pi; // 3.1415926536
|
|
===
|
|
@debug math.$pi // 3.1415926536
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
## Bounding Functions
|
|
|
|
<% function 'math.ceil($number)', 'ceil($number)', returns: 'number' do %>
|
|
Rounds `$number` up to the next highest whole number.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.clamp($min, $number, $max)', returns: 'number' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
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.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.floor($number)', 'floor($number)', returns: 'number' do %>
|
|
Rounds `$number` down to the next lowest whole number.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.max($number...)', 'max($number...)', returns: 'number' do %>
|
|
Returns the highest of one or more numbers.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.min($number...)', 'min($number...)', returns: 'number' do %>
|
|
Returns the lowest of one or more numbers.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.round($number)', 'round($number)', returns: 'number' do %>
|
|
Rounds `$number` to the nearest whole number.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
## Distance Functions
|
|
|
|
<% function 'math.abs($number)', 'abs($number)', returns: 'number' do %>
|
|
Returns the [absolute value][] of `$number`. If `$number` is negative, this
|
|
returns `-$number`, and if `$number` is positive, it returns `$number` as-is.
|
|
|
|
[absolute value]: https://en.wikipedia.org/wiki/Absolute_value
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.abs(10px); // 10px
|
|
@debug math.abs(-10px); // 10px
|
|
===
|
|
@debug math.abs(10px) // 10px
|
|
@debug math.abs(-10px) // 10px
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.hypot($number...)', returns: 'number' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
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.
|
|
|
|
[vector]: https://en.wikipedia.org/wiki/Euclidean_vector
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
## Exponential Functions
|
|
|
|
<% function 'math.log($number, $base: null)', returns: 'number' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
Returns the [logarithm][] of `$number` with respect to `$base`. If `$base` is
|
|
`null`, the [natural log][] is calculated.
|
|
|
|
`$number` and `$base` must be unitless.
|
|
|
|
[logarithm]: https://en.wikipedia.org/wiki/Logarithm
|
|
[natural log]: https://en.wikipedia.org/wiki/Natural_logarithm
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.log(10); // 2.302585093
|
|
@debug math.log(10, 10); // 1
|
|
===
|
|
@debug math.log(10) // 2.302585093
|
|
@debug math.log(10, 10) // 1
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.pow($base, $exponent)', returns: 'number' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
Raises `$base` [to the power of][] `$exponent`.
|
|
|
|
`$base` and `$exponent` must be unitless.
|
|
|
|
[to the power of]: https://en.wikipedia.org/wiki/Exponentiation
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.sqrt($number)', returns: 'number' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
Returns the [square root][] of `$number`.
|
|
|
|
`$number` must be unitless.
|
|
|
|
[square root]: https://en.wikipedia.org/wiki/Square_root
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
## Trigonometric Functions
|
|
|
|
<% function 'math.cos($number)', returns: 'number' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
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`.
|
|
|
|
[cosine]: https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.sin($number)', returns: 'number' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
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`.
|
|
|
|
[sine]: https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.tan($number)', returns: 'number' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
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`.
|
|
|
|
[tangent]: https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.acos($number)', returns: 'number' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
Returns the [arccosine][] of `$number` in `deg`.
|
|
|
|
`$number` must be unitless.
|
|
|
|
[arccosine]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.acos(0.5); // 60deg
|
|
@debug math.acos(2); // NaNdeg
|
|
===
|
|
@debug math.acos(0.5) // 60deg
|
|
@debug math.acos(2) // NaNdeg
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.asin($number)', returns: 'number' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
Returns the [arcsine][] of `$number` in `deg`.
|
|
|
|
`$number` must be unitless.
|
|
|
|
[arcsine]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.asin(0.5); // 30deg
|
|
@debug math.asin(2); // NaNdeg
|
|
===
|
|
@debug math.asin(0.5) // 30deg
|
|
@debug math.asin(2) // NaNdeg
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.atan($number)', returns: 'number' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
Returns the [arctangent][] of `$number` in `deg`.
|
|
|
|
`$number` must be unitless.
|
|
|
|
[arctangent]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.atan(10); // 84.2894068625deg
|
|
===
|
|
@debug math.atan(10) // 84.2894068625deg
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.atan2($y, $x)', returns: 'number' do %>
|
|
<% impl_status dart: '1.25.0', libsass: false, ruby: false %>
|
|
|
|
Returns the [2-argument arctangent][] of `$y` and `$x` in `deg`.
|
|
|
|
`$y` and `$x` must have compatible units or be unitless.
|
|
|
|
[2-argument arctangent]: https://en.wikipedia.org/wiki/Atan2
|
|
|
|
<% fun_fact do %>
|
|
`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`.
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.atan2(-1, 1); // 135deg
|
|
===
|
|
@debug math.atan2(-1, 1) // 135deg
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
## Unit Functions
|
|
|
|
<% function 'math.compatible($number1, $number2)',
|
|
'comparable($number1, $number2)',
|
|
returns: 'boolean' do %>
|
|
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.
|
|
|
|
[added]: ../operators/numeric
|
|
[subtracted]: ../operators/numeric
|
|
[compared]: ../operators/relational
|
|
|
|
<% heads_up do %>
|
|
The global name of this function
|
|
is <code>compa<strong>ra</strong>ble</code>, but when it was added to the
|
|
`sass:math` module the name was changed
|
|
to <code>compa<strong>ti</strong>ble</code> to more clearly convey what the
|
|
function does.
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.is-unitless($number)',
|
|
'unitless($number)',
|
|
returns: 'boolean' do %>
|
|
Returns whether `$number` has no units.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.is-unitless(100); // true
|
|
@debug math.is-unitless(100px); // false
|
|
===
|
|
@debug math.is-unitless(100) // true
|
|
@debug math.is-unitless(100px) // false
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.unit($number)',
|
|
'unit($number)',
|
|
returns: 'quoted string' do %>
|
|
Returns a string representation of `$number`'s units.
|
|
|
|
<% heads_up do %>
|
|
This function is intended for debugging; its output format is not guaranteed
|
|
to be consistent across Sass versions or implementations.
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.unit(100); // ""
|
|
@debug math.unit(100px); // "px"
|
|
@debug math.unit(5px * 10px); // "px*px"
|
|
@debug math.unit(math.div(5px, 1s)); // "px/s"
|
|
===
|
|
@debug math.unit(100) // ""
|
|
@debug math.unit(100px) // "px"
|
|
@debug math.unit(5px * 10px) // "px*px"
|
|
@debug math.unit(math.div(5px, 1s)) // "px/s"
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
## Other Functions
|
|
|
|
<% function 'math.div($number1, $number2)', returns: 'number' do %>
|
|
<% impl_status dart: '1.33.0', libsass: false, ruby: false %>
|
|
|
|
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.
|
|
|
|
<% heads_up do %>
|
|
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]: ../breaking-changes/slash-div
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.percentage($number)',
|
|
'percentage($number)',
|
|
returns: 'number' do %>
|
|
Converts a unitless `$number` (usually a decimal between 0 and 1) to a
|
|
percentage.
|
|
|
|
<% fun_fact do %>
|
|
This function is identical to `$number * 100%`.
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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%
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function 'math.random($limit: null)',
|
|
'random($limit: null)',
|
|
returns: 'number' do %>
|
|
If `$limit` is `null`, returns a random decimal number between 0 and 1.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.random(); // 0.2821251858
|
|
@debug math.random(); // 0.6221325814
|
|
===
|
|
@debug math.random() // 0.2821251858
|
|
@debug math.random() // 0.6221325814
|
|
<% end %>
|
|
|
|
* * *
|
|
|
|
If `$limit` is a number greater than or equal to 1, returns a random whole
|
|
number between 1 and `$limit`.
|
|
|
|
<% heads_up do %>
|
|
`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]: ../breaking-changes/random-with-units
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.random(100px); // 42
|
|
===
|
|
@debug math.random(100px) // 42
|
|
<% end %>
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@debug math.random(10); // 4
|
|
@debug math.random(10000); // 5373
|
|
===
|
|
@debug math.random(10) // 4
|
|
@debug math.random(10000) // 5373
|
|
<% end %>
|
|
<% end %>
|