Avanti Indietro Indice

17. La glib

La glib fornisce molte funzioni e definizioni utili pronte all'uso quando si creano applicazioni GDK e GTK. Qui verranno elencate tutte, con una breve spiegazione. Molte sono duplicati delle funzioni standard della libc, e quindi per queste non si scenderà nei dettagli. Questa vuole essere una lista di riferimento, in modo che si sappia cosa è possibile usare.

17.1 Definizioni

Le definizioni per gli estremi di molti dei tipi standard sono:

G_MINFLOAT
G_MAXFLOAT
G_MINDOUBLE
G_MAXDOUBLE
G_MINSHORT
G_MAXSHORT
G_MININT
G_MAXINT
G_MINLONG
G_MAXLONG

Ci sono anche le seguenti definizioni di tipo. Quelle rimaste non specificate sono dipendenti dall'architettura. Si ricordi di evitare di fare affidamento sulla dimensione di un puntatore se si vuole la portabilità! P.e., un puntatore su un Alpha è lungo 8 byte, ma 4 su un Intel.

char   gchar;
short  gshort;
long   glong;
int    gint;
char   gboolean;

unsigned char   guchar;
unsigned short  gushort;
unsigned long   gulong;
unsigned int    guint;

float   gfloat;
double  gdouble;
long double gldouble;

void* gpointer;

gint8
guint8
gint16
guint16
gint32
guint32

17.2 Liste a doppio collegamento

le seguenti funzioni sono usate per creare, gestire e distruggere liste a doppio collegamento. Si assume che il lettore sappia già cosa sono le liste collegate (linked list), poiché descriverle è fuori dagli scopi di questo documento. Naturalmente non è necessario conoscerle per l'uso generale di GTK, per quanto conoscerle sia comunque interessante.

GList* g_list_alloc       (void);

void   g_list_free        (GList     *list);

void   g_list_free_1      (GList     *list);

GList* g_list_append      (GList     *list,
                           gpointer   data);
                           
GList* g_list_prepend     (GList     *list,
                           gpointer   data);
                        
GList* g_list_insert      (GList     *list,
                           gpointer   data,
                           gint       position);

GList* g_list_remove      (GList     *list,
                           gpointer   data);
                           
GList* g_list_remove_link (GList     *list,
                           GList     *link);

GList* g_list_reverse     (GList     *list);

GList* g_list_nth         (GList     *list,
                           gint       n);
                           
GList* g_list_find        (GList     *list,
                           gpointer   data);

GList* g_list_last        (GList     *list);

GList* g_list_first       (GList     *list);

gint   g_list_length      (GList     *list);

void   g_list_foreach     (GList     *list,
                           GFunc      func,
                           gpointer   user_data);

17.3 Liste a collegamento singolo

Molte delle funzioni per le liste a collegamento singolo sono identiche alle precedenti. Eccone una lista completa:

GSList* g_slist_alloc       (void);

void    g_slist_free        (GSList   *list);

void    g_slist_free_1      (GSList   *list);

GSList* g_slist_append      (GSList   *list,
                             gpointer  data);
                
GSList* g_slist_prepend     (GSList   *list,
                             gpointer  data);
                             
GSList* g_slist_insert      (GSList   *list,
                             gpointer  data,
                             gint      position);
                             
GSList* g_slist_remove      (GSList   *list,
                             gpointer  data);
                             
GSList* g_slist_remove_link (GSList   *list,
                             GSList   *link);
                             
GSList* g_slist_reverse     (GSList   *list);

GSList* g_slist_nth         (GSList   *list,
                             gint      n);
                             
GSList* g_slist_find        (GSList   *list,
                             gpointer  data);
                             
GSList* g_slist_last        (GSList   *list);

gint    g_slist_length      (GSList   *list);

void    g_slist_foreach     (GSList   *list,
                             GFunc     func,
                             gpointer  user_data);
        

17.4 Gestione della memoria

gpointer g_malloc      (gulong    size);

