.unshift()

Метод unshift() добавляет один или несколько новых элементов в начало массива и возвращает длину массива, с учётом добавленных элементов.

Добавим новый элемент в начало массива:

        
          
          const numbers = [16, 32, 64]const arrayLength = numbers.unshift(8)console.log(numbers)// [8, 16, 32, 64]console.log(arrayLength)// 4
          const numbers = [16, 32, 64]
const arrayLength = numbers.unshift(8)
console.log(numbers)
// [8, 16, 32, 64]

console.log(arrayLength)
// 4

        
        
          
            
            Скопировать
            Скопировано
            Не удалось скопировать
          
        
      

Добавим три новых элемента:

        
          
          const skills = ['HTML', 'CSS', 'CI/CD']const arrayLength = skills.unshift('JS', 'Python', 'PHP')console.log(skills)// ['JS', 'Python', 'PHP', HTML', 'CSS', 'CD/CD']console.log(arrayLength)// 6
          const skills = ['HTML', 'CSS', 'CI/CD']
const arrayLength = skills.unshift('JS', 'Python', 'PHP')
console.log(skills)
// ['JS', 'Python', 'PHP', HTML', 'CSS', 'CD/CD']

console.log(arrayLength)
// 6

        
        
          
            
            Скопировать
            Скопировано
            Не удалось скопировать
          
        
      

Array.unshift принимает в качестве аргументов элементы, добавляемые к массиву.

Array.unshift возвращает длину массива, с учётом добавленных элементов.

Если метод был вызван без аргументов, массив не изменится и вернётся прежняя длинна массва:

        
          
          const numbers = [1, 2, 3, 4]const arrayLength = numbers.unshift()console.log(numbers)// [1, 2, 3, 4]console.log(arrayLength)// 4
          const numbers = [1, 2, 3, 4]
const arrayLength = numbers.unshift()
console.log(numbers)
// [1, 2, 3, 4]

console.log(arrayLength)
// 4

        
        
          
            
            Скопировать
            Скопировано
            Не удалось скопировать
          
        
      

Метод unshift() позволяет добавлять элементы в начало существующего массива. Для этих целей так же может быть использован метод splice().

Сравним:

        
          
          const numbers = [0, 1, 2]numbers.unshift(-2, -1)console.log(numbers)// [-2, -1, 0, 1, 2]
          const numbers = [0, 1, 2]
numbers.unshift(-2, -1)
console.log(numbers)
// [-2, -1, 0, 1, 2]

        
        
          
            
            Скопировать
            Скопировано
            Не удалось скопировать
          
        
      

        
          
          const numbers = [0, 1, 2]numbers.splice(0, 0, -2, -1)console.log(numbers)// [-2, -1, 0, 1, 2]
          const numbers = [0, 1, 2]
numbers.splice(0, 0, -2, -1)
console.log(numbers)
// [-2, -1, 0, 1, 2]

        
        
          
            
            Скопировать
            Скопировано
            Не удалось скопировать
          
        
      

Порядок добавляемых элементов определяется порядком аргументов при вызове unshift. Таким образом первый аргумент становится первым элементом массива.

Множественный вызов метода unshift с одним аргументом и однократный вызов с множеством аргументов имеют разный результат:

        
          
          const days1 = ['ср', 'чт']const days2 = ['ср', 'чт']days1.unshift('пн', 'вт')days2.unshift('пн')days2.unshift('вт')console.log(days1)// ['пн', 'вт', 'ср', 'чт']console.log(days2)// ['вт', 'пн', 'ср', 'чт']
          const days1 = ['ср', 'чт']
const days2 = ['ср', 'чт']
days1.unshift('пн', 'вт')
days2.unshift('пн')
days2.unshift('вт')

console.log(days1)
// ['пн', 'вт', 'ср', 'чт']

console.log(days2)
// ['вт', 'пн', 'ср', 'чт']

        
        
          
            
            Скопировать
            Скопировано
            Не удалось скопировать
          
        
      

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

💡 Чтобы добавить все элементы одного массива в начало другого, можно воспользоваться спред-синтаксисом:

        
          
          const spring = ['март', 'апрель', 'май']const months = ['июнь', 'июль', 'август']months.unshift(...spring)console.log(months)// ['март', 'апрель', 'май', 'июнь', 'июль', 'август']
          const spring = ['март', 'апрель', 'май']
const months = ['июнь', 'июль', 'август']
months.unshift(...spring)

console.log(months)
// ['март', 'апрель', 'май', 'июнь', 'июль', 'август']

        
        
          
            
            Скопировать
            Скопировано
            Не удалось скопировать
          
        
      

💡 Какое максимальное количество элементов может быть добавлено с использованием unshift()? Врядли это достижимо, однако, согласно спецификации, если итоговое количество элементов массива превысит значение 2**53 - 1, метод unshift() вызовет ошибку TypeError.