NAME

cru_splitter - specification for vertex mitosis in the cru library

SYNOPSIS

#include <cru/cru.h>

typedef struct cru_splitter_s
{
   cru_bop ana;
   cru_bop cata;
   cru_bpred fissile;
   struct cru_prop_s sp_prop;
   struct cru_ctop_quad_s sp_ctops;
} *cru_splitter;

DESCRIPTION

This structure parameterizes the cru_split library function with necessary information initialized by the application to expand a graph by replacing selected vertices with pairs of vertices in parallel. These fields are interpreted as follows.

• For each vertex in a given graph, a property is computed according to the sp_prop field following usual cru_prop calling conventions.
• Each vertex in the graph is tested by the fissile field's predicate given the vertex as its left operand and the vertex's property as its right.
• Any vertex for which the fissile predicate returns a non-zero value is passed as the left operand to the binary operators referenced in the ana and cata fields along with the vertex property as the right operand. These functions are each expected to return a separate new vertex. The resulting vertices jointly replace the given vertex in the graph.
• Properties are also computed for these two new vertices according to the sp_prop field. For purposes of these computations, the incident and outgoing edges to the new vertices are identical to those of the vertex being replaced.

Some additional interpretations can be inferred if not all fields are specified.

• If the fissile field is omitted or initialized to NULL, then every vertex is replaced unconditionally.
• If the sp_prop field is omitted or zero-filled, then the property associated with any vertex is identical to the vertex.
• For either of the ana or cata fields initialized to NULL where the vertices are scalar values, a function returning a copy of the vertex is inferred.

When the decision is made to replace a vertex, its incoming and outgoing edges must be removed and possibly replaced by edges connected to the two vertices replacing it. This aspect of the operation is specified by the conditional ternary operator quadruple structure in the sp_ctops field. If the sp_ctops field is omitted or zero-filled, then this behavior applies by default.

• Two copies are made of each edge formerly incident on the replaced vertex. The copies have the same label and the same origin as the former edge, but one is made to terminate at the vertex created by the ana function, and the other is made to terminate at the vertex created by the cata function.
• Similarly, two copies are made of each edge formerly outgoing from the replaced vertex. The copies have the same label and the same terminus as the former edge, but one is made to originate from the vertex created by the ana function, and the other is made to originate from the vertex created by the cata function.

The default behavior above is inferred only for graphs whose edge labels are created as scalar values. If the edge labels are pointers to dynamically allocated data, then the sp_ctops field must be initialized by the application. In either case, if the sp_ctops field is initialized, then it is interpreted as follows.

• For each edge formerly incident on the replaced vertex, both the ana and the cata labeler ternary predicates sp_ctops.inward.ana.tpred and sp_ctops.inward.cata.tpred on the inward side of the quadruple are passed the same three operands: the edge label as their middle operand and the properties of the edge's origin and terminus as their left and right operands, respectively.
• For each labeler whose ternary predicate returns a non-zero value, the same operands are passed to that labeler's ternary operator, either sp_ctops.inward.ana.top or sp_ctops.inward.cata.top, which is expected to return the label of a new edge to be included in the graph. Results from the ana labeler's operator label the edges connecting the origin of the former edge to the vertex created by the ana function, and results from the cata labler's operator label the edges connecting the origin of the former edge to the vertex created by the cata function.

Analogous interpretations apply to the ana and cata labler conditional ternary predicates on the outward side of the quadruple.

• For each edge formerly outgoing from the replaced vertex, both the ana and the cata labeler ternary predicates sp_ctops.outward.ana.tpred and sp_ctops.outward.cata.tpred on the outward side of the quadruple are passed the same three operands: the edge label as their middle operand and the properties of the edge's origin and terminus as their left and right operands, respectively.
• For each labeler whose ternary predicate returns a non-zero value, the same operands are passed to that labeler's ternary operator, either sp_ctops.inward.ana.top or sp_ctops.inward.cata.top, which is expected to return the label of a new edge to be included in the graph. Results from the ana labeler's operator label the edges connecting the the vertex created by the ana function to the terminus of the former edge, and results from the cata labler's operator label the edges connecting the vertex created by the cata function to the terminus of the former edge.

ERRORS

In addition to any errors pertaining to incorrectly or inadequately initialized conditional ternary operators, the cru_split function reports errors of CRU_UNDANA or CRU_UNDCAT respectively if the ana or cata fields are omitted or NULL and not inferrable. Because this operation increases the number of vertices in a graph, it may also report CRU_INTOVF if a vertex limit previously associated with the graph is exceeded.

FILES

/usr/local/include/cru/data_types.h

/usr/local/include/cru/error_codes.h

SEE ALSO

cru, cru_bop, cru_bpred, cru_builder, cru_built, cru_cbop, cru_classifier, cru_class_of, cru_class_size, cru_composed, cru_composer, cru_connect, cru_connector, cru_cqop, cru_crossed, cru_crosser, cru_ctop, cru_ctop_pair, cru_ctop_quad, cru_data_types, cru_deduplicated, cru_destructor, cru_destructor_pair, cru_edge_count, cru_fabricated, cru_fabricator, cru_filter, cru_filtered, cru_fold, cru_free_kill_switch, cru_free_later, cru_free_now, cru_free_partition, cru_function_types, cru_get, cru_hash, cru_induced, cru_inducer, cru_kernel, cru_kill, cru_killed, cru_mapreduced, cru_mapreducer, cru_merged, cru_merger, cru_mutated, cru_mutator, cru_new_kill_switch, cru_nop, cru_order, cru_order_pair, cru_partition_of, cru_plan, cru_postponed, cru_postponer, cru_prop, cru_prop_pair, cru_pruner, cru_qop, cru_qpred, cru_set, cru_sig, cru_singleton, cru_split, cru_spread, cru_strerror, cru_stretch, cru_stretched, cru_stretcher, cru_subconnector, cru_terminus_count, cru_top, cru_tpred, cru_united, cru_uop, cru_vertex_count, cru_zone

AUTHOR

Dennis Furey (milonga@delayinsensitive.com)

PROJECT PAGE

https://github.com/gueststar/cru