isNaN - JavaScript

isNaN
=====

Аннотация
---------

Функция **`isNaN()`** определяет является ли литерал или переменная нечисловым значением (`NaN`) или нет. При работе с функцией необходимо проявлять осторожность так как она имеет свои особенности. В качестве альтернативы можно использовать метод `Number.isNaN()` из ECMAScript 6, или дополнительно проверять литерал или переменную на нечисловое значение при помощи `typeof`.

Синтаксис
---------
```

isNaN(значение)
```

### Параметры

`Значение`

Литерал или переменная которые будут проверяться на нечисловое значение.

Описание
--------

### Для чего нужна функция `isNaN`?

В отличие от других возможных значениях в JavaScript, при работе с значением данного типа невозможно полагаться на == и === для определения, является ли переменная или литерал нечисловым значением (`NaN`) или нет, так как проверки `NaN == NaN` и `NaN === NaN` *в качестве значения вернут* `false`. Следовательно, для проверки нужна функция `isNaN`.

#### Примечание

Для альтернативной проверки переменной на NaN без использования функции isNaN() можно воспользоваться конструкцией x !== x
```

var x = NaN

x != x // true
x !== x // true
```

### Генерация значения `NaN`

Значение `NaN` генерируются арифметическими операциями, результатом которых является *undefined* или *unrepresentable*. Такие условия не обязательно обозначают переполнение стека. `NaN` также может являться результатом попытки преобразования числа в строку, или значения, не имеющего эквивалента в простых числовых примитивах.

Например, деление нуля на нуль возвращает `NaN` — *но деление других чисел на 0 не возвращает NaN*.
```

var x = NaN

x != x // true
x !== x // true
```

### *Особенности поведения*

С самых ранних версий функции `isNaN` её поведение для не числовых переменных или литералов было довольно-таки запутанным. Когда аргументом функции `isNaN` является переменная, тип которой не Number, она преобразуется к типу `Number`. Полученное значение затем проверяется, является ли оно `NaN`. Таким образом для не числовых значений, которые можно преобразовать в числовой тип без не-NaN значения (в частности, пустая строка или логические примитивы, которые преобразуются в 0 или 1), возвращаемое значение "false" может быть полной неожиданностью; пустая строка преобразуется в "not a number." Путаница связана с тем, что "not a number" имеет определённое значение, описанное в стандарте IEEE-794 чисел с плавающей точкой. Функцию стоит воспринимать в качестве ответа на вопрос, "Является ли это значение корректным числом по стандарту IEEE-794?"

В следующей версии ECMAScript (ES6) функция `Number.isNaN()` также присутствует. `Number.isNaN(x)` будет надёжным методом для проверки, содержит ли `x` значение `NaN` или нет. Даже с `Number.isNaN`, однако, результатом `NaN` остаётся точное числовое значение, а не просто "not a number".

Пример
------

```js
isNaN(NaN); // true
isNaN(undefined); // true
isNaN({}); // true

isNaN(true); // false
isNaN(null); // false
isNaN(37); // false

// strings
isNaN("37"); // false: "37" преобразуется в число 37 которое не NaN
isNaN("37.37"); // false: "37.37" преобразуется в число 37.37 которое не NaN
isNaN(""); // false: пустая строка преобразуется в 0 которое не NaN
isNaN(" "); // false: строка с пробелом преобразуется в 0 которое не NaN
isNaN("37,5"); // true

// Даты
isNaN(new Date()); // false
isNaN(new Date().toString()); // true

// Пример почему использование isNaN не всегда уместно
isNaN("blabla"); // true: "blabla" преобразовано в число.
// При парсинге преобразуется в число при неудаче возвращает NaN
```

Спецификация
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-isnan-number |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* `NaN`
* `Number.isNaN()`


Error - JavaScript

Error
=====

Экземпляры объекта `Error` выбрасываются при возникновении ошибок во время выполнения. Объект `Error` также может использоваться в качестве базового для пользовательских исключений. Смотрите ниже стандартные встроенные типы ошибок.

Описание
--------

Во время выполнения кода ошибки приводят к созданию и выбрасыванию новых объектов `Error`.

`Error` является сериализуемым объектом (en-US), поэтому он может быть клонирован с помощью `structuredClone()` (en-US) или передан между воркерами с использованием `postMessage()`.

### Типы ошибок

Кроме общего конструктора `Error`, в JavaScript существуют другие встроенные конструкторы ошибок, смотрите раздел Выражения обработки исключений.

`EvalError`

Создаёт экземпляр, представляющий ошибку, возникающую в глобальной функции `eval()`.

`RangeError`

Создаёт экземпляр, представляющий ошибку, возникающую при выходе числовой переменной или параметра за пределы допустимого диапазона.

`ReferenceError`

Создаёт экземпляр, представляющий ошибку, возникающую при разыменовывании недопустимой ссылки.

`SyntaxError`

Создаёт экземпляр, представляющий синтаксическую ошибку, возникающую при разборе исходного кода в функции `eval()`.

`TypeError`

Создаёт экземпляр, представляющий ошибку, возникающую при недопустимом типе для переменной или параметра.

`URIError`

Создаёт экземпляр, представляющий ошибку, возникающую при передаче в функции `encodeURI()` или `decodeURI()` недопустимых параметров.

`AggregateError` (en-US)

Создаёт экземпляр, представляющий несколько ошибок, обёрнутых в одну. Может быть полезно, например, при работе с `Promise.any()`.

`InternalError`
Non-standard

Создаёт экземпляр, представляющий ошибку, возникающую при выбрасывании внутренней ошибки в движке JavaScript. К примеру, ошибки «слишком глубокая рекурсия» («too much recursion»).

Конструктор
-----------

`Error()` (en-US)

Создаёт новый объект `Error`.

Статические методы
------------------

`Error.captureStackTrace()`
Non-standard

Нестандартная функция V8, которая создаёт свойство `stack` у экземпляра `Error`.

`Error.stackTraceLimit`
Non-standard

Нестандартное числовое свойство V8, которое ограничивает количество уровней ошибок, включаемых в трассировку стека.

`Error.prepareStackTrace()`
Non-standard
 Необязательный

Нестандартная функция V8, которая (если задана в пользовательском коде) вызывается JavaScript-движком V8 для выбрасывание исключений, позволяя определять нестандартное форматирование трассировки стека.

Свойства экземпляра
-------------------

Эти свойства определены в `Error.prototype` и есть у всех экземпляров `Error`.

`Error.prototype.constructor`

Функция-конструктор, создающая экземпляр объекта. Для экземпляров `Error` начальным значением является конструктор `Error` (en-US).

`Error.prototype.name`

Представляет название типа ошибки. Начальным значением `Error.prototype.name` является `"Error"`. Подклассы (например, `TypeError` и `SyntaxError`) имеют собственные значения свойства `name`.

`Error.prototype.stack`
Non-standard

Нестандартное свойство, содержащее трассировку стека.

Эти свойства являются собственными свойствами каждого экземпляра `Error`.

* `cause` (en-US)
    + : Причина возникновения текущей ошибки — обычно это другая обнаруженная ошибка. Для созданных пользователем объектов `Error` это значение свойства `cause` второго аргумента конструктора.
    + : Нестандартное свойство Mozilla, определяющее номер символа в строке, в которой возникла ошибка.
* `fileName`
Non-standard

    + : Нестандартное свойство Mozilla, определяющее путь к файлу, в котором возникла ошибка.
* `lineNumber`
Non-standard

    + : Нестандартное свойство Mozilla, определяющее номер строки в файле, где возникла ошибка.
* `message`
    + : Сообщение об ошибке. Для созданных пользователем объектов `Error` это строка, передаваемая в качестве первого аргумента конструктора.
Методы экземпляра
-----------------

`Error.prototype.toString()`

Возвращает строку, представляющую указанный объект. Переопределяет метод `Object.prototype.toString()`.

Примеры
-------

### Выбрасывание обычной ошибки

Обычно, вы создаёте объект `Error` с намерением возбудить ошибку с помощью ключевого слова `throw`. Вы можете обработать ошибку с помощью конструкции `try...catch`:

```js
try {
  throw new Error("Ой!");
} catch (e) {
  console.error(`${e.name}: ${e.message}`);
}
```

### Обработка ошибки конкретного типа

Для обработки только определённых типов ошибок можно делать проверку типа с помощью ключевого слова `instanceof`:

```js
try {
  foo.bar();
} catch (e) {
  if (e instanceof EvalError) {
    console.error(`${e.name}: ${e.message}`);
  } else if (e instanceof RangeError) {
    console.error(`${e.name}: ${e.message}`);
  }
  // и так далее
  else {
    // Если ни один из типов не совпал, то оставляем ошибку необработанной
    throw e;
  }
}
```

### Пользовательские типы ошибок

Вы можете захотеть определить свои собственные типы ошибок, унаследованные от `Error`, чтобы иметь возможность возбуждать их с помощью `throw new MyError()` и использовать `instanceof MyError` для проверки вида ошибки в обработчике исключений. Это помогает делать обработку ошибок более понятной.

Также смотрите обсуждение «Какой способ расширения Error в JavaScript более предпочтителен?» на StackOverflow.

**Предупреждение:** Встроенные подклассы не могут быть надёжно преобразованы в ES6 код, потому что нет возможности создать базовый класс со специфичным `new.target` без `Reflect.construct()`. Требуется дополнительная конфигурация или ручной вызов `Object.setPrototypeOf(this, CustomError.prototype)` в конце конструктора, иначе создаваемый экземпляр не будет экземпляром `CustomError`. Смотрите TypeScript FAQ для получения дополнительной информации.

**Примечание:** Некоторые браузеры включают конструктор `CustomError` в трассировку стека при использовании классов ES2015.

```js
class CustomError extends Error {
  constructor(foo = "bar", ...params) {
    // Передаём все аргументы (включая специфичные для производителя движка) родительскому конструктору
    super(...params);

    // Поддерживаем соответствующую трассировку стека с указанием места возникновения ошибки (доступно только в V8)
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, CustomError);
    }

    this.name = "CustomError";
    // Дополнительная отладочная информация
    this.foo = foo;
    this.date = new Date();
  }
}

try {
  throw new CustomError("baz", "bazMessage");
} catch (e) {
  console.error(e.name); // CustomError
  console.error(e.foo); // baz
  console.error(e.message); // bazMessage
  console.error(e.stack); // stacktrace
}
```

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-error-objects |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Полифил `Error` с поддержкой `cause` в `core-js`
* `throw`
* `try...catch`
* Stack trace API в документации V8


Generator - JavaScript

Generator
=========

**`Генератор`** - это объект, возвращаемый функцией-генератором и соответствующий как "Итерируемому" протоколу, так и протоколу "Итератор".

Конструктор
-----------

Этот объект не может быть инстанциирован напрямую. Вместо этого, экземпляр `Generator` может быть возвращён из функции-генератора:

```js
function\* generator() {
  yield 1;
  yield 2;
  yield 3;
}

const gen = generator(); // "Generator { }"

console.log(gen.next().value); // 1
console.log(generator().next().value); // 1
console.log(generator().next().value); // 1
```

Методы экземпляра
-----------------

`Generator.prototype.next()`

Возвращает значение, полученное выражением `yield`.

`Generator.prototype.return()`

