kicad/potrace/lists.h

/* Copyright (C) 2001-2015 Peter Selinger.
 *  This file is part of Potrace. It is free software and it is covered
 *  by the GNU General Public License. See the file COPYING for details. */


#ifndef _PS_LISTS_H
#define _PS_LISTS_H

/* here we define some general list macros. Because they are macros,
 *  they should work on any datatype with a "->next" component. Some of
 *  them use a "hook". If elt and list are of type t* then hook is of
 *  type t**. A hook stands for an insertion point in the list, i.e.,
 *  either before the first element, or between two elements, or after
 *  the last element. If an operation "sets the hook" for an element,
 *  then the hook is set to just before the element. One can insert
 *  something at a hook. One can also unlink at a hook: this means,
 *  unlink the element just after the hook. By "to unlink", we mean the
 *  element is removed from the list, but not deleted. Thus, it and its
 *  components still need to be freed. */

/* Note: these macros are somewhat experimental. Only the ones that
 *  are actually *used* have been tested. So be careful to test any
 *  that you use. Looking at the output of the preprocessor, "gcc -E"
 *  (possibly piped though "indent"), might help too. Also: these
 *  macros define some internal (local) variables that start with
 *  "_". */

/* we enclose macro definitions whose body consists of more than one
 *  statement in MACRO_BEGIN and MACRO_END, rather than '{' and '}'.  The
 *  reason is that we want to be able to use the macro in a context
 *  such as "if (...) macro(...); else ...". If we didn't use this obscure
 *  trick, we'd have to omit the ";" in such cases. */

#define MACRO_BEGIN do {
#define MACRO_END   } \
    while( 0 )

/* ---------------------------------------------------------------------- */
/* macros for singly-linked lists */

/* traverse list. At the end, elt is set to NULL. */
#define list_forall( elt, list ) for( elt = list; elt!=NULL; elt = elt->next )

/* set elt to the first element of list satisfying boolean condition
 *  c, or NULL if not found */
#define list_find( elt, list, c ) \
    MACRO_BEGIN list_forall( elt, list ) if( c ) \
        break; \
    MACRO_END

/* like forall, except also set hook for elt. */
#define list_forall2( elt, list, hook ) \
    for( elt = list, hook = &list; elt!=NULL; hook = &elt->next, elt = elt->next )

/* same as list_find, except also set hook for elt. */
#define list_find2( elt, list, c, hook ) \
    MACRO_BEGIN list_forall2( elt, list, hook ) if( c ) \
        break; \
    MACRO_END

/* same, except only use hook. */
#define _list_forall_hook( list, hook ) \
    for( hook = &list; *hook!=NULL; hook = &(*hook)->next )

/* same, except only use hook. Note: c may only refer to *hook, not elt. */
#define _list_find_hook( list, c, hook ) \
    MACRO_BEGIN _list_forall_hook( list, hook ) if( c ) \
        break; \
    MACRO_END

/* insert element after hook */
#define list_insert_athook( elt, hook ) \
    MACRO_BEGIN elt->next = *hook; *hook = elt; MACRO_END

/* insert element before hook */
#define list_insert_beforehook( elt, hook ) \
    MACRO_BEGIN elt->next = *hook; *hook = elt; hook = &elt->next; MACRO_END

/* unlink element after hook, let elt be unlinked element, or NULL.
 *  hook remains. */
#define list_unlink_athook( list, elt, hook ) \
    MACRO_BEGIN \
    elt = hook ? *hook : NULL; if( elt ) { *hook = elt->next; elt->next = NULL; } \
    MACRO_END

/* unlink the specific element, if it is in the list. Otherwise, set
 *  elt to NULL */
#define list_unlink( listtype, list, elt )      \
    MACRO_BEGIN                                 \
    listtype * *_hook;               \
    _list_find_hook( list, *_hook==elt, _hook );  \
    list_unlink_athook( list, elt, _hook );       \
    MACRO_END

/* prepend elt to list */
#define list_prepend( list, elt ) \
    MACRO_BEGIN elt->next = list; list = elt; MACRO_END

/* append elt to list. */
#define list_append( listtype, list, elt )     \
    MACRO_BEGIN                                \
    listtype * *_hook;                          \
    _list_forall_hook( list, _hook ) {}          \
    list_insert_athook( elt, _hook );            \
    MACRO_END

/* unlink the first element that satisfies the condition. */
#define list_unlink_cond( listtype, list, elt, c )     \
    MACRO_BEGIN                                        \
    listtype * *_hook;                  \
    list_find2( elt, list, c, _hook );                   \
    list_unlink_athook( list, elt, _hook );              \
    MACRO_END

/* let elt be the nth element of the list, starting to count from 0.
 *  Return NULL if out of bounds.   */
#define list_nth( elt, list, n )                                \
    MACRO_BEGIN                                                 \
    int _x; /* only evaluate n once */                         \
    for( _x = (n), elt = list; _x && elt; _x--, elt = elt->next ) {}   \
    MACRO_END

/* let elt be the nth element of the list, starting to count from 0.
 *  Return NULL if out of bounds.   */
#define list_nth_hook( elt, list, n, hook )                     \
    MACRO_BEGIN                                                 \
    int _x; /* only evaluate n once */                         \
    for( _x = (n), elt = list, hook = &list; _x && elt; \
         _x--, hook = &elt->next, elt = elt->next ) {}   \
    MACRO_END

/* set n to the length of the list */
#define list_length( listtype, list, n )                   \
    MACRO_BEGIN                                            \
    listtype * _elt;                        \
    n = 0;                           \
    list_forall( _elt, list )                \
    n++;                         \
    MACRO_END

/* set n to the index of the first element satisfying cond, or -1 if
 *  none found. Also set elt to the element, or NULL if none found. */
