company logo

Property :: erase - Delete/remove instance from collection

The function removes the instance positioned from the collection referenced by the property handle. When passing a key or a position the function positions the instance with the passed key or at the given position before removing it from the collection.

The property handle must be opened in write or update mode. For deleting the instance the selected instance must be available in write mode as well.

Removing an instance from a collection will delete the instance too, when the collection is owning its instances or when the instances in the collection depend on the collection. You may also request deleting the instance by passing the bDeleteInstance parameter.

Removing an instance from a collection it will maintain automatically inverse references. Moreover, the instance is removed from all derived collections (subsets). This means, instances might be deleted also, when being owned by or dependent on one of the derived collections.

When deleting an instance, which is shared base instance for other derived instances, derived instances are deleted as well.

When no instance could be located or an error occurred, the function throws an exception. An exception will be also thrown, when applying the function on property handles for attributes or exclusive base instances (exclusive generalization).

Implementation overview

Implementation details

  1. Remove current instance
    Property  :: erase (  )

    The function removes the selected instance from the collection. When the collection is owner of the instance or the instance depends on the collection, the instance will be deleted. Otherwise, the instances will be removed from the collection but not deleted.
    2. to list
  2. Delete current instance
    Property  :: erase ( bool bDeleteInstance )

    The function removes the selected instance from the collection. When the collection is owner of the instance or the instance depends on the collection, the instance will be deleted.

    When the current collection is not owner of instances and instances do not depend on the collection, instances are removed from the collection but not deleted (bDeleteInstance=false). In order to delete the instance anyhow, true has to be passed in bDeleteInstance.

    • bDeleteInstance - Delete instance requested

      The parameter must be set to true in order to delete the instance instead of removing the instance from the collection, only. The option is not required, when the instance is owned by the collection.
    3. to list
  3. Force deleting instance by position
    Property  :: erase ( int32 iPosition, bool bDeleteInstance )

    The function deletes the instance at the position passed in iPosition. Dependent instances are deleted as well. The value passed in iPosition must be a value greater or equal to -1. In case of an invalid position value, the function throws an exception. Passing -1 will delete the current instance.

    When the current collection is not owner of instances and instances do not depend on the collection, instances are removed from the collection but not deleted (bDeleteInstance=false). In order to delete the instance anyhow, true has to be passed in bDeleteInstance.

    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    • bDeleteInstance - Delete instance requested

      The parameter must be set to true in order to delete the instance instead of removing the instance from the collection, only. The option is not required, when the instance is owned by the collection.
    4. to list
  4. Force deleting instance by position
    Property  :: erase ( int32 iPosition, bool bDeleteDependent, bool bDeleteInstance )

    The function deletes the instance at the position passed in iPosition. The value passed in iPosition must be a value greater or equal to -1. In case of an invalid position value, the function throws an exception. Passing -1 will delete the current instance.

    Dependent instances are usually deleted as well (bDeleteDependent=true). In order to suppress deleting dependent instances, false has to be passed in bDeleteDependent.

    When the current collection is not owner of instances and instances do not depend on the collection, instances are removed from the collection but not deleted (bDeleteInstance=false). In order to delete the instance anyhow, true has to be passed in bDeleteInstance.

    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    • bDeleteDependent - Delete dependent instances

      Usually this option is set to true, i.e. all dependent instances are deleted when being removed from the collection. Passing false dependent instances are not deleted but removed from the collection, only.

      Instances owned by the collection, however, will be deleted always.
    • bDeleteInstance - Delete instance requested

      The parameter must be set to true in order to delete the instance instead of removing the instance from the collection, only. The option is not required, when the instance is owned by the collection.
    5. to list
  5. Delete instance by key
    Property  :: erase ( odaba::Key vSortKey )

    The function tries to locate an instance with the key value passed in vSortKey according to the selected access key. When no such instance exists, the function throws an exception. Otherwise, the instance located will be removed from the collection.

    When the current collection is not owner of instances and instances do not depend on the collection, instances are removed from the collection but not deleted.
    • vSortKey - Access key

      The sort or access key value is provided as typed string in ESDF or CSV format. Key components can be separated by '|' or ';'.

      // key: name;first_name

      Miller;Paul          // simple positioned CSV key

      "Miller";"Paul Mary" // special characters must be quoted
    6. to list
  6. Delete instance by position
    Property  :: erase ( int32 iPosition )

    The function deletes the instance at the position passed in iPosition. Dependent instances are deleted as well. The value passed in iPosition must be a value greater or equal to -1. Passing -1 will delete the current instance. In case of an invalid position value, the function throws an exception.

    When the current collection is not owner of instances and instances do not depend on the collection, instances are removed from the collection but not deleted.
    Notes:

    Deleting an instance by position may fail (without generating a database error) when a filter condition is set for the collection, which is not fulfilled for the instance to be deleted.

    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    7. to list
  7. Delete by key or position
    Property  :: erase ( odaba::Property &cProperty )

    When passing the value for removing an instance in a collection via property handle, the function is called as removing by key or index, depending on the data type defined in the property handle.

    When the property handle rPropertypasses a typed instance of the same or a specialized type as the instance to be removed, the key value is extracted from the instance passed in the property handle and remove by key is called.

    When passing a text value (STRING, or any other character type), the text data is considered as string key and remove by key is called.

    When the property handle rProperty contains a numerical value, remove by position is called. Non integer numerical values are rounded to the next lower integer number.

    When the current collection is not owner of instances and instances do not depend on the collection, instances are removed from the collection but not deleted.
    • cProperty - Property reference

      A property handle refers to a (usually) opened property. Invalid properties may cause an exception.
    8. to list
to top previous next upper table of contents Comment