Next: 4.10.34 qr Up: 4.10 Classes Previous: 4.10.32 nxo_thread Contents Index
Subsections

- 4.10.33.1 API

##
4.10.33 ql

The ql macros implement operations on a list. The type of the list elements and which field of the elements to use are determined by arguments that are passed into the macros. The macros are optimized for speed and code size, which means that there is minimal error checking built in. As a result, care must be taken to assure that these macros are used as intended, or strange things can happen.

Internally, the list is represented as a ring, so with some care, the ql and qr interfaces can be used in conjunction with each other.

Since a ql is actually a ring, it is possible to have multiple ql heads that share the same ring. This works just fine, with the caveat that operations on one ql can have side-effects on another.

### 4.10.33.1 API

ql_head(<ql_type> a_type):

  Input(s):
    a_type:
      Data type for the ql elements.
  Output(s):
    A data structure that can be used as a ql head.
  Exception(s):
    None.
  Description:
    Generate code for a ql head data structure.

ql_head_initializer(<ql_type> *a_head):

  Input(s):
    a_head:
      Pointer to a ql head.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Statically initialize a ql head.

ql_elm(<ql_type> a_type):

  Input(s):
    a_type:
      Data type for the ql elements.
  Output(s):
    A data structure that can be used as a ql element.
  Exception(s):
    None.
  Description:
    Generate code for a ql element data structure.

void ql_new(<ql_head> *a_head):

  Input(s):
    a_head:
      Pointer to a ql head.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Constructor.

void ql_elm_new(<ql_type> *a_elm, <field_name> a_field):

  Input(s):
    a_elm:
      Pointer to an element.
    a_field:
      Field within the ql elements to use.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Constructor.

<ql_type> * ql_first(<ql_head> *a_head):

  Input(s):
    a_head:
      Pointer to a ql head.
  Output(s):
    retval:
      non-NULL:
        Pointer to the first element in a_head.
      NULL:
        a_head is empty.
  Exception(s):
    None.
  Description:
    Return a pointer to the first element in the ql.

<ql_type> * ql_last(<ql_head> *a_head, <field_name> a_field):

  Input(s):
    a_head:
      Pointer to a ql head.
    a_field:
      Field within the ql elements to use.
  Output(s):
    retval:
      non-NULL:
        Pointer to the last element in a_head.
      NULL:
        a_head is empty.
  Exception(s):
    None.
  Description:
    Return a pointer to the last element in the ql.

<ql_type> * ql_next(<ql_head> *a_head, <ql_type> *a_elm, <field_name> a_field):

  Input(s):
    a_head:
      Pointer to a ql head.
    a_elm:
      Pointer to an element.
    a_field:
      Field within the ql elements to use.
  Output(s):
    retval:
      non-NULL:
        Pointer to the element after a_elm.
      NULL:
        a_elm is the last element in a_head.
  Exception(s):
    None.
  Description:
    Return a pointer to the element in a_head after a_elm.

<ql_type> * ql_prev(<ql_head> *a_head, <ql_type> *a_elm, <field_name> a_field):

  Input(s):
    a_head:
      Pointer to a ql head.
    a_elm:
      Pointer to an element.
    a_field:
      Field within the ql elements to use.
  Output(s):
    retval:
      non-NULL:
        Pointer to the element before a_elm.
      NULL:
        a_elm is the first element in a_head.
  Exception(s):
    None.
  Description:
    Return a pointer to the element in a_head before a_elm.

void ql_before_insert(<ql_head> *a_head, <ql_type> *a_qlelm, <ql_type> *a_elm, <field_name> a_field):

  Input(s):
    a_head:
      Pointer to a ql head.
    a_qlelm:
      Pointer to an element within a_head.
    a_elm:
      Pointer to an element.
    a_field:
      Field within the ql elements to use.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Insert a_elm into a_head before a_qlelm.

void ql_after_insert(<ql_type> *a_qlelm, <ql_type> *a_elm, <field_name> a_field):

  Input(s):
    a_qlelm:
      Pointer to an element within a_head.
    a_elm:
      Pointer to an element.
    a_field:
      Field within the ql elements to use.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Insert a_elm into a_head after a_qlelm.

void ql_head_insert(<ql_head> *a_head, <ql_type> *a_elm, <field_name> a_field):

  Input(s):
    a_head:
      Pointer to a ql head.
    a_elm:
      Pointer to an element.
    a_field:
      Field within the ql elements to use.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Insert a_elm at the head of a_head.

void ql_tail_insert(<ql_head> *a_head, <ql_type> *a_elm, <field_name> a_field):

  Input(s):
    a_head:
      Pointer to a ql head.
    a_elm:
      Pointer to an element.
    a_field:
      Field within the ql elements to use.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Insert a_elm at the tail of a_head.

void ql_remove(<ql_head> *a_head, <ql_type> *a_elm, <field_name> a_field):

  Input(s):
    a_head:
      Pointer to a ql head.
    a_elm:
      Pointer to an element.
    a_field:
      Field within the ql elements to use.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Remove a_elm from a_head.

void ql_head_remove(<ql_head> *a_head, <ql_type> a_type, <field_name> a_field):

  Input(s):
    a_head:
      Pointer to a ql head.
    a_type:
      Data type for the ql elements.
    a_field:
      Field within the ql elements to use.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Remove the head element of a_head.

void ql_tail_remove(<ql_head> *a_head, <ql_type> a_type, <field_name> a_field):

  Input(s):
    a_head:
      Pointer to a ql head.
    a_type:
      Data type for the ql elements.
    a_field:
      Field within the ql elements to use.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Remove the tail element of a_head.

ql_foreach(<ql_type> *a_var, <ql_type> *a_head, <field_name> a_field):

  Input(s):
    a_var:
      The name of a temporary variable to use for iteration.
    a_head:
      Pointer to a ql head.
    a_field:
      Field within the ql elements to use.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Iterate through the ql, storing a pointer to each element in a_var along the way.

ql_reverse_foreach(<ql_type> *a_var, <ql_type> *a_head, <field_name> a_field):

  Input(s):
    a_var:
      The name of a temporary variable to use for iteration.
    a_head:
      Pointer to a ql head.
    a_field:
      Field within the ql elements to use.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Iterate through the ql in the reverse direction, storing a pointer to each element in a_var along the way.

Next: 4.10.34 qr Up: 4.10 Classes Previous: 4.10.32 nxo_thread Contents Index