ChainCelsAtTail

Chains together lists of cels.

Synopsis

CCB * ChainCelsAtTail(CCB *existingCels, CCB *newCels)

Description

Chains together two lists of cels, putting the new list behind the existing cels. The return value is a pointer to the last cel in the resulting list. Either pointer can be NUL. In that case, the function just returns a pointer to the last cel in the list pointed to by the other pointer.

The most efficient way to iteratively build a list of cels is to use the return value from the prior call as the existingCels pointer for the current call. This eliminates long searches for the end of the ever-growing list of cels.

For example:

CCB *list = NULL; 
CCB *tail = NULL; 
CCB *cels; 
do {     cels = get_next_antialiased_cel(); 
    tail = ChainCelsAtTail(tail, cels); 
    if (list == NULL) { list = cels;  // remember head-of-list 
pointer first time through. } } 
    while (cels != NULL);

This function works properly with anti-aliased cels and similar constructs where a list of related cels makes up a single logical entity.

Arguments

existingCels: Pointer to the existing list of cels; may be NULL.

newCels: Pointer to the new list of cels to be added at the end of the existing list; may be NULL.

Return Value

Pointer to the last cel in the resulting list of cels.

Implementation

Library call implemented in lib3do.lib.

Associated Files

lib3do.lib, celutils.h