feat: add new move function

Author: imhoffd

packages/@ionic/utils-array/src/__tests__/index.ts

@@ -1,4 +1,4 @@
-import { concurrentFilter, conform, filter, reduce, map } from '../';
+import { concurrentFilter, conform, filter, reduce, map, move } from '../';
 
 describe('@ionic/utils-array', () => {
 
@@ -212,4 +212,53 @@ describe('@ionic/utils-array', () => {
 
   });
 
+  describe('move', () => {
+
+    const array = ['a', 'b', 'c'];
+
+    it('should move first element to last element', () => {
+      const result = move(array, 0, 2);
+      expect(result).toEqual(['b', 'c', 'a']);
+    });
+
+    it('should move last element to first element', () => {
+      const result = move(array, 2, 0);
+      expect(result).toEqual(['c', 'a', 'b']);
+    });
+
+    it('should not move element with equal indexes', () => {
+      const result = move(array, 1, 1);
+      expect(result).toEqual(['a', 'b', 'c']);
+      expect(result).not.toBe(array);
+    });
+
+    describe('out of bounds', () => {
+      it('should leave array unchanged for from index greater than array length', () => {
+        const result = move(array, 5, 0);
+        expect(result).toEqual(['a', 'b', 'c']);
+        expect(result).not.toBe(array);
+      });
+
+      it('should leave array unchanged for to index greater than array length', () => {
+        const result = move(array, 0, 5);
+        expect(result).toEqual(['a', 'b', 'c']);
+        expect(result).not.toBe(array);
+      });
+
+      it('should leave array unchanged for from index less than zero', () => {
+        const result = move(array, -1, 0);
+        expect(result).toEqual(['a', 'b', 'c']);
+        expect(result).not.toBe(array);
+      });
+
+      it('should leave array unchanged for to index less than zero', () => {
+        const result = move(array, 0, -1);
+        expect(result).toEqual(['a', 'b', 'c']);
+        expect(result).not.toBe(array);
+      });
+
+    });
+
+  });
+
 });

packages/@ionic/utils-array/src/index.ts

@@ -76,3 +76,23 @@ export async function reduce<T, U>(array: T[] | readonly T[], callback: (accumul
 
   return value;
 }
+
+/**
+ * Move an item in an array by index.
+ *
+ * This function will return a new array with the item in the `fromIndex`
+ * position moved to the `toIndex` position.
+ */
+export function move<T>(array: readonly T[], fromIndex: number, toIndex: number): T[] {
+  const element = array[fromIndex];
+  const result = [...array];
+
+  if (fromIndex <= -1 || toIndex <= -1 || fromIndex >= array.length || toIndex >= array.length) {
+    return result;
+  }
+
+  result.splice(fromIndex, 1);
+  result.splice(toIndex, 0, element);
+
+  return result;
+}