Questa è una sostituta di malloc(). Non occorre controllare il valore restituito, in quanto lo fa già questa funzione.

gpointer g_malloc0     (gulong    size);

Come la precedente, ma la memoria viene azzerata prima di restituire un puntatore ad essa.

gpointer g_realloc     (gpointer  mem,
                        gulong    size);

Riloca ``size'' byte di memoria che inizia a ``mem''. Ovviamente, la memoria dovrebbe essere stata allocata precedentemente.

void     g_free        (gpointer  mem);

Libera la memoria. Facile!

void     g_mem_profile (void);

Emette un profilo della memoria usata, ma occorre ricompilare e reinstallare la libreria aggiungendo #define MEM_PROFILE all'inizio del file glib/gmem.c.

void     g_mem_check   (gpointer  mem);

Controlla che una locazione di memoria sia valida. Occorre ricompilare e reinstallare la libreria aggiungendo #define MEM_CHECK all'inizio del file gmem.c.

17.5 Timer

Funzioni legate ai timer...

GTimer* g_timer_new     (void);

void    g_timer_destroy (GTimer  *timer);

void    g_timer_start   (GTimer  *timer);

void    g_timer_stop    (GTimer  *timer);

void    g_timer_reset   (GTimer  *timer);

gdouble g_timer_elapsed (GTimer  *timer,
                         gulong  *microseconds);

17.6 Gestione delle stringhe

Un'accozzaglia di funzioni per la gestione delle stringhe. Sembrano tutte molto interessanti, e probabilmente migliori per molte caratteristiche delle funzioni standard del C per le stringhe, ma necessitano di documentazione.

GString* g_string_new       (gchar   *init);
void     g_string_free      (GString *string,
                             gint     free_segment);
                             
GString* g_string_assign    (GString *lval,
                             gchar   *rval);
                             
GString* g_string_truncate  (GString *string,
                             gint     len);
                             
GString* g_string_append    (GString *string,
                             gchar   *val);
                            
GString* g_string_append_c  (GString *string,
                             gchar    c);
        
GString* g_string_prepend   (GString *string,
                             gchar   *val);
                             
GString* g_string_prepend_c (GString *string,
                             gchar    c);
        
void     g_string_sprintf   (GString *string,
                             gchar   *fmt,
                             ...);
        
void     g_string_sprintfa  (GString *string,
                             gchar   *fmt,
                             ...);

17.7 Funzioni d'utilità e di errore

gchar* g_strdup    (const gchar *str);

Funzione sostitutiva della strdup. Copia i contenuti originari delle stringhe in memoria appena allocata, restituendo un puntatore ad essa.

gchar* g_strerror  (gint errnum);
Si raccomanda di usare questa gunzione per tutti i messaggi di errore. E' molto più graziosa, e più portabile di perror() o di altre. L'output di solito ha la forma:

nome programma:funzione fallita:file o altre descrizioni:strerror

Di seguito un esempio di una chiamata di questo tipo usata nel nostro programma Hello World:

g_print("hello_world:open:%s:%s\n", filename, g_strerror(errno));

void g_error   (gchar *format, ...);

Visualizza un messaggio di errore. Il formato è come quello di printf, ma prepone ``** ERROR **: '' al messaggio e termina il programma. Da usare solo per errori gravi.

void g_warning (gchar *format, ...);

Come la precedente, ma prepone ``** WARNING **: '' e non termina il programma.

void g_message (gchar *format, ...);

Visualizza ``message: '' e poi il messaggio.

void g_print   (gchar *format, ...);

Sostituta di printf().

L'ultima funzione:

gchar* g_strsignal (gint signum);

Visualizza il nome del messaggio del sistema Unix associato al numero di segnale. Utile nelle funzioni generiche di gestione dei segnali.

Tutte le funzioni elencate sono più o meno prese da glib.h. Se qualcuno volesse documentare qualche funzione, mandi una email all'autore!


Avanti Indietro Indice