refactor!: rename shift to circularShift

benchmarks/array/shift.bench.ts → benchmarks/array/circularShift.bench.ts

@@ -1,13 +1,13 @@
 import * as _ from 'radashi'
 import { bench } from 'vitest'
 
-describe('shift', () => {
+describe('circularShift', () => {
   bench('with non-empty array', () => {
     const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9]
-    _.shift(arr, 3)
+    _.circularShift(arr, 3)
   })
 
   bench('with empty array', () => {
-    _.shift([], -3)
+    _.circularShift([], -3)
   })
 })

docs/array/circularShift.mdx

@@ -0,0 +1,28 @@
+---
+title: circularShift
+description: Shift array items by n steps
+---
+
+### Usage
+
+Given a list of items, return an array that shift right n positions.
+
+```ts
+import * as _ from 'radashi'
+
+const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+_.circularShift(arr, 3) // => [7, 8, 9, 1, 2, 3, 4, 5, 6]
+```
+
+#### Negative index
+
+A negative index will shift the array left.
+
+```ts
+import * as _ from 'radashi'
+
+const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+_.circularShift(arr, -3) // => [4, 5, 6, 7, 8, 9, 1, 2, 3]
+```

src/array/shift.ts → src/array/circularShift.ts

@@ -3,14 +3,14 @@
  * will shift `n` steps to the right. If `n` is less than 0, items
  * will shift `n` steps to the left.
  *
- * @see https://radashi-org.github.io/reference/array/shift
+ * @see https://radashi-org.github.io/reference/array/circularShift
  * @example
  * ```ts
- * shift([1, 2, 3], 1) // [3, 1, 2]
- * shift([1, 2, 3], -1) // [2, 3, 1]
+ * circularShift([1, 2, 3], 1) // [3, 1, 2]
+ * circularShift([1, 2, 3], -1) // [2, 3, 1]
  * ```
  */
-export function shift<T>(arr: readonly T[], n: number): T[] {
+export function circularShift<T>(arr: readonly T[], n: number): T[] {
   if (arr.length === 0) {
     return [...arr]
   }

src/mod.ts

@@ -2,6 +2,7 @@ export * from './array/alphabetical.ts'
 export * from './array/boil.ts'
 export * from './array/castArray.ts'
 export * from './array/castArrayIfExists.ts'
+export * from './array/circularShift.ts'
 export * from './array/cluster.ts'
 export * from './array/counting.ts'
 export * from './array/diff.ts'
@@ -20,7 +21,6 @@ export * from './array/replace.ts'
 export * from './array/replaceOrAppend.ts'
 export * from './array/select.ts'
 export * from './array/selectFirst.ts'
-export * from './array/shift.ts'
 export * from './array/sift.ts'
 export * from './array/sort.ts'
 export * from './array/toggle.ts'

tests/array/shift.test.ts → tests/array/circularShift.test.ts

@@ -1,37 +1,37 @@
 import * as _ from 'radashi'
 
-describe('shift', () => {
+describe('circularShift', () => {
   const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9]
   test('should shift array right 3 positions', () => {
-    const result = _.shift(arr, 3)
+    const result = _.circularShift(arr, 3)
     expect(result).toEqual([7, 8, 9, 1, 2, 3, 4, 5, 6])
   })
   test('should shift array left 3 positions', () => {
-    const result = _.shift(arr, -3)
+    const result = _.circularShift(arr, -3)
     expect(result).toEqual([4, 5, 6, 7, 8, 9, 1, 2, 3])
   })
   test('should shift array right 6 positions', () => {
-    const result = _.shift(arr, 15)
+    const result = _.circularShift(arr, 15)
     expect(result).toEqual([4, 5, 6, 7, 8, 9, 1, 2, 3])
   })
   test('should shift array left 6 positions', () => {
-    const result = _.shift(arr, -15)
+    const result = _.circularShift(arr, -15)
     expect(result).toEqual([7, 8, 9, 1, 2, 3, 4, 5, 6])
   })
   test('should keep array as is', () => {
-    const result = _.shift(arr, 0)
+    const result = _.circularShift(arr, 0)
     expect(result).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9])
   })
   test('should keep array as is', () => {
-    const result = _.shift(arr, 9)
+    const result = _.circularShift(arr, 9)
     expect(result).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9])
   })
   test('should return empty array', () => {
-    const results = _.shift([], 0)
+    const results = _.circularShift([], 0)
     expect(results).toEqual([])
   })
   test('should return empty array', () => {
-    const results = _.shift([], 10)
+    const results = _.circularShift([], 10)
     expect(results).toEqual([])
   })
 })