> For the complete documentation index, see [llms.txt](https://mistborn.gitbook.io/til-coding/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mistborn.gitbook.io/til-coding/javascript/date-and-time.md).

# Date and time

## Creation

* new Date()

  ```javascript
  let now = new Date();
  alert( now ); // shows current date/time
  ```
* new Date(milliseconds)

  ```javascript
  // 0 means 01.01.1970 UTC+0
  let Jan01_1970 = new Date(0);
  alert( Jan01_1970 );

  // now add 24 hours, get 02.01.1970 UTC+0
  let Jan02_1970 = new Date(24 * 3600 * 1000);
  alert( Jan02_1970 );
  ```
* new Date(datestring)

  ```javascript
  // string 用 Date.parse 轉換成時間
  let date = new Date("2017-01-26");
  alert(date);
  ```
* new Date(year, month, date, hours, minutes, seconds, ms)
  * The `year` must have 4 digits: `2013` is okay, `98` is not.
  * The `month` count starts with `0` (Jan), up to `11` (Dec).
  * The `date` parameter is actually the day of month, if absent then `1` is assumed.
  * If `hours/minutes/seconds/ms` is absent, they are assumed to be equal `0`.

    ```javascript
    new Date(2011, 0, 1, 0, 0, 0, 0); // // 1 Jan 2011, 00:00:00
    new Date(2011, 0, 1); // the same, hours etc are 0 by default

    let date = new Date(2011, 0, 1, 2, 3, 4, 567);
    alert( date ); // 1.01.2011, 02:03:04.567
    ```

## Access date components

* getFullYear() 取得年份
*  getMonth() 取得月份 0 - 11
*  getDate() 取得日期 1 - 31
*  getHours(), getMinutes(), getSeconds(), getMilliseconds() 取得對應的時間
*  getDay() 取得星期 0 (sunday) - 6 (saturday)
* 以上方法都是返回當地時間， getUTCFullYear(), getUTCMonth(), getUTCDay() 得到 UTC+0 時間
*  getTime() 從 1970-1-1 00:00:00 UTC+0 開始的 milliseconds
*  getTimezoneOffset() 返回跟 UTC+0 的時間差(分鐘)

  ```javascript
  // if you are in timezone UTC-1, outputs 60
  // if you are in timezone UTC+3, outputs -180
  alert( new Date().getTimezoneOffset() );
  ```

### [Setting date components](https://javascript.info/date#setting-date-components)

* setFullYear(year \[, month, date])
* setMonth(month \[, date])
* setDate(date)
* setHours(hour \[, min, sec, ms])
* setMinutes(min \[, sec, ms])
* setSeconds(sec \[, ms])
* setMilliseconds(ms)
* setTime(milliseconds) (sets the whole date by milliseconds since 01.01.1970 UTC)

除了 setTime() 都有 UTC+0 的時間。

```javascript
let today = new Date();

today.setHours(0);
alert(today); // still today, but the hour is changed to 0

today.setHours(0, 0, 0, 0);
alert(today); // still today, now 00:00:00 sharp.
```

## Autocorrection

```javascript
// date 有自動校對功能
let date = new Date(2013, 0, 32); // 32 Jan 2013 ?!?
alert(date); // ...is 1st Feb 2013!

// 不用思考是是否為閏月
let date = new Date(2016, 1, 28);
date.setDate(date.getDate() + 2);
alert( date ); // 1 Mar 2016

// 取得一段時間後的時間
let date = new Date();
date.setSeconds(date.getSeconds() + 70);
alert( date ); // shows the correct date

// 可以用零或負數
let date = new Date(2016, 0, 2); // 2 Jan 2016
date.setDate(1); // set day 1 of month
alert( date );
date.setDate(0); // min day is 1, so the last day of the previous month is assumed
alert( date ); // 31 Dec 2015
```

## Date to number, date diff

```javascript
// 時間轉換成數字，相當於用 date.getTime()
let date = new Date();
alert(+date); // the number of milliseconds, same as date.getTime()

// 日期可以相減，結果為 ms
let start = new Date(); // start counting
// do the job
for (let i = 0; i < 100000; i++) {
  let doSomething = i * i * i;
}
let end = new Date(); // done
alert( `The loop took ${end - start} ms` );
```

## Date.now()

```javascript
// 計算時間差，等同 new Date().getTime()，但沒有創造 Date 物件
let start = Date.now(); // milliseconds count from 1 Jan 1970
// do the job
for (let i = 0; i < 100000; i++) {
  let doSomething = i * i * i;
}
let end = Date.now(); // done
alert( `The loop took ${end - start} ms` ); // subtract numbers, not dates
```

## Benchmarking

```javascript
// we have date1 and date2, which function faster returns their difference in ms?
function diffSubtract(date1, date2) {
  return date2 - date1;
}

// or
function diffGetTime(date1, date2) {
  return date2.getTime() - date1.getTime();
}

// diffGetTime() 明顯快得多，因為沒有類型轉換，但這並不精確，因為執行 diffSubtract()時，CPU 可能在運行其他東西。
function diffSubtract(date1, date2) {
  return date2 - date1;
}

function diffGetTime(date1, date2) {
  return date2.getTime() - date1.getTime();
}

function bench(f) {
  let date1 = new Date(0);
  let date2 = new Date();

  let start = Date.now();
  for (let i = 0; i < 100000; i++) f(date1, date2);
  return Date.now() - start;
}

alert( 'Time of diffSubtract: ' + bench(diffSubtract) + 'ms' );
alert( 'Time of diffGetTime: ' + bench(diffGetTime) + 'ms' );

function diffSubtract(date1, date2) {
  return date2 - date1;
}

// 多測驗幾次可以增加準確度
function diffGetTime(date1, date2) {
  return date2.getTime() - date1.getTime();
}

function bench(f) {
  let date1 = new Date(0);
  let date2 = new Date();

  let start = Date.now();
  for (let i = 0; i < 100000; i++) f(date1, date2);
  return Date.now() - start;
}

let time1 = 0;
let time2 = 0;

// run bench(upperSlice) and bench(upperLoop) each 10 times alternating
for (let i = 0; i < 10; i++) {
  time1 += bench(diffSubtract);
  time2 += bench(diffGetTime);
}

alert( 'Total time for diffSubtract: ' + time1 );
alert( 'Total time for diffGetTime: ' + time2 );

// JavaScript 對執行很多次的程式碼有優化的效果，因此要將上一個加溫效果
// added for "heating up" prior to the main loop
bench(diffSubtract);
bench(diffGetTime);

// now benchmark
for (let i = 0; i < 10; i++) {
  time1 += bench(diffSubtract);
  time2 += bench(diffGetTime);
}
```

## Date.parse from a string

* `YYYY-MM-DD` – is the date: year-month-day.
* The character `"T"` is used as the delimiter.
* `HH:mm:ss.sss` – is the time: hours, minutes, seconds and milliseconds.
* The optional `'Z'` part denotes the time zone in the format `+-hh:mm`. A single letter `Z` that would mean UTC+0.

```javascript
let ms = Date.parse('2012-01-26T13:51:50.417-07:00');
alert(ms); // 1327611110417  (timestamp)

let date = new Date( Date.parse('2012-01-26T13:51:50.417-07:00') );
alert(date);
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://mistborn.gitbook.io/til-coding/javascript/date-and-time.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.