Возвращает заданное значение и заканчивает генератор.

`Generator.prototype.throw()`

Выдаёт ошибку генератора.

Пример
------

### Бесконечный Итератор

```js
function\* idMaker() {
  var index = 0;
  while (true) yield index++;
}

var gen = idMaker(); // "Generator { }"

console.log(gen.next().value); // 0
console.log(gen.next().value); // 1
console.log(gen.next().value); // 2
// ...
```

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-generator-objects |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

### Legacy generators

* The legacy Iterator protocol (en-US)
### ES2015 generators

* Functions
* `function`
* `function expression`
* `Function`
* `function*`
* `function* expression`
* `GeneratorFunction`
* The Iterator protocol


Promise - JavaScript

Promise
=======

Сводка
------

Объект **`Promise`** используется для отложенных и асинхронных вычислений.

Интерактивный пример
--------------------

Синтаксис
---------

```js
new Promise(executor);
new Promise(function(resolve, reject) { ... });
```

### Параметры

executor

 Объект функции с двумя аргументами `resolve` и `reject`. Функция `executor` получает оба аргумента и выполняется сразу, ещё до того как конструктор вернёт созданный объект. Первый аргумент (`resolve`) вызывает успешное исполнение промиса, второй (`reject`) отклоняет его.
 Обычно функция `executor` описывает выполнение какой-то асинхронной работы, по завершении которой необходимо вызвать функцию `resolve` или `reject`. Обратите внимание, что возвращаемое значение функции `executor` игнорируется.

Описание
--------

Интерфейс **`Promise`** (промис) представляет собой обёртку для значения, неизвестного на момент создания промиса. Он позволяет обрабатывать результаты асинхронных операций так, как если бы они были синхронными: вместо конечного результата асинхронного метода возвращается своего рода *обещание* (дословный перевод слова "промис") получить результат в некоторый момент в будущем.

`Promise` может находиться в трёх состояниях:

* *ожидание (pending)*: начальное состояние, не исполнен и не отклонён.
* *исполнено (fulfilled)*: операция завершена успешно.
* *отклонено (rejected)*: операция завершена с ошибкой.

При создании промис находится в *ожидании (pending)*, а затем может стать *исполненным* (*fulfilled)*, вернув полученный результат (значение), или *отклонённым* (*rejected),* вернув причину отказа. В любом из этих случаев вызывается обработчик, прикреплённый к промису методом `then`. (Если в момент назначения обработчика промис уже исполнен или отклонён, обработчик всё равно будет вызван, т.е. асинхронное исполнение промиса и назначение обработчика не будет происходить в «состоянии гонки», как, например, в случае с событиями в DOM.)

Так как методы ``Promise.prototype.then()`` и ``Promise.prototype.catch()`` сами возвращают промис, их можно вызывать цепочкой, создавая *соединения.*

![](/ru/docs/Web/JavaScript/Reference/Global_Objects/Promise/promises.png)

**Примечание:** говорят, что промис находится в состоянии *завершён (settled)* когда он или исполнен или отклонён, т.е. в любом состоянии, кроме ожидания (это лишь форма речи, не являющаяся настоящим состоянием промиса). Также можно встретить термин *исполнен (resolved)* — это значит что промис *завершён* или "заблокирован" в ожидании завершения другого промиса. В статье состояния и fates приводится более подробное описание терминологии.

Свойства
--------

`Promise.length`

Значение свойства всегда равно 1 (количество аргументов конструктора).

`Promise.prototype` (en-US)

Представляет прототип для конструктора `Promise`.

Методы
------

`Promise.all(iterable)`

Ожидает исполнения всех промисов или отклонения любого из них.

Возвращает промис, который исполнится после исполнения всех промисов в `iterable`. В случае, если любой из промисов будет отклонён, `Promise.all` будет также отклонён.

`Promise.allSettled(iterable)`

Ожидает завершения всех полученных промисов (как исполнения так и отклонения).

Возвращает промис, который исполняется когда все полученные промисы завершены (исполнены или отклонены), содержащий массив результатов исполнения полученных промисов.

`Promise.race(iterable)`

Ожидает исполнения или отклонения любого из полученных промисов.

Возвращает промис, который будет исполнен или отклонён с результатом исполнения первого исполненного или отклонённого промиса из `iterable`.

`Promise.reject(reason)`

Возвращает промис, отклонённый из-за `reason`.

`Promise.resolve(value)`

Возвращает промис, исполненный с результатом `value`.

Создание промиса
----------------

Объект `Promise` создаётся при помощи ключевого слова `new` и своего конструктора. Конструктор `Promise` принимает в качестве аргумента функцию, называемую "исполнитель" (*executor function*). Эта функция должна принимать две функции-колбэка в качестве параметров. Первый из них (`resolve`) вызывается, когда асинхронная операция завершилась успешно и вернула результат своего исполнения в виде значения. Второй колбэк (`reject`) вызывается, когда операция не удалась, и возвращает значение, указывающее на причину неудачи, чаще всего объект ошибки.

```js
const myFirstPromise = new Promise((resolve, reject) => {
  // выполняется асинхронная операция, которая в итоге вызовет:
  //
  // resolve(someValue); // успешное завершение
  // или
  // reject("failure reason"); // неудача
});
```

Чтобы снабдить функцию функциональностью промисов, нужно просто вернуть в ней объект `Promise`:

```js
function myAsyncFunction(url) {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open("GET", url);
    xhr.onload = () => resolve(xhr.responseText);
    xhr.onerror = () => reject(xhr.statusText);
    xhr.send();
  });
}
```

Примеры
-------

### Простой пример

```html
Создать промис!
```

```js
let myFirstPromise = new Promise((resolve, reject) => {
  // Мы вызываем resolve(...), когда асинхронная операция завершилась успешно, и reject(...), когда она не удалась.
  // В этом примере мы используем setTimeout(...), чтобы симулировать асинхронный код.
  // В реальности вы, скорее всего, будете использовать XHR, HTML5 API или что-то подобное.
  setTimeout(function () {
    resolve("Success!"); // Ура! Всё прошло хорошо!
  }, 250);
});

myFirstPromise.then((successMessage) => {
  // successMessage - это что угодно, что мы передали в функцию resolve(...) выше.
  // Это необязательно строка, но если это всего лишь сообщение об успешном завершении, это наверняка будет она.
  console.log("Ура! " + successMessage);
});
```

### Продвинутый пример

```html
Создать промис!
```

```html
<button id="btn">Создать Promise!</button>
<div id="log"></div>
```

Данный небольшой пример показывает механизм работы с `Promise`. Метод `testPromise()` вызывается при каждом нажатии на `<button>`. При этом создаётся промис, который успешно выполняется при помощи `window.setTimeout`, со значением `'result'` в случайном интервале от 1 до 3-х секунд.

исполнение промиса протоколируется при помощи продолжения `p1.then`. Это показывает как синхронная часть метода отвязана от асинхронного завершения промиса.

```js
var promiseCount = 0;
function testPromise() {
  var thisPromiseCount = ++promiseCount;

  var log = document.getElementById('log');
  log.insertAdjacentHTML('beforeend', thisPromiseCount +
      ') Запуск (запуск синхронного кода)
');

  // Создаём промис, возвращающее 'result' (по истечении 3-х секунд)
  var p1 = new Promise(
    // Функция разрешения позволяет завершить успешно или
    // отклонить промис
    function(resolve, reject) {
      log.insertAdjacentHTML('beforeend', thisPromiseCount +
          ') Запуск промиса (запуск асинхронного кода)
');
      // Это всего лишь пример асинхронности
      window.setTimeout(
        function() {
          // Промис исполнен!
          resolve(thisPromiseCount)
        }, Math.random() \* 2000 + 1000);
    });

  // Указываем, что сделать с исполненным промисом
  p1.then(
    // Записываем в протокол
    function(val) {
      log.insertAdjacentHTML('beforeend', val +
          ') Промис исполнен (асинхронный код завершён)
');
    });

  log.insertAdjacentHTML('beforeend', thisPromiseCount +
      ') Промис создан (синхронный код завершён)
');
}
```

```js
if ("Promise" in window) {
  btn = document.getElementById("btn");
  btn.addEventListener("click", testPromise);
} else {
  log = document.getElementById("log");
  log.innerHTML =
    "Live example not available as your browser doesn't support the Promise interface.";
}
```

```js
if ("Promise" in window) {
  let btn = document.getElementById("btn");
  btn.addEventListener("click", testPromise);
} else {
  log = document.getElementById("log");
  log.innerHTML =
    "Демонстрация невозможна, поскольку ваш браузер не поддерживает интерфейс <code>Promise<code>.";
}
```

Данный пример запускается при нажатии на кнопку. Для этого вам необходим браузер, поддерживающий `Promise`. При последовательных нажатиях на кнопку с коротким интервалом, вы можете увидеть как различные промиса будут исполнены один за другим.

### Загрузка изображения при помощи XHR

Другой простой пример использования `Promise` и `XMLHttpRequest` для загрузки изображения доступен в репозитории MDNpromise-test на GitHub. Вы также можете посмотреть его в действии. Каждый шаг прокомментирован и вы можете подробно исследовать Promise и XHR.

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-promise-objects |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Спецификация Promises/A+
* Jake Archibald: JavaScript Promises: There and Back Again
* Domenic Denicola: Callbacks, Promises, and Coroutines – Asynchronous Programming Pattern in JavaScript
* Matt Greer: JavaScript Promises ... In Wicked Detail
* Forbes Lindesay: promisejs.org
* Nolan Lawson: We have a problem with promises — Common mistakes with promises
* Promise polyfill
* Udacity: JavaScript Promises


globalThis - JavaScript

globalThis
==========

Глобальное свойство **`globalThis`** содержит значение глобального `this`, который является глобальным объектом.

Интерактивный пример
--------------------

Синтаксис
---------
```

globalThis
```

Описание
--------

Исторически, для доступа к глобальному объекту использовался разный синтаксис в разных средах JavaScript. В вебе вы могли использовать `window` (en-US), `self` или `frames`, но в Worker можно использовать только `self`. В Node.js ничего из этого не работает, поэтому вы должны использовать `global`.

Ключевое слово `this` можно использовать внутри функций в нестрогом режиме. Но в строгом режиме внутри функций и в Модулях `this` равняется `undefined`. Вы можете использовать `Function('return this')()`, но среды, которые отключают `eval()` (en-US), такие как CSP в браузерах, препятствуют использованию `Function` таким способом.

Свойство `globalThis` даёт возможность стандартного доступа к глобальному значению `this` (и как следствие, к глобальному объекту) вне зависимости от окружения. В отличии от похожих свойств, таких как `window` и `self`, оно гарантирует работу как в среде, где есть `window`, так и в среде, где его нет. Таким образом вы можете получить доступ к глобальному объекту даже не зная в какой среде будет запущен код. Чтобы помочь запомнить название, просто запомните, что глобальное значение `this` равно `globalThis`.

### HTML и WindowProxy

Во многих движках `globalThis` будет ссылкой на фактический глобальный объект, но в веб-браузерах из-за соображений безопасности iframe и cross-window он ссылается на `Proxy` вокруг фактического глобального объекта (который вы не можете получить прямым доступом). Это различие редко актуально в обычном использовании, но его важно знать.

