PK_ERROR_code_t    PK_ENTITY_copy
(
--- received arguments ---
PK_ENTITY_t        entity,          --- an entity

--- returned arguments ---
PK_ENTITY_t *const entity_copy      --- copy of given entity
)


This function produces a new entity which is a copy of the given entity.


Specific Errors:
    PK_ERROR_wrong_entity           this class of entity can not be copied
    PK_ERROR_part_not_isolated      copy would instance true-sub-part of
                                    stored part


PK_ENTITY_copy returns a copy of entity in entity_copy.

The classes of entity which may be copied are:


Assembly:
  'entity_copy' will be an uninstanced copy of 'entity'.
  The instances in 'entity_copy'
  will be copies of those in 'entity' but the parts they reference will not
  be copied. Any groups and attributes attached to the assembly are also
  copied. The state of 'entity_copy' will be "new".

  If 'entity' is an unloaded assembly it is received before copying
  is attempted.

  We define the true-sub-parts of a stored part S as those anonymous
  sub-parts of S reachable from S without encountering other stored
  parts.

  A stored or anonymous assembly which instances true-sub-parts of a stored
  part may not be copied as this would cause the stored part to become
  unisolated. For example, the parts marked with a * may not be copied and
  PK_ERROR_part_not_isolated will be returned.

                st
                 |
                st*
               /  \
              an* an*
               \  /
                an
                 |
                st


Instance:
  If 'entity' is an instance of part P in assembly A then 'entity_copy' will be
  a new instance of P in A with a copy of 'entity's transformation. Any
  attributes attached to the instance are not copied.


Body:
  'entity_copy' will be an uninstanced copy of 'entity'. Any groups and
  attributes attached to the body will also be copied. The state of
  'entity_copy' will be "new".

  If 'entity' is an unloaded body it is received before copying
  is attempted.


Surface, Curve, Point:
  'entity_copy' will be a copy of 'entity' plus any underlying geometry. If
  'entity' is construction geometry in a part 'entity_copy' will also be
  construction geometry in the same part.  Otherwise 'entity_copy' will be
  orphaned. Any attributes attached to 'entity' will not be copied.


Transformation:
  'entity_copy' is an orphaned copy of 'entity'.


Group:
  'entity_copy' will have the same members as 'entity' and will be in the
  same part. Any attributes attached to 'entity' will not be copied.