Insert Method (INamedValues2 interface)



Inserts an orphan NamedValue object into this NamedValues collection.



object.Insert ToInsert


The Rename method syntax has these parts:




An object expression that evaluates to an INamedValues2 interface.


An object expression that evaluates to an orphan NamedValue object.



NamedValue objects can have only one parent. For safety's sake, this method will not silently remove a NamedValue from its previous parent. Therefore the object to be inserted must be an orphan; that is, it must already have been removed or detached from its parent.

If the object to insert has a name that already exists in the collection, it is an error. This is unlike the Copy and Merge methods, which can optionally replace the values of duplicate items. However, in strategies that use Detach and Insert, it is generally the case that the NamedValue object's identity is important; that is, a pointer to the object has been cached somewhere. Thus it is important truly to insert the object into its new collection, and not simply to copy its value.

Name matching takes the collection's Style property into account. This specifies case and locale sensitivity, and whether leading and trailing blanks are trimmed.


Trappable Errors

In addition to generic errors (such as Out of Memory), the following errors may occur:




The collection cannot be modified because it is frozen; that is, its ReadOnly property is true.


The Parent property of the object to insert is not Nothing.


The collection already contains an item whose Name property matches the name of the object to insert.

Enabling Operational Intelligence