rotate

The rotate utility shifts the elements of an array by a given number of positions. By default the rotated-out prefix is discarded; pass { wrap: true } to append it to the end instead.

Source Code

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';

/**
 * Rotates the elements of an array by a specified number of positions.
 *
 * @example
 * ```ts
 * const arr = [1, 2, 3, 4, 5];
 * rotate(arr, 2); // [3, 4, 5]
 * rotate(arr, 2, { wrap: true }); // [3, 4, 5, 1, 2]
 * ```
 * @param array - The array to rotate.
 * @param positions - The number of positions to rotate the array.
 * @param [options] - Options for the rotate operation.
 * @param [options.wrap] - If `true`, the rotated-out elements are appended to the end.
 *
 * @returns A new array with the elements rotated.
 *
 * @throws {TypeError} If the first argument is not an array, or the second argument is not a number.
 */
export function rotate<T>(array: T[], positions: number, { wrap = false }: { wrap?: boolean } = {}): 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 rotated = array.slice(normalizedPos);

  return wrap ? [...rotated, ...array.slice(0, normalizedPos)] : rotated;
}

Features

• Immutable: Returns a new array.
• Wrap mode: Optionally cycles the removed prefix back to the end.
• Negative-safe normalization: Handles positions larger than the array length.

API

function rotate<T>(array: T[], positions: number, options?: { wrap?: boolean }): T[];

Parameters

• array: The array to rotate.
• positions: Number of positions to rotate left (shift from the front).
• options.wrap: If true, the removed prefix is appended to the end (default: false).

Returns

• A new rotated array.

Throws

• TypeError: If array is not an array or positions is not a number.

Examples

Rotate Without Wrap (Truncate)

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

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

rotate(arr, 2); // [3, 4, 5]
rotate(arr, 3); // [4, 5]

Rotate With Wrap (Cycle)

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

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

rotate(arr, 2, { wrap: true }); // [3, 4, 5, 1, 2]
rotate(arr, 1, { wrap: true }); // [2, 3, 4, 5, 1]

Carousel / Round-Robin

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

const slides = ['A', 'B', 'C', 'D'];
let current = 0;

function next() {
  current = (current + 1) % slides.length;
  return rotate(slides, current, { wrap: true });
}

next(); // ['B', 'C', 'D', 'A']
next(); // ['C', 'D', 'A', 'B']

See Also

• chunk: Split an array into equal-sized pieces.
• toggle: Add or remove an item from an array.