GtkUndo Library API
<<< Previous PageHomeUp 

GFifo

Name

GFifo -- A Fifo data structure with signals support and maximum length

Synopsis



struct      GFifo;
#define     G_FIFO_DEFAULT_MAXLEN
#define     G_FIFO_CURSOR_NEXT              (fifo)
#define     G_FIFO_CURSOR_PREV              (fifo)
#define     G_FIFO_FOREACH                  (item, fifo)
GFifo*      g_fifo_new                      (void);
GFifo*      g_fifo_new_with_max_length      (guint maxlength);
void        g_fifo_push_data                (GFifo *fifo,
                                             gpointer data);
gpointer    g_fifo_pop_data                 (GFifo *fifo);
gboolean    g_fifo_is_empty                 (GFifo *fifo);
gboolean    g_fifo_is_full                  (GFifo *fifo);
#define     g_fifo_cursor_at_end            (fifo)
#define     g_fifo_cursor_at_start          (fifo)
#define     g_fifo_cursor_get_data          (fifo)
gint        g_fifo_clear_after_cursor       (GFifo *fifo);
gpointer    g_fifo_cursor_up                (GFifo *fifo);
gpointer    g_fifo_cursor_down              (GFifo *fifo);
gint        g_fifo_cursor_goto              (GFifo *fifo,
                                             GList *target);
gint        g_fifo_cursor_goto_data         (GFifo *fifo,
                                             gpointer target);

Object Hierarchy


  GObject
   +----GFifo

Properties


  "maxlen"               guint                : Read / Write / Construct

Signal Prototypes


"cursor-moved"
            void        user_function      (GFifo *gfifo,
                                            gpointer arg1,
                                            gboolean arg2,
                                            gpointer user_data);
"elem-flushed"
            void        user_function      (GFifo *gfifo,
                                            gpointer arg1,
                                            gpointer user_data);

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

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.

fifo :a GFifo
Returns :The data handled by the element before the cursor pointed element.

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.

fifo :a GFifo
Returns :The data handled by the element after the cursor pointed element.

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);
	   }
	}

item :A GList which will take the values of each element from start to end of the fifo inside the block.
fifo :a GFifo

g_fifo_new ()

GFifo*      g_fifo_new                      (void);

Creates a new GFifo with maxlength set to G_FIFO_DEFAULT_MAXLEN.

Returns : The new GFifo

g_fifo_new_with_max_length ()

GFifo*      g_fifo_new_with_max_length      (guint maxlength);

Creates a new GFifo with maxlength set to maxlength.

maxlength : The wanted maximum length for the GFifo. 0 means infinite length.
Returns : The new GFifo.

g_fifo_push_data ()

void        g_fifo_push_data                (GFifo *fifo,
                                             gpointer 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.

fifo : A GFifo
data : The data to push on top of fifo.

g_fifo_pop_data ()

gpointer    g_fifo_pop_data                 (GFifo *fifo);

Pops the older data of fifo. A GFifo-elem-flushed signal is emitted.

fifo : a GFifo
Returns : The data of the element popped

g_fifo_is_empty ()

gboolean    g_fifo_is_empty                 (GFifo *fifo);

Tests whether the GFifo holds some data.

fifo : a GFifo
Returns : TRUE if fifo is empty

g_fifo_is_full ()

gboolean    g_fifo_is_full                  (GFifo *fifo);

Tests whether the GFifo's capacity was reached. NB: This always returns FALSE if GFifo--maxlen == 0.

fifo : a GFifo
Returns : TRUE if fifo's length is equal to GFifo--maxlen

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.

fifo :a GFifo
Returns :TRUE if fifo's cursor points to the first element 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.

fifo :a GFifo
Returns :TRUE if fifo's cursor points to the last element 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

fifo :a GFifo
Returns :the data handled by fifo's cursor.

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.

fifo : a GFifo
Returns : The number of elements cleared or -1 if an error occurred

g_fifo_cursor_up ()

gpointer    g_fifo_cursor_up                (GFifo *fifo);

Moves the cursor towards the top of fifo. Emits a GFifo-cursor-moved signal.

fifo : a GFifo
Returns : the new data pointed by cursor.

g_fifo_cursor_down ()

gpointer    g_fifo_cursor_down              (GFifo *fifo);

Moves the cursor towards the botton of fifo. Emits a GFifo-cursor-moved signal.

fifo : a GFifo
Returns : the new data pointed by cursor.

g_fifo_cursor_goto ()

gint        g_fifo_cursor_goto              (GFifo *fifo,
                                             GList *target);

Brings fifo's cursor on target. For each element crossed, a GFifo-cursor-moved signal is emitted.

fifo : a GFifo
target : a GList which has to be a member of fifo.
Returns : The number of element crossed to reach target. The returned value's sign indicates the direction. If positive, the cursor went towards the end of fifo.

g_fifo_cursor_goto_data ()

gint        g_fifo_cursor_goto_data         (GFifo *fifo,
                                             gpointer target);

Brings fifo's cursor on the closest element handling target. For each element crossed, a GFifo-cursor-moved signal is emitted.

fifo : a GFifo
target : a pointer or integer which has to be a member of fifo.
Returns : The number of element crossed to find target. The returned value's sign indicates the direction. If positive, the cursor went towards the end of fifo.

Properties

"maxlen" (guint : Read / Write / Construct)

If set to 0, the GFifo is considered infinite.

Signals

The "cursor-moved" signal

void        user_function                  (GFifo *gfifo,
                                            gpointer arg1,
                                            gboolean arg2,
                                            gpointer user_data);

Emitted each time the cursor is moved.

gfifo :the object which received the signal.
arg1 :the data handled by the element pointed by the cursor
arg2 :if TRUE, indicates that the cursor was moved toward the top of the GFifo
user_data :user data set when the signal handler was connected.

The "elem-flushed" signal

void        user_function                  (GFifo *gfifo,
                                            gpointer arg1,
                                            gpointer user_data);

This signal is emitted each time an element is flushed out of the GFifo.

gfifo :the object which received the signal.
arg1 :the data which was handled by the flushed element.
user_data :user data set when the signal handler was connected.

See Also

GList

A lighter list handling type (Doubly linked lists)



<<< Previous PageHomeUp 
Gfifo Library