@c -*-texinfo-*-
@c This is part of the GNU G-Golf Reference Manual.
@c Copyright (C) 2019 Free Software Foundation, Inc.
@c See the file g-golf.texi for copying conditions.


@c @defindex tl


@node Singly-Linked Lists
@subsection Singly-Linked Lists

G-Golf Glib Singly-Linked Lists low level API.@*
Singly-Linked Lists — Linked lists that can be iterated over in one
direction


@subheading Procedures

@indentedblock
@table @code
@item @ref{g-slist-data}
@item @ref{g-slist-next}
@item @ref{g-slist-append}
@item @ref{g-slist-prepend}
@item @ref{g-slist-free}
@item @ref{g-slist-length}
@item @ref{g-slist-nth-data}
@end table
@end indentedblock


@subheading Description

The @code{GSList} structure and its associated functions provide a
standard singly-linked list data structure.

Each element in the list contains a piece of data, together with a
pointer which links to the next element in the list. Using this pointer
it is possible to move through the list in one direction only (unlike
the @ref{Doubly-Linked Lists}, which allow movement in both directions).

Please read the @uref{@value{UGLIB-GSList}, Singly-Linked-Lists}
section from the Glib reference manual for a complete description.


@subheading Procedures


@anchor{g-slist-data}
@deffn Procedure g-slist-data g-slist

Returns a pointer.

Obtains and returns a pointer to the data in @var{g-slist}, or any integer
value, in which case, it is the responsibility of the caller to apply
the appropriate type conversion procedure.
@end deffn


@anchor{g-slist-next}
@deffn Procedure g-slist-next g-slist

Returns a pointer or #f.

Obtains and returns the next element in @var{g-slist}, or #f if there are
no more elements.
@end deffn


@anchor{g-slist-append}
@deffn Procedure g-slist-append g-slist data

Returns a pointer.

Adds @var{data} - which is (must be) a pointer - to the end of
@var{g-slist} and returns a pointer to the (possibly new) start of the
list (so make sure you store the new value).

Note that @ref{g-slist-append} has to traverse the entire list to find
the end, which is inefficient when adding multiple elements. A common
idiom to avoid the inefficiency is to prepend the elements and reverse
the list when all elements have been added.
@end deffn


@anchor{g-slist-prepend}
@deffn Procedure g-slist-prepend g-slist data

Returns a pointer.

Adds @var{data} - which is (must be) a pointer - to the start of
@var{g-slist} and returns a pointer to the (possibly new) start of the
list (so make sure you store the new value).
@end deffn


@anchor{g-slist-free}
@deffn Procedure g-slist-free g-slist

Returns nothing.

Frees all of the memory used by @var{g-slist}.
@end deffn


@anchor{g-slist-length}
@deffn Procedure g-slist-length g-slist

Returns an integer.

Obtains and returns the number of elements in @var{g-slist}. This function
iterates over the whole list to count its elements.
@end deffn


@anchor{g-slist-nth-data}
@deffn Procedure g-slist-nth-data g-slist n

Returns a pointer or #f.

Obtains and returns a pointer to the data of the @var{n}-th element of
@var{g-slist}. This iterates over the list until it reaches the n-th
position. If @var{n} is off the end of @var{g-slist}, it returns #f.
@end deffn
