FEAT: Add rm and rmAt methods

Author: bluejava

IArray.js

@@ -74,6 +74,24 @@
 		return deepFreeze(a2)
 	}
 
+	function rmAt(index)
+	{
+		var a2 = createIArray(this),
+			ret = Array.prototype.splice.call(a2, index, 1)
+		a2.ret = ret[0]
+		return deepFreeze(a2)
+	}
+
+	function rm(value)
+	{
+		var index = this.indexOf(value)
+		if(index >= 0)
+			return this.rmAt(index)
+		var a2 = createIArray(this)
+		a2.ret = undefined
+		return deepFreeze(a2) // return a clone
+	}
+
 	// Create our custom IArray prototype, with Array.prototype at the base
 	var IAProto = Object.assign(
 			Object.create(Array.prototype),
@@ -83,6 +101,8 @@
 				concat: concat,
 				isIArray: true,
 				set: set,
+				rm: rm,
+				rmAt: rmAt,
 				toJSON: function() { return this.toArray() },
 				toArray: function() { return Array.prototype.slice.call(this) }
 			}

IArray.min.js

@@ -14,14 +14,14 @@ Arrays are an extremely popular data structure in most JavaScript programs. But
 
 Some libraries exist that provide random access data structures similar to the Array but that are immutable, such as [Mori](http://swannodette.github.io/mori/) or [Immutable](https://facebook.github.io/immutable-js/) - but they are large opinionated libraries that expose a completely different API.
 
-**IArray** provides an Immutable array only, and is very light. 
+**IArray** provides an Immutable array only, and is very light.
 
 ```bash
-wc -l IArray.js 
-119 IArray.js
+wc -l IArray.js
+146 IArray.js
 ```
 
-119 lines in the *source* file, much of which is comments and the universal module definition. 
+146 lines in the *source* file, much of which is comments and the universal module definition.
 
 ## How
 
@@ -41,7 +41,7 @@ In cases where a method mutated the underlying array and also returned a value (
 
 ## API
 
-Since this extends the standard JavaScript `Array`, I will only document the methods that have *changed* from the standard Array API:
+Since this extends the standard JavaScript `Array`, I will only document the methods that have *changed* from the standard Array API. These include **3** new methods, `rm`, `rmAt` and `set` along with several methods from the `Array` API whose behavior is slightly changed to reflect the immutable nature of `IArray`.
 
 
 ### `concat(value1[, value2 ...]) => IArray`
@@ -122,6 +122,30 @@ var a2 = a1.pop()
 // a2.ret = 9				- last element stored in ret property
 ```
 
+### `rm(value) => IArray`
+
+Returns a new `IArray` with the `value` specified removed. If multiple occurrences of the value exists, the first one is removed. The removed value appears on the `ret` property of the newly created `IArray`. If the value does not exist in the array, no error is thrown, but the `ret` property contains `undefined`.
+
+```javascript
+var a1 = IArray([1, 4, 9])		// a1 is [ 1, 4, 9 ]
+var a2 = a1.rm(4)				// a2 is [ 1, 9 ]
+log(a2.ret)						// 4
+var a3 = a2.rm(6)				// this doesn't exist, so a3 is [ 1, 9 ]
+log(a3.ret)						// undefined
+```
+
+### `rmAt(index) => IArray`
+
+Returns a new `IArray` with the value at position `index` removed. The removed value appears on the `ret` property of the newly created `IArray`. If the `index` position specified is out of the range of the `IArray`, no error is thrown, but the `ret` property contains `undefined` and the values in the returned `IArray` are unchanged.
+
+```javascript
+var a1 = IArray([1, 4, 9])		// a1 is [ 1, 4, 9 ]
+var a2 = a1.rmAt(1)				// a2 is [ 1, 9 ]
+log(a2.ret)						// 4
+var a3 = a2.rmAt(6)				// position out of range, so a3 is [ 1, 9 ]
+log(a3.ret)						// undefined
+```
+
 ### `set(index, value) => IArray`
 
 Used to assign a value to a specific index within the `IArray`. This is used as a substitute to the `array[index] = value` notation, which mutates the array. The returned `IArray` is a copy of the original array with value assigned at the index specified.
@@ -200,4 +224,4 @@ var a2 = a1.unshift("hello", "world")
 
 ### License
 
-See the LICENSE file for license rights and limitations (MIT).
+See the LICENSE file for license rights and limitations (MIT).

README.md

@@ -1,6 +1,6 @@
 {
 	"name": "IArray",
-	"version": "1.1.5",
+	"version": "1.2.0",
 	"description": "Immutable Array",
 	"main": "IArray.js",
 	"scripts": {

package.json

@@ -469,6 +469,32 @@
 					assert.deepEqual(a4.toArray(), [ "hello", "world", 5, 10, 20]) // prepended to start
 
 				})
+
+			test("rm", function() {
+
+					var a1 = IArray([5, 6, 7, 8, 9, 10])
+					var a2 = a1.rm(8)
+					var a3 = a1.rm(23)	// test removal of non-existant entry
+
+					assert.deepEqual(a1.toArray(), [5, 6, 7, 8, 9, 10]) // unchanged
+					assert.deepEqual(a2.toArray(), [5, 6, 7, 9, 10]) // a1 with 8 value removed
+					assert.equal(a2.ret, 8) // here is the removed value
+					assert.deepEqual(a3.toArray(), [5, 6, 7, 8, 9, 10]) // unchanged since 23 was not present
+					assert.equal(a3.ret, undefined) // ensure return value was set as undefined
+				})
+
+				test("rmAt", function() {
+
+						var a1 = IArray([5, 6, 7, 8, 9, 10])
+						var a2 = a1.rmAt(2) // removes the 7 at position 2
+						var a3 = a1.rmAt(7)	// test removal of non-existant entry
+
+						assert.deepEqual(a1.toArray(), [5, 6, 7, 8, 9, 10]) // unchanged
+						assert.deepEqual(a2.toArray(), [5, 6, 8, 9, 10]) // a1 with 7 value at position 2 removed
+						assert.equal(a2.ret, 7) // here is the removed value
+						assert.deepEqual(a3.toArray(), [5, 6, 7, 8, 9, 10]) // unchanged since no value at position 7
+						assert.equal(a3.ret, undefined) // ensure return value was set as undefined
+					})
 		}
 
 		function testImmutableIndexChanges()