### Название

Некоторые другие популярные имена, такие как `self` и `global` были исключены из рассмотрения из-за того, что они могут нарушать совместимость с существующим кодом. Смотрите документ по планированию именования для большей информации.

Примеры
-------

До `globalThis` единственным кросс-платформенным путём получения глобального объекта в любой среде было `Function('return this')()`. Однако, это нарушает CSP в некоторых случаях. Например, es6-shim делает такую проверку:

```js
var getGlobal = function () {
  if (typeof self !== "undefined") {
    return self;
  }
  if (typeof window !== "undefined") {
    return window;
  }
  if (typeof global !== "undefined") {
    return global;
  }
  throw new Error("unable to locate global object");
};

var globals = getGlobal();

if (typeof globals.setTimeout !== "function") {
  // в данном окружении не существует setTimeout!
}
```

С `globalThis` дополнительный поиск глобального объекта в разных средах больше не нужен:

```js
if (typeof globalThis.setTimeout !== "function") {
  // в данном окружении не существует setTimeout!
}
```

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-globalthis |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Array - JavaScript

Array
=====

Объект **`Array`**, как и массивы в других языках программирования, позволяет хранить коллекцию из нескольких элементов под одним именем переменной и имеет методы для выполнения общих операций с массивами.

Описание
--------

Массивы являются спископодобными объектами, чьи прототипы содержат методы для операций обхода и изменения массива. Ни размер JavaScript-массива, ни типы его элементов не являются фиксированными. Поскольку размер массива может увеличиваться и уменьшаться в любое время, то нет гарантии, что массив окажется плотным. То есть, при работе с массивом может возникнуть ситуация, что элемент массива, к которому вы обратитесь, будет пустым и вернёт `undefined`. В целом, это удобная характеристика; но если эта особенность массива не желательна в вашем специфическом случае, вы можете рассмотреть возможность использования типизированных массивов.

Некоторые полагают, что вы не должны использовать массив в качестве ассоциативного массива. В любом случае, вместо него вы можете использовать простые `объекты`, хотя у них есть и свои подводные камни. Смотрите пост Легковесные JavaScript-словари с произвольными ключами*(англ.)* в качестве примера.

### Доступ к элементам массива

Массивы в JavaScript индексируются с нуля: первый элемент массива имеет индекс, равный `0`, а индекс последнего элемента равен значению свойства массива `length` минус 1.

```js
const arr = ["первый элемент", "второй элемент", "последний элемент"];
console.log(arr[0]); // напечатает 'первый элемент'
console.log(arr[1]); // напечатает 'второй элемент'
console.log(arr[arr.length - 1]); // напечатает 'последний элемент'
```

Элементы массива являются свойствами, точно такими же, как, например, свойство `toString`, однако попытка получить элемент массива по имени его свойства приведёт к синтаксической ошибке, поскольку имя свойства не является допустимым именем JavaScript:

```js
console.log(arr.0); // синтаксическая ошибка
```

Это не особенность массивов или их свойств. В JavaScript к свойствам, начинающимся с цифры, невозможно обратиться посредством точечной нотации; к ним можно обратиться только с помощью скобочной нотации. Например, если у вас есть объект со свойством, названным `'3d'`, вы сможете обратиться к нему только посредством скобочной нотации. Примеры:

```js
const years = [1950, 1960, 1970, 1980, 1990, 2000, 2010];
console.log(years.0);   // синтаксическая ошибка
console.log(years[0]);  // работает как положено
```

```js
renderer.3d.setTexture(model, 'character.png');     // синтаксическая ошибка
renderer['3d'].setTexture(model, 'character.png');  // работает как положено
```

Обратите внимание, что во втором примере `3d` заключено в кавычки: `'3d'`. Индексы можно заключать в кавычки (например `years['2']` вместо `years[2]`), но в этом нет необходимости. Значение 2 в выражении `years[2]` будет неявно приведено к строке движком JavaScript через метод преобразования `toString`. Именно по этой причине ключи `'2'` и `'02'` будут ссылаться на два разных элемента в объекте `years` и следующий пример выведет `true`:

```js
console.log(years["2"] != years["02"]);
```

Аналогично, к свойствам объекта, являющимся зарезервированными словами(!) можно получить доступ только посредством скобочной нотации:

```js
const promise = {
  var: "text",
  array: [1, 2, 3, 4],
};

console.log(promise["array"]);
```

### Взаимосвязь свойства `length` с числовыми свойствами

Свойство массивов `length` взаимосвязано с числовыми свойствами. Некоторые встроенные методы массива (например, `join`, `slice`, `indexOf` и т.д.) учитывают значение свойства `length` при своём вызове. Другие методы (например, `push`, `splice` и т.д.) в результате своей работы также обновляют свойство `length` массива.

```js
const fruits = [];
fruits.push("банан", "яблоко", "персик");

console.log(fruits.length); // 3
```

При установке свойства в массиве, если свойство имеет действительный индекс и этот индекс выходит за пределы текущих границ массива, движок соответствующим образом обновит свойство `length`:

```js
fruits[5] = "манго";
console.log(fruits[5]); // 'манго'
console.log(Object.keys(fruits)); // ['0', '1', '2', '5']
console.log(fruits.length); // 6
```

Увеличиваем свойство `length`

```js
fruits.length = 10;
console.log(Object.keys(fruits)); // ['0', '1', '2', '5']
console.log(fruits.length); // 10
```

Однако, уменьшение свойства `length` приведёт к удалению элементов.

```js
fruits.length = 2;
console.log(Object.keys(fruits)); // ['0', '1']
console.log(fruits.length); // 2
```

Более подробно эта тема освещена на странице, посвящённой свойству `Array.length`.

### Создание массива с использованием результата сопоставления

Результатом сопоставления регулярного выражения строке является JavaScript-массив. Этот массив имеет свойства и элементы, предоставляющие информацию о сопоставлении. Подобные массивы возвращаются методами `RegExp.exec`, `String.match` и `String.replace`. Чтобы было проще понять, откуда и какие появились свойства и элементы, посмотрите следующий пример и обратитесь к таблице ниже:

```js
// Сопоставляется с одним символом d, за которым следует один
// или более символов b, за которыми следует один символ d
// Запоминаются сопоставившиеся символы b и следующий за ними символ d
// Регистр игнорируется

const myRe = /d(b+)(d)/i;
const myArray = myRe.exec("cdbBdbsbz");
```

Свойства и элементы, возвращаемые из данного сопоставления, описаны ниже:

| Свойство/Элемент | Описание | Пример |
| --- | --- | --- |
| `input` | Свойство только для чтения, отражающее оригинальную строку, с которой сопоставлялось регулярное выражение. | cdbBdbsbz |
| `index` | Свойство только для чтения, являющееся индексом (отсчёт начинается с нуля) в строке, с которого началось сопоставление. | 1 |
| `[0]` | Элемент только для чтения, определяющий последние сопоставившиеся символы. | dbBd |
| `[1], ...[n]` | Элементы только для чтения, определяющие сопоставившиеся подстроки, заключённые в круглые скобки, если те включены в регулярное выражение. Количество возможных подстрок не ограничено. | [1]: bB [2]: d |

Конструктор
-----------

`Array()` (en-US)

Создаёт новый объект `Array`.

Статические свойства
--------------------

`Array[@@species]`

Возвращает конструктор `Array`.

Статические методы
------------------

`Array.from()`

Создаёт новый экземпляр `Array` из итерируемого или массивоподобного объекта.

`Array.fromAsync()` (en-US)

Создаёт новый экземпляр `Array` из асинхронно итерируемого, итерируемого или массивоподобного объекта.

`Array.isArray()`

Возвращает `true` если аргумент является массивом и `false` в противном случае.

`Array.of()`

Создаёт новый экземпляр `Array` с переменным количеством аргументов, независимо от количества или типа аргументов.

Свойства экземпляра
-------------------

Эти свойства определены в `Array.prototype` и есть у всех экземпляров `Array`.

`Array.prototype.constructor`

Функция-конструктор, создающая экземпляр объекта. Для экземпляров `Array` начальным значением является конструктор `Array` (en-US).

`Array.prototype[@@unscopables]`

Содержит имена свойств, которые не включены в стандарт ECMAScript до версии ES2015 и которые игнорируются оператором `with`.

Собственные свойства каждого экземпляра `Array`:

`length`

Отражает количество элементов в массиве.

Методы экземпляра
-----------------

`Array.prototype.at()`

Возвращает элемент массива с указанным индексом. Принимает отрицательные значения, для которых отсчёт идёт с конца массива.

`Array.prototype.concat()`

Возвращает новый массив, который является объединением текущего с другими массивами или значениями.

`Array.prototype.copyWithin()`

Копирует последовательность элементов внутри массива.

`Array.prototype.entries()`

Возвращает новый объект *array iterator*, который содержит пары ключ/значение для каждого индекса в массиве.

`Array.prototype.every()`

Возвращает `true` если для каждого элемента массива переданная в качестве аргумента функция возвращает `true`.

`Array.prototype.fill()`

Заполняет все элементы массива от начального индекса до последнего указанным значением.

`Array.prototype.filter()`

Возвращает новый массив, содержащий все элементы исходного массива, для которых переданная функция вернула `true`.

`Array.prototype.find()`

Возвращает значение первого элемента массива, для которого переданная в качестве аргумента функция возвращает `true`, или `undefined` если таких элементов нет.

`Array.prototype.findIndex()`

Возвращает индекс первого элемента массива, для которого переданная в качестве аргумента функция возвращает `true`, или `-1` если таких элементов нет.

`Array.prototype.findLast()` (en-US)

Возвращает значение последнего элемента массива, для которого переданная в качестве аргумента функция возвращает `true`, или `undefined` если таких элементов нет.

`Array.prototype.findLastIndex()` (en-US)

Возвращает индекс последнего элемента массива, для которого переданная в качестве аргумента функция возвращает `true`, или `-1` если таких элементов нет.

`Array.prototype.flat()`

Возвращает новый массив, содержащий элементы всех вложенных массивов до указанной глубины.

`Array.prototype.flatMap()`

Возвращает новый массив, сформированный вызовом переданной функции с каждым элементом, а затем «уплощённый» на один уровень.

`Array.prototype.forEach()`

Вызывает функцию для каждого элемента массива.

`Array.prototype.includes()`

Возвращает `true`, если массив содержит переданное значение и `false` в противном случае.

`Array.prototype.indexOf()`

Возвращает первый (наименьший) индекс, по которому может быть найден переданный элемент.

`Array.prototype.join()`

Объединяет все элементы массива в строку.

`Array.prototype.keys()`

Возвращает новый объект *array iterator*, который содержит ключи каждого индекса массива.

`Array.prototype.lastIndexOf()`

Возвращает последний (наибольший) индекс, по которому может быть найден переданный элемент или `-1` если таких элементов нет.

`Array.prototype.map()`

Возвращает новый массив, содержащий результат применения переданной функции к каждому элементу исходного массива.

`Array.prototype.pop()`

Удаляет последний элемент массива и возвращает его значение.

`Array.prototype.push()`

Добавляет один или более элементов в конец массива и возвращает новое значение `length` массива.

`Array.prototype.reduce()`

