NSPR Reference: Chapter 21 Linked Lists
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

NSPR Reference Previous Contents Next

## Chapter 21 Linked Lists

This chapter describes the NSPR API for managing linked lists. The API is a set of macros for initializing a circular (doubly linked) list, inserting and removing elements from the list. The macros are not thread safe. The caller must provide for mutually-exclusive access to the list, and for the nodes being added and removed from the list.

Linked List Types
Linked List Macros

## Linked List Types

The `PRCList` type represents a circular linked list.

#### PRCList

A circular linked list.

##### Syntax

    #include <prclist.h>

    typedef struct PRCListStr PRCList;

    struct PRCListStr {
        PRCList *next;
        PRCList *prev;
    };

##### Description

`PRClist` defines a node in a circular linked list. It can be used as the anchor of a list and can be embedded in data structures that are maintained in a linked list.

## Linked List Macros

Macros that create and operate on linked lists are:

`PR_INIT_CLIST``
` `PR_INIT_STATIC_CLIST``
` `PR_APPEND_LINK``
` `PR_INSERT_LINK``
` `PR_NEXT_LINK``
` `PR_PREV_LINK``
` `PR_REMOVE_LINK``
` `PR_REMOVE_AND_INIT_LINK``
` `PR_INSERT_BEFORE``
` `PR_INSERT_AFTER``
` `PR_CLIST_IS_EMPTY``
` `PR_LIST_HEAD``
` `PR_LIST_TAIL```

#### PR_INIT_CLIST

Initializes a circular list.

##### Syntax

    #include <prclist.h>

    PR_INIT_CLIST (PRCList *listp);

##### Parameters

The macro has this parameter:

listp | A pointer to the anchor of the linked list.

##### Description

`PR_INIT_CLIST` initializes the specified list to be an empty list.

#### PR_INIT_STATIC_CLIST

Statically initializes a circular list.

##### Syntax

    #include <prclist.h>

    PR_INIT_STATIC_CLIST (PRCList *listp);

##### Parameters

The macro has this parameter:

`listp` | A pointer to the anchor of the linked list.

##### Description

`PR_INIT_STATIC_CLIST` statically initializes the specified list to be an empty list. For example,

    PRCList free_object_list = PR_INIT_STATIC_CLIST(&free_object_list);

#### PR_APPEND_LINK

Appends an element to the end of a list.

##### Syntax

    #include <prclist.h>

    PR_APPEND_LINK (
       PRCList *elemp,
       PRCList *listp);

##### Parameters

The macro has these parameters:

`elemp` | A pointer to the element to be inserted.
`listp` | A pointer to the list.

##### Description

`PR_APPEND_LINK` adds the specified element to the end of the specified list .

#### PR_INSERT_LINK

Inserts an element at the head of the list.

##### Syntax

    #include <prclist.h>

    PR_INSERT_LINK (
       PRCList *elemp,
       PRCList *listp);

##### Parameters

The macro has these parameters:

`elemp` | A pointer to the element to be inserted.
`listp` | A pointer to the list.

##### Description

`PR_INSERT_LINK` inserts the specified element at the head of the specified list.

#### PR_NEXT_LINK

Returns the next element in a list.

##### Syntax

    #include <prclist.h>

    PRCList *PR_NEXT_LINK (PRCList *elemp);

##### Parameters

The macro has this parameter:

`elemp` | A pointer to the element.

##### Returns

A pointer to a list element.

##### Description

`PR_NEXT_LINK` returns a pointer to the element following the specified element. It can be used to traverse a list. The following element is not removed from the list.

#### PR_PREV_LINK

Returns the preceding element in a list.

##### Syntax

    #include <prclist.h>

    PRCList *PR_PREV_LINK (PRCList *elemp);

##### Parameters

The macro has this parameter:

`elemp` | A pointer to the element.

##### Returns

A pointer to a list element.

##### Description

`PR_NEXT_LINK` returns a pointer to the element preceding the specified element. It can be used to traverse a list. The preceding element is not removed from the list.

#### PR_REMOVE_LINK

Removes an element from a circular list.

##### Syntax

    #include <prclist.h>

    PR_REMOVE_LINK(PRCList *elemp);

##### Parameters

The macro has this parameter:

`elemp` | A pointer to the element.

##### Description

`PR_REMOVE_LINK` removes the specified element from its circular list.

#### PR_REMOVE_AND_INIT_LINK

Removes an element from a circular list and initializes the linkage.

##### Syntax

    #include <prclist.h>

    PR_REMOVE_AND_INIT_LINK (PRCList *elemp);

##### Parameters

The macro has this parameter:

`elemp` | A pointer to the element.

##### Description

`PR_REMOVE_AND_INIT_LINK` removes the specified element from its circular list and initializes the links of the element to point to itself.

#### PR_INSERT_BEFORE

Inserts an element before another element in a circular list.

##### Syntax

    #include <prclist.h>

    PR_INSERT_BEFORE (
       PRCList *elemp1,
       PRCList *elemp2);

##### Parameters

The macro has these parameters:

`elemp1` | A pointer to the element to be inserted.
`elemp2` | A pointer to the element before which `elemp1` is to be inserted.

##### Description

`PR_INSERT_BEFORE` inserts the element specified by `elemp1` into the circular list, before the element specified by `elemp2`.

#### PR_INSERT_AFTER

Inserts an element after another element in a circular list.

##### Syntax

    #include <prclist.h>

    PR_INSERT_AFTER (
       PRCList *elemp1,
       PRCList *elemp2);

##### Parameters

The macro has these parameters:

`elemp1` | A pointer to the element to be inserted.
`elemp2` | A pointer to the element after which `elemp1` is to be inserted.

##### Description

`PR_INSERT_AFTER` the element specified by `elemp1` into the circular list, after the element specified by `elemp2`.

#### PR_CLIST_IS_EMPTY

Checks for an empty circular list.

##### Syntax

    #include <prclist.h>

    PRIntn PR_CLIST_IS_EMPTY (PRCList *listp);

##### Parameters

The macro has this parameter:

`listp` | A pointer to the linked list.

##### Description

`PR_CLIST_IS_EMPTY` returns a non-zero value if the specified list is an empty list, otherwise returns zero.

#### PR_LIST_HEAD

Returns the head of a circular list.

##### Syntax

    #include <prclist.h>

    PRCList *PR_LIST_HEAD (PRCList *listp);

##### Parameters

The macro has this parameter:

`listp` | A pointer to a linked list.

##### Returns

A pointer to a list element.

##### Description

`PR_LIST_HEAD` returns the head of the specified circular list.

#### PR_LIST_TAIL

Returns the tail of a circular list.

##### Syntax

    #include <prclist.h>

    PRCList *PR_LIST_TAIL (PRCList *listp);

##### Parameters

The macro has this parameter:

`listp` | A pointer to the linked list.

##### Returns

A pointer to a list element.

##### Description

`PR_LIST_TAIL` returns the tail of the specified circular list.

Previous Contents Next

Last Updated May 18, 2001