#define list_index( list, n, elt, c )                      \
    MACRO_BEGIN                        \
    n = 0;                           \
    list_forall( elt, list ) {               \
        if( c ) \
            break;                    \
        n++;                         \
    }                          \
    if( !elt )                      \
        n = -1;                        \
    MACRO_END

/* set n to the number of elements in the list that satisfy condition c */
#define list_count( list, n, elt, c )                      \
    MACRO_BEGIN                        \
    n = 0;                           \
    list_forall( elt, list ) {               \
        if( c ) \
            n++;                      \
    }                                                      \
    MACRO_END

/* let elt be each element of the list, unlinked. At the end, set list=NULL. */
#define list_forall_unlink( elt, list ) \
    for( elt = list; elt ? (list = elt->next, elt->next = NULL), 1 : 0; elt = list )

/* reverse a list (efficient) */
#define list_reverse( listtype, list )            \
    MACRO_BEGIN                   \
    listtype * _list1 = NULL, *elt;          \
    list_forall_unlink( elt, list )         \
    list_prepend( _list1, elt );          \
    list = _list1;                \
    MACRO_END

/* insert the element ELT just before the first element TMP of the
 *  list for which COND holds. Here COND must be a condition of ELT and
 *  TMP.  Typical usage is to insert an element into an ordered list:
 *  for instance, list_insert_ordered(listtype, list, elt, tmp,
 *  elt->size <= tmp->size).  Note: if we give a "less than or equal"
 *  condition, the new element will be inserted just before a sequence
 *  of equal elements. If we give a "less than" condition, the new
 *  element will be inserted just after a list of equal elements.
 *  Note: it is much more efficient to construct a list with
 *  list_prepend and then order it with list_merge_sort, than to
 *  construct it with list_insert_ordered. */
#define list_insert_ordered( listtype, list, elt, tmp, cond ) \
    MACRO_BEGIN                                               \
    listtype * *_hook;                                         \
    _list_find_hook( list, ( tmp = *_hook, (cond) ), _hook );       \
    list_insert_athook( elt, _hook );                           \
    MACRO_END

/* sort the given list, according to the comparison condition.
 *  Typical usage is list_sort(listtype, list, a, b, a->size <
 *  b->size).  Note: if we give "less than or equal" condition, each
 *  segment of equal elements will be reversed in order. If we give a
 *  "less than" condition, each segment of equal elements will retain
 *  the original order. The latter is slower but sometimes
 *  prettier. Average running time: n*n/2. */
#define list_sort( listtype, list, a, b, cond )            \
    MACRO_BEGIN                                            \
    listtype * _newlist = NULL;                               \
    list_forall_unlink( a, list )                            \
    list_insert_ordered( listtype, _newlist, a, b, cond ); \
    list = _newlist;                                       \
    MACRO_END

/* a much faster sort algorithm (merge sort, n log n worst case). It
 *  is required that the list type has an additional, unused next1
 *  component. Note there is no curious reversal of order of equal
 *  elements as for list_sort. */

#define list_mergesort( listtype, list, a, b, cond )              \
    MACRO_BEGIN                               \
    listtype * _elt, **_hook1;                     \
                                    \
    for( _elt = list; _elt; _elt = _elt->next1 ) {         \
        _elt->next1 = _elt->next;                       \
        _elt->next  = NULL;                          \
    }                                 \
    do {                                                  \
        _hook1 = &(list);                               \
        while( (a = *_hook1) != NULL && (b = a->next1) != NULL ) {  \
            _elt = b->next1;                          \
            _list_merge_cond( listtype, a, b, cond, *_hook1 );          \
            _hook1  = &( (*_hook1)->next1 );                 \
            *_hook1 = _elt;                               \
        }                                   \
    } \
    while( _hook1 != &(list) );                                  \
    MACRO_END

/* merge two sorted lists. Store result at &result */
#define _list_merge_cond( listtype, a, b, cond, result )   \
    MACRO_BEGIN                                            \
    listtype * *_hook;                  \
    _hook = &(result);                     \
    while( 1 ) {                                            \
        if( a==NULL ) {                  \
            *_hook = b;                   \
            break;                        \
        } \
        else if( b==NULL ) {               \
            *_hook = a;                   \
            break;                        \
        } \
        else if( cond ) {                  \
            *_hook  = a;                   \
            _hook   = &(a->next);               \
            a = a->next;                  \
        } \
        else {                        \
            *_hook  = b;                   \
            _hook   = &(b->next);               \
            b = b->next;                  \
        }                           \
    }                          \
    MACRO_END

/* ---------------------------------------------------------------------- */
/* macros for doubly-linked lists */

#define dlist_append( head, end, elt )                    \
    MACRO_BEGIN                                            \
    elt->prev = end;                   \
    elt->next = NULL;                  \
    if( end ) {                         \
        end->next = elt;                     \
    } \
    else {                           \
        head = elt;                      \
    }                              \
    end = elt;                         \
    MACRO_END

/* let elt be each element of the list, unlinked. At the end, set list=NULL. */
#define dlist_forall_unlink( elt, head, end ) \
    for( elt = head; \
         elt ? (head = elt->next, elt->next = NULL, elt->prev = NULL), 1 : (end = NULL, 0); \
         elt = head )

/* unlink the first element of the list */
#define dlist_unlink_first( head, end, elt )               \
    MACRO_BEGIN                                \
    elt = head;                        \
    if( head ) {                        \
        head = head->next;                   \
        if( head ) {                      \
            head->prev = NULL;                 \
        } \
        else {                         \
            end = NULL;                    \
        }                            \
        elt->prev = NULL;                    \
        elt->next = NULL;                    \
    }                          \
    MACRO_END

#endif /* _PS_LISTS_H */