Вызывает указанную функцию-редьюсер для каждого элемента массива (слева направо) для получения единственного значения.

`Array.prototype.reduceRight()`

Вызывает указанную функцию-редьюсер для каждого элемента массива (справа налево) для получения единственного значения.

`Array.prototype.reverse()`

Изменяет порядок элементов массива *на месте* (то есть изменяя исходный массив) на обратный (первый станет последним, последний — первым).

`Array.prototype.shift()`

Удаляет первый элемент массива и возвращает его значение.

`Array.prototype.slice()`

Извлекает часть массива и возвращает её в виде нового массива.

`Array.prototype.some()`

Возвращает `true` если хотя бы для одного элемента массива переданная в качестве аргумента функция возвращает `true`.

`Array.prototype.sort()`

Сортирует элементы массива *на месте* (то есть изменяя исходный массив) и возвращает массив.

`Array.prototype.splice()`

Добавляет и/или удаляет элементы массива.

`Array.prototype.toLocaleString()`

Возвращает локализованную строку, представляющую исходный массив и его элементы. Переопределяет метод `Object.prototype.toLocaleString()`.

`Array.prototype.toReversed()` (en-US)

Возвращает новый массив с элементами в обратном порядке без изменения исходного массива.

`Array.prototype.toSorted()` (en-US)

Возвращает новый массив с отсортированными по возрастанию элементами без изменения исходного массива.

`Array.prototype.toSpliced()` (en-US)

Возвращает новый массив с удалёнными и/или заменёнными элементами без изменения исходного массива.

`Array.prototype.toString()`

Возвращает строку, представляющую исходный массив и его элементы. Переопределяет метод `Object.prototype.toString()`.

`Array.prototype.unshift()`

Добавляет один или более элементов в начало массива и возвращает новое значение `length` массива.

`Array.prototype.values()`

Возвращает новый объект *array iterator*, который содержит значения каждого индекса массива.

`Array.prototype.with()` (en-US)

Возвращает новый массив с заменённым значением элемента с указанным индексом без изменения исходного массива.

`Array.prototype[@@iterator]()`

Псевдоним метода `values()`.

Примеры
-------

### Пример: создание массива

Следующий пример создаёт массив `msgArray` с длиной 0, присваивает значения элементам `msgArray[0]` и `msgArray[99]`, что изменяет длину массива на 100.

```js
const msgArray = [];
msgArray[0] = "Привет";
msgArray[99] = "мир";

if (msgArray.length === 100) {
  console.log("Длина равна 100.");
}
```

### Создание массива

```js
const fruits = ["Яблоко", "Банан"];

console.log(fruits.length);
// 2
```

### Доступ к элементу массива по индексу

```js
const first = fruits[0];
// Яблоко

const last = fruits[fruits.length - 1];
// Банан
```

### Итерирование по массиву

```js
fruits.forEach(function (item, index, array) {
  console.log(item, index);
});
// Яблоко 0
// Банан 1
```

### Добавление элемента в конец массива

```js
const newLength = fruits.push("Апельсин");
// ["Яблоко", "Банан", "Апельсин"]
```

### Удаление последнего элемента массива

```js
const last = fruits.pop(); // удалим Апельсин (из конца)
// ["Яблоко", "Банан"];
```

### Удаление первого элемента массива

```js
const first = fruits.shift(); // удалим Яблоко (из начала)
// ["Банан"];
```

### Добавление элемента в начало массива

```js
const newLength = fruits.unshift("Клубника"); // добавляет в начало
// ["Клубника", "Банан"];
```

### Поиск номера элемента в массиве

```js
fruits.push("Манго");
// ["Клубника", "Банан", "Манго"]

const pos = fruits.indexOf("Банан");
// 1
```

### Удаление элемента с определённым индексом

```js
const removedItem = fruits.splice(pos, 1); // так можно удалить элемент

// ["Клубника", "Манго"]
```

### Удаление нескольких элементов, начиная с определённого индекса

```js
const vegetables = ["Капуста", "Репа", "Редиска", "Морковка"];
console.log(vegetables);
// ["Капуста", "Репа", "Редиска", "Морковка"]

const start = 1;
const deleteCount = 2;

const removedItems = vegetables.splice(start, deleteCount);
// так можно удалить элементы, deleteCount определяет количество элементов для удаления,
// начиная с позиции(pos) и далее в направлении конца массива.

console.log(vegetables);
// ["Капуста", "Морковка"] (исходный массив изменён)

console.log(removedItems);
// ["Репа", "Редиска"]
```

### Создание копии массива

```js
const shallowCopy = fruits.slice(); // так можно создать копию массива
// ["Клубника", "Манго"]
```

### Пример: создание двумерного массива

Следующий код создаёт шахматную доску в виде двумерного массива строк. Затем он перемещает пешку путём копирования символа 'p' в позиции (6,4) на позицию (4,4). Старая позиция (6,4) затирается пустым местом.

```js
const board = [
  ["R", "N", "B", "Q", "K", "B", "N", "R"],
  ["P", "P", "P", "P", "P", "P", "P", "P"],
  [" ", " ", " ", " ", " ", " ", " ", " "],
  [" ", " ", " ", " ", " ", " ", " ", " "],
  [" ", " ", " ", " ", " ", " ", " ", " "],
  [" ", " ", " ", " ", " ", " ", " ", " "],
  ["p", "p", "p", "p", "p", "p", "p", "p"],
  ["r", "n", "b", "q", "k", "b", "n", "r"],
];

console.log(board.join("\n") + "\n\n");

// Двигаем королевскую пешку вперёд на две клетки
board[4][4] = board[6][4];
board[6][4] = " ";
console.log(board.join("\n"));
```

Ниже показан вывод:
```

R,N,B,Q,K,B,N,R
P,P,P,P,P,P,P,P
 , , , , , , ,
 , , , , , , ,
 , , , , , , ,
 , , , , , , ,
p,p,p,p,p,p,p,p
r,n,b,q,k,b,n,r

R,N,B,Q,K,B,N,R
P,P,P,P,P,P,P,P
 , , , , , , ,
 , , , , , , ,
 , , , ,p, , ,
 , , , , , , ,
p,p,p,p, ,p,p,p
r,n,b,q,k,b,n,r
```

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-array-objects |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Упорядоченные наборы данных
* `TypedArray`
* `ArrayBuffer`


Int8Array - JavaScript

Int8Array
=========

Объект **`Int8Array`** представляет типизированный массив 8-разрядных целых значений. Содержимое инициализируется значением 0. Создав экземпляр **`Int8Array`**, возможно получить доступ к элементам массива, используя методы объекта или стандартный синтаксис доступа к элементу массива по его индексу (с помощью скобочной нотации).

Syntax
------
```

new Int8Array(); // new in ES2017
new Int8Array(length);
new Int8Array(typedArray);
new Int8Array(object);
new Int8Array(buffer [, byteOffset [, length]]);
```

Для более детальной информации о синтаксисе конструктора смотрите *TypedArray*.

Properties
----------

`Int8Array.BYTES_PER_ELEMENT`

Возвращает числовое значение размера элемента массива. `1` в случае с `Int8Array`.

Int8Array.length

Статическая длина конструктора `Int8Array`, всегда равна `3` (т.к. конструктор принимает до 3 аргументов). Чтобы узнать длину созданного массива, see `Int8Array.prototype.length` (en-US).

`Int8Array.name` (en-US)

Возвращает строчное значение имени конструктора. В случае с `Int8Array`: "Int8Array".

`Int8Array.prototype` (en-US)

Прототип для *TypedArray* objects.

Methods
-------

`Int8Array.from()` (en-US)

Creates a new `Int8Array` from an array-like or iterable object. See also `Array.from()`.

`Int8Array.of()` (en-US)

Creates a new `Int8Array` with a variable number of arguments. See also `Array.of()`.

`Int8Array` prototype
---------------------

All `Int8Array` objects inherit from `%TypedArray%.prototype` (en-US).

### Properties

`Int8Array.prototype.constructor`

Returns the function that created an instance's prototype. This is the `Int8Array` constructor by default.

`Int8Array.prototype.buffer` (en-US) Только для чтения

Returns the `ArrayBuffer` referenced by the `Int8Array` Fixed at construction time and thus **read only**.

`Int8Array.prototype.byteLength` (en-US) Только для чтения

Returns the length (in bytes) of the `Int8Array` from the start of its `ArrayBuffer`. Fixed at construction time and thus **read only.**

`Int8Array.prototype.byteOffset` (en-US) Только для чтения

Returns the offset (in bytes) of the `Int8Array` from the start of its `ArrayBuffer`. Fixed at construction time and thus **read only.**

`Int8Array.prototype.length` (en-US) Только для чтения

Returns the number of elements hold in the `Int8Array`. Fixed at construction time and thus **read only.**

### Methods

`Int8Array.prototype.copyWithin()` (en-US)

Copies a sequence of array elements within the array. See also `Array.prototype.copyWithin()`.

`Int8Array.prototype.entries()` (en-US)

Returns a new `Array Iterator` object that contains the key/value pairs for each index in the array. See also `Array.prototype.entries()`.

`Int8Array.prototype.every()` (en-US)

Tests whether all elements in the array pass the test provided by a function. See also `Array.prototype.every()`.

`Int8Array.prototype.fill()` (en-US)

Fills all the elements of an array from a start index to an end index with a static value. See also `Array.prototype.fill()`.

`Int8Array.prototype.filter()` (en-US)

Creates a new array with all of the elements of this array for which the provided filtering function returns true. See also `Array.prototype.filter()`.

`Int8Array.prototype.find()` (en-US)

Returns the found value in the array, if an element in the array satisfies the provided testing function or `undefined` if not found. See also `Array.prototype.find()`.

`Int8Array.prototype.findIndex()` (en-US)

Returns the found index in the array, if an element in the array satisfies the provided testing function or -1 if not found. See also `Array.prototype.findIndex()`.

`Int8Array.prototype.forEach()` (en-US)

Calls a function for each element in the array. See also `Array.prototype.forEach()`.

`Int8Array.prototype.includes()` (en-US)
Экспериментальная возможность

Determines whether a typed array includes a certain element, returning `true` or `false` as appropriate. See also `Array.prototype.includes()`.

`Int8Array.prototype.indexOf()` (en-US)

Returns the first (least) index of an element within the array equal to the specified value, or -1 if none is found. See also `Array.prototype.indexOf()`.

`Int8Array.prototype.join()`

Joins all elements of an array into a string. See also `Array.prototype.join()`.

`Int8Array.prototype.keys()` (en-US)

Returns a new `Array Iterator` that contains the keys for each index in the array. See also `Array.prototype.keys()`.

`Int8Array.prototype.lastIndexOf()` (en-US)

Returns the last (greatest) index of an element within the array equal to the specified value, or -1 if none is found. See also `Array.prototype.lastIndexOf()`.

`Int8Array.prototype.map()` (en-US)

Creates a new array with the results of calling a provided function on every element in this array. See also `Array.prototype.map()`.

`Int8Array.prototype.move()`
Non-standard
 Не реализовано

Former non-standard version of `Int8Array.prototype.copyWithin()` (en-US).

`Int8Array.prototype.reduce()` (en-US)

Apply a function against an accumulator and each value of the array (from left-to-right) as to reduce it to a single value. See also `Array.prototype.reduce()`.

