Changes the parent of <object> to be <new-parent>. If <object> is not valid, or if <new-parent> is neither valid nor equal to #-1, then E_INVARG is raised. If the programmer is neither a wizard or the owner of <object>, or if <new-parent> is not fertile (i.e., its `f' bit is not set) and the programmer is neither the owner of <new-parent> nor a wizard, then `E_PERM' is raised. If <new-parent> is equal to <object> or one of its current ancestors, E_RECMOVE is raised. If <object> or one of its descendants defines a property with the same name as one defined either on <new-parent> or on one of its ancestors, then `E_INVARG' is returned.
Changing an object's parent can have the effect of removing some properties from and adding some other properties to that object and all of its descendants (i.e., its children and its children's children, etc.). Let <common> be the nearest ancestor that <object> and <new-parent> have in common before the parent of <object> is changed. Then all properties defined by ancestors of <object> under <common> (that is, those ancestors of <object> that are in turn descendants of <common>) are removed from <object> and all of its descendants. All properties defined by <new-parent> or its ancestors under <common> are added to <object> and all of its descendants. As with `create()', the newly-added properties are given the same permission bits as they have on <new-parent>, the owner of each added property is either the owner of the object it's added to (if the `c' permissions bit is set) or the owner of that property on <new-parent>, and the value of each added property is "clear"; see the description of the built-in function `clear_property()' for details. All properties that are not removed or added in the reparenting process are completely unchanged.
If <new-parent> is equal to #-1, then <object> is given no parent at all; it becomes a new root of the parent/child hierarchy. In this case, all formerly inherited properties on <object> are simply removed.