danog/sass-site
1
0
Fork 0
mirror of https://github.com/danog/sass-site.git synced 2024-11-27 04:24:50 +01:00
Code Issues Packages Projects Releases Wiki Activity

Documentation for new built-in math functions. (#427)

Browse Source
This commit is contained in:
Awjin Ahn 2020-01-17 15:57:09 -08:00 committed by Natalie Weizenbaum
parent 799f85c59a
commit 5e2cb1a6c8
3 changed files with 536 additions and 225 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

225
source/documentation/modules/math.html.erb
View File

@ -1,225 +0,0 @@
---
title: sass:math
---
<%= partial '../snippets/built-in-module-status' %>
<% 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.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.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.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. A list of numbers can be passed
[using `...`][].
[using `...`]: ../at-rules/function#passing-arbitrary-arguments
<% 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. A list of numbers can be passed
[using `...`][].
[using `...`]: ../at-rules/function#passing-arbitrary-arguments
<% 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.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(100px / 50px); // 200%
===
@debug math.percentage(0.2) // 20%
@debug math.percentage(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.
[`null`]: ../values/null
<% 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`.
<% 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 %>
<% 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 %>
<% 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(5px / 1s); // "px/s"
===
@debug math.unit(100) // ""
@debug math.unit(100px) // "px"
@debug math.unit(5px * 10px) // "px*px"
@debug math.unit(5px / 1s) // "px/s"
<% 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 %>

518
source/documentation/modules/math.html.md.erb Normal file
View File

@ -0,0 +1,518 @@
---
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, 1/3); // 4.6415888336
@debug math.pow(5, -2); // 0.04
===
@debug math.pow(10, 2) // 100
@debug math.pow(100, 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(1/3); // 0.5773502692
@debug math.sqrt(-1); // NaN
===
@debug math.sqrt(100) // 10
@debug math.sqrt(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 %>
`atan2($y, $x)` is distinct from `atan($y / $x)` because it preserves the
quadrant of the point in question. For example, `atan2(1, -1)` corresponds
to the point `(-1, 1)` and returns `135deg`. In contrast, `atan(1 / -1)` and
`atan(-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(5px / 1s); // "px/s"
===
@debug math.unit(100) // ""
@debug math.unit(100px) // "px"
@debug math.unit(5px * 10px) // "px*px"
@debug math.unit(5px / 1s) // "px/s"
<% end %>
<% end %>
## Other Functions
<% 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(100px / 50px); // 200%
===
@debug math.percentage(0.2) // 20%
@debug math.percentage(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`.
<% 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 %>

18
source/documentation/variables.html.md.erb
View File

@ -109,6 +109,24 @@ stylesheet with a `!default` flag can be configured.
<%= partial '../code-snippets/example-use-with' %>
## Built-in Variables
Variables that are defined by a [built-in module] cannot be modified.
[built-in module]: modules
<% example(autogen_css: false) do %>
@use "sass:math" as math;
// This assignment will fail.
math.$pi: 0;
===
@use "sass:math" as math
// This assignment will fail.
math.$pi: 0
<% end %>
## Scope
Variables declared at the top level of a stylesheet are *global*. This means