-
Notifications
You must be signed in to change notification settings - Fork 22.4k
/
index.md
415 lines (327 loc) · 20.4 KB
/
index.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
---
title: Numbers and dates
slug: Web/JavaScript/Guide/Numbers_and_dates
page-type: guide
---
{{jsSidebar("JavaScript Guide")}} {{PreviousNext("Web/JavaScript/Guide/Expressions_and_operators", "Web/JavaScript/Guide/Text_formatting")}}
This chapter introduces the concepts, objects and functions used to work with and perform calculations using numbers and dates in JavaScript. This includes using numbers written in various bases including decimal, binary, and hexadecimal, as well as the use of the global {{jsxref("Math")}} object to perform a wide variety of mathematical operations on numbers.
## Numbers
In JavaScript, numbers are implemented in [double-precision 64-bit binary format IEEE 754](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) (i.e., a number between ±2^−1022 and ±2^+1023, or about ±10^−308 to ±10^+308, with a numeric precision of 53 bits). Integer values up to ±2^53 − 1 can be represented exactly.
In addition to being able to represent floating-point numbers, the number type has three symbolic values: `+`{{jsxref("Infinity")}}, `-`{{jsxref("Infinity")}}, and {{jsxref("NaN")}} (not-a-number).
See also [JavaScript data types and structures](/en-US/docs/Web/JavaScript/Data_structures) for context with other primitive types in JavaScript.
You can use four types of number literals: decimal, binary, octal, and hexadecimal.
### Decimal numbers
```js-nolint
1234567890
42
```
Decimal literals can start with a zero (`0`) followed by another decimal digit, but if all digits after the leading `0` are smaller than 8, the number is interpreted as an octal number. This is considered a legacy syntax, and number literals prefixed with `0`, whether interpreted as octal or decimal, cause a syntax error in [strict mode](/en-US/docs/Web/JavaScript/Reference/Strict_mode#legacy_octal_literals) — so, use the `0o` prefix instead.
```js-nolint example-bad
0888 // 888 parsed as decimal
0777 // parsed as octal, 511 in decimal
```
### Binary numbers
Binary number syntax uses a leading zero followed by a lowercase or uppercase Latin letter "B" (`0b` or `0B`). If the digits after the `0b` are not 0 or 1, the following {{jsxref("SyntaxError")}} is thrown: "Missing binary digits after 0b".
```js-nolint
0b10000000000000000000000000000000 // 2147483648
0b01111111100000000000000000000000 // 2139095040
0B00000000011111111111111111111111 // 8388607
```
### Octal numbers
The standard syntax for octal numbers is to prefix them with `0o`. For example:
```js-nolint
0O755 // 493
0o644 // 420
```
There's also a legacy syntax for octal numbers — by prefixing the octal number with a zero: `0644 === 420` and `"\045" === "%"`. If the digits after the `0` are outside the range 0 through 7, the number will be interpreted as a decimal number.
```js
const n = 0755; // 493
const m = 0644; // 420
```
[Strict mode](/en-US/docs/Web/JavaScript/Reference/Strict_mode) forbids this octal syntax.
### Hexadecimal numbers
Hexadecimal number syntax uses a leading zero followed by a lowercase or uppercase Latin letter "X" (`0x` or `0X`). If the digits after 0x are outside the range (0123456789ABCDEF), the following {{jsxref("SyntaxError")}} is thrown: "Identifier starts immediately after numeric literal".
```js-nolint
0xFFFFFFFFFFFFFFFFF // 295147905179352830000
0x123456789ABCDEF // 81985529216486900
0XA // 10
```
### Exponentiation
```js-nolint
0e-5 // 0
0e+5 // 0
5e1 // 50
175e-2 // 1.75
1e3 // 1000
1e-3 // 0.001
1E3 // 1000
```
## Number object
The built-in {{jsxref("Number")}} object has properties for numerical constants, such as maximum value, not-a-number, and infinity. You cannot change the values of these properties and you use them as follows:
```js
const biggestNum = Number.MAX_VALUE;
const smallestNum = Number.MIN_VALUE;
const infiniteNum = Number.POSITIVE_INFINITY;
const negInfiniteNum = Number.NEGATIVE_INFINITY;
const notANum = Number.NaN;
```
You always refer to a property of the predefined `Number` object as shown above, and not as a property of a `Number` object you create yourself.
The following table summarizes the `Number` object's properties.
| Property | Description |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| {{jsxref("Number.MAX_VALUE")}} | The largest positive representable number (`1.7976931348623157e+308`) |
| {{jsxref("Number.MIN_VALUE")}} | The smallest positive representable number (`5e-324`) |
| {{jsxref("Number.NaN")}} | Special "not a number" value |
| {{jsxref("Number.NEGATIVE_INFINITY")}} | Special negative infinite value; returned on overflow |
| {{jsxref("Number.POSITIVE_INFINITY")}} | Special positive infinite value; returned on overflow |
| {{jsxref("Number.EPSILON")}} | Difference between `1` and the smallest value greater than `1` that can be represented as a {{jsxref("Number")}} (`2.220446049250313e-16`) |
| {{jsxref("Number.MIN_SAFE_INTEGER")}} | Minimum safe integer in JavaScript (−2^53 + 1, or `−9007199254740991`) |
| {{jsxref("Number.MAX_SAFE_INTEGER")}} | Maximum safe integer in JavaScript (+2^53 − 1, or `+9007199254740991`) |
| Method | Description |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| {{jsxref("Number.parseFloat()")}} | Parses a string argument and returns a floating point number. Same as the global {{jsxref("parseFloat()")}} function. |
| {{jsxref("Number.parseInt()")}} | Parses a string argument and returns an integer of the specified radix or base. Same as the global {{jsxref("parseInt()")}} function. |
| {{jsxref("Number.isFinite()")}} | Determines whether the passed value is a finite number. |
| {{jsxref("Number.isInteger()")}} | Determines whether the passed value is an integer. |
| {{jsxref("Number.isNaN()")}} | Determines whether the passed value is {{jsxref("NaN")}}. More robust version of the original global {{jsxref("isNaN()")}}. |
| {{jsxref("Number.isSafeInteger()")}} | Determines whether the provided value is a number that is a _safe integer_. |
The `Number` prototype provides methods for retrieving information from `Number` objects in various formats. The following table summarizes the methods of `Number.prototype`.
| Method | Description |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| {{jsxref("Number/toExponential", "toExponential()")}} | Returns a string representing the number in exponential notation. |
| {{jsxref("Number/toFixed", "toFixed()")}} | Returns a string representing the number in fixed-point notation. |
| {{jsxref("Number/toPrecision", "toPrecision()")}} | Returns a string representing the number to a specified precision in fixed-point notation. |
## Math object
The built-in {{jsxref("Math")}} object has properties and methods for mathematical constants and functions. For example, the `Math` object's `PI` property has the value of pi (3.141…), which you would use in an application as
```js
Math.PI;
```
Similarly, standard mathematical functions are methods of `Math`. These include trigonometric, logarithmic, exponential, and other functions. For example, if you want to use the trigonometric function sine, you would write
```js
Math.sin(1.56);
```
Note that all trigonometric methods of `Math` take arguments in radians.
The following table summarizes the `Math` object's methods.
<table class="standard-table">
<caption>
Methods of
<code>Math</code>
</caption>
<thead>
<tr>
<th scope="col">Method</th>
<th scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{jsxref("Math.abs", "abs()")}}</td>
<td>Absolute value</td>
</tr>
<tr>
<td>
{{jsxref("Math.sin", "sin()")}},
{{jsxref("Math.cos", "cos()")}},
{{jsxref("Math.tan", "tan()")}}
</td>
<td>Standard trigonometric functions; with the argument in radians.</td>
</tr>
<tr>
<td>
{{jsxref("Math.asin", "asin()")}},
{{jsxref("Math.acos", "acos()")}},
{{jsxref("Math.atan", "atan()")}},
{{jsxref("Math.atan2", "atan2()")}}
</td>
<td>Inverse trigonometric functions; return values in radians.</td>
</tr>
<tr>
<td>
{{jsxref("Math.sinh", "sinh()")}},
{{jsxref("Math.cosh", "cosh()")}},
{{jsxref("Math.tanh", "tanh()")}}
</td>
<td>Hyperbolic functions; argument in hyperbolic angle.</td>
</tr>
<tr>
<td>
{{jsxref("Math.asinh", "asinh()")}},
{{jsxref("Math.acosh", "acosh()")}},
{{jsxref("Math.atanh", "atanh()")}}
</td>
<td>Inverse hyperbolic functions; return values in hyperbolic angle.</td>
</tr>
<tr>
<td>
<p>
{{jsxref("Math.pow", "pow()")}},
{{jsxref("Math.exp", "exp()")}},
{{jsxref("Math.expm1", "expm1()")}},
{{jsxref("Math.log", "log()")}},
{{jsxref("Math.log10", "log10()")}},
{{jsxref("Math.log1p", "log1p()")}},
{{jsxref("Math.log2", "log2()")}}
</p>
</td>
<td>Exponential and logarithmic functions.</td>
</tr>
<tr>
<td>
{{jsxref("Math.floor", "floor()")}},
{{jsxref("Math.ceil", "ceil()")}}
</td>
<td>
Returns the largest/smallest integer less/greater than or equal to an
argument.
</td>
</tr>
<tr>
<td>
{{jsxref("Math.min", "min()")}},
{{jsxref("Math.max", "max()")}}
</td>
<td>
Returns the minimum or maximum (respectively) value of a comma separated
list of numbers as arguments.
</td>
</tr>
<tr>
<td>{{jsxref("Math.random", "random()")}}</td>
<td>Returns a random number between 0 and 1.</td>
</tr>
<tr>
<td>
{{jsxref("Math.round", "round()")}},
{{jsxref("Math.fround", "fround()")}},
{{jsxref("Math.trunc", "trunc()")}},
</td>
<td>Rounding and truncation functions.</td>
</tr>
<tr>
<td>
{{jsxref("Math.sqrt", "sqrt()")}},
{{jsxref("Math.cbrt", "cbrt()")}},
{{jsxref("Math.hypot", "hypot()")}}
</td>
<td>
Square root, cube root, Square root of the sum of square arguments.
</td>
</tr>
<tr>
<td>{{jsxref("Math.sign", "sign()")}}</td>
<td>
The sign of a number, indicating whether the number is positive,
negative or zero.
</td>
</tr>
<tr>
<td>
{{jsxref("Math.clz32", "clz32()")}},<br />{{jsxref("Math.imul", "imul()")}}
</td>
<td>
Number of leading zero bits in the 32-bit binary representation.<br />The
result of the C-like 32-bit multiplication of the two arguments.
</td>
</tr>
</tbody>
</table>
Unlike many other objects, you never create a `Math` object of your own. You always use the built-in `Math` object.
## BigInts
One shortcoming of number values is they only have 64 bits. In practice, due to using IEEE 754 encoding, they cannot represent any integer larger than [`Number.MAX_SAFE_INTEGER`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER) (which is 2<sup>53</sup> - 1) accurately. To solve the need of encoding binary data and to interoperate with other languages that offer wide integers like `i64` (64-bit integers) and `i128` (128-bit integers), JavaScript also offers another data type to represent _arbitrarily large integers_: [`BigInt`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt).
A BigInt can be defined as an integer literal suffixed by `n`:
```js
const b1 = 123n;
// Can be arbitrarily large.
const b2 = -1234567890987654321n;
```
BigInts can also be constructed from number values or string values using the [`BigInt`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/BigInt) constructor.
```js
const b1 = BigInt(123);
// Using a string prevents loss of precision, since long number
// literals don't represent what they seem like.
const b2 = BigInt("-1234567890987654321");
```
Conceptually, a BigInt is just an arbitrarily long sequence of bits which encodes an integer. You can safely do any arithmetic operations without losing precision or over-/underflowing.
```js
const integer = 12 ** 34; // 4.9222352429520264e+36; only has limited precision
const bigint = 12n ** 34n; // 4922235242952026704037113243122008064n
```
Compared to numbers, BigInt values yield higher precision when representing large _integers_; however, they cannot represent _floating-point numbers_. For example, division would round to zero:
```js
const bigintDiv = 5n / 2n; // 2n, because there's no 2.5 in BigInt
```
`Math` functions cannot be used on BigInt values. There is [an open proposal](https://github.com/tc39/proposal-bigint-math) to overload certain `Math` functions like `Math.max()` to allow BigInt values.
Choosing between BigInt and number depends on your use-case and your input's range. The precision of numbers should be able to accommodate most day-to-day tasks already, and BigInts are most suitable for handling binary data.
Read more about what you can do with BigInt values in the [Expressions and Operators](/en-US/docs/Web/JavaScript/Guide/Expressions_and_operators#bigint_operators) section, or the [BigInt reference](/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt).
## Date object
JavaScript does not have a date data type. However, you can use the {{jsxref("Date")}} object and its methods to work with dates and times in your applications. The `Date` object has a large number of methods for setting, getting, and manipulating dates. It does not have any properties.
JavaScript handles dates similarly to Java. The two languages have many of the same date methods, and both languages store dates as the number of milliseconds since midnight at the beginning of January 1, 1970, UTC, with a Unix Timestamp being the number of seconds since the same instant. The instant at the midnight at the beginning of January 1, 1970, UTC is called the [epoch](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date).
The `Date` object range is -100,000,000 days to 100,000,000 days relative to the epoch.
To create a `Date` object:
```js
const dateObjectName = new Date([parameters]);
```
where `dateObjectName` is the name of the `Date` object being created; it can be a new object or a property of an existing object.
Calling `Date` without the `new` keyword returns a string representing the current date and time.
The `parameters` in the preceding syntax can be any of the following:
- Nothing: creates today's date and time. For example, `today = new Date();`.
- A string representing a date, in many different forms. The exact forms supported differ among engines, but the following form is always supported: `YYYY-MM-DDTHH:mm:ss.sssZ`. For example, `xmas95 = new Date("1995-12-25")`. If you omit hours, minutes, or seconds, the value will be set to zero.
- A set of integer values for year, month, and day. For example, `xmas95 = new Date(1995, 11, 25)`.
- A set of integer values for year, month, day, hour, minute, and seconds. For example, `xmas95 = new Date(1995, 11, 25, 9, 30, 0);`.
### Methods of the Date object
The `Date` object methods for handling dates and times fall into these broad categories:
- "set" methods, for setting date and time values in `Date` objects.
- "get" methods, for getting date and time values from `Date` objects.
- "to" methods, for returning string values from `Date` objects.
- parse and UTC methods, for parsing `Date` strings.
With the "get" and "set" methods you can get and set seconds, minutes, hours, day of the month, day of the week, months, and years separately. There is a `getDay` method that returns the day of the week, but no corresponding `setDay` method, because the day of the week is set automatically. These methods use integers to represent these values as follows:
- Seconds and minutes: 0 to 59
- Hours: 0 to 23
- Day: 0 (Sunday) to 6 (Saturday)
- Date: 1 to 31 (day of the month)
- Months: 0 (January) to 11 (December)
- Year: years since 1900
For example, suppose you define the following date:
```js
const xmas95 = new Date("1995-12-25");
```
Then `xmas95.getMonth()` returns 11, and `xmas95.getFullYear()` returns 1995.
The `getTime` and `setTime` methods are useful for comparing dates. The `getTime` method returns the number of milliseconds since the epoch for a `Date` object.
For example, the following code displays the number of days left in the current year:
```js
const today = new Date();
const endYear = new Date(1995, 11, 31, 23, 59, 59, 999); // Set day and month
endYear.setFullYear(today.getFullYear()); // Set year to this year
const msPerDay = 24 * 60 * 60 * 1000; // Number of milliseconds per day
let daysLeft = (endYear.getTime() - today.getTime()) / msPerDay;
daysLeft = Math.round(daysLeft); // Returns days left in the year
```
This example creates a `Date` object named `today` that contains today's date. It then creates a `Date` object named `endYear` and sets the year to the current year. Then, using the number of milliseconds per day, it computes the number of days between `today` and `endYear`, using `getTime` and rounding to a whole number of days.
The `parse` method is useful for assigning values from date strings to existing `Date` objects. For example, the following code uses `parse` and `setTime` to assign a date value to the `ipoDate` object:
```js
const ipoDate = new Date();
ipoDate.setTime(Date.parse("Aug 9, 1995"));
```
### Example
In the following example, the function `JSClock()` returns the time in the format of a digital clock.
```js
function JSClock() {
const time = new Date();
const hour = time.getHours();
const minute = time.getMinutes();
const second = time.getSeconds();
let temp = String(hour % 12);
if (temp === "0") {
temp = "12";
}
temp += (minute < 10 ? ":0" : ":") + minute;
temp += (second < 10 ? ":0" : ":") + second;
temp += hour >= 12 ? " P.M." : " A.M.";
return temp;
}
```
The `JSClock` function first creates a new `Date` object called `time`; since no arguments are given, time is created with the current date and time. Then calls to the `getHours`, `getMinutes`, and `getSeconds` methods assign the value of the current hour, minute, and second to `hour`, `minute`, and `second`.
The following statements build a string value based on the time. The first statement creates a variable `temp`. Its value is `hour % 12`, which is `hour` in the 12-hour system. Then, if the hour is `0`, it gets re-assigned to `12`, so that midnights and noons are displayed as `12:00` instead of `0:00`.
The next statement appends a `minute` value to `temp`. If the value of `minute` is less than 10, the conditional expression adds a string with a preceding zero; otherwise it adds a string with a demarcating colon. Then a statement appends a seconds value to `temp` in the same way.
Finally, a conditional expression appends "P.M." to `temp` if `hour` is 12 or greater; otherwise, it appends "A.M." to `temp`.
{{PreviousNext("Web/JavaScript/Guide/Expressions_and_operators", "Web/JavaScript/Guide/Text_formatting")}}