===================
Deleting a PRC Tree
===================

Any entity created with a `Create` function returns an *entity handle* that corresponds to some amount of memory in your system.
When your work is done with this entity, you may want to release it's associated memory by deleting it.

Deleting an entity is done differently according to whether it is already attached to another entity or not.

An entity is *attached* to another when is has a parent entity. For example:

* The root :struct:`A3DAsmProductOccurrence` inside an :struct:`A3DAsmModelFile` is attached to it.
* If an :struct:`A3DAsmProductOccurrence` contains a prototype, this prototype is attached to it.

Attached/Detached is simply a different way to express whether an entity is part of a PRC tree or not.

***************************
Deleting an Attached Entity
***************************

If an entity is part of a PRC tree it _will_ be implicitly deleted upon the suppression of the model file using :func:`A3DAsmModelFileDelete`.
Thus, you don't have to worry about specifically deleting each entities inside a model file.

.. code-block:: c

   // Delete a model file and recursively all its children:
   A3DStatus result = A3DAsmModelFileDelete(model_file);
   assert(result == A3D_SUCCESS);

All the handles of the deleted model file and its children will be invalidated.

**************************
Deleting a Detached Entity
**************************

To delete any entity you didn't attach to any parent, call :func:`A3DEntityDelete`.
It will delete all the child entities as well:

.. code-block:: c

   // Delete an entity and recursively all its children:
   A3DStatus result = A3DEntityDelete(entity);
   assert(result == A3D_SUCCESS);

All the handles of the deleted entity and its children will be invalidated.

.. note::

   Some entity types require a specific function for deletion. Please see:
   * :func:`A3DFileContextDelete` 
   * :func:`A3DAsmModelFileDelete` (Deprecated, use :func:`A3DEntityDelete`)
   * :func:`A3DFaceUVPointInsideManagerDelete` (Deprecated, use :func:`A3DEntityDelete`)
   * :func:`A3DGraphicsDelete` (Deprecated, use :func:`A3DEntityDelete`)
   * :func:`A3DMiscCascadedAttributesDelete` (Deprecated, use :func:`A3DEntityDelete`)
   * :func:`A3DMkpRTFFieldDelete` (Deprecated, use :func:`A3DEntityDelete`)
   * :func:`A3DProjectPointCloudManagerDelete` (Deprecated, use :func:`A3DEntityDelete`)
