【GLib】GLib学习笔记(三)：gtypes、garray、gerror、goption

1、类型：glib/gtypes.h

1.1 基本类型；

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

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

typedef float   gfloat;
typedef double  gdouble;

typedef void* gpointer;
typedef const void *gconstpointer; 	/指向的对象不可修改，但可以指向其它对象

1.2 最大最小值定义

#define G_MININT8	((gint8) -0x80)
#define G_MAXINT8	((gint8)  0x7f)
#define G_MAXUINT8	((guint8) 0xff)

#define G_MININT16	((gint16) -0x8000)
#define G_MAXINT16	((gint16)  0x7fff)
#define G_MAXUINT16	((guint16) 0xffff)

#define G_MININT32	((gint32) -0x80000000)
#define G_MAXINT32	((gint32)  0x7fffffff)
#define G_MAXUINT32	((guint32) 0xffffffff)

#define G_MININT64	((gint64) G_GINT64_CONSTANT(-0x8000000000000000))
#define G_MAXINT64	G_GINT64_CONSTANT(0x7fffffffffffffff)
#define G_MAXUINT64	G_GUINT64_CONSTANT(0xffffffffffffffff)

1.3 大小端交换，位移操作

#define GUINT16_SWAP_LE_BE_CONSTANT(val)	((guint16) ( \
    (guint16) ((guint16) (val) >> 8) |	\
    (guint16) ((guint16) (val) << 8)))

#define GUINT32_SWAP_LE_BE_CONSTANT(val)	((guint32) ( \
    (((guint32) (val) & (guint32) 0x000000ffU) << 24) | \
    (((guint32) (val) & (guint32) 0x0000ff00U) <<  8) | \
    (((guint32) (val) & (guint32) 0x00ff0000U) >>  8) | \
    (((guint32) (val) & (guint32) 0xff000000U) >> 24)))

#define GUINT64_SWAP_LE_BE_CONSTANT(val)	((guint64) ( \
      (((guint64) (val) &						\
	(guint64) G_GINT64_CONSTANT (0x00000000000000ffU)) << 56) |	\
      (((guint64) (val) &						\
	(guint64) G_GINT64_CONSTANT (0x000000000000ff00U)) << 40) |	\
      (((guint64) (val) &						\
	(guint64) G_GINT64_CONSTANT (0x0000000000ff0000U)) << 24) |	\
      (((guint64) (val) &						\
	(guint64) G_GINT64_CONSTANT (0x00000000ff000000U)) <<  8) |	\
      (((guint64) (val) &						\
	(guint64) G_GINT64_CONSTANT (0x000000ff00000000U)) >>  8) |	\
      (((guint64) (val) &						\
	(guint64) G_GINT64_CONSTANT (0x0000ff0000000000U)) >> 24) |	\
      (((guint64) (val) &						\
	(guint64) G_GINT64_CONSTANT (0x00ff000000000000U)) >> 40) |	\
      (((guint64) (val) &						\
	(guint64) G_GINT64_CONSTANT (0xff00000000000000U)) >> 56)))

2、数组：glib/garray.h

2.1 GArray 可调整大小的数组。

原型：

typedef struct _GArray GArray;
struct _GArray{
	gchar *data;
	guint len;
};

常用接口：

新建：g_array_new
释放：g_array_free
添加：g_array_append_vals、g_array_prepend_vals
删除：g_array_remove_index、g_array_remove_index_fast、g_array_remove_range
插入：g_array_insert_vals
排序：g_array_sort
搜索：g_array_binary_search

2.2 GByteArray 字节数组，guint8的数组。继承自GArray，但类型安全

原型：

typedef struct _GByteArray	GByteArray;
struct _GByteArray{
	guint8 *data;
	guint	  len;
};

常用接口：

新建：g_byte_array_new
清空：g_byte_array_free
添加：g_byte_array_append、g_byte_array_prepend
删除：g_byte_array_remove_index、g_byte_array_remove_index_fast、g_byte_array_remove_range
排序：g_byte_array_sort

2.3 GPtrArray 可调整大小的指针数组

原型：

