Skip to content

Commit 338532b

Browse files
Awjinnex3
Awjin
authored and
nex3
committed
[More Math Functions] Create the proposal (sass#2779)
1 parent d3a614a commit 338532b

File tree

1 file changed

+322
-0
lines changed

1 file changed

+322
-0
lines changed

‎proposal/more-math-functions.md

Lines changed: 322 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,322 @@
1+
# More Math Functions: Draft 1
2+
3+
*[(Issue)](https://github.com/sass/sass/issues/851)*
4+
5+
This proposal adds the following members to the built-in `sass:math` module.
6+
7+
## Table of Contents
8+
* [Variables](#variables)
9+
* [`$e`](#e)
10+
* [`$pi`](#pi)
11+
* [Functions](#functions)
12+
* [`clamp()`](#clamp)
13+
* [`hypot()`](#hypot)
14+
* [Exponentiation](#exponentiation)
15+
* [`log()`](#log)
16+
* [`pow()`](#pow)
17+
* [`sqrt()`](#sqrt)
18+
* [Trigonometry](#trigonometry)
19+
* [`cos()`](#cos)
20+
* [`sin()`](#sin)
21+
* [`tan()`](#tan)
22+
* [`acos()`](#acos)
23+
* [`asin()`](#asin)
24+
* [`atan()`](#atan)
25+
* [`atan2()`](#atan2)
26+
* [Edge cases](#edge-cases)
27+
28+
## Variables
29+
30+
### `$e`
31+
32+
Equal to the value of the mathematical constant `e` with a precision of 10
33+
digits: `2.718281828`.
34+
35+
### `$pi`
36+
37+
Equal to the value of the mathematical constant `pi` with a precision of 10
38+
digits: `3.141592654`.
39+
40+
## Functions
41+
42+
### `clamp()`
43+
44+
```
45+
clamp($min, $number, $max)
46+
```
47+
48+
* If the units of `$min`, `$number`, and `$max` are not [compatible][] with each
49+
other, throw an error.
50+
* If `$min >= $max`, return `$min`.
51+
* If `$number <= $min`, return `$min`.
52+
* If `$number >= $max`, return `$max`.
53+
* Return `$number`.
54+
55+
[compatible]: ../spec/built_in_modules/math.md#compatible
56+
57+
### `hypot()`
58+
59+
```
60+
hypot($arguments...)
61+
```
62+
63+
* If all arguments are not compatible with each other, throw an error.
64+
* If some arguments have units and some do not, throw an error.
65+
* If all arguments are unitless, the return value is unitless.
66+
* Otherwise, the return value takes the unit of the leftmost argument.
67+
* If any argument is `Infinity`, return `Infinity`.
68+
* Return the square root of the sum of the squares of each argument.
69+
70+
### Exponentiation
71+
72+
#### `log()`
73+
74+
```
75+
log($number, $base: null)
76+
```
77+
78+
* If `$number` has units or `$number < 0`, throw an error.
79+
* If `$base` is null:
80+
* If `$number == 0`, return `-Infinity` as a unitless number.
81+
* If `$number == Infinity`, return `Infinity` as a unitless number.
82+
* Return the [natural log][] of `$number`, as a unitless number.
83+
* Otherwise, if `$base < 0` or `$base == 0` or `$base == 1`, throw an error.
84+
* Otherwise, return the natural log of `$number` divided by the natural log of
85+
`$base`, as a unitless number.
86+
87+
[natural log]: https://en.wikipedia.org/wiki/Natural_logarithm
88+
89+
#### `pow()`
90+
91+
```
92+
pow($base, $exponent)
93+
```
94+
95+
* If `$base` or `$exponent` has units, throw an error.
96+
97+
* If `$exponent == 0`, return `1` as a unitless number.
98+
99+
* Otherwise, if `$exponent == Infinity`:
100+
* If `$base == 1` or `$base == -1`, return `NaN` as a unitless number.
101+
* If `$base < -1` or `$base > 1` and if `$exponent > 0`, *or* if `$base > -1`
102+
and `$base < 1` and `$exponent < 0`, return `Infinity` as a
103+
unitless number.
104+
* Return `0` as a unitless number.
105+
106+
* Otherwise:
107+
* If `$base < 0` and `$exponent` is not an integer, return `NaN` as a unitless
108+
number.
109+
110+
* If `$base == 0` and `$exponent < 0`, or if `$base == Infinity` and
111+
`$exponent > 0`, return `Infinity` as a unitless number.
112+
113+
* If `$base == -0` and `$exponent < 0`, or if `$base == -Infinity` and
114+
`$exponent > 0`:
115+
* If `$exponent` is an odd integer, return `-Infinity` as a unitless number.
116+
* Return `Infinity` as a unitless number.
117+
118+
* If `$base == 0` and `$exponent > 0`, or if `$base == Infinity` and
119+
`$exponent < 0`, return `0` as a unitless number.
120+
121+
* If `$base == -0` and `$exponent > 0`, or if `$base == -Infinity` and
122+
`$exponent < 0`:
123+
* If `$exponent` is an odd integer, return `-0` as a unitless number.
124+
* Return `0` as a unitless number.
125+
126+
* Return `$base` raised to the power of `$exponent`, as a unitless number.
127+
128+
#### `sqrt()`
129+
130+
```
131+
sqrt($number)
132+
```
133+
134+
* If `$number` has units, throw an error.
135+
* If `$number < 0`, return `NaN` as a unitless number.
136+
* If `$number == -0`, return `-0` as a unitless number.
137+
* If `$number == Infinity`, return `Infinity` as a unitless number.
138+
* Return the square root of `$number`, as a unitless number.
139+
140+
### Trigonometry
141+
142+
#### `cos()`
143+
144+
```
145+
cos($number)
146+
```
147+
148+
* If `$number` has units but is not an [angle][], throw an error.
149+
* If `$number` is unitless, treat it as though its unit were `rad`.
150+
* If `$number == Infinity`, return `NaN` as a unitless number.
151+
* Return the [cosine][] of `$number`, as a unitless number.
152+
153+
[angle]: https://drafts.csswg.org/css-values-4/#angles
154+
[cosine]: https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions
155+
156+
#### `sin()`
157+
158+
```
159+
sin($number)
160+
```
161+
162+
* If `$number` has units but is not an angle, throw an error.
163+
* If `$number` is unitless, treat it as though its unit were `rad`.
164+
* If `$number == Infinity`, return `NaN` as a unitless number.
165+
* If `$number == -0`, return `-0` as a unitless number.
166+
* Return the [sine][] of `$number`, as a unitless number.
167+
168+
[sine]: https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions
169+
170+
#### `tan()`
171+
172+
```
173+
tan($number)
174+
```
175+
176+
* If `$number` has units but is not an angle, throw an error.
177+
* If `$number` is unitless, treat it as though its unit were `rad`.
178+
* If `$number == Infinity`, return `NaN` as a unitless number.
179+
* If `$number == -0`, return `-0` as a unitless number.
180+
* If `$number` is equivalent to `90deg +/- 360deg * n`, where `n` is any
181+
integer, return `Infinity` as a unitless number.
182+
* If `$number` is equivalent to `-90deg +/- 360deg * n`, where `n` is any
183+
integer, return `-Infinity` as a unitless number.
184+
* Return the [tangent][] of `$number`, as a unitless number.
185+
186+
[tangent]: https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions
187+
188+
#### `acos()`
189+
190+
```
191+
acos($number)
192+
```
193+
194+
* If `$number` has units, throw an error.
195+
* If `$number < -1` or `$number > 1`, return `NaN` as a number in `rad`.
196+
* If `$number == 1`, return `0rad`.
197+
* Return the [arccosine][] of `$number`, as a number in `rad`.
198+
199+
[arccosine]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties
200+
201+
#### `asin()`
202+
203+
```
204+
asin($number)
205+
```
206+
207+
* If `$number` has units, throw an error.
208+
* If `$number < -1` or `$number > 1`, return `NaN` as a number in `rad`.
209+
* If `$number == -0`, return `-0rad`.
210+
* Return the [arcsine][] of `$number`, as a number in `rad`.
211+
212+
[arcsine]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties
213+
214+
#### `atan()`
215+
216+
```
217+
atan($number)
218+
```
219+
220+
* If `$number` has units, throw an error.
221+
* If `$number == -0`, return `-0rad`.
222+
* If `$number == -Infinity`, return `-0.5rad * pi`.
223+
* If `$number == Infinity`, return `0.5rad * pi`.
224+
* Return the [arctangent][] of `$number`, as a number in `rad`.
225+
226+
[arctangent]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties
227+
228+
#### `atan2()`
229+
230+
> `atan2($y, $x)` is distinct from `atan($y / $x)` because it preserves the
231+
> quadrant of the point in question. For example, `atan2(1, -1)` corresponds to
232+
> the point `(-1, 1)` and returns `0.75rad * pi`. In contrast, `atan(1 / -1)`
233+
> and `atan(-1 / 1)` resolve first to `atan(-1)`, so both return
234+
> `-0.25rad * pi`.
235+
236+
```
237+
atan2($y, $x)
238+
```
239+
240+
* If `$y` and `$x` are not compatible, throw an error.
241+
* If the inputs match one of the following edge cases, return the provided
242+
number in `rad`. Otherwise, return the [2-argument arctangent][] of `$y` and
243+
`$x`, as a number in `rad`.
244+
245+
[2-argument arctangent]: https://en.wikipedia.org/wiki/Atan2
246+
247+
##### Edge cases
248+
249+
<table>
250+
<thead>
251+
<tr>
252+
<td colspan="2"></td>
253+
<th colspan="6" style="text-align: center">X</th>
254+
</tr>
255+
<tr>
256+
<td colspan="2"></td>
257+
<th>−Infinity</th>
258+
<th>-finite</th>
259+
<th>-0</th>
260+
<th>0</th>
261+
<th>finite</th>
262+
<th>Infinity</th>
263+
</tr>
264+
</thead>
265+
<tbody>
266+
<tr>
267+
<th rowspan="6">Y</th>
268+
<th>−Infinity</th>
269+
<td>-0.75 * pi</td>
270+
<td>-0.5 * pi</td>
271+
<td>-0.5 * pi</td>
272+
<td>-0.5 * pi</td>
273+
<td>-0.5 * pi</td>
274+
<td>-0.25 * pi</td>
275+
</tr>
276+
<tr>
277+
<th>-finite</th>
278+
<td>-pi</td>
279+
<td></td>
280+
<td>-0.5 * pi</td>
281+
<td>-0.5 * pi</td>
282+
<td></td>
283+
<td>-0</td>
284+
</tr>
285+
<tr>
286+
<th>-0</th>
287+
<td>-pi</td>
288+
<td>-pi</td>
289+
<td>-pi</td>
290+
<td>-0</td>
291+
<td>-0</td>
292+
<td>-0</td>
293+
</tr>
294+
<tr>
295+
<th>0</th>
296+
<td>pi</td>
297+
<td>pi</td>
298+
<td>pi</td>
299+
<td>0</td>
300+
<td>0</td>
301+
<td>0</td>
302+
</tr>
303+
<tr>
304+
<th>finite</th>
305+
<td>pi</td>
306+
<td></td>
307+
<td>0.5 * pi</td>
308+
<td>0.5 * pi</td>
309+
<td></td>
310+
<td>0</td>
311+
</tr>
312+
<tr>
313+
<th>Infinity</th>
314+
<td>0.75 * pi</td>
315+
<td>0.5 * pi</td>
316+
<td>0.5 * pi</td>
317+
<td>0.5 * pi</td>
318+
<td>0.5 * pi</td>
319+
<td>0.25 * pi</td>
320+
</tr>
321+
</tbody>
322+
</table>

0 commit comments

Comments
 (0)