`Int8Array.prototype.reduceRight()` (en-US)

Apply a function against an accumulator and each value of the array (from right-to-left) as to reduce it to a single value. See also `Array.prototype.reduceRight()`.

`Int8Array.prototype.reverse()` (en-US)

Reverses the order of the elements of an array — the first becomes the last, and the last becomes the first. See also `Array.prototype.reverse()`.

`Int8Array.prototype.set()`

Stores multiple values in the typed array, reading input values from a specified array.

`Int8Array.prototype.slice()` (en-US)

Extracts a section of an array and returns a new array. See also `Array.prototype.slice()`.

`Int8Array.prototype.some()` (en-US)

Returns true if at least one element in this array satisfies the provided testing function. See also `Array.prototype.some()`.

`Int8Array.prototype.sort()` (en-US)

Sorts the elements of an array in place and returns the array. See also `Array.prototype.sort()`.

`Int8Array.prototype.subarray()` (en-US)

Returns a new `Int8Array` from the given start and end element index.

`Int8Array.prototype.values()` (en-US)

Returns a new `Array Iterator` object that contains the values for each index in the array. See also `Array.prototype.values()`.

`Int8Array.prototype.toLocaleString()` (en-US)

Returns a localized string representing the array and its elements. See also `Array.prototype.toLocaleString()`.

`Int8Array.prototype.toString()` (en-US)

Returns a string representing the array and its elements. See also `Array.prototype.toString()`.

`Int8Array.prototype[@@iterator]()` (en-US)

Returns a new `Array Iterator` object that contains the values for each index in the array.

Examples
--------

Different ways to create an `Int8Array`:

```js
// From a length
var int8 = new Int8Array(2);
int8[0] = 42;
console.log(int8[0]); // 42
console.log(int8.length); // 2
console.log(int8.BYTES\_PER\_ELEMENT); // 1

// From an array
var arr = new Int8Array([21, 31]);
console.log(arr[1]); // 31

// From another TypedArray
var x = new Int8Array([21, 31]);
var y = new Int8Array(x);
console.log(y[0]); // 21

// From an ArrayBuffer
var buffer = new ArrayBuffer(8);
var z = new Int8Array(buffer, 1, 4);

// From an iterable
var iterable = (function\* () {
  yield\* [1, 2, 3];
})();
var int8 = new Int8Array(iterable);
// Int8Array[1, 2, 3]
```

Specifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # table-49 |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Compatibility notes
-------------------

Starting with ECMAScript 2015, `Int8Array` constructors require to be constructed with a `new` operator. Calling a `Int8Array` constructor as a function without `new`, will throw a `TypeError` from now on.

```js
var dv = Int8Array([1, 2, 3]);
// TypeError: calling a builtin Int8Array constructor
// without new is forbidden
```

```js
var dv = new Int8Array([1, 2, 3]);
```

See also
--------

* JavaScript typed arrays
* `ArrayBuffer`
* `DataView`


RangeError - JavaScript

RangeError
==========

Объект **`RangeError`** представляет ошибку, возникающую, когда значение не входит в множество или диапазон допустимых значений.

Описание
--------

`RangeError` возникает при попытке передать в качестве аргумента функции значение, которое не входит в диапазон допустимых значений.

Это может происходить в разных случаях:

* при передаче значения, которое не является одной из допустимых строк, в `String.prototype.normalize()`,
* при попытке создать массив недопустимой длины с помощью конструктора `Array`,
* при передаче недопустимых значений в такие методы, как `Number.prototype.toExponential()`, `Number.prototype.toFixed()` или `Number.prototype.toPrecision()`.

`RangeError` является сериализуемым объектом (en-US), поэтому он может быть клонирован с помощью `structuredClone()` (en-US) или передан между воркерами с использованием `postMessage()`.

`RangeError` является подклассом `Error`.

Конструктор
-----------

`RangeError()` (en-US)

Создаёт новый объект `RangeError`.

Свойства экземпляра
-------------------

*Также наследует свойства экземпляра своего родителя `Error`*.

Эти свойства определены в `RangeError.prototype` и есть у всех экземпляров `RangeError`.

`RangeError.prototype.constructor`

Функция-конструктор, создающая экземпляр объекта. Для экземпляров `RangeError` начальным значением является конструктор `RangeError` (en-US).

`RangeError.prototype.name`

Представляет название типа ошибки. Начальным значением `RangeError.prototype.name` является `"RangeError"`.

Методы экземпляра
-----------------

*Наследует методы экземпляра своего родителя `Error`*.

Примеры
-------

### Использование `RangeError` для цифровых значений

```js
function check(n) {
  if (!(n >= -500 && n <= 500)) {
    throw new RangeError("Аргумент должен быть в диапазоне между -500 и 500.");
  }
}

try {
  check(2000);
} catch (error) {
  if (error instanceof RangeError) {
    // Обработка ошибки
  }
}
```

### Использование `RangeError` для нецифровых значений

```js
function check(value) {
  if (!["яблоко", "банан", "морковь"].includes(value)) {
    throw new RangeError(
      'Аргумент должен иметь значение "яблоко", "банан" или "морковь".',
    );
  }
}

try {
  check("капуста");
} catch (error) {
  if (error instanceof RangeError) {
    // Обработка ошибки
  }
}
```

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-native-error-types-used-in-this-standard-rangeerror |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* `Error`
* `Array`
* `Number.prototype.toExponential()`
* `Number.prototype.toFixed()`
* `Number.prototype.toPrecision()`
* `String.prototype.normalize()`


ReferenceError - JavaScript

ReferenceError
==============

Объект **`ReferenceError`** представляет ошибку, возникающую при обращении к переменной, которая не существует (или не была инициализирована) в текущей области видимости.

`ReferenceError` является сериализуемым объектом (en-US), поэтому он может быть клонирован с помощью `structuredClone()` (en-US) или передан между воркерами с использованием `postMessage()`.

`RangeReferenceErrorError` является подклассом `Error`.

Конструктор
-----------

`ReferenceError()` (en-US)

Создаёт новый объект `ReferenceError`.

Свойства экземпляра
-------------------

*Также наследует свойства экземпляра своего родителя `Error`*.

Эти свойства определены в `ReferenceError.prototype` и есть у всех экземпляров `ReferenceError`.

`ReferenceError.prototype.constructor`

Функция-конструктор, создающая экземпляр объекта. Для экземпляров `ReferenceError` начальным значением является конструктор `ReferenceError` (en-US).

`ReferenceError.prototype.name`

Представляет название типа ошибки. Начальным значением `ReferenceError.prototype.name` является `"ReferenceError"`.

Методы экземпляра
-----------------

*Наследует методы экземпляра своего родителя `Error`*.

Примеры
-------

### Перехват `ReferenceError`

```js
try {
  let a = undefinedVariable;
} catch (e) {
  console.log(e instanceof ReferenceError); // true
  console.log(e.message); // "undefinedVariable is not defined"
  console.log(e.name); // "ReferenceError"
  console.log(e.stack); // Стек ошибок
}
```

### Создание `ReferenceError`

```js
try {
  throw new ReferenceError("Привет");
} catch (e) {
  console.log(e instanceof ReferenceError); // true
  console.log(e.message); // "Привет"
  console.log(e.name); // "ReferenceError"
  console.log(e.stack); // Стек ошибок
}
```

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-native-error-types-used-in-this-standard-referenceerror |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* `Error`


String - JavaScript

String
======

Объект **`String`** используется, чтобы представить и конструировать последовательность символов.

Синтаксис
---------

Строковые литералы могут быть следующих форм:
```

'строка текста'
"строка текста"
"中文 español English हिन्दी العربية português বাংলা русский 日本語 ਪੰਜਾਬੀ 한국어 தமிழ்"
```

Кроме регулярных печатных символов можно использовать специальные символы, которые можно закодировать, используя нотацию escape-последовательностей:

| Код | Вывод |
| --- | --- |
| `\0` | нулевой символ (символ NUL) |
| `\'` | одинарная кавычка |
| `\"` | двойная кавычка |
| `\\` | обратный слеш |
| `\n` | новая строка |
| `\r` | возврат каретки |
| `\v` | вертикальная табуляция |
| `\t` | табуляция |
| `\b` | забой |
| `\f` | подача страницы |
| `\uXXXX` | Юникод-символ |
| `\xXX` | символ в кодировке Latin-1 |

Либо можно использовать глобальный объект `String` напрямую:
```

String(thing)
new String(thing)
```

### Параметры

`thing`

Всё, что может быть преобразовано в строку.

Описание
--------

Строки полезны для хранения данных, которые можно представить в текстовой форме. Некоторые из наиболее частых операций со строками — это проверка их длины, построение строки с помощью операций строковой конкатенации + и +=, проверка на существование или местоположение подстрок с помощью метода `indexOf()`, либо извлечение подстрок с помощью метода `substring()`.

### Доступ к символам

Существует два способа добраться до конкретного символа в строке. В первом способе используется метод `charAt()`:

```js
return "кот".charAt(1); // вернёт "о"
```

Другим способом (введённым в ECMAScript 5) является рассмотрение строки как массивоподобного объекта, в котором символы имеют соответствующие числовые индексы:

```js
return "кот"[1]; // вернёт "о"
```

При доступе к символам посредством нотации с квадратными скобками, попытка удалить символ, или присвоить значение числовому свойству закончится неудачей, поскольку эти свойства являются незаписываемыми и ненастраиваемыми. Смотрите документацию по методу `Object.defineProperty()` для дополнительной информации.

### Сравнение строк

Разработчики на C имеют для сравнения строк функцию `strcmp()`. В JavaScript вы просто используете операторы меньше и больше:

```js
var a = "a";
var b = "b";
if (a < b) {
  // true
  print(a + " меньше чем " + b);
} else if (a > b) {
  print(a + " больше чем " + b);
} else {
  print(a + " и " + b + " равны.");
}
```

Подобный результат также может быть достигнут путём использования метода `localeCompare()`, имеющегося у всех экземпляров `String`.

### Разница между строковыми примитивами и объектами `String`

Обратите внимание, что JavaScript различает объекты `String` и значения строкового примитива (то же самое верно и для объектов `Boolean` и `Number`).

Строковые литералы (обозначаемые двойными или одинарными кавычками) и строки, возвращённые вызовом `String` в неконструкторном контексте (то есть, без использования ключевого слова `new`) являются строковыми примитивами. JavaScript автоматически преобразует примитивы в объекты `String`, так что на строковых примитивах возможно использовать методы объекта `String`. В контекстах, когда на примитивной строке вызывается метод или происходит поиск свойства, JavaScript автоматически оборачивает строковый примитив объектом и вызывает на нём метод или ищет в нём свойство.

```js
var s_prim = "foo";
var s_obj = new String(s_prim);

console.log(typeof s_prim); // выведет 'string'
console.log(typeof s_obj); // выведет 'object'
```

Строковые примитивы и объекты `String` также дают разные результаты при использовании глобальной функции `eval()`. Примитивы, передаваемые в `eval()`, трактуются как исходный код; объекты же `String` трактуются так же, как и все остальные объекты, а именно: возвращается сам объект. Например:

```js
var s1 = "2 + 2"; // создаёт строковый примитив
var s2 = new String("2 + 2"); // создаёт объект String
console.log(eval(s1)); // выведет число 4
console.log(eval(s2)); // выведет строку '2 + 2'
```

По этим причинам код может сломаться, если он получает объекты `String`, а ожидает строковые примитивы, хотя в общем случае вам не нужно беспокоиться о различиях между ними.

Объект `String` также всегда может быть преобразован в его примитивный аналог при помощи метода `valueOf()`.

```js
console.log(eval(s2.valueOf())); // выведет число 4
```

Свойства
--------

`String.length`

Хранит длину строки. Только для чтения.

Методы
------

`String.fromCharCode()`

Возвращает строку, созданную из указанной последовательности значений Юникода.

`String.fromCodePoint()`
Экспериментальная возможность

Возвращает строку, созданную из указанной последовательности кодовых точек Юникода.

`String.raw()`
Экспериментальная возможность

Возвращает строку, созданную из сырой шаблонной строки.

Общие методы объекта `String`
-----------------------------

Методы экземпляров `String` также доступны в Firefox как часть JavaScript 1.6 (который не является частью стандарта ECMAScript) на объекте `String`, что позволяет применять эти методы к любому объекту:

```js
var num = 15;
console.log(String.replace(num, /5/, "2"));
```

Общие методы также доступны для объекта `Array`.

Следующая прослойка позволяет использовать их во всех браузерах:

```js
/\*globals define\*/
// Предполагаем, что все требуемые методы экземпляров String уже присутствуют
// (для них так же можно использовать полифилы, если их нет)
(function () {
  "use strict";

  var i,
    // Мы могли построить массив методов следующим образом, однако метод
    // getOwnPropertyNames() нельзя реализовать на JavaScript:
    // Object.getOwnPropertyNames(String).filter(function(methodName) {
    // return typeof String[methodName] === 'function';
    // });
    methods = [
      "quote",
      "substring",
      "toLowerCase",
      "toUpperCase",
      "charAt",
      "charCodeAt",
      "indexOf",
      "lastIndexOf",
      "startsWith",
      "endsWith",
      "trim",
      "trimLeft",
      "trimRight",
      "toLocaleLowerCase",
      "toLocaleUpperCase",
      "localeCompare",
      "match",
      "search",
      "replace",
      "split",
      "substr",
      "concat",
      "slice",
    ],
    methodCount = methods.length,
    assignStringGeneric = function (methodName) {
      var method = String.prototype[methodName];
      String[methodName] = function (arg1) {
        return method.apply(arg1, Array.prototype.slice.call(arguments, 1));
      };
    };

  for (i = 0; i < methodCount; i++) {
    assignStringGeneric(methods[i]);
  }
})();
```

Примеры
-------

### Пример: преобразование в строку

Объект `String` можно использовать как «безопасную» альтернативу методу `toString()`, так как хотя он обычно и вызывает соответствующий метод `toString()`, он также работает и для значений `null` и `undefined`. Например:

```js
var outputStrings = [];
for (var i = 0, n = inputValues.length; i < n; ++i) {
  outputStrings.push(String(inputValues[i]));
}
```

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-string-objects |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* `DOMString`
* Двоичные строки


Atomics - JavaScript

Atomics
=======

Объект **`Atomics`** предоставляет атомарные операции как статические методы. Используется вместе с объектом `SharedArrayBuffer`.
Атомарные операции установлены в модуле `Atomics`. В отличие от других глобальных объектов, `Atomics` не является конструктором. Его нельзя использовать вместе с оператором `new` или вызывать объект `Atomics` как функцию. Все свойства и методы `Atomics` статические (как у объекта `Math`, к примеру).

Свойства
--------

`Atomics[Symbol.toStringTag]`

Значение этого свойства - "Atomics".

Методы
------

### Атомарные операции

Когда память разделена, несколько потоков могут читать и записывать одни и те же данные в память. Атомарные операции гарантируют, что ожидаемые значения будут записаны и прочитаны, а операции завершены, прежде чем следующая операция начнёт свою работу, и они не будут прерваны.

`Atomics.add()`

Добавляет представленное значение к текущему по указанной позиции в массиве. Возвращает предыдущее значение в этой позиции.

`Atomics.and()` (en-US)

Вычисляет побитовое AND в указанной позиции массива. Возвращает предыдущее значение в этой позиции.

`Atomics.compareExchange()` (en-US)

Сохраняет представленное значение в указанную позицию массива, если оно эквивалентно представленному значению. Возвращает предыдущее значение.

`Atomics.exchange()` (en-US)

Сохраняет представленное значение в указанную позицию массива. Возвращает предыдущее значение.

`Atomics.load()` (en-US)

Возвращает значение из указанной позиции массива.

`Atomics.or()` (en-US)

Вычисляет побитовое OR в указанной позиции массива. Возвращает предыдущее значение в этой позиции.

`Atomics.store()` (en-US)

Сохраняет представленное значение в указанную позицию массива. Возвращает значение.

`Atomics.sub()`

Вычитает представленное значение из текущего по указанной позиции в массиве. Возвращает предыдущее значение в этой позиции.

`Atomics.xor()` (en-US)

Вычисляет побитовое XOR в указанной позиции массива. Возвращает предыдущее значение в этой позиции.

### Wait и notify

`wait()` и `wake()` методы моделируются на основе futexes ("fast user-space mutex" - быстрый мьютекс пользовательского пространства) Linux и предоставляют собой способы ожидания момента, когда определённое состояние не станет true, и обычно используется как блокирующие конструкции.

`Atomics.wait()` (en-US)

Проверяет, содержится в указанной позиции массива все ещё представленное значение и спит в ожидании или тайм-аут. Возвращает `"ok"`, `"not-equal"` или `"timed-out"`. Если ожидание не разрешено в вызывающем агенте, тогда выбросит ошибку исключения (большинство браузеров не разрешают `wait()` в главном потоке браузера).

`Atomics.wake()` (en-US)

Пробуждает некоторых агентов, которые спят в очереди ожидания в указанной позиции массива. Возвращает количество агентов, которые были разбужены.

`Atomics.isLockFree(size)` (en-US)

Оптимизационный примитив, который может быть использован для определения использовать ли блокирующие операции или атомарные. Возвращает `true`, если атомарные операции над массивами с указанным размерами элементов будут выполнены с использованием аппаратных атомарных операций (как противоположность блокирующим). Только для специалистов.

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics-object |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Похожие заметки
---------------

До SpiderMonkey 48, финальные имена API и семантика не были ещё реализованы. Изменения между Firefox v. 46 и v. 48:

* Методы `Atomics.futexWakeOrRequeue()` и `Atomics.fence()` полностью удалены (Firefox bug 1259544 и Firefox bug 1225028).
* Методы `Atomics.wait()` (en-US) и `Atomics.wake()` (en-US) были названы `Atomics.futexWait()` и `Atomics.futexWake()` (Firefox bug 1260910). Примечание: старые имена были удалены в версии 49 и младше (Firefox bug 1262062).
* Свойства `Atomics.OK`, `Atomics.TIMEDOUT`, `Atomics.NOTEQUAL` были удалены. `Atomics.wait()` (en-US) метод теперь возвращает строки "ok", "timed-out" и "not-equal" (Firefox bug 1260835).
* Параметр `count` метода `Atomics.wake()` (en-US) изменился: теперь он по умолчанию равен `+Infinity`, а не `0` (Firefox bug 1253350).
Смотрите также
--------------

* `ArrayBuffer`
* JavaScript typed arrays
* Web Workers
* parlib-simple – a simple library providing synchronization and work distribution abstractions.
* Shared Memory – a brief tutorial
* A Taste of JavaScript's New Parallel Primitives – Mozilla Hacks


decodeURIComponent() - JavaScript

decodeURIComponent()
====================

Метод **`decodeURIComponent()`** декодирует управляющие последовательности символов в компоненте Uniform Resource Identifier (URI), созданные с помощью метода `encodeURIComponent` или другой подобной процедуры.

Интерактивный пример
--------------------

Синтаксис
---------
```

decodeURIComponent(encodedURI)
```

### Параметры

`encodedURI`

Строка, содержащая закодированный компонент Uniform Resource Identifier.

### Возвращаемое значение

Новая строка, представляющая собой декодированную версию компонента Uniform Resource Identifier (URI), переданного в качестве параметра.

### Исключения

При неправильном использовании выдаёт исключение `URIError` ("неверный формат последовательности URI").

Описание
--------

Заменяет каждую управляющую последовательность в закодированном компоненте URI соответствующим ей символом.

Примеры
-------

### Декодирование компонента кириллического URL

```js
decodeURIComponent("JavaScript\_%D1%88%D0%B5%D0%BB%D0%BB%D1%8B");
// "JavaScript\_шеллы"
```

### Перехват ошибок

```js
try {
  var a = decodeURIComponent("%E0%A4%A");
} catch (e) {
  console.error(e);
}

// URIError: malformed URI sequence
```

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-decodeuricomponent-encodeduricomponent |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* `decodeURI`
* `encodeURI`
* `encodeURIComponent`


InternalError - JavaScript

InternalError
=============

**Не стандартно:** Эта возможность не является стандартной и стандартизировать её пока никто не собирается. Не используйте её на сайтах, смотрящих во внешний мир: она будет работать не у всех пользователей. Также могут присутствовать большие несовместимости между реализациями и её поведение может в будущем измениться.

Объект **`InternalError`** представляет ошибку, возникающую внутри движка JavaScript.

В основном такие ошибки связаны с тем, что что-то слишком велико, например:

* "too many switch cases",
* "too many parentheses in regular expression",
* "array initializer too large",
* "too much recursion".

`InternalError` является подклассом `Error`.

Конструктор
-----------

`InternalError()` (en-US)
Non-standard

Создаёт новый объект `InternalError`.

Свойства экземпляра
-------------------

*Также наследует свойства экземпляра своего родителя `Error`*.

Эти свойства определены в `InternalError.prototype` и есть у всех экземпляров `InternalError`.

`InternalError.prototype.constructor`

Функция-конструктор, создающая экземпляр объекта. Для экземпляров `InternalError` начальным значением является конструктор `InternalError` (en-US).

`InternalError.prototype.name`

Представляет название типа ошибки. Начальным значением `InternalError.prototype.name` является `"InternalError"`.

Методы экземпляра
-----------------

*Наследует методы экземпляра своего родителя `Error`*.

Примеры
-------

### Слишком глубокая рекурсия

Эта рекурсивная функция выполняется 10 раз в соответствии с условием выхода.

```js
function loop(x) {
  // условие выхода из функции
  if (x >= 10) return;

  // рекурсивный вызов
  loop(x + 1);
}

loop(0);
```

Установка для этого условия чрезвычайно высокого значения может не сработать:

```js
function loop(x) {
  if (x >= 1000000000000) return;

  loop(x + 1);
}

loop(0);

// InternalError: too much recursion
```

Для получения дополнительной информации смотрите InternalError: too much recursion.

Specifications
--------------

Не является частью какого-либо стандарта.

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `Error`
* InternalError: too much recursion


SyntaxError - JavaScript

SyntaxError
===========

Объект **`SyntaxError`** представляет ошибку, возникающую при попытке интерпретировать синтаксически неправильный код. Это происходит, когда движок JavaScript при синтаксическом анализе кода обнаруживает токены или порядок токенов, не соответствующие синтаксису языка.