typedef struct _GPtrArray	GPtrArray;
struct _GPtrArray{
	gpointer *pdata;
	guint	    len;
};

常用接口：

新建：g_ptr_array_new()
释放：g_ptr_array_free()
添加：use g_ptr_array_add()
删除：use g_ptr_array_remove()、g_ptr_array_remove_index()、g_ptr_array_remove_index_fast()
获取：g_ptr_array_index()
重置：g_ptr_array_set_size()

2.4 GBytes 一种简单的参考计数数据类型，里面的数据内容不可修改

原型：

struct _GBytes{
  gconstpointer data;  /* may be NULL iff (size == 0) */
  gsize size;  /* may be 0 */
  gatomicrefcount ref_count;
  GDestroyNotify free_func;
  gpointer user_data;
};

一种简单的参考计数数据类型，里面的数据内容不可修改。

使用#GBytes的目的是，只要有人持有对字节的引用，它所持有的内存区域就会一直保持活动状态。
当最后一个引用计数被删除时，内存被释放。
多个不相关的调用者可以在不协调其活动的情况下使用#GBytes中的字节数据，常量指针确保在它们持有引用时字节数据不会改变或移动。

#GBytes可以来自许多不同的源，这些源可能具有不同的释放内存区域的过程。
例如来自g_malloc()的内存、来自内存片、来自#GMappedFile的内存或来自其他分配器的内存。

#GBytes可以作为#GHashTable中的键。使用g_bytes_equal()和g_bytes_hash()作为g_hash_table_new()或g_hash_table_new_full()的参数。
通过将g_bytes_compare()函数传递给g_tree_new()， #GBytes还可以用作#GTree中的键。

这个字节所指向的数据不能被修改。有关可变字节数组，请参阅#GByteArray。
使用g_bytes_unref_to_array()为#GBytes序列创建可变数组。
要从可变的#GByteArray创建不可变的#GBytes，使用g_byte_array_free_to_bytes()函数。

3、错误：glib/gerror.h

GError
原型：

typedef struct _GError GError;
struct _GError{
	GQuark       domain;
	gint         code;
	gchar       *message;
};

常用接口：

新建：g_error_new
释放：g_error_free
清理：g_clear_error
复制：g_error_copy
设置：g_set_error

4、命令行解析器：glib/goption.h

4.1 GOptionContext 选项上下文

一个“GOptionContext”结构定义了命令行选项解析器接受哪些选项。该结构只有私有字段，不应该直接访问。
常用接口：

新建：g_option_context_new
释放：g_option_context_free
解析：g_option_context_parse
添加group：g_option_context_add_group
新建group并添加：g_option_context_add_main_entries

4.2 GOptionGroup 代表一组选项

“GOptionGroup”结构体定义单个组中的选项。该结构只有私有字段，不应该直接访问。
组中的所有选项共享相同的翻译功能。
需要解析命令行选项的库应该提供一个函数来获取一个保存选项的“GOptionGroup”，然后应用程序可以将其添加到#GOptionContext中。
常用接口：

新建：g_option_group_new
释放：g_option_group_free
添加条目：g_option_group_add_entries
增加引用计数：g_option_group_ref
减少引用计数：g_option_group_unref
设置钩子函数：g_option_group_set_parse_hooks	
	将两个函数与@group关联起来，这两个函数将从g_option_context_parse()中调用，分别在解析第一个选项之前和最后一个选项之后调用。
	注意，可以在使用g_option_group_new()构造组时指定要传递给@pre_parse_func和@post_parse_func的用户数据。
设置错误处理：g_option_group_set_error_hook

4.3 GOptionEntry 代表一条选项

typedef struct _GOptionEntry   GOptionEntry;
struct _GOptionEntry
{
  const gchar *long_name;	// --long_name
  gchar        short_name;	// -short_name
  gint         flags;		// GOptionFlags

  GOptionArg   arg;			// 参数类型
  gpointer     arg_data;	// 存取参数的指针
  
  const gchar *description;	// --help打印信息
  const gchar *arg_description;	// --help打印信息额外参数
};

常用函数：

新建group并添加选项：g_option_context_add_main_entries
向group中添加选项：g_option_group_add_entries