Добавляет доку для метода массива toSpliced()

js/array-to-spliced/index.md

@@ -0,0 +1,140 @@
+---
+title: "`.toSpliced()`"
+description: "Возвращает новый массив, созданный из исходного, удаляя и/или добавляя новые элементы."
+authors:
+  - vitya-ne
+related:
+  - js/array-splice
+  - js/array-with
+  - js/array-slice
+tags:
+  - doka
+---
+
+## Кратко
+
+Метод `toSpliced()` возвращает новый массив, удаляя определённое количество элементов и/или добавляя новые элементы, начиная с указанного индекса в исходном массиве.
+
+## Пример
+
+Создадим массив, удаляя из исходного массива 2 элемента, начиная с элемента с индексом 3:
+
+```js
+const months = ['Май', 'Июнь', 'Июль', 'Август', 'Сентябрь', 'Октябрь']
+
+const newMonths = months.toSpliced(3, 2)
+
+console.log(newMonths)
+// ['Май', 'Июнь', 'Июль', 'Октябрь']
+```
+
+Создадим массив, заменяя в исходном массиве 2 последних элемента:
+
+```js
+const versions = ['ES2016', 'ES2017', 'ES2018', 'неизвестно', 'неизвестно']
+
+const newVersions = versions.toSpliced(-2, 2, 'ES2019', 'ES2020')
+
+console.log(newVersions)
+// ['ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020']
+```
+
+## Как пишется
+
+`Array.toSpliced` принимает аргументы:
+
+- индекс, позиция начала изменений в исходном массиве;
+- количество удаляемых элементов в исходном массиве;
+- остальные аргументы — элементы, добавляемые к массиву.
+
+Если индекс отрицательный, то отсчёт позиции начала изменений ведётся от конца массива.
+
+Если индекс не соответствует размеру массива, то позиция начала изменений определяется по знаку индекса:
+
+- отрицательный индекс — элементы удаляются и/или добавляются начиная с 0-ого элемента исходного массива;
+- положительный индекс — элементы добавляются после последнего элемента исходного массива;
+
+Если количество удаляемых элементов меньше или равно 0, элементы не удаляются.
+
+`Array.toSpliced` возвращает новый массив.
+
+## Как понять
+
+Метод `toSpliced()` может применяться для получения копии исходного массива после редактирования последовательной группы элементов: удаления, добавления или замены. Исходный массив при этом не изменяется.
+
+Создадим массив, добавив в исходный массив 3 элемента, начиная с элемента с индексом 1:
+
+```js
+const days = ['ПН', 'ПТ']
+
+const workDays = days.toSpliced(1, 0, 'ВТ', 'СР', 'ЧТ')
+
+console.log(workDays)
+// ['ПН', 'ВТ', 'СР', 'ЧТ', 'ПТ']
+// исходный массив не изменился
+console.log(days)
+// ['ПН', 'ПТ']
+```
+
+В отличие от метода `splice()`, метод `toSpliced()` не меняет исходный массив и не возвращает удаляемые элементы:
+
+```js
+const numbers = [10, 20, 30, 40]
+
+const newNumbers = numbers.toSpliced(1, 2)
+
+console.log(newNumbers, numbers)
+// [10, 40] [10, 20, 30, 40]
+
+// а вот как работает splice()
+const deletedNumbers = numbers.splice(1, 2)
+console.log(deletedNumbers, numbers)
+// [20, 30] [10, 40]
+```
+
+## Подсказки
+
+💡 Если массив имеет незаполненные элементы, то при выполнении `toSpliced()` возвращаемый массив будет содержать для таких элементов `undefined`.
+
+Заменим в массиве последний элемент:
+
+```js
+const colors = ['crimson', , , 'purple']
+
+console.log(colors.toSpliced(-1, 1, 'blueviolet' ))
+console.log(colors)
+// ['crimson', undefined, undefined, 'blueviolet']
+// ['crimson', <2 empty items>, 'purple']
+
+```
+
+💡 Если элементы исходного массива являются объектами, то возвращаемый в результате работы метода `toSpliced()` массив будет содержать ссылки, а не новые объекты. Таким образом, изменения объекта в исходном массиве будут видны в созданном массиве и наоборот:
+
+```js
+const skills = [{name: 'HTML'}, {name: 'CSS'}, {name: 'PHP'}]
+
+// добавим новый элемент
+const result = skills.toSpliced(2, 0, {name: 'JS'});
+console.log(result)
+// [{name: 'HTML'}, {name: 'CSS'}, {name: 'JS'}, {name: 'PHP'}]
+
+// изменим элемент исходного массива
+skills[0].year = 2005
+
+console.log(skills)
+// [{name: 'HTML', year: 2005}, {name: 'CSS'}, {name: 'PHP'}]
+
+// изменение так же видны в созданном массиве
+console.log(result)
+// [{ name: 'HTML', year: 2005 }, { name: 'CSS' }, { name: 'JS' }, { name: 'PHP' }]
+```
+
+💡 Поддержка метода `toSpliced()` в основных браузерах и в Node.js появилась сравнительно недавно. Например, попытка использовать `toSpliced()` в Node.js v.18.19.0 приведёт к ошибке:
+
+```js
+try {
+  console.log([1, 2, 3].toSpliced(1, 0, 1.5))
+} catch (err) {
+  console.error('Поймали ошибку! Вот она: ', err.message)
+}
+// Поймали ошибку! Вот она:  [1,2,3].toSpliced is not a function