`SyntaxError` является сериализуемым объектом (en-US), поэтому он может быть клонирован с помощью `structuredClone()` (en-US) или передан между воркерами с использованием `postMessage()`.

`SyntaxError` является подклассом `Error`.

Конструктор
-----------

`SyntaxError()` (en-US)

Создаёт новый объект `SyntaxError`.

Свойства экземпляра
-------------------

*Также наследует свойства своего родителя `Error`*.

Эти свойства определены в `SyntaxError.prototype` и есть у всех экземпляров `SyntaxError`.

`SyntaxError.prototype.constructor`

Функция-конструктор, создающая экземпляр объекта. Для экземпляров `SyntaxError` начальным значением является конструктор `SyntaxError` (en-US).

`SyntaxError.prototype.name`

Представляет название типа ошибки. Начальным значением `SyntaxError.prototype.name` является `"SyntaxError"`.

Методы экземпляра
-----------------

*Наследует методы своего родителя `Error`*.

Примеры
-------

### Перехват `SyntaxError`

```js
try {
  eval("hoo bar");
} catch (e) {
  console.log(e instanceof SyntaxError); // true
  console.log(e.message);
  console.log(e.name); // "SyntaxError"
  console.log(e.stack); // Стек ошибок
}
```

### Создание `SyntaxError`

```js
try {
  throw new SyntaxError("Привет");
} catch (e) {
  console.log(e instanceof SyntaxError); // true
  console.log(e.message); // "Привет"
  console.log(e.name); // "SyntaxError"
  console.log(e.stack); // Стек ошибок
}
```

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-native-error-types-used-in-this-standard-syntaxerror |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* `Error`


JSON - JavaScript

JSON
====

Сводка
------

Объект **`JSON`** содержит методы для разбора объектной нотации JavaScript (JavaScript Object Notation — сокращённо JSON) и преобразования значений в JSON. Его нельзя вызвать как функцию или сконструировать как объект, и кроме своих двух методов он не содержит никакой интересной функциональности.

Описание
--------

### Объектная нотация JavaScript

JSON является синтаксисом для сериализации объектов, массивов, чисел, строк логических значений и значения `null`. Он основывается на синтаксисе JavaScript, однако всё же отличается от него: не каждый код на JavaScript является JSON, и не каждый JSON является кодом на JavaScript. Смотрите также статью JSON: подмножество JavaScript, которым он не является (на английском).

Различия между JavaScript и JSON| Тип JavaScript | Отличия от JSON |
| --- | --- |
| Объекты и массивы |
 Имена свойств должны быть строками, заключёнными в двойные кавычки;
 конечные запятые запрещены.
  |
| Числа |
 Ведущие нули запрещены; перед десятичной запятой обязательно должна быть
 хотя бы одна цифра.
  |
| Строки |
 Только ограниченный набор символов может быть заэкранирован; некоторые
 управляющие символы запрещены; разрешены юникодные символы
 разделительной линии (U+2028) и разделительного параграфа (U+2029); строки должны быть заключены в двойные кавычки. Смотрите следующий
 пример, в котором метод `JSON.parse()`
 отрабатывает без проблем, а при вычислении кода как JavaScript
 выбрасывается исключение `SyntaxError`:

```js
var code = '"\u2028\u2029"';
JSON.parse(code); // работает
eval(code); // ошибка
```

 |

Ниже представлен полный синтаксис JSON:
```

JSON = null
    or true or false
    or JSONNumber
    or JSONString
    or JSONObject
    or JSONArray

JSONNumber = - PositiveNumber
          or PositiveNumber
PositiveNumber = DecimalNumber
              or DecimalNumber . Digits
              or DecimalNumber . Digits ExponentPart
              or DecimalNumber ExponentPart
DecimalNumber = 0
             or OneToNine Digits
ExponentPart = e Exponent
            or E Exponent
Exponent = Digits
        or + Digits
        or - Digits
Digits = Digit
      or Digits Digit
Digit = 0 through 9
OneToNine = 1 through 9

JSONString = ""
          or " StringCharacters "
StringCharacters = StringCharacter
                or StringCharacters StringCharacter
StringCharacter = any character
                  except " or \ or U+0000 through U+001F
               or EscapeSequence
EscapeSequence = \" or \/ or \\ or \b or \f or \n or \r or \t
              or \u HexDigit HexDigit HexDigit HexDigit
HexDigit = 0 through 9
        or A through F
        or a through f

JSONObject = { }
          or { Members }
Members = JSONString : JSON
       or Members , JSONString : JSON

JSONArray = [ ]
         or [ ArrayElements ]
ArrayElements = JSON
             or ArrayElements , JSON
```

Во всех продукциях могут присутствовать незначащие пробельные символы, за исключением продукций `ЧислоJSON` (числа не должны содержать пробелов) и `СтрокаJSON` (где они интерпретируются как часть строки или возбуждают ошибку). Пробельными символами считаются символы табуляции (U+0009), возврата каретки (U+000D), перевода строки (U+000A) и, собственно, пробела (U+0020).

Методы
------

`JSON.parse()`

Разбирает строку JSON, возможно с преобразованием получаемого значения и его свойств и возвращает разобранное значение.

`JSON.stringify()`

Возвращает строку JSON, соответствующую указанному значению, возможно с включением только определённых свойств или с заменой значений свойств определяемым пользователем способом.

Полифил
-------

Объект `JSON` не поддерживается старыми браузерами. Вы можете работать с ним, добавив следующий код в начало ваших скриптов, он позволяет использовать объект `JSON` в реализациях, которые его ещё не поддерживают (например, в Internet Explorer 6).

Следующий алгоритм имитирует работу настоящего объекта `JSON`:

```js
if (!window.JSON) {
  window.JSON = {
    parse: function (sJSON) {
      return eval("(" + sJSON + ")");
    },
    stringify: function (vContent) {
      if (vContent instanceof Object) {
        var sOutput = "";
        if (vContent.constructor === Array) {
          for (
            var nId = 0;
            nId < vContent.length;
            sOutput += this.stringify(vContent[nId]) + ",", nId++
          );
          return "[" + sOutput.substr(0, sOutput.length - 1) + "]";
        }
        if (vContent.toString !== Object.prototype.toString) {
          return '"' + vContent.toString().replace(/"/g, "\\$&") + '"';
        }
        for (var sProp in vContent) {
          sOutput +=
            '"' +
            sProp.replace(/"/g, "\\$&") +
            '":' +
            this.stringify(vContent[sProp]) +
            ",";
        }
        return "{" + sOutput.substr(0, sOutput.length - 1) + "}";
      }
      return typeof vContent === "string"
        ? '"' + vContent.replace(/"/g, "\\$&") + '"'
        : String(vContent);
    },
  };
}
```

Более сложными известными полифилами для объекта `JSON` являются проекты JSON2 и JSON3.

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-json-object |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Использование родного объекта `JSON` (en-US)
* `Date.prototype.toJSON()`


Дата - JavaScript

Дата
====

Объекты **`Date`** в JavaScript представляют момент времени в независимом от платформы формате. Объект `Date` содержит число миллисекунд, прошедших с полуночи (00:00:00 UTC) 1 января 1970 года (этот момент называют «эпохой Unix»).

Синтаксис
---------
```

new Date();
new Date(value);
new Date(dateString);
new Date(year, month[, day[, hour[, minute[, second[, millisecond]]]]]);
```

**Примечание:** объекты `Date` могут быть созданы только путём вызова функции `Date` в качестве конструктора: обычный вызов функции (то есть, без использования оператора `new`) вернёт строку вместо объекта `Date`; в отличие от других объектных типов JavaScript, объекты `Date` не имеют литерального синтаксиса.

### Параметры

**Примечание:** если функция `Date` вызывается в качестве конструктора с более, чем одним аргументом, значения, большие логического диапазона (например, 13 в качестве номера месяца или 70 для значения минут) «переметнутся» на соседние значения. Например, вызов `new Date(2013, 13, 1)` эквивалентен вызову `new Date(2014, 1, 1)`, оба создадут дату `2014-02-01` (нумерация месяцев начинается с нуля). Тоже самое действует и для других значений: вызов `new Date(2013, 2, 1, 0, 70)` эквивалентен вызову `new Date(2013, 2, 1, 1, 10)` — оба вызова создадут дату `2013-03-01T01:10:00`.

**Примечание:** если функция Date вызывается в качестве конструктора с более чем одним аргументом, то указанные аргументы интерпретируются как локальное время. Если аргументы указывают время в UTC, используйте `new Date(`Date.UTC(...)`)` с теми же аргументами.

`value`

Целое значение, представляющее количество миллисекунд, прошедших с 1 января 1970 00:00:00 по UTC (эпохи Unix).

`dateString`

Строковое значение, представляющее дату. Строка должна быть в одном из форматов, распознаваемых методом `Date.parse()` (совместимые с IETF RFC 2822 временные метки [на английском, на русском], а также версия ISO8601 [на английском, на русском]).

`year`

Целое значение, представляющее год. Значения с 0 по 99 отображаются на года с 1900 по 1999. Смотрите пример ниже.

`month`

Целое значение, представляющее месяц, начинается с 0 для января и кончается 11 для декабря.

`day`

Необязательный параметр. Целое значение, представляющее день месяца.

`hour`

Необязательный параметр. Целое значение, представляющее часы дня.

`minute`

Необязательный параметр. Целое значение, представляющее минуты времени.

`second`

Необязательный параметр. Целое значение, представляющее секунды времени.

`millisecond`

Необязательный параметр. Целое значение, представляющее миллисекунды времени.

Описание
--------

* Если никаких аргументов передано не было, конструктор создаёт объект `Date` для текущих даты и времени, согласно системным настройкам.
* Если передано как минимум два аргумента, отсутствующие аргументы устанавливаются в стартовые значения - день месяца 1 и время полуночи.
* Дата в JavaScript измеряется в миллисекундах, прошедших с полуночи 1 января 1970 года по UTC. День содержит 86 400 000 миллисекунд. Диапазон дат объекта `Date` варьируется от -100 000 000 до 100 000 000 дней относительно 1 января 1970 года по UTC.
* Объект `Date` обеспечивает универсальное поведение на всех платформах. Значение времени может передаваться между системами для представления одинакового момента во времени и, если оно используется для создания локального объекта даты, будет отражать местный эквивалент времени.
* Объект `Date` поддерживает несколько методов для работы с UTC (всемирным координированным временем), наряду с методами работы с местным временем. UTC, также известное как среднее время по Гринвичу (GMT), ссылается на время, установленное Всемирным стандартом времени. Местное время — это время на компьютере, на котором выполняется JavaScript.
* Вызов объекта `Date` в качестве функции (то есть, без использования оператора `new`) вернёт строку, представляющую текущие дату и время.
Статические методы
------------------

`Date.now()`

Возвращает числовое значение, соответствующее текущему времени — количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC.

`Date.parse()`

Разбирает строковое представление даты и возвращает количество миллисекунд с 1 января 1970 года 00:00:00 по местному времени.

`Date.UTC()`

Принимает те же самые параметры, что и самый длинный вариант конструктора (то есть, от 2 до 7) и возвращает количество миллисекунд, прошедших с 1 января 1970 года 00:00:00 по UTC.

