Description
GFifo defines a new data structure to handle a "First In First Out" stack of data with maximum length and signal emission.
GFifo handles a cursor which is automatically moved when pushing/popping data, and which allows to browse the list.
If we push new data when the cursor is not at the top of the list, all the data between the cursor and the top of the list is cleared, and the data is pushed.
Concepts:
- Top / bottom
The top of the GFifo is the last inserted data. Its bottom is the oldest data. They can be exchanged with the words end / start.
- Maximum length
The GFifo has a maximum length. If set to 0, the GFifo is considered as infinite. When data is pushed on the top of the GFifo, if the maximum length is reached, then the oldest data is popped out of the list.
- Cursor
It is a pointer to the current element in the list. It must be considered readonly as a signal is automatically emitted when it is moved.
It is moved automatically when pushing data. If we push new data when the cursor is not at the top of the list, all the data between the cursor and the top of the list is cleared, and the data is pushed.
To move it, you may use g-fifo-cursor-up, g-fifo-cursor-down g-fifo-cursor-goto or g-fifo-cursor-goto-data.
To retreive the element it points to, you may use g-fifo-cursor-get-data and if you need to know the of the values around it, you may use G-FIFO-CURSOR-NEXT or G-FIFO-CURSOR-PREV.
To learn about the cursor's position, you may use g-fifo-cursor-at-start or g-fifo-cursor-at-end.
Details
struct GFifo
All the fields should be considered read-only. Please use the accessor functions and macros.
G_FIFO_DEFAULT_MAXLEN
#define G_FIFO_DEFAULT_MAXLEN 10 |
This is defined as 10.
G_FIFO_CURSOR_NEXT()
#define G_FIFO_CURSOR_NEXT(fifo) ((fifo->cursor && fifo->cursor->next)?fifo->cursor->next:NULL) |
Retrieves the GList* element which is after the cursor or NULL if the cursor is at GFifo's end.
Note: The cursor is not moved by a call to this macro. This is an accessor macro.
G_FIFO_CURSOR_PREV()
#define G_FIFO_CURSOR_PREV(fifo) ((fifo->cursor && (g_list_position(fifo->list,fifo->cursor)>1))?fifo->cursor->prev:NULL) |
Retrieves the GList* element which is before the cursor or NULL if the cursor is at GFifo's start.
Note: The cursor is not moved by a call to this macro. This is an accessor macro.
G_FIFO_FOREACH()
#define G_FIFO_FOREACH(item, fifo) for(item=g_list_nth(fifo->list,1);item;item=item->next) |
A convenience macro to browse a GFifo. This macro is a for() wrapper, so it may be followed by a block, either a { } C-block or a single line instruction.
void print_fifo(GFifo *fifo){
GList *elem;
G_FIFO_FOREACH(elem,fifo){
g_printerr("s\n",(gchar*)elem->data);
}
} |
g_fifo_new ()
GFifo* g_fifo_new (void); |
Creates a new GFifo with maxlength set to G_FIFO_DEFAULT_MAXLEN.
g_fifo_new_with_max_length ()
GFifo* g_fifo_new_with_max_length (guint maxlength); |
Creates a new GFifo with maxlength set to maxlength.
g_fifo_push_data ()
Adds data on top of fifo. If fifo's cursor is not at the top of it, every data between the cursor and the top of fifo is cleared before insertion.
If fifo is full (maxlength reached) the data at fifo's bottom is popped before.
g_fifo_is_empty ()
Tests whether the GFifo holds some data.
g_fifo_is_full ()
Tests whether the GFifo's capacity was reached.
NB: This always returns FALSE if GFifo--maxlen == 0.
g_fifo_cursor_at_end()
#define g_fifo_cursor_at_end(fifo) |
A test to check whether the cursor is at end of the GFifo.
g_fifo_cursor_at_start()
#define g_fifo_cursor_at_start(fifo) |
A test to check whether the cursor is at start of the GFifo.
g_fifo_cursor_get_data()
#define g_fifo_cursor_get_data(fifo) |
Retrieves the data of the current element of a GFifo
g_fifo_clear_after_cursor ()
gint g_fifo_clear_after_cursor (GFifo *fifo); |
Removes all the elements in fifo after the cursor.
For each element removed, a GFifo-elem-flushed signal is emitted.
g_fifo_cursor_up ()
Moves the cursor towards the top of fifo. Emits a GFifo-cursor-moved signal.
g_fifo_cursor_down ()
Moves the cursor towards the botton of fifo. Emits a GFifo-cursor-moved signal.
g_fifo_cursor_goto ()
Brings fifo's cursor on target. For each element crossed, a GFifo-cursor-moved signal is emitted.
g_fifo_cursor_goto_data ()
Brings fifo's cursor on the closest element handling target. For each element crossed, a GFifo-cursor-moved signal is emitted.