shift

The shift utility rotates the elements of an array by a specified number of positions. Positive numbers rotate to the right, while negative numbers rotate to the left.

Implementation

View Source Code

import { assert } from '../function/assert';
import { IS_ARRAY_ERROR_MSG, isArray } from '../typed/isArray';
import { IS_NUMBER_ERROR_MSG, isNumber } from '../typed/isNumber';

/**
 * Shifts the elements of an array to the left by a specified number of positions.
 *
 * @example
 * ```ts
 * const arr = [1, 2, 3, 4, 5];
 * shift(arr, 2); // [3, 4, 5]
 * shift(arr, 2, true); // [3, 4, 5, 1, 2]
 * ```
 * @param array - The array to shift.
 * @param positions - The number of positions to shift the array.
 * @param rotate - If `true`, the elements that are shifted out will be added to the end of the array.
 *
 * @returns A new array with the elements shifted.
 *
 * @throws {TypeError} If the first argument is not an array, or the second argument is not a number.
 */
export function shift<T>(array: T[], positions: number, rotate = false): T[] {
  assert(isArray(array), IS_ARRAY_ERROR_MSG, { args: { array }, type: TypeError });
  assert(isNumber(positions), IS_NUMBER_ERROR_MSG, { args: { positions }, type: TypeError });

  if (array.length === 0) return array;

  const normalizedPos = ((positions % array.length) + array.length) % array.length;
  const shifted = array.slice(normalizedPos);

  return rotate ? [...shifted, ...array.slice(0, normalizedPos)] : shifted;
}

shift.fp = true;

Features

• Isomorphic: Works in both Browser and Node.js.
• Rotation Support: Cycle through array elements easily.
• Flexible Positioning: Supports both positive (left shift) and negative (right shift) offsets.
• Immutable: Returns a new array, leaving the original array unchanged.

API

function shift<T>(array: T[], positions: number, rotate?: boolean): T[];

Parameters

• array: The array to shift.
• positions: The number of positions to shift the elements. Use negative numbers to shift to the right.
• rotate: Optional. If true, elements that are shifted off one end of the array are reapplied to the other end (circular shift). Defaults to false.

Returns

• A new array with elements shifted.

Examples

Basic Shifting (Removal)

import { shift } from '@vielzeug/toolkit';

const numbers = [1, 2, 3, 4, 5];

// Shift 2 positions to the left (removes first two)
shift(numbers, 2); // [3, 4, 5]

Rotating Elements

import { shift } from '@vielzeug/toolkit';

const letters = ['A', 'B', 'C', 'D'];

// Rotate 1 position to the left
shift(letters, 1, true); // ['B', 'C', 'D', 'A']

// Rotate 1 position to the right (negative shift)
shift(letters, -1, true); // ['D', 'A', 'B', 'C']

Implementation Notes

• Throws TypeError if the first argument is not an array.
• If rotate is false, shifting more positions than the array length returns an empty array.
• If rotate is true, shifting more positions than the array length is handled using modulo, ensuring continuous rotation.

See Also

• substitute: Replace elements in an array.
• chunk: Split an array into smaller segments.
• list: Create arrays from ranges or values.