Свойства экземпляра
-------------------

Эти свойства определены в `Date.prototype` и есть у всех экземпляров `Date`.

`Date.prototype.constructor`

Функция-конструктор, создающая экземпляр объекта. Для экземпляров `Date` начальным значением является конструктор `Date` (en-US).

Примеры
-------

### Пример: несколько способов создания объекта `Date`

Следующие примеры показывают несколько способов создания дат в JavaScript:

**Примечание:** разбор строкового представления дат с помощью конструктора `Date` (так же как эквивалентный ему метод `Date.parse`) может иметь различия и несоответствия в браузерах.

```js
var today = new Date();
var birthday = new Date("December 17, 1995 03:24:00");
var birthday = new Date("1995-12-17T03:24:00");
var birthday = new Date(1995, 11, 17);
var birthday = new Date(1995, 11, 17, 3, 24, 0);
```

### Пример: двухциферный год отображается на 1900 - 1999 года

Для того, чтобы создать и получить даты между 0 и 99 годом, нужно использовать методы `Date.prototype.setFullYear()` и `Date.prototype.getFullYear()`.

```js
var date = new Date(98, 1); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)

// Устаревший метод, 98 отображается на 1998 год
date.setYear(98); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)

date.setFullYear(98); // Sat Feb 01 0098 00:00:00 GMT+0000 (BST)
```

### Пример: вычисление затраченного времени

Следующие примеры показывают, как определить разницу во времени между двумя датами в JavaScript:

```js
// Используя объекты Date
var start = Date.now();

// Событие, для которого замеряется время, происходит тут:
doSomethingForALongTime();
var end = Date.now();
var elapsed = end - start; // затраченное время в миллисекундах
```

```js
// Используя встроенные методы
var start = new Date();

// Событие, для которого замеряется время, происходит тут:
doSomethingForALongTime();
var end = new Date();
var elapsed = end.getTime() - start.getTime(); // затраченное время в миллисекундах
```

```js
// Проверяет функцию и возвращает её возвращаемое значение
function printElapsedTime(fTest) {
  var nStartTime = Date.now(),
    vReturn = fTest(),
    nEndTime = Date.now();

  console.log(
    "Затраченное время: " + String(nEndTime - nStartTime) + " миллисекунд",
  );
  return vReturn;
}

yourFunctionReturn = printElapsedTime(yourFunction);
```

**Примечание:** в браузерах, поддерживающих высокое временное разрешение с помощью API замера производительности, метод `Performance.now()` может обеспечить более надёжные и точные замеры затраченного времени, нежели метод `Date.now()`.

### Получить количество секунд с начала эпохи Unix
```

var seconds = Math.floor(Date.now() / 1000);
```

В этом случае важно возвращать только целое число (так что простое деление не подойдёт), а также возвращать только фактически прошедшие секунды (поэтому этот код использует `Math.floor ()` а не `Math.round ()`).

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-date-objects |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* `Date()` (en-US)


GeneratorFunction - JavaScript

GeneratorFunction
=================

Объект **`GeneratorFunction`** предоставляет методы для работы с функциями-генераторами. В JavaScript каждая функция-генератор фактически является объектом `GeneratorFunction`.

Обратите внимание, `GeneratorFunction` *не* является глобальным объектом. Он может быть получен следующим образом:

```js
const GeneratorFunction = function\* () {}.constructor;
```

`GeneratorFunction` является подклассом `Function`.

Интерактивный пример
--------------------

Конструктор
-----------

`GeneratorFunction()` (en-US)

Создаёт новый объект `GeneratorFunction`.

Свойства экземпляра
-------------------

*Также наследует свойства своего родителя `Function`*.

Эти свойства определены в `GeneratorFunction.prototype` и есть у всех экземпляров `GeneratorFunction`.

`GeneratorFunction.prototype.constructor`

Функция-конструктор, создающая экземпляр объекта. Для экземпляров `GeneratorFunction` начальным значением является конструктор `GeneratorFunction` (en-US).

`GeneratorFunction.prototype.prototype`

Все функции-генераторы имеют доступ к общему свойству `prototype` (en-US), значением которого является `Generator.prototype`. Каждый экземпляр функции-генератора также имеет собственное свойство `prototype`. При вызове функции-генератора возвращается объект генератора, наследуемый от свойства `prototype` функции-генератора, которая в свою очередь наследуется от `GeneratorFunction.prototype.prototype`.

`GeneratorFunction.prototype[@@toStringTag]`

Начальным значением свойства `@@toStringTag` является строка `"GeneratorFunction"`. Это свойство используется в `Object.prototype.toString()`.

Методы экземпляра
-----------------

*Наследует методы своего родителя `Function`*.

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-generatorfunction-objects |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* `function*`
* выражение `function*`
* `Function`
* `AsyncFunction`
* `AsyncGeneratorFunction` (en-US)
* Functions


Intl - JavaScript

Intl
====

Сводка
------

Объект **`Intl`** является пространством имён для API интернационализации ECMAScript, предоставляющим языка-зависимое сравнение строк, форматирование чисел и дат со временем. Конструкторы объектов `Collator`, `NumberFormat` и `DateTimeFormat` являются свойствами объекта `Intl`. На этой странице описаны эти свойства, а также общая функциональность конструкторов интернационализации и других языка-зависимых функций.

Свойства
--------

`Intl.Collator`

Конструктор *сортировщиков* — объектов, включающих языка-зависимое сравнение строк.

`Intl.DateTimeFormat`

Конструктор объектов, включающих языка-зависимое форматирование даты и времени.

`Intl.NumberFormat`

Конструктор объектов, включающих языка-зависимое форматирование чисел.

Methods
-------

`Intl.getCanonicalLocales()`

Returns canonical locale names.

Идентификация и согласование локали
-----------------------------------

Конструкторы интернационализации, а также некоторые языка-зависимые методы других конструкторов (перечисленные в разделе Смотрите также) используют общий шаблон для идентификации локалей и определения используемой локали: они все принимают аргументы `locales` и `options` и согласовывают запрошенную локаль (локали) с поддерживаемыми локалями согласно алгоритму, определённому свойством `options.localeMatcher`.

### Аргумент `locales`

Аргумент `locales` должен быть либо строкой, содержащей языковую метку BCP 47, либо массивом таких языковых меток. Если аргумент `locales` не предоставлен или не определён, используется локаль по умолчанию среды выполнения.

Языковая метка BCP 47 однозначно определяет язык или локаль (разница между ними весьма расплывчата). В своей самой общей форме она может содержать в следующем порядке: код языка, код письменности и код страны, разделённые символами дефиса. Примеры:

* `"hi"`: хинди.
* `"de-AT"`: немецкий, используемый в Австрии.
* `"zh-Hans-CN"`: упрощённый китайский, используемый в Китае.

Подмётки, определяющие языки, письменности, страны (регионы) и (используется не часто) варианты в языковых метках BCP 47 могут быть найдены в Реестре языковых подмёток IANA.

BCP 47 также позволяет использовать расширения, и одно из них имеет значение для функций интернационализации JavaScript: это расширение `"u"` (Unicode). Оно может использоваться для запрашивания настраиваемого языка-зависимого поведения объектов `Collator`, `NumberFormat` или `DateTimeFormat`. Примеры:

* `"de-DE-u-co-phonebk"`: использовать вариант телефонной книги немецкого порядка сортировки, который расширяет гласные с умляутами до пар символов: ä → ae, ö → oe, ü → ue.
* `"th-TH-u-nu-thai"`: использовать тайские цифры (๐, ๑, ๒, ๓, ๔, ๕, ๖, ๗, ๘, ๙) при форматировании чисел.
* `"ja-JP-u-ca-japanese"`: использовать японский календарь при форматировании даты и времени, так что 2013 год выражается 25-м годом периода Хэйсей или 平成 25.
### Согласование локали

Аргумент `locales`, после вырезания всех расширений Unicode, интерпретируется как приоритетный запрос из приложения. Среда выполнения сравнивает его с доступными локалями в выбирает наилучшую из имеющихся. Существует два алгоритма сравнения: сопоставление `"lookup"` (поиск) следует алгоритму поиска, определённому в BCP 47; сопоставление `"best fit"` (наилучший подходящий) позволяет среде выполнения предоставлять локаль, которая, как минимум, но возможно и лучше, подходит для запроса, нежели локаль, найденная с помощью алгоритма поиска. Если приложение не предоставляет аргумент `locales` или среда выполнения не имеет локали, соответствующей запросу, то используется локаль по умолчанию для среды выполнения. Метод сопоставления можно выбрать с помощью свойства аргумента `options` (смотрите ниже).

Если выбранная языковая метка содержит подстроку расширения Unicode, это расширение будет использоваться для настройки сконструированного объекта или поведения функции. Каждый конструктор или функция поддерживают только определённое подмножество ключей, определённых расширением Unicode, и поддерживаемые значения часто зависят от языковой метки. Например, ключ `"co"` (сравнение) поддерживается только объектом `Collator`, а его значение `"phonebk"` поддерживается только для немецкого языка.

### Аргумент `options`

Аргумент `options` должен быть объектом со свойствами, которые различаются для конструкторов и функций. Если аргумент `options` не предоставлен или не определён, для всех свойств используются значения по умолчанию.

Одно свойство поддерживается для всех языка-зависимых конструкторов: свойство `localeMatcher`, чьим значением должна быть одна из строк `"lookup"` или `"best fit"` и которое выбирает один из алгоритмов сопоставления локалей, описанных выше.

Спецификации
------------

| Specification |
| --- |
| ECMAScript Internationalization API Specification # intl-object |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Введение: API интернационализации ECMAScript
* Конструкторы
    + `Intl.Collator`
    + `Intl.DateTimeFormat`
    + `Intl.NumberFormat`
* Методы
    + `String.prototype.localeCompare()`
    + `Number.prototype.toLocaleString()`
    + `Date.prototype.toLocaleString()`
    + `Date.prototype.toLocaleDateString()`
    + `Date.prototype.toLocaleTimeString()`


isFinite() - JavaScript

isFinite()
==========

Глобальная **`isFinite()`** функция определяет, является ли переданное значение конечным числом. Если необходимо, параметр сначала преобразуется в число.

Интерактивный пример
--------------------

Синтаксис
---------
```

isFinite(testValue)
```

### Параметры

`testValue`

Аргумент для проверки, является ли он конечным числом.

Описание
--------

`isFinite` это функция верхнего уровня и она не связана ни с одним объектом.

Вы можете использовать эту функцию там, где требуется определить, является ли аргумент конечным числом. Функция `isFinite` исследует число в своём параметре. Если аргумент является NaN, положительной или отрицательной бесконечностью, метод вернёт `false`; иначе возвращается `true`.

Примеры
-------

```js
isFinite(Infinity); // false
isFinite(NaN); // false
isFinite(-Infinity); // false

isFinite(0); // true
isFinite(2e64); // true

isFinite("0"); // true, но было бы false если использовать
// более надёжный вариант Number.isFinite("0")
```

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-isfinite-number |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* `Number.isFinite()`
* `Number.NaN()`
* `Number.POSITIVE_INFINITY`
* `Number.NEGATIVE_INFINITY`