PK_ERROR_code_t    PK_EDGE_imprint_point
(
--- received arguments ---
PK_EDGE_t          edge,        --- edge to be imprinted onto
PK_POINT_t         point,       --- point to imprint

--- returned arguments ---
PK_VERTEX_t *const new_vertex,  --- new vertex
PK_EDGE_t   *const new_edge     --- new edge   (may be PK_ENTITY_null)
)


This function imprints a point onto an edge, thereby creating a
new vertex.


Specific Errors:
    PK_ERROR_coincident            point coincident with existing vertex
    PK_ERROR_not_on_curve          point does not lie on edge's curve or
                                   it is outside the edge
    PK_ERROR_missing_geom          edge does not have geometry


If point does not lie on edges curve, or it is outside that part of the
curve on which the edge lies, then the error code PK_ERROR_not_on_curve is
returned.

If point lies within the edge, then a new_vertex is created at this
position.  If edge was a ring edge, then no 'new_edge' is created and
new_edge is returned as PK_ENTITY_null.  If edge was not a ring edge,
then adding the new vertex splits the edge into two.  The new edge is returned
in new_edge.  If point was an orphan then it will be attached to the new
vertex.  If point was not an orphan, then a copy of it will be attached to
the new vertex.