Implement Item#replaceWith(item)

Closes #454

src/item/Item.js

@@ -2244,6 +2244,19 @@ var Item = Base.extend(Callback, /** @lends Item# */{
         return this._remove(true, true);
     },
 
+    /**
+     * Replaces this item with the provided new item which will takes its place
+     * in the project hierarchy instead.
+     *
+     * @return {Boolean} {@true if the item was replaced}
+     */
+    replaceWith: function(item) {
+        var ok = item && item.insertBelow(this);
+        if (ok)
+            this.remove();
+        return ok;
+    },
+
     /**
      * Removes all of the item's {@link #children} (if any).
      *

test/tests/Item.js

@@ -183,6 +183,29 @@ test('item.nextSibling / item.previousSibling', function() {
     }, true);
 });
 
+test('item.replaceWith(other)', function() {
+    var project = paper.project;
+    var path = new Path();
+    var secondPath = new Path();
+    var thirdPath = new Path();
+    equals(function() {
+        return project.activeLayer.children.length;
+    }, 3);
+    path.replaceWith(secondPath);
+    equals(function() {
+        return project.activeLayer.children.length;
+    }, 2);
+    equals(function() {
+        return path.parent == null;
+    }, true);
+    equals(function() {
+        return secondPath.previousSibling == null;
+    }, true);
+    equals(function() {
+        return secondPath.nextSibling == thirdPath;
+    }, true);
+});
+
 test('item.insertChild(0, child)', function() {
     var project = paper.project;
     var path = new Path();