From 19f04a9024d48c9524604bc8097c2527b1675b98 Mon Sep 17 00:00:00 2001 From: Owen Taylor Date: Wed, 6 Sep 2000 00:04:49 +0000 Subject: [PATCH] head -n 4 ChangeLog --- docs/reference/ChangeLog | 5 + docs/reference/glib/Makefile.am | 127 +- docs/reference/glib/autogen.sh | 53 - docs/reference/glib/configure.in | 21 - docs/reference/glib/glib-decl.txt | 3492 +++++++++++++++-- docs/reference/glib/glib-overrides.txt | 14 + docs/reference/glib/glib-sections.txt | 644 ++- docs/reference/glib/glib/ChangeLog | 5 + docs/reference/glib/glib/Makefile.am | 127 +- docs/reference/glib/tmpl/allocators.sgml | 45 +- docs/reference/glib/tmpl/arrays.sgml | 224 +- docs/reference/glib/tmpl/arrays_byte.sgml | 117 +- docs/reference/glib/tmpl/arrays_pointer.sgml | 146 +- docs/reference/glib/tmpl/byte_order.sgml | 311 +- docs/reference/glib/tmpl/caches.sgml | 116 +- docs/reference/glib/tmpl/completion.sgml | 82 +- docs/reference/glib/tmpl/datalist.sgml | 137 +- docs/reference/glib/tmpl/datasets.sgml | 149 +- docs/reference/glib/tmpl/date.sgml | 1183 +++--- docs/reference/glib/tmpl/hash_tables.sgml | 300 +- docs/reference/glib/tmpl/hooks.sgml | 324 +- docs/reference/glib/tmpl/iochannels.sgml | 239 +- docs/reference/glib/tmpl/limits.sgml | 48 +- .../glib/tmpl/linked_lists_double.sgml | 346 +- .../glib/tmpl/linked_lists_single.sgml | 333 +- docs/reference/glib/tmpl/macros.sgml | 144 +- docs/reference/glib/tmpl/macros_misc.sgml | 185 +- docs/reference/glib/tmpl/main.sgml | 406 +- docs/reference/glib/tmpl/memory.sgml | 115 +- docs/reference/glib/tmpl/memory_chunks.sgml | 229 +- docs/reference/glib/tmpl/messages.sgml | 195 +- docs/reference/glib/tmpl/misc_utils.sgml | 184 +- docs/reference/glib/tmpl/modules.sgml | 133 +- docs/reference/glib/tmpl/quarks.sgml | 65 +- docs/reference/glib/tmpl/relations.sgml | 157 +- docs/reference/glib/tmpl/scanner.sgml | 263 +- docs/reference/glib/tmpl/string_chunks.sgml | 85 +- docs/reference/glib/tmpl/string_utils.sgml | 326 +- docs/reference/glib/tmpl/strings.sgml | 213 +- docs/reference/glib/tmpl/threads.sgml | 1026 ++--- docs/reference/glib/tmpl/timers.sgml | 38 +- docs/reference/glib/tmpl/trees-binary.sgml | 183 +- docs/reference/glib/tmpl/trees-nary.sgml | 390 +- docs/reference/glib/tmpl/type_conversion.sgml | 52 +- docs/reference/glib/tmpl/types.sgml | 871 +++- docs/reference/glib/tmpl/warnings.sgml | 149 +- docs/reference/glib/tmpl/windows.sgml | 112 +- 47 files changed, 7844 insertions(+), 6265 deletions(-) delete mode 100755 docs/reference/glib/autogen.sh delete mode 100644 docs/reference/glib/configure.in diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 6f682b1ba..caf9f48bc 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,8 @@ +Tue Sep 5 20:03:25 2000 Owen Taylor + + * Moved into glib source tree, updated glib-sections.txt + and Makefile.am for glib-1.3.x. + 2000-07-01 Damon Chaplin * tmpl/string_utils.sgml: updated g_strndup. diff --git a/docs/reference/glib/Makefile.am b/docs/reference/glib/Makefile.am index 0c4da6277..4fea547e1 100644 --- a/docs/reference/glib/Makefile.am +++ b/docs/reference/glib/Makefile.am @@ -6,42 +6,111 @@ DOC_MODULE=glib # The top-level SGML file. DOC_MAIN_SGML_FILE=glib-docs.sgml +# The directory containing the source code (if it contains documentation). +DOC_SOURCE_DIR=$(top_srcdir) TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) -scan: - gtkdoc-scan --module=$(DOC_MODULE) `glib-config --prefix`/include/glib.h `glib-config --prefix`/include/gmodule.h `glib-config --prefix`/lib/glib/include/glibconfig.h +tmpl_sources = \ + tmpl/allocators.sgml \ + tmpl/arrays.sgml \ + tmpl/arrays_byte.sgml \ + tmpl/arrays_pointer.sgml \ + tmpl/byte_order.sgml \ + tmpl/caches.sgml \ + tmpl/completion.sgml \ + tmpl/datalist.sgml \ + tmpl/datasets.sgml \ + tmpl/date.sgml \ + tmpl/glib-unused.sgml \ + tmpl/hash_tables.sgml \ + tmpl/hooks.sgml \ + tmpl/iochannels.sgml \ + tmpl/limits.sgml \ + tmpl/linked_lists_double.sgml \ + tmpl/linked_lists_single.sgml \ + tmpl/macros.sgml \ + tmpl/macros_misc.sgml \ + tmpl/main.sgml \ + tmpl/memory.sgml \ + tmpl/memory_chunks.sgml \ + tmpl/messages.sgml \ + tmpl/misc_utils.sgml \ + tmpl/modules.sgml \ + tmpl/quarks.sgml \ + tmpl/relations.sgml \ + tmpl/scanner.sgml \ + tmpl/string_chunks.sgml \ + tmpl/string_utils.sgml \ + tmpl/strings.sgml \ + tmpl/threads.sgml \ + tmpl/timers.sgml \ + tmpl/trees-binary.sgml \ + tmpl/trees-nary.sgml \ + tmpl/type_conversion.sgml \ + tmpl/types.sgml \ + tmpl/warnings.sgml \ + tmpl/windows.sgml -templates: scan - gtkdoc-mktmpl --module=$(DOC_MODULE) - -sgml: - gtkdoc-mkdb --module=$(DOC_MODULE) - -html: - if ! test -d html ; then mkdir html ; fi - -cd html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) - -clean-local: - rm -f *~ *.bak *.hierarchy *.signals *.args *-unused.txt - -maintainer-clean-local: clean - rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt - -install-data-local: - install -d -m 0755 $(TARGET_DIR) - install -m 0644 html/*.html $(TARGET_DIR) - install -m 0644 html/index.sgml $(TARGET_DIR) - gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(HTML_DIR) - -EXTRA_DIST = \ - $(DOC_MAIN_SGML_FILE) \ - $(DOC_MODULE)-sections.txt \ - glib-decl.txt \ +glib_docdir = $(HTML_DIR) +glib_doc_DATA = \ + glib-decl.txt \ + glib-sections.txt \ glib-overrides.txt +EXTRA_DIST = \ + $(glib_doc_DATA) + +html/book1.html: sgml/glib-doc.bottom + $(MAKE) html + +sgml/glib-doc.bottom: $(tmpl_sources) + $(MAKE) sgml + +scan: + -(cd $(srcdir) \ + && gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="config.h gmoduleconf.h gunidecomp.h gunichartables.h glibconfig-sysdefs.h" ) + +templates: scan + cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) + +sgml: + cd $(srcdir) \ + && gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) + +html: + test -d $(srcdir)/html || mkdir $(srcdir)/html + -cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + +clean-local: + rm -f *~ *.bak *.signals *-unused.txt + +maintainer-clean-local: clean + cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt + +install-data-local: + $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR) + (installfiles=`echo $(srcdir)/html/*.html`; \ + if test "$$installfiles" = '$(srcdir)/html/*.html'; \ + then echo '-- Nothing to install' ; \ + else \ + for i in $$installfiles; do \ + echo '-- Installing '$$i ; \ + $(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \ + done; \ + echo '-- Installing $(srcdir)/html/index.sgml' ; \ + $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR); \ + echo '-- Fixing Crossreferences' ; \ + gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(HTML_DIR)|| true; \ + fi) + dist-hook: + mkdir $(distdir)/html + mkdir $(distdir)/sgml mkdir $(distdir)/tmpl - cp -p tmpl/*.sgml $(distdir)/tmpl + -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html + -cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl + -cp $(srcdir)/sgml/*.sgml $(distdir)/sgml + -cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml .PHONY : html sgml templates scan diff --git a/docs/reference/glib/autogen.sh b/docs/reference/glib/autogen.sh deleted file mode 100755 index 60bcd89f7..000000000 --- a/docs/reference/glib/autogen.sh +++ /dev/null @@ -1,53 +0,0 @@ -#!/bin/sh -# Run this to generate all the initial makefiles, etc. - -srcdir=`dirname $0` -test -z "$srcdir" && srcdir=. - -ORIGDIR=`pwd` -cd $srcdir -PROJECT=GLib-Reference -TEST_TYPE=-f -FILE=glib-sections.txt - -DIE=0 - -(autoconf --version) < /dev/null > /dev/null 2>&1 || { - echo - echo "You must have autoconf installed to compile $PROJECT." - echo "Download the appropriate package for your distribution," - echo "or get the source tarball at ftp://ftp.gnu.org/pub/gnu/" - DIE=1 -} - -(automake --version) < /dev/null > /dev/null 2>&1 || { - echo - echo "You must have automake installed to compile $PROJECT." - echo "Get ftp://sourceware.cygnus.com/pub/automake/automake-1.4.tar.gz" - echo "(or a newer version if it is available)" - DIE=1 -} - -if test "$DIE" -eq 1; then - exit 1 -fi - -test $TEST_TYPE $FILE || { - echo "You must run this script in the top-level $PROJECT directory" - exit 1 -} - -if test -z "$*"; then - echo "I am going to run ./configure with no arguments - if you wish " - echo "to pass any to it, please specify them on the $0 command line." -fi - -aclocal $ACLOCAL_FLAGS -automake -a $am_opt -autoconf -cd $ORIGDIR - -$srcdir/configure --enable-maintainer-mode "$@" - -echo -echo "Now type 'make' to compile $PROJECT." diff --git a/docs/reference/glib/configure.in b/docs/reference/glib/configure.in deleted file mode 100644 index 009e1862d..000000000 --- a/docs/reference/glib/configure.in +++ /dev/null @@ -1,21 +0,0 @@ -dnl Process this file with autoconf to produce a configure script. - -AC_INIT(glib-sections.txt) - -AM_INIT_AUTOMAKE(glib-reference, 1.1.3) - -AC_ARG_WITH(html-dir, [ --with-html-dir=PATH path to installed docs ]) - -AC_ISC_POSIX -AC_PROG_CC - -if test "x$with_html_dir" = "x" ; then - HTML_DIR='${datadir}/gtk-doc/html' -else - HTML_DIR=$with_html_dir -fi - -AC_SUBST(HTML_DIR) - -AC_OUTPUT([Makefile]) - diff --git a/docs/reference/glib/glib-decl.txt b/docs/reference/glib/glib-decl.txt index 4a57bf92e..f8dd681b8 100644 --- a/docs/reference/glib/glib-decl.txt +++ b/docs/reference/glib/glib-decl.txt @@ -1,3 +1,91 @@ + +GError + + +GError +struct GError +{ + GQuark domain; + gint code; + gchar *message; +}; + + +g_error_new +GError * +GQuark domain,gint code,const gchar *format,... + + +g_error_new_literal +GError * +GQuark domain,gint code,const gchar *message + + +g_error_free +void +GError *error + + +g_error_copy +GError * +const GError *error + + +g_error_matches +gboolean +const GError *error,GQuark domain,gint code + + +g_set_error +void +GError **err,GQuark domain,gint code,const gchar *format,... + + +g_propagate_error +void +GError **dest,GError *src + + +g_clear_error +void +GError **err + + +G_GNUC_EXTENSION +# define G_GNUC_EXTENSION __extension__ + + +G_GNUC_EXTENSION +# define G_GNUC_EXTENSION + + +G_E +#define G_E 2.7182818284590452354E0 + + +G_LN2 +#define G_LN2 6.9314718055994530942E-1 + + +G_LN10 +#define G_LN10 2.3025850929940456840E0 + + +G_PI +#define G_PI 3.14159265358979323846E0 + + +G_PI_2 +#define G_PI_2 1.57079632679489661923E0 + + +G_PI_4 +#define G_PI_4 0.78539816339744830962E0 + + +G_SQRT2 +#define G_SQRT2 1.4142135623730950488E0 + G_DIR_SEPARATOR #define G_DIR_SEPARATOR '\\' @@ -32,7 +120,11 @@ NULL -#define NULL ((void*) 0) +# define NULL (0L) + + +NULL +# define NULL ((void*) 0) FALSE @@ -59,6 +151,26 @@ #define CLAMP(x, low, high) (((x) > (high)) ? (high) : (((x) < (low)) ? (low) : (x))) +G_STRINGIFY +#define G_STRINGIFY(macro_or_string) G_STRINGIFY_ARG (macro_or_string) + + +G_STRINGIFY_ARG +#define G_STRINGIFY_ARG(contents) #contents + + +G_STRLOC +# define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__) ":" __PRETTY_FUNCTION__ "()" + + +G_STRLOC +# define G_STRLOC __FILE__ ":" G_STRINGIFY (__LINE__) + + +G_N_ELEMENTS +#define G_N_ELEMENTS(arr) (sizeof (arr) / sizeof ((arr)[0])) + + G_VA_COPY # define G_VA_COPY(ap1, ap2) (*(ap1) = *(ap2)) @@ -73,12 +185,12 @@ G_STRUCT_OFFSET #define G_STRUCT_OFFSET(struct_type, member) \ - ((gulong) ((gchar*) &((struct_type*) 0)->member)) + ((glong) ((guint8*) &((struct_type*) 0)->member)) G_STRUCT_MEMBER_P #define G_STRUCT_MEMBER_P(struct_p, struct_offset) \ - ((gpointer) ((gchar*) (struct_p) + (gulong) (struct_offset))) + ((gpointer) ((guint8*) (struct_p) + (glong) (struct_offset))) G_STRUCT_MEMBER @@ -290,10 +402,6 @@ } G_STMT_END -g_string -#define g_string(x) #x - - g_assert #define g_assert(expr) @@ -352,13 +460,21 @@ #define g_return_val_if_fail(expr,val) +g_return_if_reached +#define g_return_if_reached() return + + +g_return_val_if_reached +#define g_return_val_if_reached(val) return (val) + + g_return_if_fail #define g_return_if_fail(expr) G_STMT_START{ \ if (!(expr)) \ { \ g_log (G_LOG_DOMAIN, \ G_LOG_LEVEL_CRITICAL, \ - "file %s: line %d (%s): assertion `%s' failed.", \ + "file %s: line %d (%s): assertion `%s' failed", \ __FILE__, \ __LINE__, \ __PRETTY_FUNCTION__, \ @@ -373,22 +489,44 @@ { \ g_log (G_LOG_DOMAIN, \ G_LOG_LEVEL_CRITICAL, \ - "file %s: line %d (%s): assertion `%s' failed.", \ + "file %s: line %d (%s): assertion `%s' failed", \ __FILE__, \ __LINE__, \ __PRETTY_FUNCTION__, \ #expr); \ - return val; \ + return (val); \ }; }G_STMT_END +g_return_if_reached +#define g_return_if_reached() G_STMT_START{ \ + g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_CRITICAL, \ + "file %s: line %d (%s): should not be reached", \ + __FILE__, \ + __LINE__, \ + __PRETTY_FUNCTION__); \ + return; }G_STMT_END + + +g_return_val_if_reached +#define g_return_val_if_reached(val) G_STMT_START{ \ + g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_CRITICAL, \ + "file %s: line %d (%s): should not be reached", \ + __FILE__, \ + __LINE__, \ + __PRETTY_FUNCTION__); \ + return (val); }G_STMT_END + + g_return_if_fail #define g_return_if_fail(expr) G_STMT_START{ \ if (!(expr)) \ { \ g_log (G_LOG_DOMAIN, \ G_LOG_LEVEL_CRITICAL, \ - "file %s: line %d: assertion `%s' failed.", \ + "file %s: line %d: assertion `%s' failed", \ __FILE__, \ __LINE__, \ #expr); \ @@ -402,13 +540,33 @@ { \ g_log (G_LOG_DOMAIN, \ G_LOG_LEVEL_CRITICAL, \ - "file %s: line %d: assertion `%s' failed.", \ + "file %s: line %d: assertion `%s' failed", \ __FILE__, \ __LINE__, \ #expr); \ - return val; \ + return (val); \ }; }G_STMT_END + +g_return_if_reached +#define g_return_if_reached() G_STMT_START{ \ + g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_CRITICAL, \ + "file %s: line %d: should not be reached", \ + __FILE__, \ + __LINE__); \ + return; }G_STMT_END + + +g_return_val_if_reached +#define g_return_val_if_reached(val) G_STMT_START{ \ + g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_CRITICAL, \ + "file %s: line %d: should not be reached", \ + __FILE__, \ + __LINE__); \ + return (val); }G_STMT_END + gchar typedef char gchar; @@ -430,6 +588,10 @@ typedef int gint; typedef gint gboolean; +gstring +typedef gchar* gstring; + + guchar typedef unsigned char guchar; @@ -445,6 +607,30 @@ typedef unsigned long gulong; guint typedef unsigned int guint; + +G_GSHORT_FORMAT +#define G_GSHORT_FORMAT "hi" + + +G_GUSHORT_FORMAT +#define G_GUSHORT_FORMAT "hu" + + +G_GINT_FORMAT +#define G_GINT_FORMAT "i" + + +G_GUINT_FORMAT +#define G_GUINT_FORMAT "u" + + +G_GLONG_FORMAT +#define G_GLONG_FORMAT "li" + + +G_GULONG_FORMAT +#define G_GULONG_FORMAT "lu" + gfloat typedef float gfloat; @@ -470,14 +656,6 @@ typedef void* gpointer; typedef const void *gconstpointer; -gssize -typedef gint32 gssize; - - -gsize -typedef guint32 gsize; - - GQuark typedef guint32 GQuark; @@ -731,16 +909,16 @@ typedef gint32 GTime; #define g_htons(val) (GUINT16_TO_BE (val)) -GUTILS_C_VAR -# define GUTILS_C_VAR __declspec(dllexport) +GLIB_VAR +# define GLIB_VAR __declspec(dllexport) -GUTILS_C_VAR -# define GUTILS_C_VAR extern __declspec(dllimport) +GLIB_VAR +# define GLIB_VAR extern __declspec(dllimport) -GUTILS_C_VAR -# define GUTILS_C_VAR extern +GLIB_VAR +# define GLIB_VAR extern GLIB_CHECK_VERSION @@ -793,6 +971,12 @@ typedef gint32 GTime; GPtrArray +GQueue + + +GRand + + GRelation @@ -814,6 +998,9 @@ typedef gint32 GTime; GTimer +GTrashStack + + GTree @@ -998,12 +1185,6 @@ GNode *node, gpointer data -GSearchFunc -gint -gpointer key, - gpointer data - - GScannerMsgFunc void GScanner *scanner, @@ -1023,6 +1204,30 @@ gpointer key, void +GArray +struct GArray +{ + gchar *data; + guint len; +}; + + +GByteArray +struct GByteArray +{ + guint8 *data; + guint len; +}; + + +GDebugKey +struct GDebugKey +{ + gchar *key; + guint value; +}; + + GList struct GList { @@ -1032,6 +1237,23 @@ struct GList }; +GPtrArray +struct GPtrArray +{ + gpointer *pdata; + guint len; +}; + + +GQueue +struct GQueue +{ + GList *head; + GList *tail; + guint length; +}; + + GSList struct GSList { @@ -1048,27 +1270,10 @@ struct GString }; -GArray -struct GArray +GTrashStack +struct GTrashStack { - gchar *data; - guint len; -}; - - -GByteArray -struct GByteArray -{ - guint8 *data; - guint len; -}; - - -GPtrArray -struct GPtrArray -{ - gpointer *pdata; - guint len; + GTrashStack *next; }; @@ -1078,14 +1283,68 @@ struct GTuples guint len; }; - -GDebugKey -struct GDebugKey + +G_IEEE754_FLOAT_BIAS +#define G_IEEE754_FLOAT_BIAS (127) + + +G_IEEE754_DOUBLE_BIAS +#define G_IEEE754_DOUBLE_BIAS (1023) + + +G_LOG_2_BASE_10 +#define G_LOG_2_BASE_10 (0.30102999566398119521) + + +GFloatIEEE754 +union GFloatIEEE754 { - gchar *key; - guint value; + gfloat v_float; + struct { + guint mantissa : 23; + guint biased_exponent : 8; + guint sign : 1; + } mpn; }; - + + +GDoubleIEEE754 +union GDoubleIEEE754 +{ + gdouble v_double; + struct { + guint mantissa_low : 32; + guint mantissa_high : 20; + guint biased_exponent : 11; + guint sign : 1; + } mpn; +}; + + +GFloatIEEE754 +union GFloatIEEE754 +{ + gfloat v_float; + struct { + guint sign : 1; + guint biased_exponent : 8; + guint mantissa : 23; + } mpn; +}; + + +GDoubleIEEE754 +union GDoubleIEEE754 +{ + gdouble v_double; + struct { + guint sign : 1; + guint biased_exponent : 11; + guint mantissa_high : 20; + guint mantissa_low : 32; + } mpn; +}; + g_list_push_allocator void @@ -1139,7 +1398,7 @@ GList *list1,GList *list2 g_list_remove GList * -GList *list,gpointer data +GList *list,gconstpointer data g_list_remove_link @@ -1147,6 +1406,11 @@ GList *list,gpointer data GList *list,GList *llink +g_list_delete_link +GList * +GList *list,GList *link + + g_list_reverse GList * GList *list @@ -1164,12 +1428,12 @@ GList *list,guint n g_list_find GList * -GList *list,gpointer data +GList *list,gconstpointer data g_list_find_custom GList * -GList *list,gpointer data,GCompareFunc func +GList *list,gconstpointer data,GCompareFunc func g_list_position @@ -1179,7 +1443,7 @@ GList *list,GList *llink g_list_index gint -GList *list,gpointer data +GList *list,gconstpointer data g_list_last @@ -1265,6 +1529,11 @@ GSList *list,gpointer data,gint position GSList *list,gpointer data,GCompareFunc func +g_slist_insert_before +GSList * +GSList *slist,GSList *sibling,gpointer data + + g_slist_concat GSList * GSList *list1,GSList *list2 @@ -1272,12 +1541,17 @@ GSList *list1,GSList *list2 g_slist_remove GSList * -GSList *list,gpointer data +GSList *list,gconstpointer data g_slist_remove_link GSList * -GSList *list,GSList *llink +GSList *list,GSList *link + + +g_slist_delete_link +GSList * +GSList *list,GSList *link g_slist_reverse @@ -1297,12 +1571,12 @@ GSList *list,guint n g_slist_find GSList * -GSList *list,gpointer data +GSList *list,gconstpointer data g_slist_find_custom GSList * -GSList *list,gpointer data,GCompareFunc func +GSList *list,gconstpointer data,GCompareFunc func g_slist_position @@ -1312,7 +1586,7 @@ GSList *list,GSList *llink g_slist_index gint -GSList *list,gpointer data +GSList *list,gconstpointer data g_slist_last @@ -1341,9 +1615,74 @@ GSList *list,guint n g_slist_next -#define g_slist_next(slist) ((slist) ? (((GSList *)(slist))->next) : NULL) +#define g_slist_next(slist) ((slist) ? (((GSList *)(slist))->next) : NULL) +g_queue_new +GQueue * +void + + +g_queue_free +void +GQueue *queue + + +g_queue_push_head +void +GQueue *queue,gpointer data + + +g_queue_push_tail +void +GQueue *queue,gpointer data + + +g_queue_pop_head +gpointer +GQueue *queue + + +g_queue_pop_tail +gpointer +GQueue *queue + + +g_queue_is_empty +gboolean +GQueue *queue + + +g_queue_peek_head +gpointer +GQueue *queue + + +g_queue_peek_tail +gpointer +GQueue *queue + + +g_queue_push_head_link +void +GQueue *queue,GList *link + + +g_queue_push_tail_link +void +GQueue *queue,GList *link + + +g_queue_pop_head_link +GList * +GQueue *queue + + +g_queue_pop_tail_link +GList * +GQueue *queue + + g_hash_table_new GHashTable * GHashFunc hash_func,GCompareFunc key_compare_func @@ -1374,16 +1713,6 @@ GHashTable *hash_table,gconstpointer key GHashTable *hash_table,gconstpointer lookup_key,gpointer *orig_key,gpointer *value -g_hash_table_freeze -void -GHashTable *hash_table - - -g_hash_table_thaw -void -GHashTable *hash_table - - g_hash_table_foreach void GHashTable *hash_table,GHFunc func,gpointer user_data @@ -1399,6 +1728,16 @@ GHashTable *hash_table,GHRFunc func,gpointer user_data GHashTable *hash_table +g_hash_table_freeze +void +GHashTable *hash_table + + +g_hash_table_thaw +void +GHashTable *hash_table + + g_cache_new GCache * GCacheNewFunc value_new_func,GCacheDestroyFunc value_destroy_func,GCacheDupFunc key_dup_func,GCacheDestroyFunc key_destroy_func,GHashFunc hash_key_func,GHashFunc hash_value_func,GCompareFunc key_compare_func @@ -1416,7 +1755,7 @@ GCache *cache,gpointer key g_cache_remove void -GCache *cache,gpointer value +GCache *cache,gconstpointer value g_cache_key_foreach @@ -1446,12 +1785,12 @@ GTree *tree,gpointer key,gpointer value g_tree_remove void -GTree *tree,gpointer key +GTree *tree,gconstpointer key g_tree_lookup gpointer -GTree *tree,gpointer key +GTree *tree,gconstpointer key g_tree_traverse @@ -1461,7 +1800,7 @@ GTree *tree,GTraverseFunc traverse_func,GTraverseType traverse_type,gpointer g_tree_search gpointer -GTree *tree,GSearchFunc search_func,gpointer data +GTree *tree,GCompareFunc search_func,gconstpointer data g_tree_height @@ -1520,6 +1859,11 @@ GNode *root GNode *node +g_node_copy +GNode * +GNode *node + + g_node_insert GNode * GNode *parent,gint position,GNode *node @@ -1900,21 +2244,51 @@ GLogLevelFlags fatal_mask g_error -#define g_error(format, args...) g_log (G_LOG_DOMAIN, \ - G_LOG_LEVEL_ERROR, \ - format, ##args) +#define g_error(...) g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_ERROR, \ + __VA_ARGS__) g_message -#define g_message(format, args...) g_log (G_LOG_DOMAIN, \ - G_LOG_LEVEL_MESSAGE, \ - format, ##args) +#define g_message(...) g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_MESSAGE, \ + __VA_ARGS__) + + +g_critical +#define g_critical(...) g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_CRITICAL, \ + __VA_ARGS__) g_warning -#define g_warning(format, args...) g_log (G_LOG_DOMAIN, \ - G_LOG_LEVEL_WARNING, \ - format, ##args) +#define g_warning(...) g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_WARNING, \ + __VA_ARGS__) + + +g_error +#define g_error(format...) g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_ERROR, \ + format) + + +g_message +#define g_message(format...) g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_MESSAGE, \ + format) + + +g_critical +#define g_critical(format...) g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_CRITICAL, \ + format) + + +g_warning +#define g_warning(format...) g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_WARNING, \ + format) GPrintFunc @@ -2092,6 +2466,10 @@ void void void + +G_MICROSEC +#define G_MICROSEC 1000000 + g_timer_new GTimer * @@ -2122,6 +2500,11 @@ GTimer *timer gdouble GTimer *timer,gulong *microseconds + +g_usleep +void +gulong microseconds + G_STR_DELIMITERS #define G_STR_DELIMITERS "_-|> <." @@ -2132,6 +2515,11 @@ GTimer *timer,gulong *microseconds gchar *string,const gchar *delimiters,gchar new_delimiter +g_strcanon +gchar * +gchar *string,const gchar *valid_chars,gchar subsitutor + + g_strtod gdouble const gchar *nptr,gchar **endptr @@ -2158,20 +2546,30 @@ const gchar *s1,const gchar *s2,guint n g_strdown -void +gchar * gchar *string g_strup -void +gchar * gchar *string g_strreverse -void +gchar * gchar *string +g_strlcpy +gsize +gchar *dest,const gchar *src,gsize dest_size + + +g_strlcat +gsize +gchar *dest,const gchar *src,gsize dest_size + + g_strchug gchar * gchar *string @@ -2221,9 +2619,24 @@ const gchar *string1,... const gchar *separator,... +g_strcompress +gchar * +const gchar *source + + +g_filename_to_utf8 +gchar * +const gchar *opsysstring + + +g_filename_from_utf8 +gchar * +const gchar *utf8string + + g_strescape gchar * -gchar *string +const gchar *source,const gchar *exceptions g_memdup @@ -2296,11 +2709,6 @@ gchar *string,gulong n,gchar const *format,... gchar *string,gulong n,gchar const *format,va_list args -g_basename -gchar * -const gchar *file_name - - g_path_is_absolute gboolean const gchar *file_name @@ -2311,6 +2719,11 @@ const gchar *file_name gchar *file_name +g_basename +gchar * +const gchar *file_name + + g_dirname gchar * const gchar *file_name @@ -2321,6 +2734,16 @@ const gchar *file_name void +g_path_get_basename +gchar * +const gchar *file_name + + +g_path_get_dirname +gchar * +const gchar *file_name + + g_getenv gchar * const gchar *variable @@ -2346,6 +2769,26 @@ guint32 mask,gint nth_bit guint number +g_trash_stack_push +void +GTrashStack **stack_p,gpointer data_p + + +g_trash_stack_pop +gpointer +GTrashStack **stack_p + + +g_trash_stack_peek +gpointer +GTrashStack **stack_p + + +g_trash_stack_height +guint +GTrashStack **stack_p + + g_string_chunk_new GStringChunk * gint size @@ -2368,62 +2811,87 @@ GStringChunk *chunk,const gchar *string g_string_new GString * -const gchar *init +const gchar *init g_string_sized_new GString * -guint dfl_size +guint dfl_size g_string_free -void -GString *string,gint free_segment +gchar * +GString *string,gboolean free_segment + + +g_string_equal +gboolean +const GString *v,const GString *v2 + + +g_string_hash +guint +const GString *str g_string_assign GString * -GString *lval,const gchar *rval +GString *string,const gchar *rval g_string_truncate GString * -GString *string,gint len +GString *string,guint len + + +g_string_insert_len +GString * +GString *string,gint pos,const gchar *val,gint len g_string_append GString * -GString *string,const gchar *val +GString *string,const gchar *val + + +g_string_append_len +GString * +GString *string,const gchar *val,gint len g_string_append_c GString * -GString *string,gchar c +GString *string,gchar c g_string_prepend GString * -GString *string,const gchar *val +GString *string,const gchar *val g_string_prepend_c GString * -GString *string,gchar c +GString *string,gchar c + + +g_string_prepend_len +GString * +GString *string,const gchar *val,gint len g_string_insert GString * -GString *string,gint pos,const gchar *val +GString *string,gint pos,const gchar *val g_string_insert_c GString * -GString *string,gint pos,gchar c +GString *string,gint pos,gchar c g_string_erase GString * -GString *string,gint pos,gint len +GString *string,gint pos,gint len g_string_down @@ -2437,13 +2905,13 @@ GString *string g_string_sprintf -void -GString *string,const gchar *format,... +void +GString *string,const gchar *format,... g_string_sprintfa -void -GString *string,const gchar *format,... +void +GString *string,const gchar *format,... g_array_append_val @@ -2467,8 +2935,13 @@ GString *string,const gchar *format,... gboolean zero_terminated,gboolean clear,guint element_size +g_array_sized_new +GArray * +gboolean zero_terminated,gboolean clear,guint element_size,guint reserved_size + + g_array_free -void +gchar * GArray *array,gboolean free_segment @@ -2511,8 +2984,13 @@ GArray *array,guint index void +g_ptr_array_sized_new +GPtrArray * +guint reserved_size + + g_ptr_array_free -void +gpointer * GPtrArray *array,gboolean free_seg @@ -2551,8 +3029,13 @@ GPtrArray *array,gpointer data void +g_byte_array_sized_new +GByteArray * +guint reserved_size + + g_byte_array_free -void +guint8 * GByteArray *array,gboolean free_segment @@ -2582,22 +3065,22 @@ GByteArray *array,guint index g_str_equal -gint +gboolean gconstpointer v,gconstpointer v2 g_str_hash -guint +guint gconstpointer v g_int_equal -gint +gint gconstpointer v,gconstpointer v2 g_int_hash -guint +guint gconstpointer v @@ -2652,7 +3135,7 @@ GData **datalist,GQuark key_id,gpointer data,GDestroyNotify destroy_fu g_datalist_id_remove_no_notify -void +gpointer GData **datalist,GQuark key_id @@ -2712,7 +3195,7 @@ gconstpointer dataset_location,GQuark key_id,gpointer data,GDestroyNotify g_dataset_id_remove_no_notify -void +gpointer gconstpointer dataset_location,GQuark key_id @@ -2764,6 +3247,10 @@ gconstpointer dataset_location,GDataForeachFunc func,gpointer user_data #define G_CSET_a_2_z "abcdefghijklmnopqrstuvwxyz" +G_CSET_DIGITS +#define G_CSET_DIGITS "0123456789" + + G_CSET_LATINC #define G_CSET_LATINC "\300\301\302\303\304\305\306"\ "\307\310\311\312\313\314\315\316\317\320"\ @@ -3019,16 +3506,6 @@ GScanner *scanner,guint scope_id,GHFunc func,gpointer user_data GScanner *scanner,const gchar *symbol -g_scanner_freeze_symbol_table -void -GScanner *scanner - - -g_scanner_thaw_symbol_table -void -GScanner *scanner - - g_scanner_unexp_token void GScanner *scanner,GTokenType expected_token,const gchar *identifier_spec,const gchar *symbol_spec,const gchar *symbol_name,const gchar *message,gint is_error @@ -3066,6 +3543,16 @@ const gchar *filename g_scanner_scope_foreach_symbol ((scanner), 0, (func), (data)); \ } G_STMT_END + +g_scanner_freeze_symbol_table +void +GScanner *scanner + + +g_scanner_thaw_symbol_table +void +GScanner *scanner + GCompletion struct GCompletion @@ -3457,6 +3944,71 @@ GTuples *tuples GTuples *tuples,gint index,gint field +g_rand_new_with_seed +GRand * +guint32 seed + + +g_rand_new +GRand * +void + + +g_rand_free +void +GRand *rand + + +g_rand_set_seed +void +GRand *rand,guint32 seed + + +g_rand_int +guint32 +GRand *rand + + +g_rand_int_range +gint32 +GRand *rand,gint32 min,gint32 max + + +g_rand_double +gdouble +GRand *rand + + +g_rand_double_range +gdouble +GRand *rand,gdouble min,gdouble max + + +g_random_set_seed +void +guint32 seed + + +g_random_int +guint32 +void + + +g_random_int_range +gint32 +gint32 min,gint32 max + + +g_random_double +gdouble +void + + +g_random_double_range +gdouble +gdouble min,gdouble max + + g_spaced_primes_closest guint guint num @@ -3610,7 +4162,7 @@ struct GSourceFuncs GTimeVal *current_time, gpointer user_data); gboolean (*dispatch) (gpointer source_data, - GTimeVal *current_time, + GTimeVal *dispatch_time, gpointer user_data); GDestroyNotify destroy; }; @@ -3668,7 +4220,7 @@ GSourceFuncs *funcs,gpointer user_data g_get_current_time void -GTimeVal *result +GTimeVal *result g_main_new @@ -3765,6 +4317,11 @@ GPollFD *fd GPollFunc func +g_main_win32_get_poll_func +GPollFunc +void + + g_io_channel_unix_new GIOChannel * int fd @@ -3779,6 +4336,16 @@ GIOChannel *channel #define G_WIN32_MSG_HANDLE 19981206 +g_io_channel_win32_make_pollfd +void +GIOChannel *channel,GIOCondition condition,GPollFD *fd + + +g_io_channel_win32_poll +gint +GPollFD *fds,gint n_fds,gint timeout + + g_main_poll_win32_msg_add void gint priority,GPollFD *fd,guint hwnd @@ -3789,24 +4356,9 @@ gint priority,GPollFD *fd,guint hwnd guint hwnd -g_io_channel_win32_new_pipe -GIOChannel * -int fd - - -g_io_channel_win32_new_pipe_with_wakeups -GIOChannel * -int fd,guint peer,int peer_fd - - -g_io_channel_win32_pipe_request_wakeups -void -GIOChannel *channel,guint peer,int peer_fd - - -g_io_channel_win32_pipe_readable -void -int fd,guint offset +g_io_channel_win32_new_fd +GIOChannel * +int fd g_io_channel_win32_get_fd @@ -3827,97 +4379,106 @@ int socket typedef int pid_t; -getcwd -# define getcwd _getcwd - - -getpid -# define getpid _getpid - - -access -# define access _access - - -open -# define open _open - - -read -# define read _read - - -write -# define write _write - - -lseek -# define lseek _lseek - - -close -# define close _close - - pipe -# define pipe(phandles) _pipe (phandles, 4096, _O_BINARY) - - -popen -# define popen _popen - - -pclose -# define pclose _pclose - - -fdopen -# define fdopen _fdopen +#define pipe(phandles) _pipe (phandles, 4096, _O_BINARY) ftruncate -# define ftruncate(fd, size) gwin_ftruncate (fd, size) +# define ftruncate(fd, size) g_win32_ftruncate (fd, size) opendir -# define opendir gwin_opendir +# define opendir g_win32_opendir readdir -# define readdir gwin_readdir +# define readdir g_win32_readdir rewinddir -# define rewinddir gwin_rewinddir +# define rewinddir g_win32_rewinddir closedir -# define closedir gwin_closedir +# define closedir g_win32_closedir NAME_MAX # define NAME_MAX 255 -gwin_ftruncate +g_win32_ftruncate int gint f,guint size -gwin_opendir +g_win32_opendir DIR * const gchar *dirname -gwin_rewinddir +g_win32_rewinddir void DIR *dir -gwin_closedir +g_win32_closedir gint DIR *dir + +g_win32_getlocale +gchar * +void + + +g_win32_error_message +gchar * +gint error + + +g_thread_error_quark +GQuark + + + +G_THREAD_ERROR +#define G_THREAD_ERROR g_thread_error_quark() + + +GThreadError +typedef enum +{ + G_THREAD_ERROR_AGAIN /* Resource temporarily unavailable */ +} GThreadError; + + +GThreadFunc +void +gpointer value + + +GThreadPriority +typedef enum +{ + G_THREAD_PRIORITY_LOW, + G_THREAD_PRIORITY_NORMAL, + G_THREAD_PRIORITY_HIGH, + G_THREAD_PRIORITY_URGENT +} GThreadPriority; + + +GThread + + +GThread +struct GThread +{ + GThreadPriority priority; + gboolean bound; + gboolean joinable; +}; + GMutex @@ -3931,30 +4492,50 @@ DIR *dir GStaticPrivate +GAsyncQueue + + +GThreadPool + + GThreadFunctions GThreadFunctions struct GThreadFunctions { - GMutex* (*mutex_new) (void); - void (*mutex_lock) (GMutex *mutex); - gboolean (*mutex_trylock) (GMutex *mutex); - void (*mutex_unlock) (GMutex *mutex); - void (*mutex_free) (GMutex *mutex); - GCond* (*cond_new) (void); - void (*cond_signal) (GCond *cond); - void (*cond_broadcast) (GCond *cond); - void (*cond_wait) (GCond *cond, - GMutex *mutex); - gboolean (*cond_timed_wait) (GCond *cond, - GMutex *mutex, - GTimeVal *end_time); - void (*cond_free) (GCond *cond); - GPrivate* (*private_new) (GDestroyNotify destructor); - gpointer (*private_get) (GPrivate *private_key); - void (*private_set) (GPrivate *private_key, - gpointer data); + GMutex* (*mutex_new) (void); + void (*mutex_lock) (GMutex *mutex); + gboolean (*mutex_trylock) (GMutex *mutex); + void (*mutex_unlock) (GMutex *mutex); + void (*mutex_free) (GMutex *mutex); + GCond* (*cond_new) (void); + void (*cond_signal) (GCond *cond); + void (*cond_broadcast) (GCond *cond); + void (*cond_wait) (GCond *cond, + GMutex *mutex); + gboolean (*cond_timed_wait) (GCond *cond, + GMutex *mutex, + GTimeVal *end_time); + void (*cond_free) (GCond *cond); + GPrivate* (*private_new) (GDestroyNotify destructor); + gpointer (*private_get) (GPrivate *private_key); + void (*private_set) (GPrivate *private_key, + gpointer data); + void (*thread_create) (GThreadFunc thread_func, + gpointer arg, + gulong stack_size, + gboolean joinable, + gboolean bound, + GThreadPriority priority, + gpointer thread, + GError **error); + void (*thread_yield) (void); + void (*thread_join) (gpointer thread); + void (*thread_exit) (void); + void (*thread_set_priority)(gpointer thread, + GThreadPriority priority); + void (*thread_self) (gpointer thread); }; @@ -4047,6 +4628,34 @@ GMutex **mutex (private_key, value)) +g_thread_yield +#define g_thread_yield() G_THREAD_CF (thread_yield, (void)0, ()) + + +g_thread_exit +#define g_thread_exit() G_THREAD_CF (thread_exit, (void)0, ()) + + +g_thread_create +GThread * +GThreadFunc thread_func,gpointer arg,gulong stack_size,gboolean joinable,gboolean bound,GThreadPriority priority,GError **error + + +g_thread_self +GThread * + + + +g_thread_join +void +GThread *thread + + +g_thread_set_priority +void +GThread *thread,GThreadPriority priority + + g_static_mutex_lock #define g_static_mutex_lock(mutex) \ g_mutex_lock (g_static_mutex_get_mutex (mutex)) @@ -4083,13 +4692,118 @@ GStaticPrivate *private_key GStaticPrivate *private_key,gpointer data,GDestroyNotify notify +g_static_private_get_for_thread +gpointer +GStaticPrivate *private_key,GThread *thread + + +g_static_private_set_for_thread +void +GStaticPrivate *private_key,GThread *thread,gpointer data,GDestroyNotify notify + + +GStaticRecMutex + + +GStaticRecMutex +struct GStaticRecMutex +{ + GStaticMutex mutex; + unsigned int depth; + GSystemThread owner; +}; + + +G_STATIC_REC_MUTEX_INIT +#define G_STATIC_REC_MUTEX_INIT { G_STATIC_MUTEX_INIT } + + +g_static_rec_mutex_lock +void +GStaticRecMutex *mutex + + +g_static_rec_mutex_trylock +gboolean +GStaticRecMutex *mutex + + +g_static_rec_mutex_unlock +void +GStaticRecMutex *mutex + + +g_static_rec_mutex_lock_full +void +GStaticRecMutex *mutex,guint depth + + +g_static_rec_mutex_unlock_full +guint +GStaticRecMutex *mutex + + +GStaticRWLock + + +GStaticRWLock +struct GStaticRWLock +{ + GStaticMutex mutex; + GCond *read_cond; + GCond *write_cond; + guint read_counter; + gboolean write; + guint want_to_write; +}; + + +G_STATIC_RW_LOCK_INIT +#define G_STATIC_RW_LOCK_INIT { G_STATIC_MUTEX_INIT, NULL, NULL, 0, FALSE, FALSE } + + +g_static_rw_lock_reader_lock +void +GStaticRWLock* lock + + +g_static_rw_lock_reader_trylock +gboolean +GStaticRWLock* lock + + +g_static_rw_lock_reader_unlock +void +GStaticRWLock* lock + + +g_static_rw_lock_writer_lock +void +GStaticRWLock* lock + + +g_static_rw_lock_writer_trylock +gboolean +GStaticRWLock* lock + + +g_static_rw_lock_writer_unlock +void +GStaticRWLock* lock + + +g_static_rw_lock_free +void +GStaticRWLock* lock + + glib_dummy_decl void void G_LOCK_NAME -#define G_LOCK_NAME(name) (g__ ## name ## _lock) +#define G_LOCK_NAME(name) g__ ## name ## _lock G_LOCK_DEFINE_STATIC @@ -4126,12 +4840,11 @@ void G_TRYLOCK -# define G_TRYLOCK(name) G_STMT_START{ \ - g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \ +# define G_TRYLOCK(name) \ + (g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \ "file %s: line %d (%s): try locking: %s ", \ __FILE__, __LINE__, G_GNUC_PRETTY_FUNCTION, \ - #name); \ - }G_STMT_END, g_static_mutex_trylock (&G_LOCK_NAME (name)) + #name), g_static_mutex_trylock (&G_LOCK_NAME (name))) G_LOCK @@ -4167,84 +4880,418 @@ void G_TRYLOCK -# define G_TRYLOCK(name) (FALSE) +# define G_TRYLOCK(name) (TRUE) - -g_log_domain_gmodule -extern const char *g_log_domain_gmodule; - - -G_MODULE_IMPORT -#define G_MODULE_IMPORT extern - - -G_MODULE_EXPORT -# define G_MODULE_EXPORT __declspec(dllexport) - - -G_MODULE_EXPORT -# define G_MODULE_EXPORT - - -GModuleFlags -typedef enum -{ - G_MODULE_BIND_LAZY = 1 << 0, - G_MODULE_BIND_MASK = 0x01 -} GModuleFlags; - + +g_async_queue_new +GAsyncQueue * +void + + +g_async_queue_lock +void +GAsyncQueue *queue + + +g_async_queue_unlock +void +GAsyncQueue *queue + + +g_async_queue_ref +void +GAsyncQueue *queue + + +g_async_queue_ref_unlocked +void +GAsyncQueue *queue + + +g_async_queue_unref +void +GAsyncQueue *queue + + +g_async_queue_unref_and_unlock +void +GAsyncQueue *queue + + +g_async_queue_push +void +GAsyncQueue *queue,gpointer data + + +g_async_queue_push_unlocked +void +GAsyncQueue *queue,gpointer data + + +g_async_queue_pop +gpointer +GAsyncQueue *queue + + +g_async_queue_pop_unlocked +gpointer +GAsyncQueue *queue + + +g_async_queue_try_pop +gpointer +GAsyncQueue *queue + + +g_async_queue_try_pop_unlocked +gpointer +GAsyncQueue *queue + + +g_async_queue_timed_pop +gpointer +GAsyncQueue *queue,GTimeVal *end_time + + +g_async_queue_timed_pop_unlocked +gpointer +GAsyncQueue *queue,GTimeVal *end_time + + +g_async_queue_length +gint +GAsyncQueue *queue + + +g_async_queue_length_unlocked +gint +GAsyncQueue *queue + -GModule +GThreadPool +struct GThreadPool +{ + GFunc thread_func; + gulong stack_size; + gboolean bound; + GThreadPriority priority; + gboolean exclusive; + gpointer user_data; +}; - -GModuleCheckInit -const gchar * -GModule *module - - -GModuleUnload -void -GModule *module - -g_module_supported -gboolean +g_thread_pool_new +GThreadPool * +GFunc thread_func,gint max_threads,gulong stack_size,gboolean bound,GThreadPriority priority,gboolean exclusive,gpointer user_data,GError **error + + +g_thread_pool_push +void +GThreadPool *pool,gpointer data,GError **error + + +g_thread_pool_set_max_threads +void +GThreadPool *pool,gint max_threads,GError **error + + +g_thread_pool_get_max_threads +gint +GThreadPool *pool + + +g_thread_pool_get_num_threads +guint +GThreadPool *pool + + +g_thread_pool_unprocessed +guint +GThreadPool *pool + + +g_thread_pool_free +void +GThreadPool *pool,gboolean immediate,gboolean wait + + +g_thread_pool_set_max_unused_threads +void +gint max_threads + + +g_thread_pool_get_max_unused_threads +gint void -g_module_open -GModule * -const gchar *file_name,GModuleFlags flags - - -g_module_close -gboolean -GModule *module - - -g_module_make_resident -void -GModule *module - - -g_module_error -gchar * +g_thread_pool_get_num_unused_threads +guint void -g_module_symbol -gboolean -GModule *module,const gchar *symbol_name,gpointer *symbol +g_thread_pool_stop_unused_threads +void +void + + +gunichar +typedef guint32 gunichar; + + +gunichar2 +typedef guint16 gunichar2; + + +GUnicodeType +typedef enum { + G_UNICODE_CONTROL, + G_UNICODE_FORMAT, + G_UNICODE_UNASSIGNED, + G_UNICODE_PRIVATE_USE, + G_UNICODE_SURROGATE, + G_UNICODE_LOWERCASE_LETTER, + G_UNICODE_MODIFIER_LETTER, + G_UNICODE_OTHER_LETTER, + G_UNICODE_TITLECASE_LETTER, + G_UNICODE_UPPERCASE_LETTER, + G_UNICODE_COMBINING_MARK, + G_UNICODE_ENCLOSING_MARK, + G_UNICODE_NON_SPACING_MARK, + G_UNICODE_DECIMAL_NUMBER, + G_UNICODE_LETTER_NUMBER, + G_UNICODE_OTHER_NUMBER, + G_UNICODE_CONNECT_PUNCTUATION, + G_UNICODE_DASH_PUNCTUATION, + G_UNICODE_CLOSE_PUNCTUATION, + G_UNICODE_FINAL_PUNCTUATION, + G_UNICODE_INITIAL_PUNCTUATION, + G_UNICODE_OTHER_PUNCTUATION, + G_UNICODE_OPEN_PUNCTUATION, + G_UNICODE_CURRENCY_SYMBOL, + G_UNICODE_MODIFIER_SYMBOL, + G_UNICODE_MATH_SYMBOL, + G_UNICODE_OTHER_SYMBOL, + G_UNICODE_LINE_SEPARATOR, + G_UNICODE_PARAGRAPH_SEPARATOR, + G_UNICODE_SPACE_SEPARATOR +} GUnicodeType; + + +g_get_charset +gboolean +char **charset -g_module_name -gchar * -GModule *module +g_unichar_isalnum +gboolean +gunichar c -g_module_build_path -gchar * -const gchar *directory,const gchar *module_name +g_unichar_isalpha +gboolean +gunichar c + + +g_unichar_iscntrl +gboolean +gunichar c + + +g_unichar_isdigit +gboolean +gunichar c + + +g_unichar_isgraph +gboolean +gunichar c + + +g_unichar_islower +gboolean +gunichar c + + +g_unichar_isprint +gboolean +gunichar c + + +g_unichar_ispunct +gboolean +gunichar c + + +g_unichar_isspace +gboolean +gunichar c + + +g_unichar_isupper +gboolean +gunichar c + + +g_unichar_isxdigit +gboolean +gunichar c + + +g_unichar_istitle +gboolean +gunichar c + + +g_unichar_isdefined +gboolean +gunichar c + + +g_unichar_iswide +gboolean +gunichar c + + +g_unichar_toupper +gunichar +gunichar c + + +g_unichar_tolower +gunichar +gunichar c + + +g_unichar_totitle +gunichar +gunichar c + + +g_unichar_digit_value +gint +gunichar c + + +g_unichar_xdigit_value +gint +gunichar c + + +g_unichar_type +GUnicodeType +gunichar c + + +g_unicode_canonical_ordering +void +gunichar *string,size_t len + + +g_unicode_canonical_decomposition +gunichar * +gunichar ch,size_t *result_len + + +GLIB_VAR +# define GLIB_VAR __declspec(dllexport) + + +GLIB_VAR +# define GLIB_VAR extern __declspec(dllimport) + + +GLIB_VAR +# define GLIB_VAR extern + + +g_utf8_next_char +#define g_utf8_next_char(p) (char *)((p) + g_utf8_skip[*(guchar *)(p)]) + + +g_utf8_get_char +gunichar +const gchar *p + + +g_utf8_offset_to_pointer +gchar * +const gchar *str,gint offset + + +g_utf8_pointer_to_offset +gint +const gchar *str,const gchar *pos + + +g_utf8_prev_char +gchar * +const gchar *p + + +g_utf8_find_next_char +gchar * +const gchar *p,const gchar *bound + + +g_utf8_find_prev_char +gchar * +const gchar *str,const gchar *p + + +g_utf8_strlen +gint +const gchar *p,gint max + + +g_utf8_strncpy +gchar * +gchar *dest,const gchar *src,size_t n + + +g_utf8_strchr +gchar * +const gchar *p,gunichar ch + + +g_utf8_strrchr +gchar * +const gchar *p,gunichar ch + + +g_utf8_to_utf16 +gunichar2 * +const gchar *str,gint len + + +g_utf8_to_ucs4 +gunichar * +const gchar *str,gint len + + +g_utf16_to_ucs4 +gunichar * +const gunichar2 *str,gint len + + +g_utf16_to_utf8 +gchar * +const gunichar2 *str,gint len + + +g_ucs4_to_utf16 +gunichar * +const gunichar *str,gint len + + +g_ucs4_to_utf8 +gchar * +const gunichar *str,gint len + + +g_unichar_to_utf8 +gint +gunichar c,char *outbuf GLIB_HAVE_SYS_POLL_H @@ -4275,6 +5322,10 @@ const gchar *directory,const gchar *module_name #define G_MAXSHORT SHRT_MAX +G_MAXUSHORT +#define G_MAXUSHORT USHRT_MAX + + G_MININT #define G_MININT INT_MIN @@ -4283,6 +5334,10 @@ const gchar *directory,const gchar *module_name #define G_MAXINT INT_MAX +G_MAXUINT +#define G_MAXUINT UINT_MAX + + G_MINLONG #define G_MINLONG LONG_MIN @@ -4290,6 +5345,10 @@ const gchar *directory,const gchar *module_name G_MAXLONG #define G_MAXLONG LONG_MAX + +G_MAXULONG +#define G_MAXULONG ULONG_MAX + gint8 typedef signed char gint8; @@ -4306,6 +5365,14 @@ typedef signed short gint16; guint16 typedef unsigned short guint16; + +G_GINT16_FORMAT +#define G_GINT16_FORMAT "hi" + + +G_GUINT16_FORMAT +#define G_GUINT16_FORMAT "hu" + gint32 typedef signed int gint32; @@ -4315,12 +5382,12 @@ typedef signed int gint32; typedef unsigned int guint32; -G_GNUC_EXTENSION -# define G_GNUC_EXTENSION __extension__ +G_GINT32_FORMAT +#define G_GINT32_FORMAT "i" -G_GNUC_EXTENSION -# define G_GNUC_EXTENSION +G_GUINT32_FORMAT +#define G_GUINT32_FORMAT "u" G_HAVE_GINT64 @@ -4335,9 +5402,25 @@ G_GNUC_EXTENSION typedef signed long long gint64; G_GNUC_EXTENSION typedef unsigned long long guint64; +G_GINT64_FORMAT +#define G_GINT64_FORMAT "lli" + + +G_GUINT64_FORMAT +#define G_GUINT64_FORMAT "llu" + + G_GINT64_CONSTANT #define G_GINT64_CONSTANT(val) (G_GNUC_EXTENSION (val##LL)) + +gssize +typedef gint32 gssize; + + +gsize +typedef guint32 gsize; + GPOINTER_TO_INT #define GPOINTER_TO_INT(p) ((gint) (p)) @@ -4372,11 +5455,19 @@ G_GNUC_EXTENSION typedef unsigned long long guint64; GLIB_MINOR_VERSION -#define GLIB_MINOR_VERSION 2 +#define GLIB_MINOR_VERSION 3 GLIB_MICRO_VERSION -#define GLIB_MICRO_VERSION 3 +#define GLIB_MICRO_VERSION 1 + + +G_OS_UNIX +#define G_OS_UNIX + + +G_VA_COPY +#define G_VA_COPY __va_copy G_HAVE_INLINE @@ -4426,6 +5517,16 @@ struct GStaticMutex g_static_mutex_get_mutex #define g_static_mutex_get_mutex(mutex) (g_thread_use_default_impl ? ((GMutex*) &((mutex)->aligned_pad_u)) : g_static_mutex_get_mutex_impl (&((mutex)->runtime_mutex))) + +GSystemThread +union GSystemThread +{ + char data[4]; + double dummy_double; + void *dummy_pointer; + long dummy_long; +}; + GINT16_TO_LE #define GINT16_TO_LE(val) ((gint16) (val)) @@ -4534,11 +5635,1786 @@ struct GStaticMutex GLIB_SYSDEF_POLLNVAL #define GLIB_SYSDEF_POLLNVAL =32 + +g_log_domain_gmodule +extern const char *g_log_domain_gmodule; + -G_HAVE_WCHAR_H -#define G_HAVE_WCHAR_H 1 +G_MODULE_IMPORT +#define G_MODULE_IMPORT extern -G_HAVE_WCTYPE_H -#define G_HAVE_WCTYPE_H 1 +G_MODULE_EXPORT +# define G_MODULE_EXPORT __declspec(dllexport) + +G_MODULE_EXPORT +# define G_MODULE_EXPORT + + +GModuleFlags +typedef enum +{ + G_MODULE_BIND_LAZY = 1 << 0, + G_MODULE_BIND_MASK = 0x01 +} GModuleFlags; + + +GModule + + +GModuleCheckInit +const gchar * +GModule *module + + +GModuleUnload +void +GModule *module + + +g_module_supported +gboolean +void + + +g_module_open +GModule * +const gchar *file_name,GModuleFlags flags + + +g_module_close +gboolean +GModule *module + + +g_module_make_resident +void +GModule *module + + +g_module_error +gchar * +void + + +g_module_symbol +gboolean +GModule *module,const gchar *symbol_name,gpointer *symbol + + +g_module_name +gchar * +GModule *module + + +g_module_build_path +gchar * +const gchar *directory,const gchar *module_name + + +G_TYPE_IS_ENUM +#define G_TYPE_IS_ENUM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_ENUM) + + +G_ENUM_CLASS +#define G_ENUM_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_ENUM, GEnumClass)) + + +G_IS_ENUM_CLASS +#define G_IS_ENUM_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_ENUM)) + + +G_ENUM_CLASS_TYPE +#define G_ENUM_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class)) + + +G_ENUM_CLASS_TYPE_NAME +#define G_ENUM_CLASS_TYPE_NAME(class) (g_type_name (G_ENUM_TYPE (class))) + + +G_TYPE_IS_FLAGS +#define G_TYPE_IS_FLAGS(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_FLAGS) + + +G_FLAGS_CLASS +#define G_FLAGS_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_FLAGS, GFlagsClass)) + + +G_IS_FLAGS_CLASS +#define G_IS_FLAGS_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_FLAGS)) + + +G_FLAGS_CLASS_TYPE +#define G_FLAGS_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class)) + + +G_FLAGS_CLASS_TYPE_NAME +#define G_FLAGS_CLASS_TYPE_NAME(class) (g_type_name (G_FLAGS_TYPE (class))) + + +G_IS_VALUE_ENUM +#define G_IS_VALUE_ENUM(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_ENUM)) + + +G_IS_VALUE_FLAGS +#define G_IS_VALUE_FLAGS(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_FLAGS)) + + +GEnumClass + + +GFlagsClass + + +GEnumValue + + +GFlagsValue + + +GEnumValue +struct GEnumValue +{ + gint value; + gchar *value_name; + gchar *value_nick; +}; + + +GFlagsValue +struct GFlagsValue +{ + guint value; + gchar *value_name; + gchar *value_nick; +}; + + +g_enum_get_value +GEnumValue * +GEnumClass *enum_class,gint value + + +g_enum_get_value_by_name +GEnumValue * +GEnumClass *enum_class,const gchar *name + + +g_enum_get_value_by_nick +GEnumValue * +GEnumClass *enum_class,const gchar *nick + + +g_flags_get_first_value +GFlagsValue * +GFlagsClass *flags_class,guint value + + +g_flags_get_value_by_name +GFlagsValue * +GFlagsClass *flags_class,const gchar *name + + +g_flags_get_value_by_nick +GFlagsValue * +GFlagsClass *flags_class,const gchar *nick + + +g_value_set_enum +void +GValue *value,gint v_enum + + +g_value_get_enum +gint +GValue *value + + +g_value_set_flags +void +GValue *value,guint v_flags + + +g_value_get_flags +guint +GValue *value + + +g_enum_register_static +GType +const gchar *name,const GEnumValue *const_static_values + + +g_flags_register_static +GType +const gchar *name,const GFlagsValue *const_static_values + + +g_enum_complete_type_info +void +GType g_enum_type,GTypeInfo *info,const GEnumValue *const_values + + +g_flags_complete_type_info +void +GType g_flags_type,GTypeInfo *info,const GFlagsValue *const_values + + +G_TYPE_IS_OBJECT +#define G_TYPE_IS_OBJECT(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_OBJECT) + + +G_OBJECT +#define G_OBJECT(object) (G_IS_OBJECT (object) ? ((GObject*) (object)) : \ + G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_OBJECT, GObject)) + + +G_OBJECT_CLASS +#define G_OBJECT_CLASS(class) (G_IS_OBJECT_CLASS (class) ? ((GObjectClass*) (class)) : \ + G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_OBJECT, GObjectClass)) + + +G_IS_OBJECT +#define G_IS_OBJECT(object) (((GObject*) (object)) != NULL && \ + G_IS_OBJECT_CLASS (((GTypeInstance*) (object))->g_class)) + + +G_IS_OBJECT_CLASS +#define G_IS_OBJECT_CLASS(class) (((GTypeClass*) (class)) != NULL && \ + G_TYPE_IS_OBJECT (((GTypeClass*) (class))->g_type)) + + +G_OBJECT_GET_CLASS +#define G_OBJECT_GET_CLASS(object) (G_TYPE_INSTANCE_GET_CLASS ((object), G_TYPE_OBJECT, GObjectClass)) + + +G_OBJECT_TYPE +#define G_OBJECT_TYPE(object) (G_TYPE_FROM_INSTANCE (object)) + + +G_OBJECT_TYPE_NAME +#define G_OBJECT_TYPE_NAME(object) (g_type_name (G_OBJECT_TYPE (object))) + + +G_OBJECT_CLASS_TYPE +#define G_OBJECT_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class)) + + +G_OBJECT_CLASS_NAME +#define G_OBJECT_CLASS_NAME(class) (g_type_name (G_OBJECT_CLASS_TYPE (class))) + + +G_IS_VALUE_OBJECT +#define G_IS_VALUE_OBJECT(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_OBJECT)) + + +G_NOTIFY_PRIORITY +#define G_NOTIFY_PRIORITY (G_PRIORITY_HIGH_IDLE + 20) + + +GObject + + +GObjectClass + + +GObjectGetParamFunc +void +GObject *object, + guint param_id, + GValue *value, + GParamSpec *pspec, + const gchar *trailer + + +GObjectSetParamFunc +void +GObject *object, + guint param_id, + GValue *value, + GParamSpec *pspec, + const gchar *trailer + + +GObjectFinalizeFunc +void +GObject *object + + +GObject +struct GObject +{ + GTypeInstance g_type_instance; + + /*< private >*/ + guint ref_count; + GData *qdata; +}; + + +g_object_class_install_param +void +GObjectClass *oclass,guint param_id,GParamSpec *pspec + + +g_object_class_find_param_spec +GParamSpec * +GObjectClass *oclass,const gchar *param_name + + +g_object_new +gpointer +GType object_type,const gchar *first_param_name,... + + +g_object_new_valist +gpointer +GType object_type,const gchar *first_param_name,va_list var_args + + +g_object_set +void +GObject *object,const gchar *first_param_name,... + + +g_object_get +void +GObject *object,const gchar *first_param_name,... + + +g_object_set_valist +void +GObject *object,const gchar *first_param_name,va_list var_args + + +g_object_get_valist +void +GObject *object,const gchar *first_param_name,va_list var_args + + +g_object_set_param +void +GObject *object,const gchar *param_name,const GValue *value + + +g_object_get_param +void +GObject *object,const gchar *param_name,GValue *value + + +g_object_queue_param_changed +void +GObject *object,const gchar *param_name + + +g_object_ref +GObject * +GObject *object + + +g_object_unref +void +GObject *object + + +g_object_get_qdata +gpointer +GObject *object,GQuark quark + + +g_object_set_qdata +void +GObject *object,GQuark quark,gpointer data + + +g_object_set_qdata_full +void +GObject *object,GQuark quark,gpointer data,GDestroyNotify destroy + + +g_object_steal_qdata +gpointer +GObject *object,GQuark quark + + +g_value_set_object +void +GValue *value,GObject *v_object + + +g_value_get_object +GObject * +GValue *value + + +g_value_dup_object +GObject * +GValue *value + + +G_WARN_INVALID_PARAM_ID +#define G_WARN_INVALID_PARAM_ID(object, param_id, pspec) \ +G_STMT_START { \ + GObject *_object = (GObject*) (object); \ + GParamSpec *_pspec = (GParamSpec*) (pspec); \ + guint _param_id = (param_id); \ + g_warning ("%s: invalid parameter id %u for \"%s\" of type `%s' in `%s'", \ + G_STRLOC, \ + _param_id, \ + _pspec->name, \ + g_type_name (G_PARAM_SPEC_TYPE (_pspec)), \ + BSE_OBJECT_TYPE_NAME (_object)); \ +} G_STMT_END + + +G_TYPE_IS_PARAM +#define G_TYPE_IS_PARAM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM) + + +G_PARAM_SPEC_TYPE +#define G_PARAM_SPEC_TYPE(pspec) (G_TYPE_FROM_INSTANCE (pspec)) + + +G_PARAM_SPEC_TYPE_NAME +#define G_PARAM_SPEC_TYPE_NAME(pspec) (g_type_name (G_PARAM_SPEC_TYPE (pspec))) + + +G_PARAM_SPEC +#define G_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec)) + + +G_IS_PARAM_SPEC +#define G_IS_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM)) + + +G_PARAM_SPEC_GET_CLASS +#define G_PARAM_SPEC_GET_CLASS(pspec) (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass)) + + +G_IS_PARAM_VALUE +#define G_IS_PARAM_VALUE(pspec, value) (g_type_is_a (G_VALUE_TYPE (value), G_PARAM_SPEC_VALUE_TYPE (pspec))) /* FIXME */ + + +G_PARAM_SPEC_VALUE_TYPE +#define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC_GET_CLASS (pspec)->value_type) + + +GParamFlags +typedef enum +{ + G_PARAM_READABLE = 1 << 0, + G_PARAM_WRITABLE = 1 << 1, + G_PARAM_MASK = 0x000f, + /* bits in the range 0xfff0 are reserved for 3rd party usage */ + G_PARAM_USER_MASK = 0xfff0 +} GParamFlags; + + +GParamSpecClass + + +GParamSpec + + +GParamSpec +struct GParamSpec +{ + GTypeInstance g_instance; + + gchar *name; + gchar *nick; + gchar *blurb; + GParamFlags flags; + + /*< private >*/ + GType owner_type; + GData *qdata; + guint ref_count; +}; + + +g_param_spec_ref +GParamSpec * +GParamSpec *pspec + + +g_param_spec_unref +void +GParamSpec *pspec + + +g_param_spec_get_qdata +gpointer +GParamSpec *pspec,GQuark quark + + +g_param_spec_set_qdata +void +GParamSpec *pspec,GQuark quark,gpointer data + + +g_param_spec_set_qdata_full +void +GParamSpec *pspec,GQuark quark,gpointer data,GDestroyNotify destroy + + +g_param_spec_steal_qdata +gpointer +GParamSpec *pspec,GQuark quark + + +g_param_value_set_default +void +GParamSpec *pspec,GValue *value + + +g_param_value_defaults +gboolean +GParamSpec *pspec,GValue *value + + +g_param_value_validate +gboolean +GParamSpec *pspec,GValue *value + + +g_param_values_cmp +gint +GParamSpec *pspec,const GValue *value1,const GValue *value2 + + +g_param_spec_internal +gpointer +GType param_type,const gchar *name,const gchar *nick,const gchar *blurb,GParamFlags flags + + +g_param_spec_hash_table_new +GHashTable * +void + + +g_param_spec_hash_table_insert +void +GHashTable *hash_table,GParamSpec *pspec,GType owner_type + + +g_param_spec_hash_table_remove +void +GHashTable *hash_table,GParamSpec *pspec + + +g_param_spec_hash_table_lookup +GParamSpec * +GHashTable *hash_table,const gchar *param_name,GType owner_type,gboolean try_ancestors,const gchar **trailer + + +G_IS_PARAM_SPEC_CHAR +#define G_IS_PARAM_SPEC_CHAR(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_CHAR)) + + +G_PARAM_SPEC_CHAR +#define G_PARAM_SPEC_CHAR(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_CHAR, GParamSpecChar)) + + +G_IS_PARAM_SPEC_UCHAR +#define G_IS_PARAM_SPEC_UCHAR(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UCHAR)) + + +G_PARAM_SPEC_UCHAR +#define G_PARAM_SPEC_UCHAR(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UCHAR, GParamSpecUChar)) + + +G_IS_PARAM_SPEC_BOOLEAN +#define G_IS_PARAM_SPEC_BOOLEAN(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_BOOLEAN)) + + +G_PARAM_SPEC_BOOLEAN +#define G_PARAM_SPEC_BOOLEAN(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_BOOLEAN, GParamSpecBoolean)) + + +G_IS_PARAM_SPEC_INT +#define G_IS_PARAM_SPEC_INT(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_INT)) + + +G_PARAM_SPEC_INT +#define G_PARAM_SPEC_INT(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_INT, GParamSpecInt)) + + +G_IS_PARAM_SPEC_UINT +#define G_IS_PARAM_SPEC_UINT(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UINT)) + + +G_PARAM_SPEC_UINT +#define G_PARAM_SPEC_UINT(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UINT, GParamSpecUInt)) + + +G_IS_PARAM_SPEC_LONG +#define G_IS_PARAM_SPEC_LONG(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_LONG)) + + +G_PARAM_SPEC_LONG +#define G_PARAM_SPEC_LONG(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_LONG, GParamSpecLong)) + + +G_IS_PARAM_SPEC_ULONG +#define G_IS_PARAM_SPEC_ULONG(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_ULONG)) + + +G_PARAM_SPEC_ULONG +#define G_PARAM_SPEC_ULONG(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_ULONG, GParamSpecULong)) + + +G_IS_PARAM_SPEC_ENUM +#define G_IS_PARAM_SPEC_ENUM(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_ENUM)) + + +G_PARAM_SPEC_ENUM +#define G_PARAM_SPEC_ENUM(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_ENUM, GParamSpecEnum)) + + +G_IS_PARAM_SPEC_FLAGS +#define G_IS_PARAM_SPEC_FLAGS(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_FLAGS)) + + +G_PARAM_SPEC_FLAGS +#define G_PARAM_SPEC_FLAGS(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_FLAGS, GParamSpecFlags)) + + +G_IS_PARAM_SPEC_FLOAT +#define G_IS_PARAM_SPEC_FLOAT(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_FLOAT)) + + +G_PARAM_SPEC_FLOAT +#define G_PARAM_SPEC_FLOAT(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_FLOAT, GParamSpecFloat)) + + +G_IS_PARAM_SPEC_DOUBLE +#define G_IS_PARAM_SPEC_DOUBLE(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_DOUBLE)) + + +G_PARAM_SPEC_DOUBLE +#define G_PARAM_SPEC_DOUBLE(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_DOUBLE, GParamSpecDouble)) + + +G_IS_PARAM_SPEC_STRING +#define G_IS_PARAM_SPEC_STRING(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_STRING)) + + +G_PARAM_SPEC_STRING +#define G_PARAM_SPEC_STRING(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_STRING, GParamSpecString)) + + +G_IS_PARAM_SPEC_OBJECT +#define G_IS_PARAM_SPEC_OBJECT(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_OBJECT)) + + +G_PARAM_SPEC_OBJECT +#define G_PARAM_SPEC_OBJECT(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_OBJECT, GParamSpecObject)) + + +GParamSpecChar + + +GParamSpecUChar + + +GParamSpecBoolean + + +GParamSpecInt + + +GParamSpecUInt + + +GParamSpecLong + + +GParamSpecULong + + +GParamSpecEnum + + +GParamSpecFlags + + +GParamSpecFloat + + +GParamSpecDouble + + +GParamSpecString + + +GParamSpecObject + + +GParamSpecChar +struct GParamSpecChar +{ + GParamSpec parent_instance; + + gint8 minimum; + gint8 maximum; + gint8 default_value; +}; + + +GParamSpecUChar +struct GParamSpecUChar +{ + GParamSpec parent_instance; + + guint8 minimum; + guint8 maximum; + guint8 default_value; +}; + + +GParamSpecBoolean +struct GParamSpecBoolean +{ + GParamSpec parent_instance; + + gboolean default_value; +}; + + +GParamSpecInt +struct GParamSpecInt +{ + GParamSpec parent_instance; + + gint minimum; + gint maximum; + gint default_value; +}; + + +GParamSpecUInt +struct GParamSpecUInt +{ + GParamSpec parent_instance; + + guint minimum; + guint maximum; + guint default_value; +}; + + +GParamSpecLong +struct GParamSpecLong +{ + GParamSpec parent_instance; + + glong minimum; + glong maximum; + glong default_value; +}; + + +GParamSpecULong +struct GParamSpecULong +{ + GParamSpec parent_instance; + + gulong minimum; + gulong maximum; + gulong default_value; +}; + + +GParamSpecEnum +struct GParamSpecEnum +{ + GParamSpec parent_instance; + + GEnumClass *enum_class; + glong default_value; +}; + + +GParamSpecFlags +struct GParamSpecFlags +{ + GParamSpec parent_instance; + + GFlagsClass *flags_class; + gulong default_value; +}; + + +GParamSpecFloat +struct GParamSpecFloat +{ + GParamSpec parent_instance; + + gfloat minimum; + gfloat maximum; + gfloat default_value; + gfloat epsilon; +}; + + +GParamSpecDouble +struct GParamSpecDouble +{ + GParamSpec parent_instance; + + gdouble minimum; + gdouble maximum; + gdouble default_value; + gdouble epsilon; +}; + + +GParamSpecString +struct GParamSpecString +{ + GParamSpec parent_instance; + + gchar *default_value; + gchar *cset_first; + gchar *cset_nth; + gchar substitutor; + guint null_fold_if_empty : 1; + guint ensure_non_null : 1; +}; + + +GParamSpecObject +struct GParamSpecObject +{ + GParamSpec parent_instance; + + GType object_type; +}; + + +g_param_spec_char +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,gint8 minimum,gint8 maximum,gint8 default_value,GParamFlags flags + + +g_param_spec_uchar +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,guint8 minimum,guint8 maximum,guint8 default_value,GParamFlags flags + + +g_param_spec_boolean +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,gboolean default_value,GParamFlags flags + + +g_param_spec_int +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,gint minimum,gint maximum,gint default_value,GParamFlags flags + + +g_param_spec_uint +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,guint minimum,guint maximum,guint default_value,GParamFlags flags + + +g_param_spec_long +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,glong minimum,glong maximum,glong default_value,GParamFlags flags + + +g_param_spec_ulong +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,gulong minimum,gulong maximum,gulong default_value,GParamFlags flags + + +g_param_spec_enum +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,GType enum_type,gint default_value,GParamFlags flags + + +g_param_spec_flags +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,GType flags_type,guint default_value,GParamFlags flags + + +g_param_spec_float +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,gfloat minimum,gfloat maximum,gfloat default_value,GParamFlags flags + + +g_param_spec_double +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,gdouble minimum,gdouble maximum,gdouble default_value,GParamFlags flags + + +g_param_spec_string +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,const gchar *default_value,GParamFlags flags + + +g_param_spec_string_c +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,const gchar *default_value,GParamFlags flags + + +g_param_spec_object +GParamSpec * +const gchar *name,const gchar *nick,const gchar *blurb,GType object_type,GParamFlags flags + + +g_log_domain_gobject +extern const char *g_log_domain_gobject; + + +G_TYPE_FUNDAMENTAL +#define G_TYPE_FUNDAMENTAL(type) ((type) & 0xff) + + +G_TYPE_FUNDAMENTAL_MAX +#define G_TYPE_FUNDAMENTAL_MAX (0xff) + + +G_TYPE_DERIVE_ID +#define G_TYPE_DERIVE_ID(ptype, branch_seqno) (G_TYPE_FUNDAMENTAL (ptype) | ((branch_seqno) << 8)) + + +G_TYPE_BRANCH_SEQNO +#define G_TYPE_BRANCH_SEQNO(type) ((type) >> 8) + + +G_TYPE_FUNDAMENTAL_LAST +#define G_TYPE_FUNDAMENTAL_LAST ((GType) g_type_fundamental_last ()) + + +GTypeFundamentals +typedef enum /*< skip >*/ +{ + /* standard types, introduced by g_type_init() */ + G_TYPE_INVALID, + G_TYPE_NONE, + G_TYPE_INTERFACE, + + /* GLib type ids */ + G_TYPE_CHAR, + G_TYPE_UCHAR, + G_TYPE_BOOLEAN, + G_TYPE_INT, + G_TYPE_UINT, + G_TYPE_LONG, + G_TYPE_ULONG, + G_TYPE_ENUM, + G_TYPE_FLAGS, + G_TYPE_FLOAT, + G_TYPE_DOUBLE, + G_TYPE_STRING, + G_TYPE_PARAM, + G_TYPE_OBJECT, + + /* the following reserved ids should vanish soon */ + G_TYPE_GTK_BOXED, + G_TYPE_GTK_POINTER, + G_TYPE_GTK_SIGNAL, + + /* reserved fundamental type ids, + * mail gtk-devel-list@redhat.com for reservations + */ + G_TYPE_BSE_PROCEDURE, + G_TYPE_BSE_TIME, + G_TYPE_BSE_NOTE, + G_TYPE_BSE_DOTS, + G_TYPE_GLE_GOBJECT, + + G_TYPE_LAST_RESERVED_FUNDAMENTAL, + + /* derived type ids */ + /* FIXME: G_TYPE_PARAM_INTERFACE */ + G_TYPE_PARAM_CHAR = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 1), + G_TYPE_PARAM_UCHAR = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 2), + G_TYPE_PARAM_BOOLEAN = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 3), + G_TYPE_PARAM_INT = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 4), + G_TYPE_PARAM_UINT = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 5), + G_TYPE_PARAM_LONG = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 6), + G_TYPE_PARAM_ULONG = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 7), + G_TYPE_PARAM_ENUM = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 8), + G_TYPE_PARAM_FLAGS = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 9), + G_TYPE_PARAM_FLOAT = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 10), + G_TYPE_PARAM_DOUBLE = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 11), + G_TYPE_PARAM_STRING = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 12), + /* FIXME: G_TYPE_PARAM_PARAM */ + G_TYPE_PARAM_OBJECT = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 13) +} GTypeFundamentals; + + +G_TYPE_IS_INTERFACE +#define G_TYPE_IS_INTERFACE(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE) + + +G_TYPE_IS_CLASSED +#define G_TYPE_IS_CLASSED(type) (g_type_check_flags ((type), G_TYPE_FLAG_CLASSED)) + + +G_TYPE_IS_INSTANTIATABLE +#define G_TYPE_IS_INSTANTIATABLE(type) (g_type_check_flags ((type), G_TYPE_FLAG_INSTANTIATABLE)) + + +G_TYPE_IS_DERIVABLE +#define G_TYPE_IS_DERIVABLE(type) (g_type_check_flags ((type), G_TYPE_FLAG_DERIVABLE)) + + +G_TYPE_IS_DEEP_DERIVABLE +#define G_TYPE_IS_DEEP_DERIVABLE(type) (g_type_check_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE)) + + +G_TYPE_IS_PARAM +#define G_TYPE_IS_PARAM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM) + + +GType +typedef guint32 GType; + + +GValue + + +GTypePlugin + + +GTypePluginVTable + + +GTypeClass + + +GTypeInterface + + +GTypeInstance + + +GTypeInfo + + +GTypeFundamentalInfo + + +GInterfaceInfo + + +GTypeValueTable + + +GTypeInstance +struct GTypeInstance +{ + /*< private >*/ + GTypeClass *g_class; +}; + + +GTypeInterface +struct GTypeInterface +{ + /*< private >*/ + GType g_type; /* iface type */ + GType g_instance_type; +}; + + +G_TYPE_CHECK_INSTANCE_CAST +#define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type) (_G_TYPE_CIC ((instance), (g_type), c_type)) + + +G_TYPE_CHECK_CLASS_CAST +#define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type) (_G_TYPE_CCC ((g_class), (g_type), c_type)) + + +G_TYPE_CHECK_INSTANCE_TYPE +#define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type) (_G_TYPE_CIT ((instance), (g_type))) + + +G_TYPE_CHECK_CLASS_TYPE +#define G_TYPE_CHECK_CLASS_TYPE(g_class, g_type) (_G_TYPE_CCT ((g_class), (g_type))) + + +G_TYPE_INSTANCE_GET_CLASS +#define G_TYPE_INSTANCE_GET_CLASS(instance, g_type, c_type) (_G_TYPE_IGC ((instance), c_type)) + + +G_TYPE_FROM_INSTANCE +#define G_TYPE_FROM_INSTANCE(instance) (G_TYPE_FROM_CLASS (((GTypeInstance*) (instance))->g_class)) + + +G_TYPE_FROM_CLASS +#define G_TYPE_FROM_CLASS(g_class) (((GTypeClass*) (g_class))->g_type) + + +G_TYPE_FROM_INTERFACE +#define G_TYPE_FROM_INTERFACE(g_iface) (((GTypeInterface*) (g_iface))->g_type) + + +g_type_init +void +void + + +g_type_name +gchar * +GType type + + +g_type_qname +GQuark +GType type + + +g_type_from_name +GType +const gchar *name + + +g_type_parent +GType +GType type + + +g_type_next_base +GType +GType type,GType base_type + + +g_type_is_a +gboolean +GType type,GType is_a_type + + +g_type_conforms_to +gboolean +GType type,GType iface_type + + +g_type_fundamental_branch_last +guint +GType type + + +g_type_class_ref +gpointer +GType type + + +g_type_class_peek +gpointer +GType type + + +g_type_class_unref +void +gpointer g_class + + +g_type_class_peek_parent +gpointer +gpointer g_class + + +g_type_interface_peek +gpointer +gpointer instance_class,GType iface_type + + +g_type_children +GType * +GType type,guint *n_children + + +g_type_interfaces +GType * +GType type,guint *n_interfaces + + +g_type_set_qdata +void +GType type,GQuark quark,gpointer data + + +g_type_get_qdata +gpointer +GType type,GQuark quark + + +GBaseInitFunc +void +gpointer g_class + + +GBaseFinalizeFunc +void +gpointer g_class + + +GClassInitFunc +void +gpointer g_class, + gpointer class_data + + +GClassFinalizeFunc +void +gpointer g_class, + gpointer class_data + + +GInstanceInitFunc +void +GTypeInstance *instance, + gpointer g_class + + +GInterfaceInitFunc +void +gpointer g_iface, + gpointer iface_data + + +GInterfaceFinalizeFunc +void +gpointer g_iface, + gpointer iface_data + + +GTypePluginRef +void +GTypePlugin *plugin + + +GTypePluginUnRef +void +GTypePlugin *plugin + + +GTypePluginFillTypeInfo +void +GTypePlugin *plugin, + GType g_type, + GTypeInfo *info, + GTypeValueTable *value_table + + +GTypePluginFillInterfaceInfo +void +GTypePlugin *plugin, + GType interface_type, + GType instance_type, + GInterfaceInfo *info + + +GTypeClassCacheFunc +gboolean +gpointer cache_data, + GTypeClass *g_class + + +GTypePlugin +struct GTypePlugin +{ + GTypePluginVTable *vtable; +}; + + +GTypePluginVTable +struct GTypePluginVTable +{ + GTypePluginRef plugin_ref; + GTypePluginUnRef plugin_unref; + GTypePluginFillTypeInfo complete_type_info; + GTypePluginFillInterfaceInfo complete_interface_info; +}; + + +GTypeFlags +typedef enum /*< skip >*/ +{ + G_TYPE_FLAG_CLASSED = (1 << 0), + G_TYPE_FLAG_INSTANTIATABLE = (1 << 1), + G_TYPE_FLAG_DERIVABLE = (1 << 2), + G_TYPE_FLAG_DEEP_DERIVABLE = (1 << 3) +} GTypeFlags; + + +GTypeInfo +struct GTypeInfo +{ + /* interface types, classed types, instantiated types */ + guint16 class_size; + + GBaseInitFunc base_init; + GBaseFinalizeFunc base_finalize; + + /* classed types, instantiated types */ + GClassInitFunc class_init; + GClassFinalizeFunc class_finalize; + gconstpointer class_data; + + /* instantiated types */ + guint16 instance_size; + guint16 n_preallocs; + GInstanceInitFunc instance_init; + + /* value handling */ + const GTypeValueTable *value_table; +}; + + +GTypeFundamentalInfo +struct GTypeFundamentalInfo +{ + GTypeFlags type_flags; +}; + + +GInterfaceInfo +struct GInterfaceInfo +{ + GInterfaceInitFunc interface_init; + GInterfaceFinalizeFunc interface_finalize; + gpointer interface_data; +}; + + +GTypeValueTable +struct GTypeValueTable +{ + void (*value_init) (GValue *value); + void (*value_free) (GValue *value); + void (*value_copy) (const GValue *src_value, + GValue *dest_value); + /* varargs functionality (optional) */ + guint collect_type; + gchar* (*collect_value) (GValue *value, + guint nth_value, + GType *collect_type, + GTypeCValue *collect_value); + guint lcopy_type; + gchar* (*lcopy_value) (const GValue *value, + guint nth_value, + GType *collect_type, + GTypeCValue *collect_value); +}; + + +g_type_register_static +GType +GType parent_type,const gchar *type_name,const GTypeInfo *info + + +g_type_register_dynamic +GType +GType parent_type,const gchar *type_name,GTypePlugin *plugin + + +g_type_register_fundamental +GType +GType type_id,const gchar *type_name,const GTypeInfo *info,const GTypeFundamentalInfo *finfo + + +g_type_add_interface_static +void +GType instance_type,GType interface_type,GInterfaceInfo *info + + +g_type_add_interface_dynamic +void +GType instance_type,GType interface_type,GTypePlugin *plugin + + +g_type_class_is_a +gboolean +GTypeClass *g_class,GType is_a_type + + +g_type_check_class_cast +GTypeClass * +GTypeClass *g_class,GType is_a_type + + +g_type_check_instance_cast +GTypeInstance * +GTypeInstance *instance,GType iface_type + + +g_type_instance_conforms_to +gboolean +GTypeInstance *instance,GType iface_type + + +g_type_check_flags +gboolean +GType type,GTypeFlags flags + + +g_type_create_instance +GTypeInstance * +GType type + + +g_type_free_instance +void +GTypeInstance *instance + + +g_type_value_table_peek +GTypeValueTable * +GType type + + +g_type_add_class_cache_func +void +gpointer cache_data,GTypeClassCacheFunc cache_func + + +g_type_remove_class_cache_func +void +gpointer cache_data,GTypeClassCacheFunc cache_func + + +g_type_class_unref_uncached +void +gpointer g_class + + +g_type_get_plugin +GTypePlugin * +GType type + + +g_type_fundamental_last +GType +void + + +G_TYPE_IS_VALUE +#define G_TYPE_IS_VALUE(type) (g_type_value_table_peek (type) != NULL) + + +G_IS_VALUE +#define G_IS_VALUE(value) (G_TYPE_IS_VALUE (G_VALUE_TYPE (value))) /* FIXME */ + + +G_VALUE_TYPE +#define G_VALUE_TYPE(value) (G_TYPE_FROM_CLASS (value)) + + +G_VALUE_TYPE_NAME +#define G_VALUE_TYPE_NAME(value) (g_type_name (G_VALUE_TYPE (value))) + + +GValueExchange +void +GValue *value1, + GValue *value2 + + +GValue +struct GValue +{ + /*< private >*/ + GType g_type; + + /* public for GTypeValueTable methods */ + union { + gint v_int; + guint v_uint; + glong v_long; + gulong v_ulong; + gfloat v_float; + gdouble v_double; + gpointer v_pointer; + } data[4]; +}; + + +g_value_init +void +GValue *value,GType g_type + + +g_value_copy +void +const GValue *src_value,GValue *dest_value + + +g_value_convert +gboolean +const GValue *src_value,GValue *dest_value + + +g_value_reset +void +GValue *value + + +g_value_unset +void +GValue *value + + +g_values_exchange +gboolean +GValue *value1,GValue *value2 + + +g_value_types_exchangable +gboolean +GType value_type1,GType value_type2 + + +g_value_register_exchange_func +void +GType value_type1,GType value_type2,GValueExchange func + + +GTypeCValue +union GTypeCValue +{ + gint v_int; + glong v_long; + gdouble v_double; + gpointer v_pointer; +}; + + +G_VALUE_COLLECT +#define G_VALUE_COLLECT(value, var_args, __error) \ +G_STMT_START { \ + GValue *_value = (value); \ + GTypeValueTable *_vtable = g_type_value_table_peek (G_VALUE_TYPE (_value)); \ + gchar *_error_msg = NULL; \ + guint _collect_type = _vtable->collect_type; \ + guint _nth_value = 0; \ + \ + g_value_reset (_value); \ + while (_collect_type && !_error_msg) \ + { \ + GTypeCValue _cvalue; \ + \ + memset (&_cvalue, 0, sizeof (_cvalue)); \ + switch (_collect_type) \ + { \ + case G_VALUE_COLLECT_INT: \ + _cvalue.v_int = va_arg ((var_args), gint); \ + break; \ + case G_VALUE_COLLECT_LONG: \ + _cvalue.v_long = va_arg ((var_args), glong); \ + break; \ + case G_VALUE_COLLECT_DOUBLE: \ + _cvalue.v_double = va_arg ((var_args), gdouble); \ + break; \ + case G_VALUE_COLLECT_POINTER: \ + _cvalue.v_pointer = va_arg ((var_args), gpointer); \ + break; \ + default: \ + _error_msg = g_strdup_printf ("%s: invalid collect type (%d) used for %s", \ + G_STRLOC, \ + _collect_type, \ + "G_VALUE_COLLECT()"); \ + continue; \ + } \ + _error_msg = _vtable->collect_value (_value, \ + _nth_value++, \ + &_collect_type, \ + &_cvalue); \ + } \ + *(__error) = _error_msg; \ +} G_STMT_END + + +G_VALUE_LCOPY +#define G_VALUE_LCOPY(value, var_args, __error) \ +G_STMT_START { \ + GValue *_value = (value); \ + GTypeValueTable *_vtable = g_type_value_table_peek (G_VALUE_TYPE (_value)); \ + gchar *_error_msg = NULL; \ + guint _lcopy_type = _vtable->lcopy_type; \ + guint _nth_value = 0; \ + \ + while (_lcopy_type && !_error_msg) \ + { \ + GTypeCValue _cvalue; \ + \ + memset (&_cvalue, 0, sizeof (_cvalue)); \ + switch (_lcopy_type) \ + { \ + case G_VALUE_COLLECT_INT: \ + _cvalue.v_int = va_arg ((var_args), gint); \ + break; \ + case G_VALUE_COLLECT_LONG: \ + _cvalue.v_long = va_arg ((var_args), glong); \ + break; \ + case G_VALUE_COLLECT_DOUBLE: \ + _cvalue.v_double = va_arg ((var_args), gdouble); \ + break; \ + case G_VALUE_COLLECT_POINTER: \ + _cvalue.v_pointer = va_arg ((var_args), gpointer); \ + break; \ + default: \ + _error_msg = g_strdup_printf ("%s: invalid collect type (%d) used for %s", \ + G_STRLOC, \ + _lcopy_type, \ + "G_VALUE_LCOPY()"); \ + continue; \ + } \ + _error_msg = _vtable->lcopy_value (_value, \ + _nth_value++, \ + &_lcopy_type, \ + &_cvalue); \ + } \ + *(__error) = _error_msg; \ +} G_STMT_END + + +G_IS_VALUE_CHAR +#define G_IS_VALUE_CHAR(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_CHAR)) + + +G_IS_VALUE_UCHAR +#define G_IS_VALUE_UCHAR(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_UCHAR)) + + +G_IS_VALUE_BOOLEAN +#define G_IS_VALUE_BOOLEAN(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_BOOLEAN)) + + +G_IS_VALUE_INT +#define G_IS_VALUE_INT(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_INT)) + + +G_IS_VALUE_UINT +#define G_IS_VALUE_UINT(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_UINT)) + + +G_IS_VALUE_LONG +#define G_IS_VALUE_LONG(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_LONG)) + + +G_IS_VALUE_ULONG +#define G_IS_VALUE_ULONG(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_ULONG)) + + +G_IS_VALUE_FLOAT +#define G_IS_VALUE_FLOAT(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_FLOAT)) + + +G_IS_VALUE_DOUBLE +#define G_IS_VALUE_DOUBLE(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_DOUBLE)) + + +G_IS_VALUE_STRING +#define G_IS_VALUE_STRING(value) (G_TYPE_CHECK_CLASS_TYPE ((value), G_TYPE_STRING)) + + +g_value_set_char +void +GValue *value,gint8 v_char + + +g_value_get_char +gint8 +GValue *value + + +g_value_set_uchar +void +GValue *value,guint8 v_uchar + + +g_value_get_uchar +guint8 +GValue *value + + +g_value_set_boolean +void +GValue *value,gboolean v_boolean + + +g_value_get_boolean +gboolean +GValue *value + + +g_value_set_int +void +GValue *value,gint v_int + + +g_value_get_int +gint +GValue *value + + +g_value_set_uint +void +GValue *value,guint v_uint + + +g_value_get_uint +guint +GValue *value + + +g_value_set_long +void +GValue *value,glong v_long + + +g_value_get_long +glong +GValue *value + + +g_value_set_ulong +void +GValue *value,gulong v_ulong + + +g_value_get_ulong +gulong +GValue *value + + +g_value_set_float +void +GValue *value,gfloat v_float + + +g_value_get_float +gfloat +GValue *value + + +g_value_set_double +void +GValue *value,gdouble v_double + + +g_value_get_double +gdouble +GValue *value + + +g_value_set_string +void +GValue *value,const gchar *v_string + + +g_value_get_string +gchar * +GValue *value + + +g_value_dup_string +gchar * +GValue *value + diff --git a/docs/reference/glib/glib-overrides.txt b/docs/reference/glib/glib-overrides.txt index 002bcfb92..e11bbb096 100644 --- a/docs/reference/glib/glib-overrides.txt +++ b/docs/reference/glib/glib-overrides.txt @@ -187,5 +187,19 @@ GPrivate *private_key, gpointer data #define G_STATIC_PRIVATE_INIT +# Definitions for different operating systems + +G_OS_UNIX +#define G_OS_UNIX + + +G_OS_WIN32 +#define G_OS_WIN32 + + + +G_OS_BEOS +#define G_OS_BEOS + diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index e48890e01..d810745c4 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -1,4 +1,3 @@ - glib.h
@@ -40,13 +39,11 @@ gdouble gsize gssize + +gstring + gldouble - -# I don't really know where to put these. -G_HAVE_WCHAR_H -G_HAVE_WCTYPE_H -GUTILS_C_VAR
@@ -54,14 +51,17 @@ GUTILS_C_VAR limits G_MININT G_MAXINT +G_MAXUINT G_MINSHORT G_MAXSHORT +G_MAXUSHORT G_MINLONG G_MAXLONG +G_MAXULONG G_MINFLOAT @@ -79,6 +79,11 @@ GLIB_MAJOR_VERSION GLIB_MINOR_VERSION GLIB_MICRO_VERSION + +G_OS_WIN32 +G_OS_BEOS +G_OS_UNIX + GLIB_CHECK_VERSION @@ -216,6 +221,26 @@ GUINT64_SWAP_LE_BE_CONSTANT GUINT64_SWAP_LE_BE_X86
+
+Numerical Definitions +numerical +G_IEEE754_FLOAT_BIAS +G_IEEE754_DOUBLE_BIAS +GFloatIEEE754 +GDoubleIEEE754 + + + +G_E +G_LN2 +G_LN10 +G_PI +G_PI_2 +G_PI_4 +G_SQRT2 +G_LOG_2_BASE_10 +
+
Miscellaneous Macros macros_misc @@ -225,9 +250,15 @@ G_INLINE_FUNC G_STMT_START G_STMT_END + +G_N_ELEMENTS + G_VA_COPY + +G_STRINGIFY + G_GNUC_EXTENSION G_GNUC_CONST @@ -240,9 +271,25 @@ G_GNUC_FUNCTION G_GNUC_PRETTY_FUNCTION -g_string +G_STRLOC + + +G_GSHORT_FORMAT +G_GUSHORT_FORMAT +G_GINT_FORMAT +G_GUINT_FORMAT +G_GLONG_FORMAT +G_GULONG_FORMAT +G_GINT16_FORMAT +G_GUINT16_FORMAT +G_GINT32_FORMAT +G_GUINT32_FORMAT +G_GINT64_FORMAT +G_GUINT64_FORMAT +GLIB_VAR +G_STRINGIFY_ARG G_HAVE_INLINE G_CAN_INLINE inline @@ -250,6 +297,20 @@ G_HAVE___INLINE G_HAVE___INLINE__
+
+Error Reporting +error_reporting +GError +g_error_new +g_error_new_literal +g_error_free +g_error_copy +g_error_matches +g_set_error +g_propagate_error +g_clear_error +
+
The Main Event Loop main @@ -286,6 +347,7 @@ g_main_remove_poll g_main_set_poll_func +g_main_win32_get_poll_func GPollFunc @@ -317,11 +379,26 @@ G_THREADS_IMPL_POSIX G_THREADS_IMPL_SOLARIS G_THREADS_IMPL_NONE + +G_THREAD_ERROR +GThreadError + GThreadFunctions g_thread_init g_thread_supported + +GThreadFunc +GThreadPriority +GThread +g_thread_create +g_thread_self +g_thread_join +g_thread_set_priority +g_thread_yield +g_thread_exit + GMutex g_mutex_new @@ -346,6 +423,26 @@ G_LOCK G_TRYLOCK G_UNLOCK + +GStaticRecMutex +G_STATIC_REC_MUTEX_INIT +g_static_rec_mutex_lock +g_static_rec_mutex_trylock +g_static_rec_mutex_unlock +g_static_rec_mutex_lock_full +g_static_rec_mutex_unlock_full + + +GStaticRWLock +G_STATIC_RW_LOCK_INIT +g_static_rw_lock_reader_lock +g_static_rw_lock_reader_trylock +g_static_rw_lock_reader_unlock +g_static_rw_lock_writer_lock +g_static_rw_lock_writer_trylock +g_static_rw_lock_writer_unlock +g_static_rw_lock_free + GCond g_cond_new @@ -365,7 +462,9 @@ g_private_set GStaticPrivate G_STATIC_PRIVATE_INIT g_static_private_get +g_static_private_get_for_thread g_static_private_set +g_static_private_set_for_thread G_THREAD_CF @@ -373,6 +472,48 @@ G_THREAD_UF g_static_mutex_get_mutex_impl G_LOCK_NAME glib_dummy_decl +GSystemThread +g_thread_error_quark +
+ +
+Thread Pools +thread_pools +GThreadPool +g_thread_pool_new +g_thread_pool_push +g_thread_pool_set_max_threads +g_thread_pool_get_max_threads +g_thread_pool_get_num_threads +g_thread_pool_unprocessed +g_thread_pool_free +g_thread_pool_set_max_unused_threads +g_thread_pool_get_max_unused_threads +g_thread_pool_get_num_unused_threads +g_thread_pool_stop_unused_threads +
+ +
+Asynchronous Queues +async_queues +GAsyncQueue +g_async_queue_new +g_async_queue_lock +g_async_queue_unlock +g_async_queue_ref +g_async_queue_ref_unlocked +g_async_queue_unref +g_async_queue_unref_and_unlock +g_async_queue_push +g_async_queue_push_unlocked +g_async_queue_pop +g_async_queue_pop_unlocked +g_async_queue_try_pop +g_async_queue_try_pop_unlocked +g_async_queue_timed_pop +g_async_queue_timed_pop_unlocked +g_async_queue_length +g_async_queue_length_unlocked
@@ -409,14 +550,12 @@ GIOFunc GIOFuncs +g_io_channel_win32_new_fd g_io_channel_win32_new_messages -g_io_channel_win32_new_pipe -g_io_channel_win32_new_pipe_with_wakeups g_io_channel_win32_new_stream_socket - +g_io_channel_win32_poll +g_io_channel_win32_make_pollfd g_io_channel_win32_get_fd -g_io_channel_win32_pipe_readable -g_io_channel_win32_pipe_request_wakeups
@@ -458,6 +597,8 @@ g_set_printerr_handler g_return_if_fail g_return_val_if_fail +g_return_if_reached +g_return_val_if_reached g_assert @@ -487,6 +628,7 @@ g_log g_logv g_message g_warning +g_critical g_error @@ -523,6 +665,10 @@ g_strdup g_strndup g_strnfill + +g_strlcpy +g_strlcat + g_strdup_printf g_strdup_vprintf @@ -551,6 +697,8 @@ g_strstrip g_strdelimit G_STR_DELIMITERS g_strescape +g_strcompress +g_strcanon g_strsplit g_strfreev g_strconcat @@ -565,8 +713,10 @@ g_strsignal
Date and Time Functions date +G_MICROSEC GTimeVal g_get_current_time +g_usleep GDate @@ -715,6 +865,10 @@ g_basename g_dirname g_path_is_absolute g_path_skip_root +g_path_get_dirname +g_path_get_basename +g_filename_to_utf8 +g_filename_from_utf8 g_bit_nth_lsf @@ -791,6 +945,7 @@ GTokenValue GErrorType G_CSET_a_2_z G_CSET_A_2_Z +G_CSET_DIGITS G_CSET_LATINC G_CSET_LATINS @@ -838,30 +993,22 @@ g_completion_free windows MAXPATHLEN NAME_MAX -getcwd -getpid pid_t -access -open -read -write -lseek -close pipe -popen -pclose -fdopen ftruncate opendir readdir rewinddir closedir +g_win32_error_message +g_win32_getlocale + -gwin_ftruncate -gwin_closedir -gwin_opendir -gwin_rewinddir +g_win32_ftruncate +g_win32_closedir +g_win32_opendir +g_win32_rewinddir
@@ -910,6 +1057,7 @@ g_list_insert g_list_insert_sorted g_list_remove g_list_remove_link +g_list_delete_link g_list_free @@ -954,9 +1102,11 @@ g_slist_alloc g_slist_append g_slist_prepend g_slist_insert +g_slist_insert_before g_slist_insert_sorted g_slist_remove g_slist_remove_link +g_slist_delete_link g_slist_free g_slist_free_1 @@ -985,6 +1135,37 @@ g_slist_push_allocator g_slist_pop_allocator
+
+Doubly-ended Queues +queue + +GQueue +g_queue_new +g_queue_free +g_queue_push_head +g_queue_push_tail +g_queue_pop_head +g_queue_pop_tail +g_queue_is_empty +g_queue_peek_head +g_queue_peek_tail +g_queue_push_head_link +g_queue_push_tail_link +g_queue_pop_head_link +g_queue_pop_tail_link +
+ +
+Trash Stacks +trash_stack +GTrashStack + +g_trash_stack_push +g_trash_stack_pop +g_trash_stack_peek +g_trash_stack_height +
+
Hash Tables hash_tables @@ -1026,10 +1207,13 @@ g_string_sprintf g_string_sprintfa g_string_append g_string_append_c +g_string_append_len g_string_prepend g_string_prepend_c +g_string_prepend_len g_string_insert g_string_insert_c +g_string_insert_len g_string_erase g_string_truncate g_string_free @@ -1038,6 +1222,10 @@ g_string_free g_string_up g_string_down + +g_string_hash +g_string_equal +
@@ -1056,6 +1244,7 @@ g_string_chunk_free arrays GArray g_array_new +g_array_sized_new g_array_append_val g_array_append_vals g_array_prepend_val @@ -1074,6 +1263,7 @@ g_array_free arrays_pointer GPtrArray g_ptr_array_new +g_ptr_array_sized_new g_ptr_array_add g_ptr_array_remove g_ptr_array_remove_index @@ -1090,6 +1280,7 @@ g_ptr_array_free arrays_byte GByteArray g_byte_array_new +g_byte_array_sized_new g_byte_array_append g_byte_array_prepend g_byte_array_remove_index @@ -1109,7 +1300,6 @@ g_tree_nnodes g_tree_height g_tree_lookup g_tree_search -GSearchFunc g_tree_traverse GTraverseFunc GTraverseType @@ -1122,6 +1312,7 @@ g_tree_destroy trees-nary GNode g_node_new +g_node_copy g_node_insert @@ -1290,3 +1481,400 @@ G_ALLOCATOR_LIST G_ALLOCATOR_NODE G_ALLOCATOR_SLIST
+ +
+Random Numbers +random_numbers +GRand +g_rand_new_with_seed +g_rand_new +g_rand_free +g_rand_set_seed +g_rand_int +g_rand_int_range +g_rand_double +g_rand_double_range +g_random_set_seed +g_random_int +g_random_int_range +g_random_double +g_random_double_range +
+ +
+Unicode Manipulation +unicode + +
+gunicode +gunichar +gunichar2 + + +g_get_charset + + +g_unichar_isalnum +g_unichar_isalpha +g_unichar_iscntrl +g_unichar_isdigit +g_unichar_isgraph +g_unichar_islower +g_unichar_isprint +g_unichar_ispunct +g_unichar_isspace +g_unichar_isupper +g_unichar_isxdigit +g_unichar_istitle +g_unichar_isdefined +g_unichar_iswide +g_unichar_toupper +g_unichar_tolower +g_unichar_totitle +g_unichar_digit_value +g_unichar_xdigit_value +GUnicodeType +g_unichar_type +g_unicode_canonical_ordering +g_unicode_canonical_decomposition + + +g_utf8_next_char +g_utf8_get_char +g_utf8_offset_to_pointer +g_utf8_pointer_to_offset +g_utf8_prev_char +g_utf8_find_next_char +g_utf8_find_prev_char +g_utf8_strlen +g_utf8_strncpy +g_utf8_strchr +g_utf8_strrchr + + +g_utf8_to_utf16 +g_utf8_to_ucs4 +g_utf16_to_ucs4 +g_utf16_to_utf8 +g_ucs4_to_utf16 +g_ucs4_to_utf8 +g_unichar_to_utf8 +
+ +
+Type Information +types +GType +G_TYPE_FUNDAMENTAL +G_TYPE_FUNDAMENTAL_MAX +G_TYPE_DERIVE_ID +G_TYPE_BRANCH_SEQNO +G_TYPE_FUNDAMENTAL_LAST +GTypeFundamentals +G_TYPE_IS_CLASSED +G_TYPE_IS_INSTANTIATABLE +G_TYPE_IS_DERIVABLE +G_TYPE_IS_DEEP_DERIVABLE +G_TYPE_IS_PARAM +G_TYPE_IS_INTERFACE +GTypePlugin +GTypePluginVTable +GTypeInterface +GTypeInstance +GTypeInfo +GTypeFundamentalInfo +GInterfaceInfo +GTypeValueTable +GType +G_TYPE_CHECK_INSTANCE_CAST +G_TYPE_CHECK_CLASS_CAST +G_TYPE_CHECK_INSTANCE_TYPE +G_TYPE_CHECK_CLASS_TYPE +G_TYPE_INSTANCE_GET_CLASS +G_TYPE_FROM_INSTANCE +G_TYPE_FROM_CLASS +G_TYPE_FROM_INTERFACE +g_type_init +g_type_name +g_type_qname +g_type_from_name +g_type_parent +g_type_next_base +g_type_is_a +g_type_conforms_to +g_type_fundamental_branch_last +g_type_class_ref +g_type_class_peek +g_type_class_unref +g_type_class_peek_parent +g_type_interface_peek +g_type_children +g_type_interfaces +g_type_set_qdata +g_type_get_qdata +GBaseInitFunc +GBaseFinalizeFunc +GClassInitFunc +GClassFinalizeFunc +GInstanceInitFunc +GInterfaceInitFunc +GInterfaceFinalizeFunc +GTypePluginRef +GTypePluginUnRef +GTypePluginFillTypeInfo +GTypePluginFillInterfaceInfo +GTypeClassCacheFunc +GTypeFlags +g_type_register_static +g_type_register_dynamic +g_type_register_fundamental +g_type_add_interface_static +g_type_add_interface_dynamic +g_type_class_is_a +g_type_check_class_cast +g_type_check_instance_cast +g_type_instance_conforms_to +g_type_check_flags +g_type_create_instance +g_type_free_instance +g_type_value_table_peek +g_type_add_class_cache_func +g_type_remove_class_cache_func +g_type_class_unref_uncached +g_type_get_plugin +g_type_fundamental_last + + +g_log_domain_gobject +
+ +
+The Base Object Type +objects +GObject +GObjectClass +G_OBJECT +G_OBJECT_GET_CLASS +G_OBJECT_TYPE +G_OBJECT_TYPE_NAME +G_OBJECT_CLASS_TYPE +G_OBJECT_CLASS_NAME +G_IS_VALUE_OBJECT +G_TYPE_IS_OBJECT +G_IS_OBJECT +G_OBJECT_CLASS +G_IS_OBJECT_CLASS +G_NOTIFY_PRIORITY +GObjectGetParamFunc +GObjectSetParamFunc +GObjectFinalizeFunc +g_object_class_install_param +g_object_class_find_param_spec +g_object_new +g_object_new_valist +g_object_set +g_object_get +g_object_set_valist +g_object_get_valist +g_object_set_param +g_object_get_param +g_object_queue_param_changed +g_object_ref +g_object_unref +g_object_get_qdata +g_object_set_qdata +g_object_set_qdata_full +g_object_steal_qdata +g_value_set_object +g_value_get_object +g_value_dup_object +G_WARN_INVALID_PARAM_ID +
+ +
+Enumeration and Flag Types +enumerations_flags +GEnumClass +GFlagsClass +G_ENUM_CLASS_TYPE +G_ENUM_CLASS_TYPE_NAME +G_TYPE_IS_ENUM +G_ENUM_CLASS +G_IS_ENUM_CLASS +G_TYPE_IS_FLAGS +G_FLAGS_CLASS +G_IS_FLAGS_CLASS +G_FLAGS_CLASS_TYPE +G_FLAGS_CLASS_TYPE_NAME +G_IS_VALUE_ENUM +G_IS_VALUE_FLAGS +GEnumValue +GFlagsValue +g_enum_get_value +g_enum_get_value_by_name +g_enum_get_value_by_nick +g_flags_get_first_value +g_flags_get_value_by_name +g_flags_get_value_by_nick +g_value_set_enum +g_value_get_enum +g_value_set_flags +g_value_get_flags +g_enum_register_static +g_flags_register_static +g_enum_complete_type_info +g_flags_complete_type_info +
+ +
+Generic values +generic_values +G_VALUE_TYPE +G_VALUE_TYPE_NAME +G_TYPE_IS_VALUE +G_IS_VALUE +GValueExchange +GValue +g_value_init +g_value_copy +g_value_convert +g_value_reset +g_value_unset +g_values_exchange +g_value_types_exchangable +g_value_register_exchange_func +
+ +
+Standard value types +value_types +G_IS_VALUE_CHAR +G_IS_VALUE_UCHAR +G_IS_VALUE_BOOLEAN +G_IS_VALUE_INT +G_IS_VALUE_UINT +G_IS_VALUE_LONG +G_IS_VALUE_ULONG +G_IS_VALUE_FLOAT +G_IS_VALUE_DOUBLE +G_IS_VALUE_STRING +g_value_set_char +g_value_get_char +g_value_set_uchar +g_value_get_uchar +g_value_set_boolean +g_value_get_boolean +g_value_set_int +g_value_get_int +g_value_set_uint +g_value_get_uint +g_value_set_long +g_value_get_long +g_value_set_ulong +g_value_get_ulong +g_value_set_float +g_value_get_float +g_value_set_double +g_value_get_double +g_value_set_string +g_value_get_string +g_value_dup_string +
+ +
+Object Parameter Specifications +param_specs +GParamSpec +GParamSpecClass +G_PARAM_SPEC_TYPE +G_PARAM_SPEC_TYPE_NAME +G_PARAM_SPEC +G_IS_PARAM_SPEC +G_PARAM_SPEC_GET_CLASS +G_IS_PARAM_VALUE +G_PARAM_SPEC_VALUE_TYPE +G_TYPE_IS_PARAM +GParamFlags +g_param_spec_ref +g_param_spec_unref +g_param_spec_get_qdata +g_param_spec_set_qdata +g_param_spec_set_qdata_full +g_param_spec_steal_qdata +g_param_value_set_default +g_param_value_defaults +g_param_value_validate +g_param_values_cmp +g_param_spec_internal +g_param_spec_hash_table_new +g_param_spec_hash_table_insert +g_param_spec_hash_table_remove +g_param_spec_hash_table_lookup +
+ +
+Standard Parameter Types +standard_params +G_IS_PARAM_SPEC_CHAR +G_PARAM_SPEC_CHAR +G_IS_PARAM_SPEC_UCHAR +G_PARAM_SPEC_UCHAR +G_IS_PARAM_SPEC_BOOLEAN +G_PARAM_SPEC_BOOLEAN +G_IS_PARAM_SPEC_INT +G_PARAM_SPEC_INT +G_IS_PARAM_SPEC_UINT +G_PARAM_SPEC_UINT +G_IS_PARAM_SPEC_LONG +G_PARAM_SPEC_LONG +G_IS_PARAM_SPEC_ULONG +G_PARAM_SPEC_ULONG +G_IS_PARAM_SPEC_ENUM +G_PARAM_SPEC_ENUM +G_IS_PARAM_SPEC_FLAGS +G_PARAM_SPEC_FLAGS +G_IS_PARAM_SPEC_FLOAT +G_PARAM_SPEC_FLOAT +G_IS_PARAM_SPEC_DOUBLE +G_PARAM_SPEC_DOUBLE +G_IS_PARAM_SPEC_STRING +G_PARAM_SPEC_STRING +G_IS_PARAM_SPEC_OBJECT +G_PARAM_SPEC_OBJECT +GParamSpecChar +GParamSpecUChar +GParamSpecBoolean +GParamSpecInt +GParamSpecUInt +GParamSpecLong +GParamSpecULong +GParamSpecEnum +GParamSpecFlags +GParamSpecFloat +GParamSpecDouble +GParamSpecString +GParamSpecObject +g_param_spec_char +g_param_spec_uchar +g_param_spec_boolean +g_param_spec_int +g_param_spec_uint +g_param_spec_long +g_param_spec_ulong +g_param_spec_enum +g_param_spec_flags +g_param_spec_float +g_param_spec_double +g_param_spec_string +g_param_spec_string_c +g_param_spec_object +
+ +
+Varargs Value Collection +value_collection +GTypeCValue +G_VALUE_COLLECT +G_VALUE_LCOPY +
+ diff --git a/docs/reference/glib/glib/ChangeLog b/docs/reference/glib/glib/ChangeLog index 6f682b1ba..caf9f48bc 100644 --- a/docs/reference/glib/glib/ChangeLog +++ b/docs/reference/glib/glib/ChangeLog @@ -1,3 +1,8 @@ +Tue Sep 5 20:03:25 2000 Owen Taylor + + * Moved into glib source tree, updated glib-sections.txt + and Makefile.am for glib-1.3.x. + 2000-07-01 Damon Chaplin * tmpl/string_utils.sgml: updated g_strndup. diff --git a/docs/reference/glib/glib/Makefile.am b/docs/reference/glib/glib/Makefile.am index 0c4da6277..4fea547e1 100644 --- a/docs/reference/glib/glib/Makefile.am +++ b/docs/reference/glib/glib/Makefile.am @@ -6,42 +6,111 @@ DOC_MODULE=glib # The top-level SGML file. DOC_MAIN_SGML_FILE=glib-docs.sgml +# The directory containing the source code (if it contains documentation). +DOC_SOURCE_DIR=$(top_srcdir) TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) -scan: - gtkdoc-scan --module=$(DOC_MODULE) `glib-config --prefix`/include/glib.h `glib-config --prefix`/include/gmodule.h `glib-config --prefix`/lib/glib/include/glibconfig.h +tmpl_sources = \ + tmpl/allocators.sgml \ + tmpl/arrays.sgml \ + tmpl/arrays_byte.sgml \ + tmpl/arrays_pointer.sgml \ + tmpl/byte_order.sgml \ + tmpl/caches.sgml \ + tmpl/completion.sgml \ + tmpl/datalist.sgml \ + tmpl/datasets.sgml \ + tmpl/date.sgml \ + tmpl/glib-unused.sgml \ + tmpl/hash_tables.sgml \ + tmpl/hooks.sgml \ + tmpl/iochannels.sgml \ + tmpl/limits.sgml \ + tmpl/linked_lists_double.sgml \ + tmpl/linked_lists_single.sgml \ + tmpl/macros.sgml \ + tmpl/macros_misc.sgml \ + tmpl/main.sgml \ + tmpl/memory.sgml \ + tmpl/memory_chunks.sgml \ + tmpl/messages.sgml \ + tmpl/misc_utils.sgml \ + tmpl/modules.sgml \ + tmpl/quarks.sgml \ + tmpl/relations.sgml \ + tmpl/scanner.sgml \ + tmpl/string_chunks.sgml \ + tmpl/string_utils.sgml \ + tmpl/strings.sgml \ + tmpl/threads.sgml \ + tmpl/timers.sgml \ + tmpl/trees-binary.sgml \ + tmpl/trees-nary.sgml \ + tmpl/type_conversion.sgml \ + tmpl/types.sgml \ + tmpl/warnings.sgml \ + tmpl/windows.sgml -templates: scan - gtkdoc-mktmpl --module=$(DOC_MODULE) - -sgml: - gtkdoc-mkdb --module=$(DOC_MODULE) - -html: - if ! test -d html ; then mkdir html ; fi - -cd html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) - -clean-local: - rm -f *~ *.bak *.hierarchy *.signals *.args *-unused.txt - -maintainer-clean-local: clean - rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt - -install-data-local: - install -d -m 0755 $(TARGET_DIR) - install -m 0644 html/*.html $(TARGET_DIR) - install -m 0644 html/index.sgml $(TARGET_DIR) - gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(HTML_DIR) - -EXTRA_DIST = \ - $(DOC_MAIN_SGML_FILE) \ - $(DOC_MODULE)-sections.txt \ - glib-decl.txt \ +glib_docdir = $(HTML_DIR) +glib_doc_DATA = \ + glib-decl.txt \ + glib-sections.txt \ glib-overrides.txt +EXTRA_DIST = \ + $(glib_doc_DATA) + +html/book1.html: sgml/glib-doc.bottom + $(MAKE) html + +sgml/glib-doc.bottom: $(tmpl_sources) + $(MAKE) sgml + +scan: + -(cd $(srcdir) \ + && gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="config.h gmoduleconf.h gunidecomp.h gunichartables.h glibconfig-sysdefs.h" ) + +templates: scan + cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) + +sgml: + cd $(srcdir) \ + && gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) + +html: + test -d $(srcdir)/html || mkdir $(srcdir)/html + -cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + +clean-local: + rm -f *~ *.bak *.signals *-unused.txt + +maintainer-clean-local: clean + cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt + +install-data-local: + $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR) + (installfiles=`echo $(srcdir)/html/*.html`; \ + if test "$$installfiles" = '$(srcdir)/html/*.html'; \ + then echo '-- Nothing to install' ; \ + else \ + for i in $$installfiles; do \ + echo '-- Installing '$$i ; \ + $(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \ + done; \ + echo '-- Installing $(srcdir)/html/index.sgml' ; \ + $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR); \ + echo '-- Fixing Crossreferences' ; \ + gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(HTML_DIR)|| true; \ + fi) + dist-hook: + mkdir $(distdir)/html + mkdir $(distdir)/sgml mkdir $(distdir)/tmpl - cp -p tmpl/*.sgml $(distdir)/tmpl + -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html + -cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl + -cp $(srcdir)/sgml/*.sgml $(distdir)/sgml + -cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml .PHONY : html sgml templates scan diff --git a/docs/reference/glib/tmpl/allocators.sgml b/docs/reference/glib/tmpl/allocators.sgml index 6b12fd27c..cf354ddc2 100644 --- a/docs/reference/glib/tmpl/allocators.sgml +++ b/docs/reference/glib/tmpl/allocators.sgml @@ -2,64 +2,41 @@ Memory Allocators -allocates chunks of memory for #GList, #GSList and #GNode. + -The #GAllocator is used as an efficient way to allocate small pieces of -memory for use with the #GList, #GSList and #GNode data structures. -It uses a #GMemChunk so elements are allocated in groups, rather than -individually. - - -The #GList, #GSList and #GNode implementations create default #GAllocator -objects, which are probably sufficient for most purposes. These default -allocators use blocks of 128 elements. - - -To use your own #GAllocator, create it with g_allocator_new(). Then -use g_list_push_allocator(), g_slist_push_allocator() or -g_node_push_allocator() before any code which allocates new #GList, #GSList -or #GNode elements respectively. After allocating the new elements, you must -use g_list_pop_allocator(), g_slist_pop_allocator() or g_node_pop_allocator() -to restore the previous allocators. - - -Note that you cannot use the same allocator for #GList, #GSList and #GNode -elements. Each must use separate allocators. + + + -The #GAllocator struct contains private data. and should only be accessed -using the following functions. + -Creates a new #GAllocator. + -@name: the name of the #GAllocator. This name is used to set the name of the -#GMemChunk used by the #GAllocator, and is only used for debugging. -@n_preallocs: the number of elements in each block of memory allocated. -Larger blocks mean less calls to g_malloc(), but some memory may be wasted. -(GLib uses 128 elements per block by default.) The value must be between 1 -and 65535. -@Returns: a new #GAllocator. +@name: +@n_preallocs: +@Returns: -Frees all of the memory allocated by the #GAllocator. + -@allocator: a #GAllocator. +@allocator: diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml index d985d4e3b..f40e49ed1 100644 --- a/docs/reference/glib/tmpl/arrays.sgml +++ b/docs/reference/glib/tmpl/arrays.sgml @@ -2,242 +2,160 @@ Arrays -arrays of arbitrary elements which grow automatically as elements are added. + -Arrays are similar to standard C arrays, except that they grow automatically -as elements are added. - - -Array elements can be of any size (though all elements of one array are the -same size), and the array can be automatically cleared to '0's and -zero-terminated. - - -To create a new array use g_array_new(). - - -To add elements to an array, use g_array_append_val(), g_array_append_vals(), -g_array_prepend_val(), and g_array_prepend_vals(). - - -To access an element of an array, use g_array_index(). - - -To set the size of an array, use g_array_set_size(). - - -To free an array, use g_array_free(). - - -Using a GArray to store gint values. - - GArray *garray; - gint i; - /* We create a new array to store gint values. - We don't want it zero-terminated or cleared to 0's. */ - garray = g_array_new (FALSE, FALSE, sizeof (gint)); - for (i = 0; i < 10000; i++) - g_array_append_val (garray, i); + - for (i = 0; i < 10000; i++) - if (g_array_index (garray, gint, i) != i) - g_print ("ERROR: got %d instead of %d\n", - g_array_index (garray, gint, i), i); - - g_array_free (garray, TRUE); - + -Contains the public fields of an Array. + -@data: a pointer to the element data. The data may be moved as elements are -added to the #GArray. -@len: the number of elements in the #GArray. +@data: +@len: -Creates a new #GArray. + -@zero_terminated: TRUE if the array should have an extra element at the end -which is set to '0'. -@clear: TRUE if #GArray elements should be automatically cleared to '0' -when they are allocated. -@element_size: the size of each element in bytes. -@Returns: the new #GArray. +@zero_terminated: +@clear: +@element_size: +@Returns: + + + + + + + +@zero_terminated: +@clear: +@element_size: +@reserved_size: +@Returns: -Adds the value on to the end of the array. -The array will grow in size automatically if necessary. - - - -g_array_append_val() is a macro which uses a reference to the value -parameter @v. This means that you cannot use it with literal values -such as "27". You must use variables. - - -@a: a #GArray. -@v: the value to append to the #GArray. -@Returns: the #GArray. + + +@a: +@v: -Adds @len elements onto the end of the array. + -@array: a #GArray. -@data: a pointer to the elements to append to the end of the array. -@len: the number of elements to append. -@Returns: the #GArray. +@array: +@data: +@len: +@Returns: -Adds the value on to the start of the array. -The array will grow in size automatically if necessary. - - -This operation is slower than g_array_append_val() since the existing elements -in the array have to be moved to make space for the new element. - - - -g_array_prepend_val() is a macro which uses a reference to the value -parameter @v. This means that you cannot use it with literal values -such as "27". You must use variables. - - -@a: a #GArray. -@v: the value to prepend to the #GArray. -@Returns: the #GArray. + + +@a: +@v: -Adds @len elements onto the start of the array. - - -This operation is slower than g_array_append_vals() since the existing elements -in the array have to be moved to make space for the new elements. + -@array: a #GArray. -@data: a pointer to the elements to prepend to the start of the array. -@len: the number of elements to prepend. -@Returns: the #GArray. +@array: +@data: +@len: +@Returns: -Inserts an element into an array at the given index. - - - -g_array_insert_val() is a macro which uses a reference to the value -parameter @v. This means that you cannot use it with literal values -such as "27". You must use variables. - - -@a: a #GArray. -@i: the index to place the element at. -@v: the value to insert into the array. -@Returns: the #GArray. + + +@a: +@i: +@v: -Inserts @len elements into a #GArray at the given index. + -@array: a #GArray. -@index: the index to place the elements at. -@data: a pointer to the elements to insert. -@len: the number of elements to insert. -@Returns: the #GArray. +@array: +@index: +@data: +@len: +@Returns: -Removes the element at the given index from a #GArray. -The following elements are moved down one place. + -@array: a #GArray. -@index: the index of the element to remove. -@Returns: the #GArray. +@array: +@index: +@Returns: -Removes the element at the given index from a #GArray. -The last element in the array is used to fill in the space, so this function -does not preserve the order of the #GArray. But it is faster than -g_array_remove_index(). + -@array: a @GArray. -@index: the index of the element to remove. -@Returns: the #GArray. +@array: +@index: +@Returns: -Returns the element of a #GArray at the given index. -The return value is cast to the given type. - -Getting a pointer to an element in a GArray. - - EDayViewEvent *event; - - /* This gets a pointer to the 3rd element in the array of EDayViewEvent - structs. */ - event = &g_array_index (events, EDayViewEvent, 3); - - -@a: a #GArray. -@t: the type of the elements. -@i: the index of the element to return. -@Returns: the element of the #GArray at the index given by @i. +@a: +@t: +@i: -Sets the size of the array, expanding it if necessary. -If the array was created with clear set to TRUE, the new elements are set to 0. + -@array: a #GArray. -@length: the new size of the #GArray. -@Returns: the #GArray. +@array: +@length: +@Returns: -Frees the memory allocated for the #GArray. -If free_segment is TRUE it frees the actual element data as well. + -@array: a #GArray. -@free_segment: if TRUE the actual element data is freed as well. +@array: +@free_segment: +@Returns: diff --git a/docs/reference/glib/tmpl/arrays_byte.sgml b/docs/reference/glib/tmpl/arrays_byte.sgml index 17c1a8d96..c5d5da2ff 100644 --- a/docs/reference/glib/tmpl/arrays_byte.sgml +++ b/docs/reference/glib/tmpl/arrays_byte.sgml @@ -2,135 +2,104 @@ Byte Arrays -arrays of bytes, which grow automatically as elements are added. + -GByteArray is based on #GArray, to provide arrays of bytes which grow -automatically as elements are added. - - -To create a new #GByteArray use g_byte_array_new(). - - -To add elements to a #GByteArray, use g_byte_array_append(), and -g_byte_array_prepend(). - - -To set the size of a GByteArray, use g_byte_array_set_size(). - - -To free a GByteArray, use g_byte_array_free(). + - -Using a GByteArray. - - GByteArray *gbarray; - gint i; - - gbarray = g_byte_array_new (); - for (i = 0; i < 10000; i++) - g_byte_array_append (gbarray, (guint8*) "abcd", 4); - - for (i = 0; i < 10000; i++) - { - g_assert (gbarray->data[4*i] == 'a'); - g_assert (gbarray->data[4*i+1] == 'b'); - g_assert (gbarray->data[4*i+2] == 'c'); - g_assert (gbarray->data[4*i+3] == 'd'); - } - - g_byte_array_free (gbarray, TRUE); - + -The #GByteArray struct allows access to the public fields of a #GByteArray. + -@data: a pointer to the element data. The data may be moved as elements are -added to the #GByteArray. -@len: the number of elements in the #GByteArray. +@data: +@len: -Creates a new #GByteArray. + -@Returns: the new #GByteArray. +@Returns: + + + + + + + +@reserved_size: +@Returns: -Adds the given bytes to the end of the #GByteArray. -The array will grow in size automatically if necessary. + -@array: a #GByteArray. -@data: the byte data to be added. -@len: the number of bytes to add. -@Returns: the #GByteArray. +@array: +@data: +@len: +@Returns: -Adds the given data to the start of the #GByteArray. -The array will grow in size automatically if necessary. + -@array: a #GByteArray. -@data: the byte data to be added. -@len: the number of bytes to add. -@Returns: the #GByteArray. +@array: +@data: +@len: +@Returns: -Removes the byte at the given index from a #GByteArray. -The following bytes are moved down one place. + -@array: a #GByteArray. -@index: the index of the byte to remove. -@Returns: the #GByteArray. +@array: +@index: +@Returns: -Removes the byte at the given index from a #GByteArray. -The last element in the array is used to fill in the space, so this function -does not preserve the order of the #GByteArray. But it is faster than -g_byte_array_remove_index(). + -@array: a #GByteArray. -@index: the index of the byte to remove. -@Returns: the #GByteArray. +@array: +@index: +@Returns: -Sets the size of the #GByteArray, expanding it if necessary. + -@array: a #GByteArray. -@length: the new size of the #GByteArray. -@Returns: the #GByteArray. +@array: +@length: +@Returns: -Frees the memory allocated by the #GByteArray. -If free_segment is TRUE it frees the actual byte data. + -@array: a #GByteArray. -@free_segment: if TRUE the actual byte data is freed as well. +@array: +@free_segment: +@Returns: diff --git a/docs/reference/glib/tmpl/arrays_pointer.sgml b/docs/reference/glib/tmpl/arrays_pointer.sgml index cc8595c80..21d7287d5 100644 --- a/docs/reference/glib/tmpl/arrays_pointer.sgml +++ b/docs/reference/glib/tmpl/arrays_pointer.sgml @@ -2,71 +2,23 @@ Pointer Arrays -arrays of pointers to any type of data, which grow automatically as new -elements are added. + -Pointer Arrays are similar to Arrays but are used only for storing pointers. - - - -If you remove elements from the array, elements at the end of the array -are moved into the space previously occupied by the removed element. -This means that you should not rely on the index of particular elements -remaining the same. You should also be careful when deleting elements while -iterating over the array. - - - -To create a pointer array, use g_ptr_array_new(). - - -To add elements to a pointer array, use g_ptr_array_add(). - - -To remove elements from a pointer array, use g_ptr_array_remove(), -g_ptr_array_remove_index() or g_ptr_array_remove_index_fast(). - - -To access an element of a pointer array, use g_ptr_array_index(). - - -To set the size of a pointer array, use g_ptr_array_set_size(). - - -To free a pointer array, use g_ptr_array_free(). - - -Using a GPtrArray. - - GPtrArray *gparray; - gchar *string1 = "one", *string2 = "two", *string3 = "three"; - gparray = g_ptr_array_new (); - g_ptr_array_add (gparray, (gpointer) string1); - g_ptr_array_add (gparray, (gpointer) string2); - g_ptr_array_add (gparray, (gpointer) string3); + - if (g_ptr_array_index (gparray, 0) != (gpointer) string1) - g_print ("ERROR: got %p instead of %p\n", - g_ptr_array_index (gparray, 0), string1); - - g_ptr_array_free (gparray, TRUE); - + -Contains the public fields of a pointer array. -The pdata field points to the array of pointers, -which may as when the array grows. -The len field is the number of pointers in the -array. + @pdata: @@ -74,105 +26,95 @@ array. -Creates a new #GPtrArray. + -@Returns: the new #GPtrArray. +@Returns: + + + + + + + +@reserved_size: +@Returns: -Adds a pointer to the end of the pointer array. -The array will grow in size automatically if necessary. + -@array: a #GPtrArray. -@data: the pointer to add. +@array: +@data: -Removes the first occurrence of the given pointer from the pointer array. -The following elements are moved down one place. - - -It returns TRUE if the pointer was removed, or FALSE if the pointer -was not found. + -@array: a #GPtrArray. -@data: the pointer to remove. -@Returns: TRUE if the pointer is removed. FALSE if the pointer is not found -in the array. +@array: +@data: +@Returns: -Removes the pointer at the given index from the pointer array. -The following elements are moved down one place. + -@array: a #GPtrArray. -@index: the index of the pointer to remove. -@Returns: the pointer which was removed. +@array: +@index: +@Returns: -Removes the first occurrence of the given pointer from the pointer array. -The last element in the array is used to fill in the space, so this function -does not preserve the order of the array. But it is faster than -g_ptr_array_remove(). - - -It returns TRUE if the pointer was removed, or FALSE if the pointer -was not found. + -@array: a #GPtrArray. -@data: the pointer to remove. -@Returns: TRUE if the pointer was found in the array. +@array: +@data: +@Returns: -Removes the pointer at the given index from the pointer array. -The last element in the array is used to fill in the space, so this function -does not preserve the order of the array. But it is faster than -g_ptr_array_remove_index(). + -@array: a #GPtrArray. -@index: the index of the pointer to remove. -@Returns: the pointer which was removed. +@array: +@index: +@Returns: -Sets the size of the array, expanding it if necessary. -New elements are set to NULL. + -@array: a #GPtrArray. -@length: the new length of the pointer array. +@array: +@length: -Returns the pointer at the given index of the pointer array. + -@array: a #GPtrArray. -@index: the index of the pointer to return. -@Returns: the pointer at the given index. +@array: +@index: -Frees all of the memory allocated for the pointer array. + -@array: a #GPtrArray. -@free_seg: if TRUE the actual element data is freed as well. +@array: +@free_seg: +@Returns: diff --git a/docs/reference/glib/tmpl/byte_order.sgml b/docs/reference/glib/tmpl/byte_order.sgml index 01e931c9a..87b455a7b 100644 --- a/docs/reference/glib/tmpl/byte_order.sgml +++ b/docs/reference/glib/tmpl/byte_order.sgml @@ -2,544 +2,453 @@ Byte Order Macros -a portable way to convert between different byte orders. + -These macros provide a portable way to determine the host byte order -and to convert values between different byte orders. - - -The byte order is the order in which bytes are stored to create larger -data types such as the #gint and #glong values. -The host byte order is the byte order used on the current machine. - - -Some processors store the most significant bytes (i.e. the bytes that -hold the largest part of the value) first. These are known as big-endian -processors. - - -Other processors (notably the x86 family) store the most significant byte -last. These are known as little-endian processors. - - -Finally, to complicate matters, some other processors store the bytes in -a rather curious order known as PDP-endian. For a 4-byte word, the 3rd -most significant byte is stored first, then the 4th, then the 1st and finally -the 2nd. - - -Obviously there is a problem when these different processors communicate -with each other, for example over networks or by using binary file formats. -This is where these macros come in. -They are typically used to convert values into a byte order -which has been agreed on for use when communicating between different -processors. The Internet uses what is known as 'network byte order' -as the standard byte order (which is in fact the big-endian byte order). + + + -The host byte order. -This can be either #G_LITTLE_ENDIAN or #G_BIG_ENDIAN (support for -#G_PDP_ENDIAN may be added in future.) + -Specifies one of the possible types of byte order. -See #G_BYTE_ORDER. + -Specifies one of the possible types of byte order. -See #G_BYTE_ORDER. + -Specifies one of the possible types of byte order (currently unused). -See #G_BYTE_ORDER. + -Converts a 32-bit integer value from host to network byte order. + -@val: a 32-bit integer value in host byte order. -@Returns: @val converted to network byte order. +@val: -Converts a 16-bit integer value from host to network byte order. + -@val: a 16-bit integer value in host byte order. -@Returns: @val converted to network byte order. +@val: -Converts a 32-bit integer value from network to host byte order. + -@val: a 32-bit integer value in network byte order. -@Returns: @val converted to host byte order. +@val: -Converts a 16-bit integer value from network to host byte order. + -@val: a 16-bit integer value in network byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #gint value from big-endian to host byte order. + -@val: a #gint value in big-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #gint value from little-endian to host byte order. + -@val: a #gint value in little-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #gint value from host byte order to big-endian. + -@val: a #gint value in host byte order. -@Returns: @val converted to big-endian byte order. +@val: -Converts a #gint value from host byte order to little-endian. + -@val: a #gint value in host byte order. -@Returns: @val converted to little-endian byte order. +@val: -Converts a #guint value from big-endian to host byte order. + -@val: a #guint value in big-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #guint value from little-endian to host byte order. + -@val: a #guint value in little-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #guint value from host byte order to big-endian. + -@val: a #guint value in host byte order. -@Returns: @val converted to big-endian byte order. +@val: -Converts a #guint value from host byte order to little-endian. + -@val: a #guint value in host byte order. -@Returns: @val converted to little-endian byte order. +@val: -Converts a #glong value from big-endian to the host byte order. + -@val: a #glong value in big-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #glong value from little-endian to host byte order. + -@val: a #glong value in little-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #glong value from host byte order to big-endian. + -@val: a #glong value in host byte order. -@Returns: @val converted to big-endian byte order. +@val: -Converts a #glong value from host byte order to little-endian. + -@val: a #glong value in host byte order. -@Returns: @val converted to little-endian. +@val: -Converts a #gulong value from big-endian to host byte order. + -@val: a #gulong value in big-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #gulong value from little-endian to host byte order. + -@val: a #gulong value in little-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #gulong value from host byte order to big-endian. + -@val: a #gulong value in host byte order. -@Returns: @val converted to big-endian. +@val: -Converts a #gulong value from host byte order to little-endian. + -@val: a #gulong value in host byte order. -@Returns: @val converted to little-endian. +@val: -Converts a #gint16 value from big-endian to host byte order. + -@val: a #gint16 value in big-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #gint16 value from little-endian to host byte order. + -@val: a #gint16 value in little-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #gint16 value from host byte order to big-endian. + -@val: a #gint16 value in host byte order. -@Returns: @val converted to big-endian. +@val: -Converts a #gint16 value from host byte order to little-endian. + -@val: a #gint16 value in host byte order. -@Returns: @val converted to little-endian. +@val: -Converts a #guint16 value from big-endian to host byte order. + -@val: a #guint16 value in big-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #guint16 value from little-endian to host byte order. + -@val: a #guint16 value in little-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #guint16 value from host byte order to big-endian. + -@val: a #guint16 value in host byte order. -@Returns: @val converted to big-endian. +@val: -Converts a #guint16 value from host byte order to little-endian. + -@val: a #guint16 value in host byte order. -@Returns: @val converted to little-endian. +@val: -Converts a #gint32 value from big-endian to host byte order. + -@val: a #gint32 value in big-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #gint32 value from little-endian to host byte order. + -@val: a #gint32 value in little-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #gint32 value from host byte order to big-endian. + -@val: a #gint32 value in host byte order. -@Returns: @val converted to big-endian. +@val: -Converts a #gint32 value from host byte order to little-endian. + -@val: a #gint32 value in host byte order. -@Returns: @val converted to little-endian. +@val: -Converts a #guint32 value from big-endian to host byte order. + -@val: a #guint32 value in big-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #guint32 value from little-endian to host byte order. + -@val: a #guint32 value in little-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #guint32 value from host byte order to big-endian. + -@val: a #guint32 value in host byte order. -@Returns: @val converted to big-endian. +@val: -Converts a #guint32 value from host byte order to little-endian. + -@val: a #guint32 value in host byte order. -@Returns: @val converted to little-endian. +@val: -Converts a #gint64 value from big-endian to host byte order. + -@val: a #gint64 value in big-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #gint64 value from little-endian to host byte order. + -@val: a #gint64 value in little-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #gint64 value from host byte order to big-endian. + -@val: a #gint64 value in host byte order. -@Returns: @val converted to big-endian. +@val: -Converts a #gint64 value from host byte order to little-endian. + -@val: a #gint64 value in host byte order. -@Returns: @val converted to little-endian. +@val: -Converts a #guint64 value from big-endian to host byte order. + -@val: a #guint64 value in big-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #guint64 value from little-endian to host byte order. + -@val: a #guint64 value in little-endian byte order. -@Returns: @val converted to host byte order. +@val: -Converts a #guint64 value from host byte order to big-endian. + -@val: a #guint64 value in host byte order. -@Returns: @val converted to big-endian. +@val: -Converts a #guint64 value from host byte order to little-endian. + -@val: a #guint64 value in host byte order. -@Returns: @val converted to little-endian. +@val: -Converts a #guint16 value between big-endian and pdp-endian byte order. -The conversion is symmetric so it can be used both ways. + -@val: a #guint16 value in big-endian or pdp-endian byte order. -@Returns: @val converted to the opposite byte order. +@val: -Converts a #guint16 value between little-endian and big-endian byte order. -The conversion is symmetric so it can be used both ways. + -@val: a #guint16 value in little-endian or big-endian byte order. -@Returns: @val converted to the opposite byte order. +@val: -Converts a #guint16 value between little-endian and pdp-endian byte order. -The conversion is symmetric so it can be used both ways. + -@val: a #guint16 value in little-endian or pdp-endian byte order. -@Returns: @val converted to the opposite byte order. +@val: -Converts a #guint32 value between big-endian and pdp-endian byte order. -The conversion is symmetric so it can be used both ways. + -@val: a #guint32 value in big-endian or pdp-endian byte order. -@Returns: @val converted to the opposite byte order. +@val: -Converts a #guint32 value between little-endian and big-endian byte order. -The conversion is symmetric so it can be used both ways. + -@val: a #guint32 value in little-endian or big-endian byte order. -@Returns: @val converted to the opposite byte order. +@val: -Converts a #guint32 value between little-endian and pdp-endian byte order. -The conversion is symmetric so it can be used both ways. + -@val: a #guint32 value in little-endian or pdp-endian byte order. -@Returns: @val converted to the opposite byte order. +@val: -Converts a #guint64 value between little-endian and big-endian byte order. -The conversion is symmetric so it can be used both ways. + -@val: a #guint64 value in little-endian or big-endian byte order. -@Returns: @val converted to the opposite byte order. +@val: diff --git a/docs/reference/glib/tmpl/caches.sgml b/docs/reference/glib/tmpl/caches.sgml index aad81b57a..1355726fb 100644 --- a/docs/reference/glib/tmpl/caches.sgml +++ b/docs/reference/glib/tmpl/caches.sgml @@ -2,96 +2,63 @@ Caches -allows sharing of complex data structures to save resources. + -A #GCache allows sharing of complex data structures, in order to save -system resources. - - -GTK uses a #GCache for both GtkStyles and GdkGCs. These consume a lot of -resouces, so a #GCache is used to see if a GtkStyle or GdkGC with the -required properties already exists. If it does, then the existing -GtkStyle or GdkGC is used instead of creating a new one. - - -#GCache uses keys and values. -A #GCache key describes the properties of a particular resource. -A #GCache value is the actual resource. + + + -The #GCache struct is an opaque data structure containing information about -a #GCache. It should only be accesssed via the following functions. + -Creates a new GCache. + -@value_new_func: a function to create a new object given a key. -This is called by g_cache_insert() if an object with the given key -does not already exist. -@value_destroy_func: a function to destroy an object. It is -called by g_cache_remove() when the object is no longer needed (i.e. its -reference count drops to 0). -@key_dup_func: a function to copy a key. It is called by -g_cache_insert() if the key does not already exist in the GCache. -@key_destroy_func: a function to destroy a key. It is -called by g_cache_remove() when the object is no longer needed (i.e. its -reference count drops to 0). -@hash_key_func: a function to create a hash value from a key. -@hash_value_func: a function to create a hash value from a value. -@key_compare_func: a function to compare two keys. It should return TRUE if -the two keys are equivalent. -@Returns: a new #GCache. +@value_new_func: +@value_destroy_func: +@key_dup_func: +@key_destroy_func: +@hash_key_func: +@hash_value_func: +@key_compare_func: +@Returns: -Gets the value corresponding to the given key, creating it if necessary. -It first checks if the value already exists in the #GCache, by using -the @key_compare_func function passed to g_cache_new(). -If it does already exist it is returned, and its reference count is increased -by one. -If the value does not currently exist, if is created by calling the -@value_new_func. The key is duplicated by calling -@key_dup_func and the duplicated key and value are inserted -into the #GCache. + -@cache: a #GCache. -@key: a key describing a #GCache object. -@Returns: a pointer to a #GCache value. +@cache: +@key: +@Returns: -Decreases the reference count of the given value. -If it drops to 0 then the value and its corresponding key are destroyed, -using the @value_destroy_func and @key_destroy_func passed to g_cache_new(). + -@cache: a #GCache. -@value: the value to remove. +@cache: +@value: -Frees the memory allocated for the GCache. - - -Note that it does not destroy the keys and values which were contained in the -GCache. + @cache: @@ -99,54 +66,47 @@ GCache. -Calls the given function for each of the keys in the #GCache. + -@cache: a #GCache. -@func: the function to call with each #GCache key. -@user_data: user data to pass to the function. +@cache: +@func: +@user_data: -Calls the given function for each of the values in the #GCache. + -@cache: a #GCache. -@func: the function to call with each #GCache value. -@user_data: user data to pass to the function. +@cache: +@func: +@user_data: -Specifies the type of the @value_destroy_func and @key_destroy_func functions -passed to g_cache_new(). -The functions are passed a pointer to the #GCache key or #GCache value and -should free any memory and other resources associated with it. + -@value: the #GCache value to destroy. +@value: -Specifies the type of the @key_dup_func function passed to g_cache_new(). -The function is passed a key (NOT a value as the prototype implies) and -should return a duplicate of the key. + -@value: the #GCache key to destroy (NOT a #GCache value as it seems). -@Returns: a copy of the #GCache key. +@value: +@Returns: -Specifies the type of the @value_new_func function passed to g_cache_new(). -It is passed a #GCache key and should create the value corresponding to the -key. + -@key: a #GCache key. -@Returns: a new #GCache value corresponding to the key. +@key: +@Returns: diff --git a/docs/reference/glib/tmpl/completion.sgml b/docs/reference/glib/tmpl/completion.sgml index 6bb768160..adba6c3cf 100644 --- a/docs/reference/glib/tmpl/completion.sgml +++ b/docs/reference/glib/tmpl/completion.sgml @@ -2,45 +2,23 @@ Automatic String Completion -support for automatic completion using a group of target strings. + -#GCompletion provides support for automatic completion of a string using -any group of target strings. It is typically used for file name completion -as is common in many Unix shells. - - -A #GCompletion is created using g_completion_new(). -Target items are added and removed with -g_completion_add_items(), g_completion_remove_items() and -g_completion_clear_items(). -A completion attempt is requested with g_completion_complete(). -When no longer needed, the #GCompletion is freed with g_completion_free(). - - -Items in the completion can be simple strings (e.g. file names), -or pointers to arbitrary data structures. If data structures are used -you must provide a #GCompletionFunc in g_completion_new(), -which retrieves the item's string from the data structure. + + + -The data structure used for automatic completion. -items is the list of target items (strings -or data structures). -func is the function called to get the string -associated with a target item. It is NULL if the target items are strings. -prefix is the last prefix passed to -g_completion_complete(). -cache is the list of items which begin with -prefix. + @items: @@ -50,72 +28,64 @@ g_completion_complete(). -Creates a new #GCompletion. + -@func: the function to be called to return the string representing an item -in the #GCompletion, or NULL if strings are going to be used as the -#GCompletion items. -@Returns: the new #GCompletion. +@func: +@Returns: -Specifies the type of the function passed to g_completion_new(). -It should return the string corresponding to the given target item. -This is used when you use data structures as #GCompletion items. + -@Param1: the completion item. -@Returns: the string corresponding to the item. +@Param1: +@Returns: -Adds items to the #GCompletion. + -@cmp: the #GCompletion. -@items: the list of items to add. +@cmp: +@items: -Removes items from a #GCompletion. + -@cmp: the #GCompletion. -@items: the items to remove. +@cmp: +@items: -Removes all items from the #GCompletion. + -@cmp: the #GCompletion. +@cmp: -Attempts to complete the string @prefix using the #GCompletion target items. + -@cmp: the #GCompletion. -@prefix: the prefix string, typically typed by the user, which is compared -with each of the items. -@new_prefix: if non-NULL, returns the longest prefix which is common to all -items that matched @prefix, or NULL if no items matched @prefix. -This string should be freed when no longer needed. -@Returns: the list of items whose strings begin with @prefix. This should -not be changed. +@cmp: +@prefix: +@new_prefix: +@Returns: -Frees all memory used by the #GCompletion. + -@cmp: the #GCompletion. +@cmp: diff --git a/docs/reference/glib/tmpl/datalist.sgml b/docs/reference/glib/tmpl/datalist.sgml index 99ac4ac2c..33df5a353 100644 --- a/docs/reference/glib/tmpl/datalist.sgml +++ b/docs/reference/glib/tmpl/datalist.sgml @@ -2,112 +2,72 @@ Keyed Data Lists -lists of data elements which are accessible by a string or #GQuark identifier. + -Keyed data lists provide lists of arbitrary data elements which can be accessed -either with a string or with a #GQuark corresponding to the string. - - -The GQuark methods are quicker, since the strings have to be converted to -GQuarks anyway. - - -Data lists are used in GTK for associating arbitrary data with -GtkObjects, using gtk_object_set_data() and related functions. + - -To create a datalist, use g_datalist_init(). - - -To add data elements to a datalist use g_datalist_id_set_data(), -g_datalist_id_set_data_full(), g_datalist_set_data() -and g_datalist_set_data_full(). - - -To get data elements from a datalist use g_datalist_id_get_data() and -g_datalist_get_data(). - - -To iterate over all data elements in a datalist use g_datalist_foreach(). - - -To remove data elements from a datalist use g_datalist_id_remove_data() and -g_datalist_remove_data(). - - -To remove all data elements from a datalist, use g_datalist_clear(). - + -The #GData struct is an opaque data structure to represent a -Keyed Data List. -It should only be accessed via the following functions. + -Resets the datalist to NULL. -It does not free any memory or call any destroy functions. + -@datalist: a pointer to a pointer to a datalist. +@datalist: -Sets the data corresponding to the given #GQuark id. -Any previous data with the same key is removed, and its -destroy function is called. + -@dl: a datalist. -@q: the #GQuark to identify the data element. -@d: the data element. +@dl: +@q: +@d: -Sets the data corresponding to the given #GQuark id, and the function to -be called when the element is removed from the datalist. -Any previous data with the same key is removed, and its -destroy function is called. + -@datalist: a datalist. -@key_id: the #GQuark to identify the data element. -@data: the data element. -@destroy_func: the function to call when the data element is removed. This -function will be called with the data element and can be used to free any -memory allocated for it. +@datalist: +@key_id: +@data: +@destroy_func: -Gets a data element. + -@datalist: a datalist. -@key_id: the #GQuark identifying a data element. -@Returns: the data element, or NULL if it is not found. +@datalist: +@key_id: +@Returns: -Removes an element, using its #GQuark identifier. + -@dl: a datalist. -@q: the #GQuark identifying the data element. +@dl: +@q: @@ -117,52 +77,46 @@ Removes an element, using its #GQuark identifier. @datalist: @key_id: +@Returns: -Sets the data element corresponding to the given string identifier. + -@dl: a datalist. -@k: the string to identify the data element. -@d: the data element. +@dl: +@k: +@d: -Sets the data element corresponding to the given string identifier, and the -function to be called when the data element is removed. + -@dl: a datalist. -@k: the string to identify the data element. -@d: the data element. -@f: the function to call when the data element is removed. This -function will be called with the data element and can be used to free any -memory allocated for it. +@dl: +@k: +@d: +@f: -Gets a data element, using its string identifer. -This is slower than g_datalist_id_get_data() because the string is first -converted to a #GQuark. + -@dl: a datalist. -@k: the string identifying a data element. -@Returns: the data element, or NULL if it is not found. +@dl: +@k: -Removes an element using its string identifier. -The data element's destroy function is called if it has been set. + -@dl: a datalist. -@k: the string identifying the data element. +@dl: +@k: @@ -176,22 +130,19 @@ The data element's destroy function is called if it has been set. -Calls the given function for each data element of the datalist. -The function is called with each data element's #GQuark id and data, -together with the given @user_data parameter. + -@datalist: a datalist. -@func: the function to call for each data element. -@user_data: user data to pass to the function. +@datalist: +@func: +@user_data: -Frees all the data elements of the datalist. -The data elements' destroy functions are called if they have been set. + -@datalist: a datalist. +@datalist: diff --git a/docs/reference/glib/tmpl/datasets.sgml b/docs/reference/glib/tmpl/datasets.sgml index b51803775..f935397b2 100644 --- a/docs/reference/glib/tmpl/datasets.sgml +++ b/docs/reference/glib/tmpl/datasets.sgml @@ -2,110 +2,66 @@ Datasets -associate groups of data elements with particular memory locations. + -Datasets associate groups of data elements with particular memory locations. -These are useful if you need to associate data with a structure returned -from an external library. Since you cannot modify the structure, you use -its location in memory as the key into a dataset, where you can associate -any number of data elements with it. - - -There are two forms of most of the dataset functions. -The first form uses strings to identify the data elements associated with -a location. The second form uses #GQuark identifiers, which are created -with a call to g_quark_from_string() or g_quark_from_static_string(). -The second form is quicker, since it does not require looking up the string -in the hash table of #GQuark identifiers. - - -There is no function to create a dataset. It is automatically created as -soon as you add elements to it. - - -To add data elements to a dataset use g_dataset_id_set_data(), -g_dataset_id_set_data_full(), g_dataset_set_data() -and g_dataset_set_data_full(). - - -To get data elements from a dataset use g_dataset_id_get_data() and -g_dataset_get_data(). - - -To iterate over all data elements in a dataset use g_dataset_foreach(). - - -To remove data elements from a dataset use g_dataset_id_remove_data() and -g_dataset_remove_data(). - - -To destroy a dataset, use g_dataset_destroy(). + + + -Sets the data element associated with the given #GQuark id. -Any previous data with the same key is removed, and its destroy function -is called. + -@l: the location identifying the dataset. -@k: the #GQuark id to identify the data element. -@d: the data element. +@l: +@k: +@d: -Sets the data element associated with the given #GQuark id, and also the -function to call when the data element is destroyed. -Any previous data with the same key is removed, and its -destroy function is called. + -@dataset_location: the location identifying the dataset. -@key_id: the #GQuark id to identify the data element. -@data: the data element. -@destroy_func: the function to call when the data element is removed. This -function will be called with the data element and can be used to free any -memory allocated for it. +@dataset_location: +@key_id: +@data: +@destroy_func: -Specifies the type of function which is called when a data element is -destroyed. It is passed the pointer to the data element and should free -any memory and resources allocated for it. + -@data: the data element. +@data: -Gets the data element corresponding to a #GQuark. + -@dataset_location: the location identifying the dataset. -@key_id: the #GQuark id to identify the data element. -@Returns: the data element corresponding to the #GQuark, or NULL if it is -not found. +@dataset_location: +@key_id: +@Returns: -Removes a data element from a dataset. -The data element's destroy function is called if it has been set. + -@l: the location identifying the dataset. -@k: the #GQuark id identifying the data element. +@l: +@k: @@ -115,51 +71,46 @@ The data element's destroy function is called if it has been set. @dataset_location: @key_id: +@Returns: -Sets the data corresponding to the given string identifier. + -@l: the location identifying the dataset. -@k: the string to identify the data element. -@d: the data element. +@l: +@k: +@d: -Sets the data corresponding to the given string identifier, and the function -to call when the data element is destroyed. + -@l: the location identifying the dataset. -@k: the string to identify the data element. -@d: the data element. -@f: the function to call when the data element is removed. This -function will be called with the data element and can be used to free any -memory allocated for it. +@l: +@k: +@d: +@f: -Gets the data element corresponding to a string. + -@l: the location identifying the dataset. -@k: the string identifying the data element. -@Returns: the data element corresponding to the string, or NULL if it is not -found. +@l: +@k: -Removes a data element corresponding to a string. -Its destroy function is called if it has been set. + -@l: the location identifying the dataset. -@k: the string identifying the data element. +@l: +@k: @@ -173,33 +124,29 @@ Its destroy function is called if it has been set. -Calls the given function for each data element which is associated with the -given location. + -@dataset_location: the location identifying the dataset. -@func: the function to call for each data element. -@user_data: user data to pass to the function. +@dataset_location: +@func: +@user_data: -Specifies the type of function passed to g_dataset_foreach(). -It is called with each #GQuark id and associated data element, -together with the @user_data parameter supplied to g_dataset_foreach(). + -@key_id: the #GQuark id to identifying the data element. -@data: the data element. -@user_data: user data passed to g_dataset_foreach(). +@key_id: +@data: +@user_data: -Destroys the dataset, freeing all memory allocated, and calling any -destroy functions set for data elements. + -@dataset_location: the location identifying the dataset. +@dataset_location: diff --git a/docs/reference/glib/tmpl/date.sgml b/docs/reference/glib/tmpl/date.sgml index cfced74dc..8ed97ce51 100644 --- a/docs/reference/glib/tmpl/date.sgml +++ b/docs/reference/glib/tmpl/date.sgml @@ -1,654 +1,529 @@ - -Date and Time Functions - - -calendrical calculations and miscellaneous time stuff. - - - -The #GDate data structure represents a day between January 1, Year 1, -and sometime a few thousand years in the future (right now it will go -to the year 65535 or so, but g_date_set_parse() only parses up to the -year 8000 or so - just count on "a few thousand"). #GDate is meant to -represent everyday dates, not astronomical dates or historical dates -or ISO timestamps or the like. It extrapolates the current Gregorian -calendar forward and backward in time; there is no attempt to change -the calendar to match time periods or locations. #GDate does not store -time information; it represents a day. - - - -The #GDate implementation has several nice features; it is only a -64-bit struct, so storing large numbers of dates is very efficient. It -can keep both a Julian and Day-Month-Year representation of the date, -since some calculations are much easier with one representation or the -other. A Julian representation is simply a count of days since some -fixed day in the past; for #GDate the fixed day is January 1, 1 AD. -("Julian" dates in the #GDate API aren't really Julian dates in the -technical sense; technically, Julian dates count from the start of the -Julian period, Jan 1, 4713 BC). - - - -#GDate is simple to use. First you need a "blank" date; you can get a -dynamically allocated date from g_date_new(), or you can declare an -automatic variable or array and initialize it to a sane state by -calling g_date_clear(). A cleared date is sane; it's safe to call -g_date_set_dmy() and the other mutator functions to initialize the -value of a cleared date. However, a cleared date is initially -invalid, meaning that it doesn't represent a day -that exists. It is undefined to call any of the date calculation -routines on an invalid date. If you obtain a date from a user or other -unpredictable source, you should check its validity with the -g_date_valid() predicate. g_date_valid() is also used to check for -errors with g_date_set_parse() and other functions that can -fail. Dates can be invalidated by calling g_date_clear() again. - - - -It is very important to use the API to access the #GDate -struct. Often only the DMY or only the Julian -representation is valid. Sometimes neither is valid. Use the API. - - - -glib doesn't contain any time-manipulation functions; however, there -is a #GTime typedef which is equivalent to time_t, and a #GTimeVal -struct which represents a more precise time (with microseconds). You -can request the current time as a #GTimeVal with g_get_current_time(). - - - - - - - - - -Represents a precise time, with seconds and microseconds. Same as the -struct timeval returned by the -gettimeofday() UNIX call. - - -@tv_sec: -@tv_usec: - - - -Equivalent to gettimeofday(), but also works on -Win32. Returns the current time. - - -@result: - - - - -Simply a replacement for time_t. Unrelated to GTimer. - - - - - -Represents a day between January 1, Year 1 and a few thousand years in -the future. None of its members should be accessed directly. If the -GDate is obtained from g_date_new(), it will -be safe to mutate but invalid and thus not safe for calendrical computations. -If it's declared on the stack, it will contain garbage so must be -initialized with g_date_clear(). g_date_clear() makes the date invalid -but sane. An invalid date doesn't represent a day, it's "empty." A -date becomes valid after you set it to a Julian day or you set a day, -month, and year. - - -@julian_days: -@julian: -@dmy: -@day: -@month: -@year: - - - -This enumeration isn't used in the API, but may be useful if you need -to mark a number as a day, month, or year. - - -@G_DATE_DAY: -@G_DATE_MONTH: -@G_DATE_YEAR: - - - -Integer representing a day of the month; between 1 and -31. #G_DATE_BAD_DAY represents an invalid day of the month. - - - - - -Enumeration representing a month; values are #G_DATE_JANUARY, -#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the "invalid" value. - - -@G_DATE_BAD_MONTH: -@G_DATE_JANUARY: -@G_DATE_FEBRUARY: -@G_DATE_MARCH: -@G_DATE_APRIL: -@G_DATE_MAY: -@G_DATE_JUNE: -@G_DATE_JULY: -@G_DATE_AUGUST: -@G_DATE_SEPTEMBER: -@G_DATE_OCTOBER: -@G_DATE_NOVEMBER: -@G_DATE_DECEMBER: - - - -Enumeration representing a day of the week; #G_DATE_MONDAY, -#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday. - - -@G_DATE_BAD_WEEKDAY: -@G_DATE_MONDAY: -@G_DATE_TUESDAY: -@G_DATE_WEDNESDAY: -@G_DATE_THURSDAY: -@G_DATE_FRIDAY: -@G_DATE_SATURDAY: -@G_DATE_SUNDAY: - - - -Integer representing a year; #G_DATE_BAD_YEAR is the invalid -value. The year must be 1 or higher; negative (BC) years are not -allowed. The year is represented with four digits. - - - - - -Represents an invalid #GDateDay. - - - - - - -Represents an invalid Julian day number. - - - - - - -Represents an invalid year. - - - - - - -Increment a date some number of days. To move forward by weeks, add -weeks*7 days. The date must be valid. - - -@date: The date to increment -@n_days: Number of days to move the date forward - - - - -Increment a date by some number of months. If the day of the month is -greater than 28, this routine may change the day of the month (because -the destination month may not have the current day in it). The date -must be valid. - - -@date: Date to increment -@n_months: Number of months to move forward - - - - -Increment a date by some number of years. If the date is February 29, -and the destination year is not a leap year, the date will be changed -to February 28. The date must be valid. - - -@date: Date to increment -@n_years: Number of years to move forward - - - - -Initialize one or more #GDate structs to a sane but invalid -state. The cleared dates will not represent an existing date, but will -not contain garbage. Useful to init a date declared on the stack. -Validity can be tested with g_date_valid(). - - -@date: Pointer to one or more dates to clear -@n_dates: Number of dates to clear - - - - -qsort()-style comparsion function for dates. Both -dates must be valid. - - -@lhs: First date to compare -@rhs: Second date to compare -@Returns: 0 for equal, less than zero if @lhs is less than @rhs, -greater than zero if @lhs is greater than @rhs - - - - -Return the day of the month; the #GDate must be valid. - - -@date: Date to extract the day of the month from -@Returns: Day of the month - - - - -Return the day of the year, where Jan 1 is the first day of the -year. Date must be valid. - - -@date: Date to extract day of year from -@Returns: Day of the year - - - - -Return the number of days in a month, taking leap years into account. - - -@month: Month -@year: Year -@Returns: Number of days in @month during the year @year. - - - - -Free a #GDate returned from g_date_new() - - -@date: Date to free - - - - -Returns TRUE if the date is on the first of a month. Date must be valid. - - -@date: Date to check -@Returns: Boolean, if the date is the first of the month - - - - -Returns TRUE if the date is the last day of the month. Date must be valid. - - -@date: Date to check -@Returns: Boolean, if the date is the last day of the month - - - - -Returns TRUE if the year is a leap year - - -@year: Year to check -@Returns: Boolean, if the year is a leap year - - - - -Accessor, returns the Julian day or "serial number" of the #GDate. The -Julian day is simply the number of days since January 1, Year 1; i.e., -January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, -etc. Date must be valid. - - -@date: Date to extract the Julian day from -@Returns: Julian day - - - - -Return the week of the year, where weeks are understood to start on -Monday. If the date is before the first Monday of the year, return -0. Date must be valid. - - -@date: Date to use -@Returns: Week of the year - - - - -Return the number of weeks in the year, where weeks are taken to start -on Monday. Will be 52 or 53. Date must be valid. (Years always have 52 -7-day periods, plus 1 or 2 extra days depending on whether it's a leap -year. This function is basically telling you how many Mondays are in -the year, i.e. there are 53 Mondays if one of the extra days happens -to be a Monday.) - - -@year: Year -@Returns: Number of Mondays in the year - - - - -Accessor for the month of the year. Date must be valid. - - -@date: Date to get the month from -@Returns: A #GDateMonth - - - - -Allocate a #GDate and initialize it to a sane state. The new date will -be cleared (as if you'd called g_date_clear()) but invalid (it won't -represent an existing day). Free the return value with g_date_free(). - - -@Returns: The newly-allocated #GDate - - - - -Like g_date_new(), but also sets the value of the date. Assuming the -day/month/year triplet you pass in represents an existing day, the -returned date will be valid. - - -@day: Day of the month -@month: Month of the year -@year: Year -@Returns: Allocated date initialized with @day, @month, and @year - - - - -Like g_date_new(), but also sets the value of the date. Assuming the -Julian day number you pass in is valid (greater than 0, less than an -unreasonably large number), the returned date will be valid. - - -@julian_day: Days since January 1, Year 1 -@Returns: Allocated date initialized with @julian_day - - - - -Set the day of the month for a #GDate. If the resulting day-month-year -triplet is invalid, the date will be invalid. - - -@date: Date to set the day for -@day: Day to set - - - - -Set the value of a #GDate from a day, month, and year. The DMY triplet -must be valid; if you aren't sure it is, call g_date_valid_dmy() to -check before you set it. - - -@date: Date to set the value of -@day: Day -@month: Month -@y: Year - - - - -Set the value of a #GDate from a Julian day number. - - -@date: Date to set -@julian_date: Julian day number (days since January 1, Year 1) - - - - -Set the month of the year for a #GDate. If the resulting - day-month-year triplet is invalid, the date will be invalid. - - -@date: Date -@month: Month to set - - - - -Parse a user-inputted string @str, and try to figure out what date it -represents, taking the current locale into account. If the string is -successfully parsed, the date will be valid after the call. Otherwise, -it will be invalid. You should check using g_date_valid() to see -whether the parsing succeeded. - - - -This function is not appropriate for file formats and the like; it -isn't very precise, and its exact behavior varies with the -locale. It's intended to be a heuristic routine that guesses what the -user means by a given string (and it does work pretty well in that -capacity). - - -@date: Date to fill in -@str: String to parse - - - - -Set the value of a date from a #GTime (time_t) value. To set the value -of a date to the current day, you could write: - - g_date_set_time(date, time(NULL)); - - - -@date: Date to update -@time: #GTime value to set - - - - -Set the year for a #GDate. If the resulting day-month-year triplet is - invalid, the date will be invalid. - - -@date: Date -@year: Year to set - - - - -Generate a printed representation of the date, in a locale-specific -way. Works just like the standard C strftime() -function, but only accepts date-related formats; time-related formats -give undefined results. Date must be valid. - - -@s: Destination buffer -@slen: Max buffer size -@format: Format string -@date: valid #GDate -@Returns: number of characters written to the buffer, or 0 the buffer was too small - - - - -Move a date some number of days into the past. To move by weeks, just -move by weeks*7 days. Date must be valid. - - -@date: Date to decrement -@n_days: Number of days to move - - - - -Move a date some number of months into the past. If the current day of -the month doesn't exist in the destination month, the day of the month -may change. Date must be valid. - - -@date: Date to decrement -@n_months: Number of months to move - - - - -Move a date some number of years into the past. If the current day -doesn't exist in the destination year (i.e. it's February 29 and you -move to a non-leap-year) then the day is changed to February 29. Date -must be valid. - - -@date: Date to decrement -@n_years: Number of years to move - - - - -Week of the year during which this date falls, if weeks are understood -to being on Sunday. Date must be valid. Can return 0 if the day is -before the first Sunday of the year. - - -@date: Date -@Returns: Week number - - - - -Return the number of weeks in the year, where weeks are taken to start -on Sunday. Will be 52 or 53. Date must be valid. (Years always have 52 -7-day periods, plus 1 or 2 extra days depending on whether it's a leap -year. This function is basically telling you how many Sundays are in -the year, i.e. there are 53 Sundays if one of the extra days happens -to be a Sunday.) - - -@year: Year to count weeks in -@Returns: Number of weeks - - - - -Fills in the date-related bits of a struct tm -using the @date value. Initializes the non-date parts with something -sane but meaningless. - - -@date: Date to set the struct tm from -@tm: struct tm to fill - - - - -Returns TRUE if the #GDate represents an existing day. #GDate must not -contain garbage; it should have been initialized with g_date_clear() -if it wasn't allocated by one of the g_date_new() variants. - - -@date: Date to check -@Returns: Whether the date is valid. - - - - -Returns TRUE if the day of the month is valid (a day is valid if it's -between 1 and 31 inclusive). - - -@day: Day to check. -@Returns: Boolean, whether the day is valid. - - - - -Returns TRUE if the day/month/year triplet forms a valid, existing day -in the range of days GDate understands (Year 1 or later, no more than -a few thousand years in the future). - - -@day: Day -@month: Month -@year: Year -@Returns: Boolean, whether the date is a valid one - - - - -Returns TRUE if the Julian day is valid. Anything greater than zero is basically a -valid Julian, though there is a 32-bit limit. - - -@julian_date: Julian day to check -@Returns: Boolean, whether the Julian day is valid. - - - - -Returns TRUE if the month value is valid. The 12 #GDateMonth -enumeration values are the only valid months. - - -@month: Month -@Returns: Boolean, whether the month is valid - - - - -Returns TRUE if the weekday is valid. The 7 #GDateWeekday enumeration -values are the only valid weekdays. - - -@weekday: Weekday -@Returns: Boolean, whether the weekday is valid. - - - - -Returns TRUE if the year is valid. Any year greater than 0 is valid, -though there is a 16-bit limit to what GDate will understand. - - -@year: Year -@Returns: Boolean, whether the year is valid. - - - - -Returns the day of the week for a #GDate. The date must be valid. - - -@date: Date -@Returns: Day of the week as a #GDateWeekday - - - - -Accessor; returns the year of a #GDate. The date must be valid. - - -@date: Date -@Returns: Year in which the date falls - - + +Date and Time Functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@tv_sec: +@tv_usec: + + + + + + +@result: + + + + + + + +@microseconds: + + + + + + + +@julian_days: +@julian: +@dmy: +@day: +@month: +@year: + + + + + + + + + + + + +@G_DATE_DAY: +@G_DATE_MONTH: +@G_DATE_YEAR: + + + + + + + + + + + + +@G_DATE_BAD_MONTH: +@G_DATE_JANUARY: +@G_DATE_FEBRUARY: +@G_DATE_MARCH: +@G_DATE_APRIL: +@G_DATE_MAY: +@G_DATE_JUNE: +@G_DATE_JULY: +@G_DATE_AUGUST: +@G_DATE_SEPTEMBER: +@G_DATE_OCTOBER: +@G_DATE_NOVEMBER: +@G_DATE_DECEMBER: + + + + + + + + + + + + +@G_DATE_BAD_WEEKDAY: +@G_DATE_MONDAY: +@G_DATE_TUESDAY: +@G_DATE_WEDNESDAY: +@G_DATE_THURSDAY: +@G_DATE_FRIDAY: +@G_DATE_SATURDAY: +@G_DATE_SUNDAY: + + + + + + + + + + + + + + + + + + + + + + + + + + + +@Returns: + + + + + + + +@day: +@month: +@year: +@Returns: + + + + + + + +@julian_day: +@Returns: + + + + + + + +@date: +@n_dates: + + + + + + + +@date: + + + + + + + +@date: +@day: + + + + + + + +@date: +@month: + + + + + + + +@date: +@year: + + + + + + + +@date: +@day: +@month: +@y: + + + + + + + +@date: +@julian_date: + + + + + + + +@date: +@time: + + + + + + + +@date: +@str: + + + + + + + +@date: +@n_days: + + + + + + + +@date: +@n_days: + + + + + + + +@date: +@n_months: + + + + + + + +@date: +@n_months: + + + + + + + +@date: +@n_years: + + + + + + + +@date: +@n_years: + + + + + + + +@lhs: +@rhs: +@Returns: + + + + + + + +@date: +@Returns: + + + + + + + +@date: +@Returns: + + + + + + + +@date: +@Returns: + + + + + + + +@date: +@Returns: + + + + + + + +@date: +@Returns: + + + + + + + +@date: +@Returns: + + + + + + + +@month: +@year: +@Returns: + + + + + + + +@date: +@Returns: + + + + + + + +@date: +@Returns: + + + + + + + +@year: +@Returns: + + + + + + + +@date: +@Returns: + + + + + + + +@year: +@Returns: + + + + + + + +@date: +@Returns: + + + + + + + +@year: +@Returns: + + + + + + + +@s: +@slen: +@format: +@date: +@Returns: + + + + + + + +@date: +@tm: + + + + + + + +@date: +@Returns: + + + + + + + +@day: +@Returns: + + + + + + + +@month: +@Returns: + + + + + + + +@year: +@Returns: + + + + + + + +@day: +@month: +@year: +@Returns: + + + + + + + +@julian_date: +@Returns: + + + + + + + +@weekday: +@Returns: + + diff --git a/docs/reference/glib/tmpl/hash_tables.sgml b/docs/reference/glib/tmpl/hash_tables.sgml index 75ffd0600..8c0577826 100644 --- a/docs/reference/glib/tmpl/hash_tables.sgml +++ b/docs/reference/glib/tmpl/hash_tables.sgml @@ -2,357 +2,225 @@ Hash Tables -associations between keys and values so that given a key the value -can be found quickly. + -A #GHashTable provides associations between keys and values which -is optimized so that given a key, the associated value can be found -very quickly. - - -Note that neither keys nor values are copied when inserted into the -#GHashTable, so they must exist for the lifetime of the #GHashTable. -This means that the use of static strings is OK, but temporary -strings (i.e. those created in buffers and those returned by GTK widgets) -should be copied with g_strdup() before being inserted. - - -If keys or values are dynamically allocated, you must be careful to ensure -that they are freed when they are removed from the #GHashTable, and also -when they are overwritten by new insertions into the #GHashTable. -It is also not advisable to mix static strings and dynamically-allocated -strings in a #GHashTable, because it then becomes difficult to determine -whether the string should be freed. - - -To create a #GHashTable, use g_hash_table_new(). - - -To insert a key and value into a #GHashTable, use g_hash_table_insert(). - - -To lookup a value corresponding to a given key, use g_hash_table_lookup() -and g_hash_table_lookup_extended(). - - -To remove a key and value, use g_hash_table_remove(). - - -To call a function for each key and value pair use g_hash_table_foreach(). - - -To destroy a #GHashTable use g_hash_table_destroy(). + + + -The #GHashTable struct is an opaque data structure to represent a -Hash Table. -It should only be accessed via the following functions. + -Creates a new #GHashTable. + -@hash_func: a function to create a hash value from a key. -Hash values are used to determine where keys are stored within the -#GHashTable data structure. -The g_direct_hash(), g_int_hash() and g_str_hash() functions are provided for -some common types of keys. If hash_func is NULL, g_direct_hash() is used. -@key_compare_func: a function to compare two keys to see if they are equal. -This is used when looking up keys in the #GHashTable. -The g_direct_equal(), g_int_equal() and g_str_equal() functions are provided -for the most common types of keys. If compare_func is NULL, keys are compared -directly in a similar fashion to g_direct_equal(), but without the overhead -of a function call. -@Returns: a new #GHashTable. +@hash_func: +@key_compare_func: +@Returns: -Specifies the type of the hash function which is passed to -g_hash_table_new() when a #GHashTable is created. - - -The function is passed a key and should return a guint hash value. -The functions g_direct_hash(), g_int_hash() and g_str_hash() provide -hash functions which can be used when the key is a #gpointer, #gint, and -#gchar* respectively. - - -FIXME: Need more here. -The hash values should be evenly distributed over a fairly large range? -The modulus is taken with the hash table size (a prime number) -to find the 'bucket' to place each key into. -The function should also be very fast, since it is called for each key -lookup. + -@key: a key. -@Returns: the hash value corresponding to the key. +@key: +@Returns: -Specifies the type of a comparison function used to compare two values. -The value which should be returned depends on the context in which the -#GCompareFunc is used. - - -In g_hash_table_new(), g_cache_new(), and g_relation_index() the function -should return TRUE if the two parameters are equal, or FALSE if they are not. - - -In g_list_find_custom() and g_slist_find_custom() the function should return -0 if the two parameters are equal. - - -In g_list_insert_sorted(), g_list_sort(), g_slist_insert_sorted(), -g_slist_sort() and g_tree_new() the function should return a negative integer -if the first value comes before the second, 0 if they are equal, or a positive -integer if the first value comes after the second. + -@a: a value. -@b: a value to compare with. -@Returns: TRUE if the two values are equivalent. +@a: +@b: +@Returns: -Inserts a new key and value into a #GHashTable. -If the key already exists in the #GHashTable its current value is replaced -with the new value. - - - -If the keys or values use dynamically allocated memory, then you should -first check if the key already exists in the GHashTable. If it does, -you should free the existing key and/or value before inserting the -new key and value. - - -@hash_table: a #GHashTable. -@key: a key to insert. -@value: the value to associate with the key. + + +@hash_table: +@key: +@value: -Returns the number of key/value pairs in a #GHashTable. + -@hash_table: a #GHashTable. -@Returns: the number of key/value pairs in the #GHashTable. +@hash_table: +@Returns: -Looks up a key in the #GHashTable, returning the associated value or NULL -if the key is not found. + -@hash_table: a #GHashTable. -@key: the key to look up. -@Returns: the associated value, or NULL if the key is not found. +@hash_table: +@key: +@Returns: -Looks up a key in the #GHashTable, returning the original key and the -associated value and a gboolean which is TRUE if the key was found. -This is useful if you need to free the memory allocated for the -original key, for example before calling g_hash_table_remove(). + -@hash_table: a #GHashTable. -@lookup_key: the key to look up. -@orig_key: returns the original key. -@value: returns the value associated with the key. -@Returns: TRUE if the key was found in the #GHashTable. +@hash_table: +@lookup_key: +@orig_key: +@value: +@Returns: -Calls the given function for each of the key/value pairs in the #GHashTable. -The function is passed the key and value of each pair, and the given -@user_data parameter. + -@hash_table: a #GHashTable. -@func: the function to call for each key/value pair. -@user_data: use data to pass to the function. +@hash_table: +@func: +@user_data: -Specifies the type of the function passed to g_hash_table_foreach(). -It is called with each key/value pair, together with the @user_data parameter -which is passed to g_hash_table_foreach(). + -@key: a key. -@value: the value corresponding to the key. -@user_data: user data passed to g_hash_table_foreach(). +@key: +@value: +@user_data: -Removes a key and its associated value from a #GHashTable. - - - -As with g_hash_table_insert(), you should make sure that any dynamically -allocated values are freed yourself. - - -@hash_table: a #GHashTable. -@key: the key to remove. + + +@hash_table: +@key: -Calls the given function for each key/value pair in the #GHashTable. -If the function returns TRUE, then the key/value pair is removed from the -#GHashTable. + -@hash_table: a #GHashTable. -@func: the function to call for each key/value pair. -@user_data: user data to pass to the function. -@Returns: the number of key/value paris removed. +@hash_table: +@func: +@user_data: +@Returns: -Specifies the type of the function passed to g_hash_table_foreach_remove(). -It is called with each key/value pair, together with the @user_data parameter -passed to g_hash_table_foreach_remove(). -It should return TRUE if the key/value pair should be removed from the -#GHashTable. + -@key: a key. -@value: the value associated with the key. -@user_data: user data passed to g_hash_table_remove(). -@Returns: TRUE if the key/value pair should be removed from the #GHashTable. +@key: +@value: +@user_data: +@Returns: -Disable resizing of a #GHashTable. - - -This should be used if you need to make a lot of changes to a #GHashTable -at once, as it reduces the number of times that the #GHashTable is rebuilt. -You should call g_hash_table_thaw() after updating the #GHashTable to -enable resizing again. + -@hash_table: a #GHashTable. +@hash_table: -Enables resizing of a #GHashTable. + -@hash_table: a #GHashTable. +@hash_table: -Destroys the #GHashTable. - - - -If keys and/or values are dynamically allocated, you should free them -first. - - -@hash_table: a #GHashTable. + + +@hash_table: -Compares two #gpointer arguments and returns TRUE if they are equal. -It can be passed to g_hash_table_new() as the @key_compare_func -parameter, when using pointers as keys in a #GHashTable. + -@v: a key. -@v2: a key to compare with @v. -@Returns: TRUE if the two keys match. +@v: +@v2: +@Returns: -Converts a gpointer to a hash value. -It can be passed to g_hash_table_new() as the @hash_func parameter, when -using gpointer values as keys in a #GHashTable. + -@v: a gpointer key. -@Returns: a hash value corresponding to the key. +@v: +@Returns: -Compares the two #gint values being pointed to and returns TRUE if they are -equal. -It can be passed to g_hash_table_new() as the @key_compare_func -parameter, when using pointers to integers as keys in a #GHashTable. + -@v: a pointer to a #gint key. -@v2: a pointer to a #gint key to compare with @v. -@Returns: TRUE if the two keys match. +@v: +@v2: +@Returns: -Converts a pointer to a #gint to a hash value. -It can be passed to g_hash_table_new() as the @hash_func parameter, when -using pointers to gint values as keys in a #GHashTable. + -@v: a pointer to a #gint key. -@Returns: a hash value corresponding to the key. +@v: +@Returns: -Compares two strings and returns TRUE if they are equal. -It can be passed to g_hash_table_new() as the @key_compare_func -parameter, when using strings as keys in a #GHashTable. + -@v: a key. -@v2: a key to compare with @v. -@Returns: TRUE if the two keys match. +@v: +@v2: +@Returns: -Converts a string to a hash value. -It can be passed to g_hash_table_new() as the @hash_func parameter, when -using strings as keys in a #GHashTable. + -@v: a string key. -@Returns: a hash value corresponding to the key. +@v: +@Returns: diff --git a/docs/reference/glib/tmpl/hooks.sgml b/docs/reference/glib/tmpl/hooks.sgml index 47cf06e1f..bd74101c9 100644 --- a/docs/reference/glib/tmpl/hooks.sgml +++ b/docs/reference/glib/tmpl/hooks.sgml @@ -2,65 +2,23 @@ Hook Functions -support for manipulating lists of hook functions. + -The #GHookList, #GHook and their related functions provide support for -lists of hook functions. Functions can be added and removed from the lists, -and the list of hook functions can be invoked. + + - - - - - -#guint seq_id; -the next free #GHook id. - - - -#guint hook_size; -the size of the #GHookList elements, in bytes. - - - -#guint is_setup : 1; -1 if the #GHookList has been initialized. - - - -#GHook *hooks; -the first #GHook element in the list. - - - -#GMemChunk *hook_memchunk; -the #GMemChunk used for allocating the #GHook elements. - - - -#GHookFreeFunc hook_free; -the function to call to free a #GHook element. - - - -#GHookFreeFunc hook_destroy; -the function to call to destory a #GHook element. - - - - @seq_id: @@ -74,51 +32,6 @@ and the list of hook functions can be invoked. - - - - - -#gpointer data; -. - - - -#GHook *next; -. - - - -#GHook *prev; -. - - - -#guint ref_count; -. - - - -#guint hook_id; -. - - - -#guint flags; -. - - - -#gpointer data; -. - - - -#GDestroyNotify destroy; -. - - - @data: @@ -184,34 +97,29 @@ and the list of hook functions can be invoked. -Initializes a #GHookList. -This must be called before the #GHookList is used. + -@hook_list: a #GHookList. -@hook_size: the size of each element in the #GHookList, typically -sizeof (GHook). +@hook_list: +@hook_size: -Calls all of the #GHook functions in a #GHookList. + -@hook_list: a #GHookList. -@may_recurse: TRUE if functions which are already running (e.g. in another -thread) can be called. If set to FALSE, these are skipped. +@hook_list: +@may_recurse: -Calls all of the #GHook functions in a #GHookList. -Any function which returns TRUE is removed from the #GHookList. + -@hook_list: a #GHookList. -@may_recurse: TRUE if functions which are already running (e.g. in another -thread) can be called. If set to FALSE, these are skipped. +@hook_list: +@may_recurse: @@ -219,7 +127,7 @@ thread) can be called. If set to FALSE, these are skipped. -@hook_list: a #GHookList. +@hook_list: @may_recurse: @marshaller: @data: @@ -230,7 +138,7 @@ thread) can be called. If set to FALSE, these are skipped. -@hook_list: a #GHookList. +@hook_list: @may_recurse: @marshaller: @data: @@ -238,183 +146,164 @@ thread) can be called. If set to FALSE, these are skipped. -Removes all the #GHook elements from a #GHookList. + -@hook_list: a #GHookList. +@hook_list: -Allocates space for a #GHook and initializes it. + -@hook_list: a #GHookList. -@Returns: a new #GHook. +@hook_list: +@Returns: -Appends a #GHook onto the end of a #GHookList. + -@hook_list: a #GHookList. -@hook: the #GHook to add to the end of @hook_list. +@hook_list: +@hook: -Prepends a #GHook on the start of a #GHookList. + -@hook_list: a #GHookList. -@hook: the #GHook to add to the start of @hook_list. +@hook_list: +@hook: -Inserts a #GHook into a #GHookList, before a given #GHook. + -@hook_list: a #GHookList. -@sibling: the #GHook to insert the new #GHook before. -@hook: the #GHook to insert. +@hook_list: +@sibling: +@hook: -Inserts a #GHook into a #GHookList, sorted by the given function. + -@hook_list: a #GHookList. -@hook: the #GHook to insert. -@func: the comparison function used to sort the #GHook elements. +@hook_list: +@hook: +@func: -Defines the type of function used to compare #GHook elements in -g_hook_insert_sorted(). + -@new_hook: the #GHook being inserted. -@sibling: the #GHook to compare with @new_hook. -@Returns: a value <= 0 if @new_hook should be before @sibling. +@new_hook: +@sibling: +@Returns: -Compares the ids of two #GHook elements, returning a negative value -if the second id is greater than the first. + -@new_hook: a #GHook. -@sibling: a #GHook to compare with @new_hook. -@Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook. +@new_hook: +@sibling: +@Returns: -Returns the #GHook with the given id, or NULL if it is not found. + -@hook_list: a #GHookList. -@hook_id: a hook id. -@Returns: the #GHook with the given id, or NULL if it is not found. +@hook_list: +@hook_id: +@Returns: -Finds a #GHook in a #GHookList using the given function to test for a match. + -@hook_list: a #GHookList. -@need_valids: TRUE if #GHook elements which have been destroyed should be -skipped. -@func: the function to call for each #GHook, which should return TRUE when -the #GHook has been found. -@data: the data passed to @func. -@Returns: the found #GHook or NULL if no matching #GHook is found. +@hook_list: +@need_valids: +@func: +@data: +@Returns: -Finds a #GHook in a #GHookList with the given data. + -@hook_list: a #GHookList. -@need_valids: TRUE if #GHook elements which have been destroyed should be -skipped. -@data: the data to find. -@Returns: the #GHook with the given @data or NULL if no matching -#GHook is found. +@hook_list: +@need_valids: +@data: +@Returns: -Finds a #GHook in a #GHookList with the given function. + -@hook_list: a #GHookList. -@need_valids: TRUE if #GHook elements which have been destroyed should be -skipped. -@func: the function to find. -@Returns: the #GHook with the given @func or NULL if no matching -#GHook is found. +@hook_list: +@need_valids: +@func: +@Returns: -Defines the type of the function passed to g_hooK_find_func(). + -@hook: a #GHook. -@data: user data passed to g_hook_find_func(). -@Returns: TRUE if the required #GHook has been found. +@hook: +@data: +@Returns: -Finds a #GHook in a #GHookList with the given function and data. + -@hook_list: a #GHookList. -@need_valids: TRUE if #GHook elements which have been destroyed should be -skipped. -@func: the function to find. -@data: the data to find. -@Returns: the #GHook with the given @func and @data or NULL if no matching -#GHook is found. +@hook_list: +@need_valids: +@func: +@data: +@Returns: -Returns the first #GHook in a #GHookList which has not been destroyed. -The reference count for the #GHook is incremented, so you must call -g_hook_unref() to restore it when no longer needed. (Or call -g_hook_next_valid() if you are stepping through the #GHookList.) + -@hook_list: a #GHookList. -@may_be_in_call: TRUE if hooks which are currently running (e.g. in another -thread) are considered valid. If set to FALSE, these are skipped. -@Returns: the first valid #GHook, or NULL if none are valid. +@hook_list: +@may_be_in_call: +@Returns: -Returns the next #GHook in a #GHookList which has not been destroyed. -The reference count for the #GHook is incremented, so you must call -g_hook_unref() to restore it when no longer needed. (Or continue to call -g_hook_next_valid() until NULL is returned.) -@hook_list: a #GHookList. -@hook: the current #GHook. -@may_be_in_call: TRUE if hooks which are currently running (e.g. in another -thread) are considered valid. If set to FALSE, these are skipped. -@Returns: the next valid #GHook, or NULL if none are valid. +@hook_list: +@hook: +@may_be_in_call: +@Returns: @@ -435,90 +324,79 @@ thread) are considered valid. If set to FALSE, these are skipped. -Returns TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active -and it has not been destroyed. + -@hook: a #GHook. -@Returns: TRUE if the #GHook is valid. +@hook: -Returns TRUE if the #GHook is active, which is normally TRUE until the #GHook -is destroyed. + -@hook: a #GHook. -@Returns: TRUE if the #GHook is active. +@hook: -Returns TRUE if the #GHook function is currently executing. + -@hook: a #GHook. -@Returns: TRUE if the #GHook function is currently executing. +@hook: -Returns TRUE if the #GHook is not in a #GHookList. -@hook: a #GHook. -@Returns: TRUE if the #GHook is not in a #GHookList. +@hook: -Increments the reference count for a #GHook. + -@hook_list: a #GHookList. -@hook: the #GHook to increment the reference count of. +@hook_list: +@hook: -Decrements the reference count of a #GHook. -If the reference count falls to 0, the #GHook is removed from the #GHookList -and g_hook_free() is called to free it. + -@hook_list: a #GHookList. +@hook_list: @hook: -Calls the #GHookList @hook_free function if it exists, and frees the memory -allocated for the #GHook. + -@hook_list: a #GHookList. -@hook: the #GHook to free. +@hook_list: +@hook: -Destroys a #GHook, given its ID. + -@hook_list: a #GHookList. -@hook_id: a hook ID. -@Returns: TRUE if the #GHook was found in the #GHookList and destroyed. +@hook_list: +@hook_id: +@Returns: -Removes one #GHook from a #GHookList, calling the @hook_destroy function in -the #GHookList, and the @destroy function of the #GHook, if they exist. + -@hook_list: a #GHookList. -@hook: the #GHook to remove. +@hook_list: +@hook: diff --git a/docs/reference/glib/tmpl/iochannels.sgml b/docs/reference/glib/tmpl/iochannels.sgml index 1c44eb2ce..a9365443c 100644 --- a/docs/reference/glib/tmpl/iochannels.sgml +++ b/docs/reference/glib/tmpl/iochannels.sgml @@ -2,68 +2,23 @@ IO Channels -portable support for using files, pipes and sockets. + -The #GIOChannel data type aims to provide a portable method for using file -descriptors, pipes, and sockets, and integrating them into the -main event loop. -Currently full support is available on Unix platforms, though support for -Windows is only partially complete. - - -To create a new #GIOChannel on Unix systems use g_io_channel_unix_new(). -This works for plain file descriptors, pipes and sockets. - - -Once a #GIOChannel has been created, it can be used in a generic manner -with the functions g_io_channel_read(), g_io_channel_write(), -g_io_channel_seek(), and g_io_channel_close(). - - -To add a #GIOChannel to the -main event loop -use g_io_add_watch() or g_io_add_watch_full(). Here you specify which events -you are interested in on the #GIOChannel, and provide a function to be -called whenever these events occur. - - -#GIOChannel instances are created with an initial reference count of 1. -g_io_channel_ref() and g_io_channel_unref() can be used to increment or -decrement the reference count respectively. When the reference count falls -to 0, the #GIOChannel is freed. (Though it isn't closed automatically.) -Using g_io_add_watch() or g_io_add_watch_full() increments a channel's -reference count. - - -GTK+ contains the convenience function gtk_input_add_full() -which creates a #GIOChannel from a file descriptor and adds it to the -main event loop. -The event source can later be removed with gtk_input_remove(). -Similar functions can also be found in GDK. + + - - -gtk_input_add_full(), gtk_input_remove(), gdk_input_add(), -gdk_input_add_full(), gdk_input_remove() - -Convenience functions for creating #GIOChannel instances and adding them to the -main event loop. - - - - + -A data structure representing an IO Channel. The fields should be considered -private and should only be accessed with the following functions. + @channel_flags: @@ -72,47 +27,40 @@ private and should only be accessed with the following functions. -Creates a new #GIOChannel given a file descriptor. -On Unix systems this works for plain files, pipes, and sockets. - - -The returned #GIOChannel has a reference count of 1. + -@fd: a file descriptor. -@Returns: a new #GIOChannel. +@fd: +@Returns: -Returns the file descriptor of the Unix #GIOChannel. + -@channel: a #GIOChannel, created with g_io_channel_unix_new(). -@Returns: the file descriptor of the #GIOChannel. +@channel: +@Returns: -Initializes a #GIOChannel struct. This is called by each of the above functions -when creating a #GIOChannel, and so is not often needed by the application -programmer (unless you are creating a new type of #GIOChannel). + -@channel: a #GIOChannel. +@channel: -Reads data from a #GIOChannel. + -@channel: a #GIOChannel. -@buf: a buffer to read the data into (which should be at least count bytes -long). -@count: the number of bytes to read from the #GIOChannel. -@bytes_read: returns the number of bytes actually read. -@Returns: %G_IO_ERROR_NONE if the operation was successful. +@channel: +@buf: +@count: +@bytes_read: +@Returns: @@ -127,56 +75,29 @@ long). -Writes data to a #GIOChannel. + -@channel: a #GIOChannel. -@buf: the buffer containing the data to write. -@count: the number of bytes to write. -@bytes_written: the number of bytes actually written. -@Returns: %G_IO_ERROR_NONE if the operation was successful. +@channel: +@buf: +@count: +@bytes_written: +@Returns: -Sets the current position in the #GIOChannel, similar to the standard system -call fseek(). + -@channel: a #GIOChannel. -@offset: an offset, in bytes, which is added to the position specified by -@type. -@type: the position in the file, which can be %G_SEEK_CUR (the current -position), %G_SEEK_SET (the start of the file), or %G_SEEK_END (the end of the -file). -@Returns: %G_IO_ERROR_NONE if the operation was successful. +@channel: +@offset: +@type: +@Returns: -An enumeration specifying the base position for a g_io_channel_seek() -operation. - - - - - - -G_SEEK_CUR -the current position in the file. - - - -G_SEEK_SET -the start of the file. - - - -G_SEEK_END -the end of the file. - - - @@ -186,100 +107,56 @@ operation. -Closes a #GIOChannel. -The #GIOChannel will be freed when its reference count drops to 0. + -@channel: a #GIOChannel. +@channel: -Increments the reference count of a #GIOChannel. + -@channel: a #GIOChannel. +@channel: -Decrements the reference count of a #GIOChannel. + -@channel: a #GIOChannel. +@channel: -Adds the #GIOChannel into the -main event loop -with the default priority. + -@channel: a #GIOChannel. -@condition: the condition to watch for. -@func: the function to call when the condition is satisfied. -@user_data: user data to pass to @func. -@Returns: the event source id. +@channel: +@condition: +@func: +@user_data: +@Returns: -Adds the #GIOChannel into the -main event loop -with the given priority. + -@channel: a #GIOChannel. -@priority: the priority of the #GIOChannel source. -@condition: the condition to watch for. -@func: the function to call when the condition is satisfied. -@user_data: user data to pass to @func. -@notify: the function to call when the source is removed. -@Returns: the event source id. +@channel: +@priority: +@condition: +@func: +@user_data: +@notify: +@Returns: -A bitwise combination representing a condition to watch for on an event -source. - - - - - - -G_IO_IN -There is data to read. - - - -G_IO_OUT -Data can be written (without blocking). - - - -G_IO_PRI -There is urgent data to read. - - - -G_IO_ERR -Error condition. - - - -G_IO_HUP -Hung up (the connection has been broken, usually for pipes and -sockets). - - - -G_IO_NVAL -Invalid request. The file descriptor is not open. - - - @@ -292,22 +169,18 @@ sockets). -Specifies the type of function passed to g_io_add_watch() or -g_io_add_watch_full(), which is called when the requested condition on a -#GIOChannel is satisfied. + -@source: the #GIOChannel event source. -@condition: the condition which has been satisfied. -@data: user data set in g_io_add_watch() or g_io_add_watch_full(). -@Returns: the function should return FALSE if the event source should be -removed. +@source: +@condition: +@data: +@Returns: -A table of functions used to handle different types of #GIOChannel in a -generic way. + @io_read: diff --git a/docs/reference/glib/tmpl/limits.sgml b/docs/reference/glib/tmpl/limits.sgml index ec68926de..57a65293c 100644 --- a/docs/reference/glib/tmpl/limits.sgml +++ b/docs/reference/glib/tmpl/limits.sgml @@ -2,85 +2,107 @@ Limits of Basic Types -portable method of determining the limits of the standard types. + -These macros provide a portable method to determine the limits of some of -the standard integer and floating point types. + + + -The minimum value which can be held in a #gint. + -The maximum value which can be held in a #gint. + + + + + + + + -The minimum value which can be held in a #gshort. + -The maximum value which can be held in a #gshort. + + + + + + + + -The minimum value which can be held in a #glong. + -The maximum value which can be held in a #glong. + + + + + + + + -The minimum value which can be held in a #gfloat. + -The maximum value which can be held in a #gfloat. + -The minimum value which can be held in a #gdouble. + -The maximum value which can be held in a #gdouble. + diff --git a/docs/reference/glib/tmpl/linked_lists_double.sgml b/docs/reference/glib/tmpl/linked_lists_double.sgml index 995379c8c..1b3a9188f 100644 --- a/docs/reference/glib/tmpl/linked_lists_double.sgml +++ b/docs/reference/glib/tmpl/linked_lists_double.sgml @@ -2,76 +2,23 @@ Doubly-Linked Lists -linked lists containing integer values or pointers to data, with the ability -to iterate over the list in both directions. + -The #GList structure and its associated functions provide a standard -doubly-linked list data structure. - - -Each element in the list contains a piece of data, together with pointers -which link to the previous and next elements in the list. -Using these pointers it is possible to move through the list in both -directions (unlike the -Singly-Linked Lists -which only allows movement through the list in the forward direction). - - -The data contained in each element can be either integer values, by using one -of the -Type Conversion Macros, -or simply pointers to any type of data. - - -List elements are allocated in blocks using a #GListAllocator, which is -more efficient than allocating elements individually. - - -Note that most of the #GList functions expect to be passed a pointer to -the first element in the list. The functions which insert elements return -the new start of the list, which may have changed. - - -There is no function to create a #GList. NULL is considered to be the empty -list so you simply set a #GList* to NULL. - - -To add elements, use g_list_append(), g_list_prepend(), g_list_insert() -and g_list_insert_sorted(). - - -To remove elements, use g_list_remove(). - - -To find elements in the list use g_list_first(), g_list_last(), g_list_next(), -g_list_previous(), g_list_nth(), g_list_nth_data(), g_list_find() and -g_list_find_custom(). - - -To find the index of an element use g_list_position() and g_list_index(). - - -To call a function for each element in the list use g_list_foreach(). - - -To free the entire list, use g_list_free(). + + + -The #GList struct is used for each element in a doubly-linked list. -The data field holds the element's data, which can -be a pointer to any kind of data, or any integer value using the -Type Conversion Macros. -The next and prev -pointers are the links to the next and previous elements in the list. + @data: @@ -80,336 +27,273 @@ pointers are the links to the next and previous elements in the list. -Adds a new element on to the end of the list. + - - -The return value is the new start of the list, which may have changed, so -make sure you store the new value. - - - - /* Notice that these are initialized to the empty list. */ - GList *list = NULL, *number_list = NULL; - /* This is a list of strings. */ - list = g_list_append (list, "first"); - list = g_list_append (list, "second"); - - /* This is a list of integers. */ - number_list = g_list_append (number_list, GINT_TO_POINTER (27)); - number_list = g_list_append (number_list, GINT_TO_POINTER (14)); - - -@list: a pointer to a #GList. -@data: the data for the new element. -@Returns: the new start of the #GList. +@list: +@data: +@Returns: -Adds a new element on to the start of the list. - - - -The return value is the new start of the list, which may have changed, so -make sure you store the new value. - - - - /* Notice that it is initialized to the empty list. */ - GList *list = NULL; - list = g_list_prepend (list, "last"); - list = g_list_prepend (list, "first"); - -@list: a pointer to a #GList. -@data: the data for the new element. -@Returns: the new start of the #GList. + + +@list: +@data: +@Returns: -Inserts a new element into the list at the given position. + -@list: a pointer to a #GList. -@data: the data for the new element. -@position: the position to insert the element. If this is negative, or is -larger than the number of elements in the list, the new element is added on -to the end of the list. -@Returns: the new start of the #GList. +@list: +@data: +@position: +@Returns: -Inserts a new element into the list, using the given comparison function -to determine its position. + -@list: a pointer to a #GList. -@data: the data for the new element. -@func: the function to compare elements in the list. It should return a -number > 0 if the first parameter comes after the second parameter in -the sort order. -@Returns: the new start of the #GList. +@list: +@data: +@func: +@Returns: -Removes an element from a #GList. -If two elements contain the same data, only the first is removed. -If none of the elements contain the data, the #GList is unchanged. + -@list: a #GList. -@data: the data of the element to remove. -@Returns: the new start of the #GList. +@list: +@data: +@Returns: -Removes an element from a #GList, without freeing the element. -The removed element's prev and next links are set to NULL, so that it becomes a -self-contained list with one element. + -@list: a #GList. -@llink: an element in the #GList. -@Returns: the new start of the #GList, without the element. +@list: +@llink: +@Returns: + + + + + + + +@list: +@link: +@Returns: -Frees all of the memory used by a #GList. -The freed elements are added to the #GListAllocator free list. + - - -If list elements contain dynamically-allocated memory, they should be freed -first. - - @list: -Allocates space for one #GList element. -It is called by g_list_append(), g_list_prepend(), g_list_insert() and -g_list_insert_sorted() and so is rarely used on its own. + -@Returns: a pointer to the newly-allocated #GList element. +@Returns: -Frees one #GList element. -It is usually used after g_list_remove_link(). + -@list: a #GList element. +@list: -Gets the number of elements in a #GList. + -@list: a #GList. -@Returns: the number of elements in the #GList. +@list: +@Returns: -Copies a #GList. - - -Note that this is a "shallow" copy. If the list elements consist of pointers -to data, the pointers are copied but the actual data isn't. + -@list: a #GList. -@Returns: a copy of @list. +@list: +@Returns: -Reverses a #GList. -It simply switches the next and prev pointers of each element. + -@list: a #GList. -@Returns: the start of the reversed #GList. +@list: +@Returns: -Sorts a #GList using the given comparison function. + -@list: a #GList. -@compare_func: the comparison function used to sort the #GList. This function -is passed 2 elements of the #GList and should return 0 if they are equal, -a negative value if the first element comes before the second, or a positive -value if the first element comes after the second. -@Returns: the start of the sorted #GList. +@list: +@compare_func: +@Returns: -Adds the second #GList onto the end of the first #GList. -Note that the elements of the second #GList are not copied. -They are used directly. + -@list1: a #GList. -@list2: the #GList to add to the end of the first #GList. -@Returns: the start of the new #GList. +@list1: +@list2: +@Returns: -Calls a function for each element of a #GList. + -@list: a #GList. -@func: the function to call with each element's data. -@user_data: user data to pass to the function. +@list: +@func: +@user_data: -Specifies the type of functions passed to g_list_foreach() and -g_slist_foreach(). + -@data: the element's data. -@user_data: user data passed to g_list_foreach() or g_slist_foreach(). +@data: +@user_data: -Gets the first element in a #GList. + -@list: a #GList. -@Returns: the first element in a #GList, or NULL if the #GList has no elements. +@list: +@Returns: -Gets the last element in a #GList. + -@list: a #GList. -@Returns: the last element in the #GList, or NULL if the #GList has no -elements. +@list: +@Returns: -A convenience macro to gets the previous element in a #GList. + -@list: an element in a #GList. -@Returns: the previous element, or NULL if there are no previous elements. +@list: -A convenience macro to gets the next element in a #GList. + -@list: an element in a #GList. -@Returns: the next element, or NULL if there are no more elements. +@list: -Gets the element at the given position in a #GList. + -@list: a #GList. -@n: the position of the element, counting from 0. -@Returns: the element, or NULL if the position is off the end of the #GList. +@list: +@n: +@Returns: -Gets the data of the element at the given position. + -@list: a #GList. -@n: the position of the element. -@Returns: the element's data, or NULL if the position is off the end of the -#GList. +@list: +@n: +@Returns: -Finds the element in a #GList which contains the given data. + -@list: a #GList. -@data: the element data to find. -@Returns: the found #GList element, or NULL if it is not found. +@list: +@data: +@Returns: -Finds an element in a #GList, using a supplied function to find the desired -element. -It iterates over the list, calling the given function which should return 0 -when the desired element is found. -The function takes two #gconstpointer arguments, the #GList element's data -and the given user data. + -@list: a #GList. -@data: user data passed to the function. -@func: the function to call for each element. It should return 0 when the -desired element is found. -@Returns: the found #GList element, or NULL if it is not found. +@list: +@data: +@func: +@Returns: -Gets the position of the given element in the #GList (starting from 0). + -@list: a #GList. -@llink: an element in the #GList. -@Returns: the position of the element in the #GList, or -1 if the element is -not found. +@list: +@llink: +@Returns: -Gets the position of the element containing the given data (starting from 0). - - -@list: a #GList. -@data: the data to find. -@Returns: the index of the element containing the data, or -1 if the data -is not found. - - - - -Restores the previous #GAllocator, used when allocating #GList elements. + +@list: +@data: +@Returns: -Sets the allocator to use to allocate #GList elements. -Use g_list_pop_allocator() to restore the previous allocator. + + + +@allocator: + + + + + -@allocator: the #GAllocator to use when allocating #GList elements. diff --git a/docs/reference/glib/tmpl/linked_lists_single.sgml b/docs/reference/glib/tmpl/linked_lists_single.sgml index 61f9bb9e4..6467f7e38 100644 --- a/docs/reference/glib/tmpl/linked_lists_single.sgml +++ b/docs/reference/glib/tmpl/linked_lists_single.sgml @@ -2,76 +2,23 @@ Singly-Linked Lists -linked lists containing integer values or pointers to data, limited to -iterating over the list in one direction. + -The #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 -Doubly-Linked Lists -which allow movement in both directions). - - -The data contained in each element can be either integer values, by using one -of the -Type Conversion Macros, -or simply pointers to any type of data. - - -List elements are allocated in blocks using a #GListAllocator, which is -more efficient than allocating elements individually. - - -Note that most of the #GSList functions expect to be passed a pointer to -the first element in the list. The functions which insert elements return -the new start of the list, which may have changed. - - -There is no function to create a #GSList. NULL is considered to be the empty -list so you simply set a #GSList* to NULL. - - -To add elements, use g_slist_append(), g_slist_prepend(), g_slist_insert() -and g_slist_insert_sorted(). - - -To remove elements, use g_slist_remove(). - - -To find elements in the list use g_slist_last(), g_slist_next(), -g_slist_nth(), g_slist_nth_data(), g_slist_find() and -g_slist_find_custom(). - - -To find the index of an element use g_slist_position() and g_slist_index(). - - -To call a function for each element in the list use g_slist_foreach(). - - -To free the entire list, use g_slist_free(). + + + -The #GSList struct is used for each element in the singly-linked list. -The data field holds the element's data, which can -be a pointer to any kind of data, or any integer value using the -Type Conversion Macros. -The next field contains the link to the next -element in the list. + @data: @@ -79,300 +26,258 @@ element in the list. -Allocates space for one #GSList element. -It is called by the g_slist_append(), g_slist_prepend(), g_slist_insert() and -g_slist_insert_sorted() functions and so is rarely used on its own. + -@Returns: a pointer to the newly-allocated #GSList element. +@Returns: -Adds a new element on to the end of the list. + - - -The return value is the new start of the list, which may have changed, so -make sure you store the new value. - - - - /* Notice that these are initialized to the empty list. */ - GSList *list = NULL, *number_list = NULL; - /* This is a list of strings. */ - list = g_slist_append (list, "first"); - list = g_slist_append (list, "second"); - - /* This is a list of integers. */ - number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); - number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); - - -@list: a #GSList. -@data: the data for the new element. -@Returns: the new start of the #GSList. +@list: +@data: +@Returns: -Adds a new element on to the start of the list. - - - -The return value is the new start of the list, which may have changed, so -make sure you store the new value. - - - - /* Notice that it is initialized to the empty list. */ - GSList *list = NULL; - list = g_slist_prepend (list, "last"); - list = g_slist_prepend (list, "first"); - -@list: a #GSList. -@data: the data for the new element. -@Returns: the new start of the #GSList. + + +@list: +@data: +@Returns: -Inserts a new element into the list at the given position. + -@list: a #GSList. -@data: the data for the new element. -@position: the position to insert the element. If this is negative, or is -larger than the number of elements in the list, the new element is added on -to the end of the list. -@Returns: the new start of the #GSList. +@list: +@data: +@position: +@Returns: + + + + + + + +@slist: +@sibling: +@data: +@Returns: -Inserts a new element into the list, using the given comparison function -to determine its position. + -@list: a #GSList. -@data: the data for the new element. -@func: the function to compare elements in the list. It should return a -number > 0 if the first parameter comes after the second parameter in -the sort order. -@Returns: the new start of the #GSList. +@list: +@data: +@func: +@Returns: -Removes an element from a #GSList. -If two elements contain the same data, only the first is removed. -If none of the elements contain the data, the #GSList is unchanged. + -@list: a #GSList. -@data: the data of the element to remove. -@Returns: the new start of the #GSList. +@list: +@data: +@Returns: -Removes an element from a #GSList, without freeing the element. -The removed element's next link is set to NULL, so that it becomes a -self-contained list with one element. + -@list: a #GSList. -@llink: an element in the #GSList. -@Returns: the new start of the #GSList, without the element. +@list: +@link: +@Returns: + + + + + + + +@list: +@link: +@Returns: -Frees all of the memory used by a #GSList. -The freed elements are added to the #GListAllocator free list. + -@list: a #GSList. +@list: -Frees one #GSList element. -It is usually used after g_slist_remove_link(). + -@list: a #GSList element. +@list: -Gets the number of elements in a #GSList. + -@list: a #GSList. -@Returns: the number of elements in the #GSList. +@list: +@Returns: -Copies a #GSList. - - -Note that this is a "shallow" copy. If the list elements consist of pointers -to data, the pointers are copied but the actual data isn't. + -@list: a #GSList. -@Returns: a copy of @list. +@list: +@Returns: -Reverses a #GSList. + -@list: a #GSList. -@Returns: the start of the reversed #GSList. +@list: +@Returns: -Sorts a #GSList using the given comparison function. + -@list: a #GSList. -@compare_func: the comparison function used to sort the #GSList. This function -is passed 2 elements of the #GSList and should return 0 if they are equal, -a negative value if the first element comes before the second, or a positive -value if the first element comes after the second. -@Returns: the start of the sorted #GList. +@list: +@compare_func: +@Returns: -Adds the second #GSList onto the end of the first #GSList. -Note that the elements of the second #GSList are not copied. -They are used directly. + -@list1: a #GSList. -@list2: the #GSList to add to the end of the first #GSList. -@Returns: the start of the new #GSList. +@list1: +@list2: +@Returns: -Calls a function for each element of a #GSList. + -@list: a #GSList. -@func: the function to call with each element's data. -@user_data: user data to pass to the function. +@list: +@func: +@user_data: -Gets the last element in a #GSList. + -@list: a #GSList. -@Returns: the last element in the #GSList, or NULL if the #GSList has no -elements. +@list: +@Returns: -A convenience macro to gets the next element in a #GSList. + -@slist: an element in a #GSList. -@Returns: the next element, or NULL if there are no more elements. +@slist: -Gets the element at the given position in a #GSList. + -@list: a #GSList. -@n: the position of the element, counting from 0. -@Returns: the element, or NULL if the position is off the end of the #GSList. +@list: +@n: +@Returns: -Gets the data of the element at the given position. + -@list: a #GSList. -@n: the position of the element. -@Returns: the element's data, or NULL if the position is off the end of the -#GSList. +@list: +@n: +@Returns: -Finds the element in a #GSList which contains the given data. + -@list: a #GSList. -@data: the element data to find. -@Returns: the found #GSList element, or NULL if it is not found. +@list: +@data: +@Returns: -Finds an element in a #GSList, using a supplied function to find the desired -element. -It iterates over the list, calling the given function which should return 0 -when the desired element is found. -The function takes two #gconstpointer arguments, the #GSList element's data -and the given user data. + -@list: a #GSList. -@data: user data passed to the function. -@func: the function to call for each element. It should return 0 when the -desired element is found. -@Returns: the found #GSList element, or NULL if it is not found. +@list: +@data: +@func: +@Returns: -Gets the position of the given element in the #GSList (starting from 0). + -@list: a #GSList. -@llink: an element in the #GSList. -@Returns: the position of the element in the #GSList, or -1 if the element -is not found. +@list: +@llink: +@Returns: -Gets the position of the element containing the given data (starting from 0). + -@list: a #GSList. -@data: the data to find. -@Returns: the index of the element containing the data, or -1 if the data -is not found. - - - - -Restores the previous #GAllocator, used when allocating #GSList elements. - +@list: +@data: +@Returns: -Sets the allocator to use to allocate #GSList elements. -Use g_slist_pop_allocator() to restore the previous allocator. + + + +@allocator: + + + + + -@allocator: the #GAllocator to use when allocating #GSList elements. diff --git a/docs/reference/glib/tmpl/macros.sgml b/docs/reference/glib/tmpl/macros.sgml index e597270da..bf09e3488 100644 --- a/docs/reference/glib/tmpl/macros.sgml +++ b/docs/reference/glib/tmpl/macros.sgml @@ -2,206 +2,182 @@ Standard Macros -commonly-used macros. + -These macros provide a few commonly-used features. + + + -The major version number of the GLib library. + -The minor version number of the GLib library. + -The micro version number of the GLib library. + + + + + + + + + + + + + + + + + + + + + + -Checks the version of the GLib library. -It returns TRUE if the GLib library is the same or newer than the given -version. - -Checking the version of the GLib library. - - if (!GLIB_CHECK_VERSION (1, 2, 0)) - g_error ("GLib version 1.2.0 or above is needed"); - - -@major: the major version number. -@minor: the minor version number. -@micro: the micro version number. +@major: +@minor: +@micro: -The directory separator character. -This is '/' on Unix machines and '\' under Windows. + -The directory separator as a string. -This is "/" on Unix machines and "\" under Windows. + -The search path separator character. -This is ':' on Unix machines and ';' under Windows. + -The search path separator as a string. -This is ":" on Unix machines and ";" under Windows. + -Defines the TRUE value for the #gboolean type. + -Defines the FALSE value for the #gboolean type. + -Defines the standard NULL pointer. + -Calculates the minimum of @a and @b. + -@a: a numeric value. -@b: a numeric value. -@Returns: the minimum of @a and @b. +@a: +@b: -Calculates the maximum of @a and @b. + -@a: a numeric value. -@b: a numeric value. -@Returns: the maximum of @a and @b. +@a: +@b: -Calculates the absolute value of @a. -The absolute value is simply the number with any negative sign taken away. - - -For example, - - -ABS(-10) is 10. - - -ABS(10) is also 10. - - + -@a: a numeric value. -@Returns: the absolute value of @a. +@a: -Ensures that @x is between the limits set by @low and @high. - - -For example, - - -CLAMP(5, 10, 15) is 10. - - -CLAMP(15, 5, 10) is 10. - - -CLAMP(20, 15, 25) is 20. - - + -@x: the value to clamp. -@low: the minimum value allowed. -@high: the maximum value allowed. -@Returns: the value of @x clamped to the range between @low and @high. +@x: +@low: +@high: -Returns a member of a structure at a given offset, using the given type. + -@member_type: the type of the struct field. -@struct_p: a pointer to a struct. -@struct_offset: the offset of the field from the start of the struct, in bytes. -@Returns: the struct member. +@member_type: +@struct_p: +@struct_offset: -Returns an untyped pointer to a given offset of a struct. + -@struct_p: a pointer to a struct. -@struct_offset: the offset from the start of the struct, in bytes. -@Returns: an untyped pointer to @struct_p plus @struct_offset bytes. +@struct_p: +@struct_offset: -Returns the offset, in bytes, of a member of a struct. + -@struct_type: a structure type, e.g. GtkWidget. -@member: a field in the structure, e.g. window. -@Returns: the offset of @member from the start of @struct_type. +@struct_type: +@member: diff --git a/docs/reference/glib/tmpl/macros_misc.sgml b/docs/reference/glib/tmpl/macros_misc.sgml index cfae430f7..ba10972db 100644 --- a/docs/reference/glib/tmpl/macros_misc.sgml +++ b/docs/reference/glib/tmpl/macros_misc.sgml @@ -2,157 +2,222 @@ Miscellaneous Macros -specialised macros which are not used often. + -These macros provide more specialized features which are not needed so often -by application programmers. + + + -Used to declare inline functions. If inline functions are not supported on -the particular platform, the macro evaluates to the empty string. + -Used within multi-statement macros so that they can be used in places where -only one statement is expected by the compiler. + -Used within multi-statement macros so that they can be used in places where -only one statement is expected by the compiler. + + + + + + +@arr: + + -Portable way to copy va_list variables. + -@ap1: the va_list variable to place a copy of @ap2 in. -@ap2: a va_list. +@ap1: +@ap2: + + + + + + + +@macro_or_string: -Expands to "__extension__" when GNU C is used as the compiler. -This simply tells GNU C not to warn about the following non-standard code -when compiling with the -pedantic option. + -Expands to the GNU C const function attribute if the compiler is GNU C. -This enables optimization of the function. -See the GNU C documentation for details. + -Expands to the GNU C noreturn function attribute if the compiler is GNU C. -It is used for declaring functions which never return. -It enables optimization of the function, and avoids possible compiler -warnings. See the GNU C documentation for details. + -Expands to the GNU C unused function attribute if the compiler is GNU C. -It is used for declaring functions which may never be used. -It avoids possible compiler warnings. See the GNU C documentation for details. + -Expands to the GNU C format function attribute if the compiler is GNU C. -This is used for declaring functions which take a variable number of -arguments, with the same syntax as printf(). -It allows the compiler to type-check the arguments passed to the function. -See the GNU C documentation for details. + -@format_idx: the index of the argument corresponding to the format string. -(The arguments are numbered from 1). -@arg_idx: the index of the first of the format arguments. +@format_idx: +@arg_idx: -Expands to the GNU C format function attribute if the compiler is GNU C. -This is used for declaring functions which take a variable number of -arguments, with the same syntax as scanf(). -It allows the compiler to type-check the arguments passed to the function. -See the GNU C documentation for details. + -@format_idx: the index of the argument corresponding to the format string. -(The arguments are numbered from 1). -@arg_idx: the index of the first of the format arguments. +@format_idx: +@arg_idx: -Expands to the GNU C format_arg function attribute if the compiler is GNU C. -This is used for declaring functions which take a variable number of -parameters, like printf() and -scanf(). See the GNU C documentation for details. -FIXME: I can't find this in my GNU C documentation. Take out? -@arg_idx: the index of the argument. +@arg_idx: -Expands to the GNU C __FUNCTION__ variable if the compiler is GNU C, -or "" if it isn't. -The GNU C __FUNCTION__ variable contains the name of the current function. -See the GNU C documentation for details. + -Expands to the GNU C __PRETTY_FUNCTION__ variable if the compiler is GNU C, -or "" if it isn't. -The GNU C __PRETTY_FUNCTION__ variable contains the name of the current -function. For a C program this is the same as the __FUNCTION__ variable -but for C++ it also includes extra information such as the class -and function prototype. See the GNU C documentation for details. + - + -Turns the argument into a string literal by using the '#' stringizing operator. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -@x: text to convert to a literal string. diff --git a/docs/reference/glib/tmpl/main.sgml b/docs/reference/glib/tmpl/main.sgml index e97e91a5d..7c12f1e8c 100644 --- a/docs/reference/glib/tmpl/main.sgml +++ b/docs/reference/glib/tmpl/main.sgml @@ -2,321 +2,196 @@ The Main Event Loop -manages all available sources of events. + -The main event loop manages all the available sources of events for GLib -and GTK+ applications. These events can come from any number of different -types of sources such as file descriptors (plain files, pipes or sockets) -and timeouts. -New types of event sources can also be added using g_source_add(). - - -Each event source is assigned a priority. -The default priority, #G_PRIORITY_DEFAULT, is 0. -Values less than 0 denote higher priorities. -Values greater than 0 denote lower priorities. -Events from high priority sources -are always processed before events from lower priority sources. - - -Idle functions can also be added, and assigned a priority. These will be -run whenever no events with a higher priority are ready to be processed. - - -The #GMainLoop data type represents a main event loop. -A #GMainLoop is created with g_main_new(). After adding the initial event -sources, g_main_run() is called. This continuously checks for new events -from each of the event sources and dispatches them. -Finally, the processing of an event from one of the sources leads to a call -to g_main_quit() to exit the main loop, and g_main_run() returns. - - -It is possible to create new instances of #GMainLoop recursively. -This is often used in GTK+ applications when showing modal dialog boxes. -However, all event sources are global; they are not tied to a particular -#GMainLoop. - - -GTK+ contains wrappers of many of these functions, -e.g. gtk_main(), gtk_main_quit(), gtk_events_pending(), gtk_idle_add(), -gtk_timeout_add() and gtk_input_add_full(). -In a GTK+ application, these wrapper functions should be used instead. + + + -The #GMainLoop struct is an opaque data type representing the main event loop -of a GLib or GTK+ application. + -Creates a new #GMainLoop. + -@is_running: set to TRUE to indicate that the loop is running. This is not -very important since calling g_main_run() will set this to TRUE anyway. -@Returns: a new #GMainLoop. +@is_running: +@Returns: -Frees the memory allocated for the #GMainLoop. + -@loop: a #GMainLoop. +@loop: -Runs a main loop until it stops running, which occurs when g_main_quit() -is called. + -@loop: a #GMainLoop. +@loop: -Returns TRUE if the main loop is running. + -@loop: a #GMainLoop. -@Returns: TRUE if the main loop is running. +@loop: +@Returns: -Returns TRUE if any events are pending (i.e. ready to be processed). + -@Returns: TRUE if any events are pending. +@Returns: -Runs a single iteration of the main loop. -This will check which event sources are ready to be processed, and will -process the highest priority event sources which are ready. + -@may_block: set to TRUE if it should block (i.e. wait) until an event source -becomes ready. It will return after an event source has been processed. -If set to FALSE it will return immediately if no event source is ready to be -processed. -@Returns: TRUE if more events are pending. +@may_block: +@Returns: -Stops the #GMainLoop. If g_main_run() was called to run the #GMainLoop, -it will now return. + -@loop: a #GMainLoop. +@loop: -Use this for high priority event sources. -It is not used within GLib or GTK+. + -Use this for default priority event sources. -In GLib this priority is used when adding timeout functions with -g_timeout_add(). -In GDK this priority is used for events from the X Windows server. + -Use this for high priority idle functions. -GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, and -#G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is done to -ensure that any pending resizes are processed before any pending redraws, -so that widgets are not redrawn twice unnecessarily.) + -Use this for default priority idle functions. -In GLib this priority is used when adding idle functions with g_idle_add(). + -Use this for very low priority background tasks. -It is not used within GLib or GTK+. + -Sets a function to be called at regular intervals, with the default priority, -#G_PRIORITY_DEFAULT. -The function is called repeatedly until it returns FALSE, at which point -the timeout is automatically destroyed and the function will not be called -again. -The first call to the function will be at the end of the first @interval. - - -Note that timeout functions may be delayed, due to the processing of other -event sources. Thus they should not be relied on for precise timing. -After each call to the timeout function, the time of the next -timeout is recalculated based on the current time and the given interval -(it does not try to 'catch up' time lost in delays). + -@interval: the time between calls to @function, in milliseconds (1/1000ths -of a second.) -@function: the function to call at each interval. -@data: data to pass to @function. -@Returns: the id of the event source. +@interval: +@function: +@data: +@Returns: -Sets a function to be called at regular intervals, with the given priority. -The function is called repeatedly until it returns FALSE, at which point -the timeout is automatically destroyed and the function will not be called -again. -The @notify function is called when the timeout is destroyed. -The first call to the function will be at the end of the first @interval. - - -Note that timeout functions may be delayed, due to the processing of other -event sources. Thus they should not be relied on for precise timing. -After each call to the timeout function, the time of the next -timeout is recalculated based on the current time and the given interval -(it does not try to 'catch up' time lost in delays). + -@priority: the priority of the function. See #G_PRIORITY_DEFAULT, -#G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH, #G_PRIORITY_HIGH_IDLE, and -#G_PRIORITY_LOW. -@interval: the time between calls to the function, in milliseconds (1/1000ths -of a second.) -@function: the function to call at each interval. -@data: data to pass to @function (and @notify). -@notify: the function to call when the timeout is destroyed, or NULL. -@Returns: the id of event source. +@priority: +@interval: +@function: +@data: +@notify: +@Returns: -Specifies the type of function passed to g_timeout_add(), g_timeout_add_full(), -g_idle_add(), and g_idle_add_full(). + -@data: data passed to the function, set when the source was created with one -of the above functions. -@Returns: it should return FALSE if the source should be removed. +@data: +@Returns: -Adds a function to be called whenever there are no higher priority events -pending. The function is given the default idle priority, -#G_PRIORITY_DEFAULT_IDLE. -If the function returns FALSE it is automatically removed from the list of -event sources and will not be called again. + -@function: the function to call. -@data: data to pass to the function. -@Returns: the id of the event source. +@function: +@data: +@Returns: -Adds a function to be called whenever there are no higher priority events -pending. -If the function returns FALSE it is automatically removed from the list of -event sources and will not be called again. + -@priority: the priority of the idle function, which should be somewhere around -#G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. -@function: the function to call. -@data: data to pass to the function. -@destroy: the function to call when the timeout is destroyed, or NULL. -@Returns: the id of the event source. +@priority: +@function: +@data: +@destroy: +@Returns: -Removes the idle function with the given data. + -@data: the data which is passed to the idle function. -@Returns: TRUE if the idle function was found. +@data: +@Returns: -Adds a file descriptor to be polled. -This is usually combined with g_source_add() to add an event source. -The event source's check function will typically test the revents -field in the #GPollFD struct and return TRUE if events need to be processed. + -@fd: a #GPollFD, which is a file descriptor together with a bitwise -combination of #GIOCondition flags determining which events to poll for. -@priority: the priority of the poll, which should be the same as the priority -used for g_source_add() to ensure that the file descriptor is polled whenever -the results may be needed. -See #G_PRIORITY_DEFAULT, #G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH, -#G_PRIORITY_HIGH_IDLE, and #G_PRIORITY_LOW. +@fd: +@priority: - - - - - -#gint fd; -the file descriptor to poll (or a HANDLE on Win32 platforms). - - - -#gushort events; -a bitwise combination of flags from #GIOCondition, specifying which -events should be polled for. Typically for reading from a file descriptor -you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use -%G_IO_OUT | %G_IO_ERR. - - - - -#gushort revents; -a bitwise combination of flags from #GIOCondition, returned from the -poll() function to indicate which events occurred. - - - - @fd: @@ -325,128 +200,56 @@ poll() function to indicate which events occurred. -Removes a file descriptor from the list being polled. + -@fd: the #GPollFD to remove. +@fd: -Sets the function to use to handle polling of file descriptors. -It will be used instead of the poll() system call -(or GLib's replacement function, which is used where -poll() isn't available). - - -This function could possibly be used to integrate the GLib event loop -with an external event loop. + -@func: the function to call to poll all file descriptors. +@func: + + + + + + + +@Returns: -Specifies the type of function passed to g_main_set_poll_func(). -The semantics of the function should match those of the -poll() system call. + -@ufds: an array of #GPollFD elements. -@nfsd: the number of elements in @ufds. -@timeout: the maximum time to wait for an event of the file descriptors. -@Returns: the number of #GPollFD elements which have events or errors reported, -or -1 if an error occurred. +@ufds: +@nfsd: +@timeout: +@Returns: -Adds an event source to the main loop. + -@priority: the priority of the event source. See #G_PRIORITY_DEFAULT, -#G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH, #G_PRIORITY_HIGH_IDLE, and -#G_PRIORITY_LOW. -@can_recurse: if it is safe to call the source functions recursively. -@funcs: the functions to handle the source. -@source_data: data specific to the type of event source. -@user_data: user data which will be passed to the user function handling the -source. -@notify: the function to call when the source is destroyed. -@Returns: the id of the event source. +@priority: +@can_recurse: +@funcs: +@source_data: +@user_data: +@notify: +@Returns: -The #GSourceFuncs struct contains a table of functions used to handle -event sources in a generic manner. - - - - - -prepare - -Called before all the file descriptors are polled. -If the source can determine that it is ready here (without waiting for the -results of the poll() call) it should return TRUE. -It can also return a @timeout value which should be the maximum timeout -(in milliseconds) which should be passed to the poll() call. -The actual timeout used will be -1 if all sources returned -1, or it will -be the minimum of all the @timeout values returned which were >= 0. - - - - -check - -Called after all the file descriptors are polled. -The source should return TRUE if it is ready to be processed. -Note that some time may have passed since the previous prepare function was -called, so the source should be checked again here. - - - - -dispatch - -Called to process the event source, after it has returned TRUE in either -its @prepare or its @check function. - - - - -destroy - -Called when the source is destroyed. It will be called with the user data -parameter passed to the g_source_add() and related functions. - - - - - - -For idle sources, the prepare and check functions always return TRUE to -indicate that the source is always ready to be processed. -The prepare function also returns a timeout value of 0 to ensure that the -poll() call doesn't block (since that would be time wasted which could have -been spent running the idle function). - - -For timeout sources, the prepare and check functions both return TRUE if the -timeout interval has expired. -The prepare function also returns a timeout value to ensure that the poll() -call doesn't block too long and miss the next timeout. - - -For file descriptor sources, the prepare function typically returns FALSE, -since it must wait until poll() has been called before it knows whether any -events need to be processed. It sets the returned timeout to -1 to indicate -that it doesn't mind how long the poll() call blocks. -In the check function, it tests the results of the poll() call to see if -the required condition has been met, and returns TRUE if so. @prepare: @@ -456,55 +259,38 @@ the required condition has been met, and returns TRUE if so. -Removes the event source with the given id. -The id is returned when the source is created, either directly with -g_source_add(), or indirectly with g_idle_add(), g_idle_add_full(), -g_timeout_add() and g_timeout_add_full(). + -@tag: the id of the event source to remove. -@Returns: TRUE if the source was found and removed. +@tag: +@Returns: -Removes the first event source found with the given #GSourceFuncs and user -data. - - -Event sources are sorted with the highest priority first. Sources with equal -priority are stored in the order in which they were added. + -@funcs: the #GSourceFuncs of the source to remove. -@user_data: the user data of the source to remove. -@Returns: TRUE if an event source was found and removed. +@funcs: +@user_data: +@Returns: -Removes the first event source found with the given source data. - - -Event sources are sorted with the highest priority first. Sources with equal -priority are stored in the order in which they were added. + -@source_data: the source data, which contains information specific to the -type of source. -@Returns: TRUE if an event source was found and removed. +@source_data: +@Returns: -Removes the first event source found with the given user data. - - -Event sources are sorted with the highest priority first. Sources with equal -priority are stored in the order in which they were added. + -@user_data: the user data of the source to remove. -@Returns: TRUE if an event source was found and removed. +@user_data: +@Returns: diff --git a/docs/reference/glib/tmpl/memory.sgml b/docs/reference/glib/tmpl/memory.sgml index 4a6e1b434..c1f236d4e 100644 --- a/docs/reference/glib/tmpl/memory.sgml +++ b/docs/reference/glib/tmpl/memory.sgml @@ -2,155 +2,116 @@ Memory Allocation -general memory-handling. + -These functions provide support for allocating and freeing memory. + - - -If any call to allocate memory fails, the application is terminated. -This also means that there is no need to check if the call succeeded. - - + + -Allocates @count elements of type @type. -The returned pointer is cast to a pointer to the given type. -If @count is 0 it returns NULL. + -@type: the type of the elements to allocate. -@count: the number of elements to allocate. -@Returns: a pointer to the allocated memory, cast to a pointer to @type. +@type: +@count: -Allocates @count elements of type @type, initialized to 0's. -The returned pointer is cast to a pointer to the given type. -If @count is 0 it returns NULL. + -@type: the type of the elements to allocate. -@count: the number of elements to allocate. -@Returns: a pointer to the allocated memory, cast to a pointer to @type. +@type: +@count: -Reallocates the memory pointed to by @mem, so that it now has space for -@count elements of type @type. It returns the new address of the memory, -which may have been moved. + -@type: the type of the elements to allocate. -@mem: the currently allocated memory. -@count: the number of elements to allocate. -@Returns: a pointer to the new allocated memory, cast to a pointer to @type. +@type: +@mem: +@count: -Allocates @size bytes of memory. -If @size is 0 it returns NULL. + -@size: the number of bytes to allocate. -@Returns: a pointer to the allocated memory. +@size: +@Returns: -Allocates @size bytes of memory, initialized to 0's. -If @size is 0 it returns NULL. + -@size: the number of bytes to allocate. -@Returns: a pointer to the allocated memory. +@size: +@Returns: -Reallocates the memory pointed to by @mem, so that it now has space for -@size bytes of memory. It returns the new address of the memory, which may -have been moved. + -@mem: the memory to reallocate. -@size: the new size of the allocated memory, in bytes. -@Returns: the new address of the allocated memory. +@mem: +@size: +@Returns: -Frees the memory pointed to by @mem. -If @mem is NULL it simply returns. + -@mem: the memory to free. +@mem: -Copies a block of memory @n bytes long, from @s to @d. -The source and destination areas may overlap. - - - -On architectures where memmove() is not available, this function is implemented -using bcopy(), which may not be able to handle overlapping areas. - - -@d: the destination address to copy the bytes to. -@s: the source address to copy the bytes from. -@n: the number of bytes to copy. + + +@d: +@s: +@n: -Allocates @byte_size bytes of memory, and copies @byte_size bytes into it -from @mem. If @mem is NULL it returns NULL. + -@mem: the memory to copy. -@byte_size: the number of bytes to copy. -@Returns: a pointer to the newly allocated copy of the memory, or NULL if @mem -is NULL. +@mem: +@byte_size: +@Returns: -Outputs a summary of memory usage. -To use this function you must configure glib with the flag -'--enable-mem-profile=yes' before compiling. - - -It outputs the frequency of allocations of different sizes, -the total number of bytes which have been allocated, -the total number of bytes which have been freed, -and the difference between the previous two values, i.e. the number of bytes -still in use. + -Checks if the given memory has already been freed. If it has it outputs -a warning message. -To use this function you must configure glib with the flag -'--enable-mem-check=yes' before compiling. + -@mem: the memory to check. +@mem: diff --git a/docs/reference/glib/tmpl/memory_chunks.sgml b/docs/reference/glib/tmpl/memory_chunks.sgml index 2f33963b9..3f2f596d6 100644 --- a/docs/reference/glib/tmpl/memory_chunks.sgml +++ b/docs/reference/glib/tmpl/memory_chunks.sgml @@ -2,302 +2,159 @@ Memory Chunks -efficient way to allocate groups of equal-sized chunks of memory. + -Memory chunks provide an efficient way to allocate equal-sized pieces of -memory, called atoms. They are used extensively within GLib itself. -For example, the -Doubly Linked Lists -use memory chunks to allocate space for elements of the lists. - - -There are two types of memory chunks, #G_ALLOC_ONLY, and #G_ALLOC_AND_FREE. - - -#G_ALLOC_ONLY chunks only allow allocation of atoms. The atoms can never -be freed individually. The memory chunk can only be free in its entirety. - - -#G_ALLOC_AND_FREE chunks do allow atoms to be freed individually. -The disadvantage of this is that the memory chunk has to keep track of which -atoms have been freed. This results in more memory being used and a slight -degradation in performance. - - - - -To create a memory chunk use g_mem_chunk_new() or the convenience macro -g_mem_chunk_create(). - - -To allocate a new atom use g_mem_chunk_alloc(), g_mem_chunk_alloc0(), -or the convenience macros g_chunk_new() or g_chunk_new0(). - - -To free an atom use g_mem_chunk_free(), or the convenience macro -g_chunk_free(). (Atoms can only be freed if the memory chunk is created -with the type set to #G_ALLOC_AND_FREE.) - - -To free any blocks of memory which are no longer being used, use -g_mem_chunk_clean(). To clean all memory chunks, use g_blow_chunks(). - - -To reset the memory chunk, freeing all of the atoms, use g_mem_chunk_reset(). - - -To destroy a memory chunk, use g_mem_chunk_destroy(). - - -To help debug memory chunks, use g_mem_chunk_info() and g_mem_chunk_print(). - -Using a GMemChunk. - - GMemChunk *mem_chunk; - gchar *mem[10000]; - gint i; - - /* Create a GMemChunk with atoms 50 bytes long, and memory blocks holding - 100 bytes. Note that this means that only 2 atoms fit into each memory - block and so isn't very efficient. */ - mem_chunk = g_mem_chunk_new ("test mem chunk", 50, 100, G_ALLOC_AND_FREE); - - /* Now allocate 10000 atoms. */ - for (i = 0; i < 10000; i++) - { - mem[i] = g_chunk_new (gchar, mem_chunk); - - /* Fill in the atom memory with some junk. */ - for (j = 0; j < 50; j++) - mem[i][j] = i * j; - } - - /* Now free all of the atoms. Note that since we are going to destroy the - GMemChunk, this wouldn't normally be used. */ - for (i = 0; i < 10000; i++) - { - g_mem_chunk_free (mem_chunk, mem[i]); - } - - /* We are finished with the GMemChunk, so we destroy it. */ - g_mem_chunk_destroy (mem_chunk); - - - -Using a GMemChunk with data structures. - - GMemChunk *array_mem_chunk; - GRealArray *array; - - /* Create a GMemChunk to hold GRealArray structures, using the - g_mem_chunk_create() convenience macro. We want 1024 atoms in each - memory block, and we want to be able to free individual atoms. */ - array_mem_chunk = g_mem_chunk_create (GRealArray, 1024, G_ALLOC_AND_FREE); - - /* Allocate one atom, using the g_chunk_new() convenience macro. */ - array = g_chunk_new (GRealArray, array_mem_chunk); - - /* We can now use array just like a normal pointer to a structure. */ - array->data = NULL; - array->len = 0; - array->alloc = 0; - array->zero_terminated = (zero_terminated ? 1 : 0); - array->clear = (clear ? 1 : 0); - array->elt_size = elt_size; - - /* We can free the element, so it can be reused. */ - g_chunk_free (array, array_mem_chunk); - - /* We destroy the GMemChunk when we are finished with it. */ - g_mem_chunk_destroy (array_mem_chunk); - + -The #GMemChunk struct is an opaque data structure representing a memory -chunk. It should be accessed only through the use of the following functions. + -Specifies the type of a #GMemChunk. -Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms -will be freed individually. + -Specifies the type of a #GMemChunk. -Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms -will never be freed individually. + -Creates a new #GMemChunk. + -@name: a string to identify the #GMemChunk. It is not copied so it -should be valid for the lifetime of the #GMemChunk. It is only used in -g_mem_chunk_print(), which is used for debugging. -@atom_size: the size, in bytes, of each element in the #GMemChunk. -@area_size: the size, in bytes, of each block of memory allocated to contain -the atoms. -@type: the type of the #GMemChunk. -#G_ALLOC_AND_FREE is used if the atoms will be freed individually. -#G_ALLOC_ONLY should be used if atoms will never be freed individually. -#G_ALLOC_ONLY is quicker, since it does not need to track free atoms, -but it obviously wastes memory if you no longer need many of the atoms. -@Returns: the new #GMemChunk. +@name: +@atom_size: +@area_size: +@type: +@Returns: -Allocates an atom of memory from a #GMemChunk. + -@mem_chunk: a #GMemChunk. -@Returns: a pointer to the allocated atom. +@mem_chunk: +@Returns: -Allocates an atom of memory from a #GMemChunk, setting the memory to 0. + -@mem_chunk: a #GMemChunk. -@Returns: a pointer to the allocated atom. +@mem_chunk: +@Returns: -Frees an atom in a #GMemChunk. -This should only be called if the #GMemChunk was created with -#G_ALLOC_AND_FREE. Otherwise it will simply return. + -@mem_chunk: a #GMemChunk. -@mem: a pointer to the atom to free. +@mem_chunk: +@mem: -Frees all of the memory allocated for a #GMemChunk. + -@mem_chunk: a #GMemChunk. +@mem_chunk: -A convenience macro for creating a new #GMemChunk. -It calls g_mem_chunk_new(), using the given type to create the #GMemChunk -name. The atom size is determined using sizeof(), and the -area size is calculated by multiplying the @pre_alloc parameter with -the atom size. + -@type: the type of the atoms, typically a structure name. -@pre_alloc: the number of atoms to store in each block of memory. -@alloc_type: the type of the #GMemChunk. -#G_ALLOC_AND_FREE is used if the atoms will be freed individually. -#G_ALLOC_ONLY should be used if atoms will never be freed individually. -#G_ALLOC_ONLY is quicker, since it does not need to track free atoms, -but it obviously wastes memory if you no longer need many of the atoms. -@Returns: the new #GMemChunk. +@type: +@pre_alloc: +@alloc_type: -A convenience macro to allocate an atom of memory from a #GMemChunk. -It calls g_mem_chunk_alloc() and casts the returned atom to a pointer to -the given type, avoiding a type cast in the source code. + -@type: the type of the #GMemChunk atoms, typically a structure name. -@chunk: a #GMemChunk. -@Returns: a pointer to the allocated atom, cast to a pointer to @type. +@type: +@chunk: -A convenience macro to allocate an atom of memory from a #GMemChunk. -It calls g_mem_chunk_alloc0() and casts the returned atom to a pointer to -the given type, avoiding a type cast in the source code. + -@type: the type of the #GMemChunk atoms, typically a structure name. -@chunk: a #GMemChunk. -@Returns: a pointer to the allocated atom, cast to a pointer to @type. +@type: +@chunk: -A convenience macro to free an atom of memory from a #GMemChunk. -It simply switches the arguments and calls g_mem_chunk_free() -It is included simply to complement the other convenience macros, g_chunk_new() -and g_chunk_new0(). + -@mem: a pointer to the atom to be freed. -@mem_chunk: a #GMemChunk. +@mem: +@mem_chunk: -Resets a GMemChunk to its initial state. -It frees all of the currently allocated blocks of memory. + -@mem_chunk: a #GMemChunk. +@mem_chunk: -Frees any blocks in a #GMemChunk which are no longer being used. + -@mem_chunk: a #GMemChunk. +@mem_chunk: -Calls g_mem_chunk_clean() on all #GMemChunk objects. + -Outputs debugging information for all #GMemChunk objects currently in use. -It outputs the number of #GMemChunk objects currently allocated, -and calls g_mem_chunk_print() to output information on each one. + -Outputs debugging information for a #GMemChunk. -It outputs the name of the #GMemChunk (set with g_mem_chunk_new()), -the number of bytes used, and the number of blocks of memory allocated. + -@mem_chunk: a #GMemChunk. +@mem_chunk: diff --git a/docs/reference/glib/tmpl/messages.sgml b/docs/reference/glib/tmpl/messages.sgml index 743a1b4dc..7d94f128f 100644 --- a/docs/reference/glib/tmpl/messages.sgml +++ b/docs/reference/glib/tmpl/messages.sgml @@ -2,38 +2,23 @@ Message Logging -versatile support for logging messages with different levels of importance. + -These functions provide support for logging error messages or messages -used for debugging. + - -There are several built-in levels of messages, defined in #GLogLevelFlags. -These can be extended with user-defined levels. - + -Defines the log domain. -For applications, this is typically left as the default NULL (or "") domain. -Libraries should define this so that any messages which they log can -be differentiated from messages from other libraries and application code. -But be careful not to define it in any public header files. - - -For example, GTK uses this in its Makefile.am: - -INCLUDES = \ - -DG_LOG_DOMAIN=\"Gtk\" - + @@ -52,33 +37,32 @@ INCLUDES = \ -GLib log levels that are considered fatal by default. + -Log level shift offset for user defined log levels (0-7 are used by GLib). + -Specifies the prototype of log handler functions. + -@log_domain: the log domain of the message. -@log_level: the log level of the message (including the fatal and recursion -flags). -@message: the message to process. -@user_data: user data, set in g_log_set_handler(). +@log_domain: +@log_level: +@message: +@user_data: -Flags specifying the level of log messages. + @G_LOG_FLAG_RECURSION: @@ -93,188 +77,149 @@ Flags specifying the level of log messages. -Logs an error or debugging message. -If the log level has been set as fatal, the abort() -function is called to terminate the program. + -@log_domain: the log domain, usually #G_LOG_DOMAIN. -@log_level: the log level, either from #GLogLevelFlags or a user-defined level. -@format: the message format. See the printf() -documentation. -@Varargs: the parameters to insert into the format string. +@log_domain: +@log_level: +@format: +@Varargs: -Logs an error or debugging message. -If the log level has been set as fatal, the abort() -function is called to terminate the program. + -@log_domain: the log domain. -@log_level: the log level. -@format: the message format. See the printf() -documentation. -@args: the parameters to insert into the format string. +@log_domain: +@log_level: +@format: +@args: -A convenience function/macro to log a normal message. + -@format: the message format. See the printf() -documentation. -@args...: the parameters to insert into the format string. +@...: -A convenience function/macro to log a warning message. + -@format: the message format. See the printf() -documentation. -@args...: the parameters to insert into the format string. +@...: + + + + + + + +@...: -A convenience function/macro to log an error message. -Error messages are always fatal, resulting in a call to -abort() to terminate the application. + -@format: the message format. See the printf() -documentation. -@args...: the parameters to insert into the format string. +@...: -Sets the log handler for a domain and a set of log levels. -To handle fatal and recursive messages the @log_levels parameter -must be combined with the G_LOG_FLAG_FATAL and G_LOG_FLAG_RECURSIVE bit flags. - - -Note that since the G_LOG_LEVEL_ERROR log level is always fatal, if you want -to set a handler for this log level you must combine it with G_LOG_FLAG_FATAL. + - -Adding a log handler for all warning messages - - g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL - | G_LOG_FLAG_RECURSIVE, my_log_handler, NULL); - - - - -@log_domain: the log domain, or NULL for the default "" application domain. -@log_levels: the log levels to apply the log handler for. To handle fatal -and recursive messages as well, combine the log levels with the -G_LOG_FLAG_FATAL and G_LOG_FLAG_RECURSIVE bit flags. -@log_func: the log handler function. -@user_data: data passed to the log handler. -@Returns: the id of the new handler. +@log_domain: +@log_levels: +@log_func: +@user_data: +@Returns: -Removes the log handler. + -@log_domain: the log domain. -@handler_id: the id of the handler, which was returned in g_log_set_handler(). +@log_domain: +@handler_id: -Sets the message levels which are always fatal, in any log domain. -When a message with any of these levels is logged the program terminates. -You can only set the levels defined by GLib to be fatal. -%G_LOG_LEVEL_ERROR is always fatal. + -@fatal_mask: the mask containing bits set for each level of error which is -to be fatal. -@Returns: the old fatal mask. +@fatal_mask: +@Returns: -Sets the log levels which are fatal in the given domain. -%G_LOG_LEVEL_ERROR is always fatal. + -@log_domain: the log domain. -@fatal_mask: the new fatal mask. -@Returns: the old fatal mask for the log domain. +@log_domain: +@fatal_mask: +@Returns: -The default log handler. -This is used if no log handler has been set for the particular log domain -and log level combination. It outputs the message to stderr or stdout -and if the log level is fatal it calls abort(). - - -stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, and -%G_LOG_LEVEL_WARNING. stdout is used for the rest. -(On the Windows platform, stdout is always used.) + -@log_domain: the log domain of the message. -@log_level: the level of the message. -@message: the message. -@unused_data: data passed from g_log which is unused. +@log_domain: +@log_level: +@message: +@unused_data: -Sets the function to be called to handle error messages. -This function is deprecated in favour of the new logging facilities. + -@func: the function to be called to handle error messages. -@Returns: the old error handler. +@func: +@Returns: -Specifies the type of function passed to g_set_error_handler(). + -@str: the error message. +@str: -Sets the function to be called to handle warning messages. -This function is deprecated in favour of the new logging facilities. + -@func: the function to be called to handle warning messages. -@Returns: the old warning handler. +@func: +@Returns: -Specifies the type of function passed to g_set_warning_handler(). + -@str: the warning message. +@str: -Sets the function to be called to handle messages. -This function is deprecated in favour of the new logging facilities. + -@func: the function to be called to handle normal messages. -@Returns: the old message handler. +@func: +@Returns: diff --git a/docs/reference/glib/tmpl/misc_utils.sgml b/docs/reference/glib/tmpl/misc_utils.sgml index eaa873634..5576e1a5d 100644 --- a/docs/reference/glib/tmpl/misc_utils.sgml +++ b/docs/reference/glib/tmpl/misc_utils.sgml @@ -2,213 +2,217 @@ Miscellaneous Utility Functions -a selection of portable utility functions. + -These are portable utility functions. + + + -Gets the name of the program. -(If you are using GDK or GTK the program name is set in gdk_init(), which -is called by gtk_init(). The program name is found by taking the last -component of argv[0].) + -@Returns: the name of the program. +@Returns: -Sets the name of the program. + -@prgname: the name of the program. +@prgname: -Returns an environment variable. -On windows systems the returned value is only valid until the next call to -g_getenv(). + -@variable: the environment variable to get. -@Returns: the value of the environment variable, or NULL if the environment -variable is not found. +@variable: +@Returns: -Gets the user name of the current user. + -@Returns: the user name of the current user. +@Returns: -Gets the real name of the user. This comes from the user's entry in the -passwd file. + -@Returns: the user's real name. +@Returns: -Gets the current user's home directory. + -@Returns: the current user's home directory. +@Returns: -Gets the directory to use for temporary files. -This is found from inspecting the environment variables TMPDIR, TMP, and TEMP -in that order. If none of those are defined "/tmp" is returned. + -@Returns: the directory to use for temporary files. +@Returns: -Gets the current directory. -The returned string should be freed when no longer needed. + -@Returns: the current directory. +@Returns: -Gets the name of the file without any leading directory components. -It returns a pointer into the given file name string. + -@file_name: the name of the file. -@Returns: the name of the file without any leading directory components. +@file_name: +@Returns: -Gets the directory components of a file name. -If the file name has no directory components "." is returned. -The returned string should be freed when no longer needed. + -@file_name: the name of the file. -@Returns: the directory components of the file. +@file_name: +@Returns: -Returns TRUE if the given @file_name is an absolute file name, -i.e. it contains a full path from the root directory such as '/usr/local' -or 'C:/windows' on windows systems. + -@file_name: a file name. -@Returns: TRUE if @file_name is an absolute path. +@file_name: +@Returns: -Returns a pointer into @file_name after the root component, i.e. after -the '/' in Unix or 'C:/' under Windows. If @file_name is not an absolute -path it returns NULL. + -@file_name: a file name. -@Returns: a pointer into @file_name after the root component. +@file_name: +@Returns: + + + + + + + +@file_name: +@Returns: + + + + + + + +@file_name: +@Returns: + + + + + + + +@opsysstring: +@Returns: + + + + + + + +@utf8string: +@Returns: -Find the position of the first bit set in @mask, searching from (but not -including) @nth_bit upwards. Bits are numbered from 0 (least significant) -to 31. To start searching from the 0th bit, set @nth_bit to -1. + -@mask: a #guint32 containing up to 32 bit flags. -@nth_bit: the index of the bit to start the search from. -@Returns: the index of the first bit set which is higher than @nth_bit. +@mask: +@nth_bit: +@Returns: -Find the position of the first bit set in @mask, searching from (but not -including) @nth_bit downwards. Bits are numbered from 0 (least significant) -to 31. To start searching from the 31st bit, set @nth_bit to 32 or -1. + -@mask: a #guint32 containing up to 32 bit flags. -@nth_bit: the index of the bit to start the search from. -@Returns: the index of the first bit set which is lower than @nth_bit. +@mask: +@nth_bit: +@Returns: -Gets the number of bits used to hold @number, -e.g. if @number is 4, 3 bits are needed. + -@number: a guint. -@Returns: the number of bits used to hold @number. +@number: +@Returns: -Gets the smallest prime number from a built-in array of primes which -is larger than @num. This is used within GLib to calculate the optimum -size of a #GHashTable. - - -The built-in array of primes ranges from 11 to 13845163 such that -each prime is approximately 1.5-2 times the previous prime. + -@num: a guint. -@Returns: the smallest prime number from a built-in array of primes which is -larger than @num. +@num: +@Returns: -Specifies a function to be called at normal program termination. + -@func: the function to call on normal program termination. +@func: -Parses a string containing debugging options separated by ':' into a guint -containing bit flags. -This is used within GDK and GTK to parse the debug options passed on the -command line or through environment variables. + -@string: a list of debug options separated by ':' or "all" to set all flags. -@keys: pointer to an array of #GDebugKey which associate strings with -bit flags. -@nkeys: the number of #GDebugKey in the array. -@Returns: the combined set of bit flags. +@string: +@keys: +@nkeys: +@Returns: -Associates a string with a bit flag. -Used in g_parse_debug_string(). + @key: @@ -216,16 +220,14 @@ Used in g_parse_debug_string(). -Declares a type of function which takes no arguments and has no return value. -It is used to specify the type function passed to g_atexit(). + -Declares a type of function which takes an arbitrary data pointer argument -and has no return value. It is not currently used in GLib or GTK+. + @data: diff --git a/docs/reference/glib/tmpl/modules.sgml b/docs/reference/glib/tmpl/modules.sgml index f3d0ba83e..ec1f92a23 100644 --- a/docs/reference/glib/tmpl/modules.sgml +++ b/docs/reference/glib/tmpl/modules.sgml @@ -2,105 +2,57 @@ Dynamic Loading of Modules -portable method for dynamically loading 'plug-ins'. + -These functions provide a portable way to dynamically load object files -(commonly known as 'plug-ins'). -The current implementation supports all systems that provide -an implementation of dlopen() (e.g. Linux/Sun), as well as HP-UX via its -shl_load() mechanism, and Windows platforms via DLLs. - - -To use them you must first determine whether dynamic loading -is supported on the platform by calling g_module_supported(). -If it is, you can open a module with g_module_open(), -find the module's symbols (e.g. function names) with g_module_symbol(), -and later close the module with g_module_close(). -g_module_name() will return the file name of a currently opened module. - - -If any of the above functions fail, the error status can be found with -g_module_error(). - - -The gmodule implementation features reference counting for opened modules, -and supports hook functions within a module which are called when the -module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload). - - -If your module introduces static data to common subsystems in the running -program, e.g. through calling g_quark_from_static_string ("my-module-stuff"), -it must ensure that it is never unloaded, by calling g_module_make_resident(). + + + -The #GModule struct is an opaque data structure to represent a -Dynamically-Loaded Module. -It should only be accessed via the following functions. + -Checks if modules are supported on the current platform. + -@Returns: TRUE if modules are supported. +@Returns: -A portable way to build the filename of a module. The platform-specific -prefix and suffix are added to the filename, if needed, and the result is -added to the directory, using the correct separator character. - - -The directory should specify the directory where the module can be found. -It can be NULL or an empty string to indicate that the module is in a standard -operating-system specific directory, though this is not recommended since the -wrong module may be found. - - -For example, calling g_module_build_path() on a Linux system with a directory -of "/lib" and a module_name of "mylibrary" will return "/lib/libmylibrary.so". -On a Windows system, using "\Windows" as the directory it will return -"\Windows\mylibrary.dll". + -@directory: the directory where the module is. This can be NULL or the empty -string to indicate that the standard operating system-specific directories -will be used, though that is not recommended. -@module_name: the name of the module. -@Returns: the complete path of the module, including the standard library -prefix and suffix. This should be freed when no longer needed. +@directory: +@module_name: +@Returns: -Opens a module. -If the module has already been opened, its reference count is incremented. + -@file_name: the name of the file containing the module. -@flags: the flags used for opening the module. Currently this can be 0 or -G_MODULE_BIND_LAZY for lazy binding, where symbols are only bound when needed. -@Returns: a #GModule on success, or NULL on failure. +@file_name: +@flags: +@Returns: -Flags passed to g_module_open(). -G_MODULE_BIND_LAZY specifies that symbols are only resolved when needed. -The default action is to bind all symbols when the module is loaded. -(G_MODULE_BIND_LAZY is not supported on all platforms.) + @G_MODULE_BIND_LAZY: @@ -108,85 +60,76 @@ The default action is to bind all symbols when the module is loaded. -Gets a symbol pointer from a module. + -@module: the module. -@symbol_name: the name of the symbol to find. -@symbol: returns the pointer to the symbol value. -@Returns: TRUE on success. +@module: +@symbol_name: +@symbol: +@Returns: -Gets the file name from a #GModule. + -@module: the module. -@Returns: the file name of the module, or "main" if the module is the main -program itself. +@module: +@Returns: -Ensures that a module will never be unloaded. -Any future g_module_close() calls on the module will be ignored. + -@module: a module to make permanently resident. +@module: -Closes a module. + -@module: the module to close. -@Returns: TRUE on success. +@module: +@Returns: -Gets a string describing the last module error. + -@Returns: a string describing the last module error. +@Returns: -Specifies the type of the module initialization function. -If a module contains a function named g_module_check_init() it is called -automatically when the module is loaded. It is passed the #GModule structure -and should return NULL on success or a string describing the initialization -error. + -@module: the #GModule corresponding to the module which has just been loaded. -@Returns: NULL on success, or a string describing the initialization error. +@module: +@Returns: -Specifies the type of the module function called when it is unloaded. -If a module contains a function named g_module_unload() it is called -automatically when the module is unloaded. -It is passed the #GModule structure. + -@module: the module about to be unloaded. +@module: -Used to declare functions exported by modules. + -Used to declare functions imported from modules. + diff --git a/docs/reference/glib/tmpl/quarks.sgml b/docs/reference/glib/tmpl/quarks.sgml index b62e032aa..997e336a6 100644 --- a/docs/reference/glib/tmpl/quarks.sgml +++ b/docs/reference/glib/tmpl/quarks.sgml @@ -2,90 +2,59 @@ Quarks -a 2-way association between a string and a unique integer identifier. + -Quarks are associations between strings and integer identifiers. -Given either the string or the #GQuark identifier it is possible to -retrieve the other. - - -Quarks are used for both -Datasets and -Keyed Data Lists. - - -To create a new quark from a string, use g_quark_from_string() or -g_quark_from_static_string(). - - -To find the string corresponding to a given #GQuark, use g_quark_to_string(). - - -To find the #GQuark corresponding to a given string, use g_quark_try_string(). + + + -A GQuark is an integer which uniquely identifies a particular string. + -Gets the #GQuark identifying the given string. -If the string does not currently have an associated #GQuark, a new -#GQuark is created, using a copy of the string. + -@string: a string. -@Returns: the #GQuark identifying the string. +@string: +@Returns: -Gets the #GQuark identifying the given (static) string. -If the string does not currently have an associated #GQuark, a new -#GQuark is created, linked to the given string. - - -Note that this function is identical to g_quark_from_string() except -that if a new #GQuark is created the string itself is used rather than -a copy. This saves memory, but can only be used if the string will -always exist (if, for example, it is a statically-allocated string). + -@string: a string. -@Returns: the #GQuark identifying the string. +@string: +@Returns: -Gets the string associated with the given #GQuark. + -@quark: a #GQuark. -@Returns: the string associated with the #GQuark. +@quark: +@Returns: -Gets the #GQuark associated with the given string, or 0 if the string has -no associated #GQuark. - - -If you want the GQuark to be created if it doesn't already exist, use -g_quark_from_string() or g_quark_from_static_string(). + -@string: a string. -@Returns: the #GQuark associated with the string, or 0 if there is no -#GQuark associated with the string. +@string: +@Returns: diff --git a/docs/reference/glib/tmpl/relations.sgml b/docs/reference/glib/tmpl/relations.sgml index 4c1dd6110..7bf216f54 100644 --- a/docs/reference/glib/tmpl/relations.sgml +++ b/docs/reference/glib/tmpl/relations.sgml @@ -2,200 +2,137 @@ Relations and Tuples -tables of data which can be indexed on any number of fields. + -A #GRelation is a table of data which can be indexed on any number of fields, -rather like simple database tables. A #GRelation contains a number of -records, called tuples. Each record contains a number of fields. -Records are not ordered, so it is not possible to find the record at a -particular index. - - -Note that #GRelation tables are currently limited to 2 fields. - - -To create a GRelation, use g_relation_new(). - - -To specify which fields should be indexed, use g_relation_index(). -Note that this must be called before any tuples are added to the #GRelation. - - -To add records to a #GRelation use g_relation_insert(). - - -To determine if a given record appears in a #GRelation, use -g_relation_exists(). Note that fields are compared directly, so pointers -must point to the exact same position (i.e. different copies of the same -string will not match.) - - -To count the number of records which have a particular value in a given -field, use g_relation_count(). - - -To get all the records which have a particular value in a given field, -use g_relation_select(). To access fields of the resulting records, -use g_tuples_index(). To free the resulting records use g_tuples_destroy(). - - -To delete all records which have a particular value in a given field, -use g_relation_delete(). - - -To destroy the #GRelation, use g_relation_destroy(). - - -To help debug #GRelation objects, use g_relation_print(). + + + -The #GRelation struct is an opaque data structure to represent a -Relation. -It should only be accessed via the following functions. + -Creates a new #GRelation with the given number of fields. -Note that currently the number of fields must be 2. + -@fields: the number of fields. -@Returns: a new #GRelation. +@fields: +@Returns: -Creates an index on the given field. -Note that this must be called before any records are added to the #GRelation. + -@relation: a #GRelation. -@field: the field to index, counting from 0. -@hash_func: a function to produce a hash value from the field data. -@key_compare_func: a function to compare two values of the given field. +@relation: +@field: +@hash_func: +@key_compare_func: -Inserts a record into a #GRelation. + -@relation: a #GRelation. -@Varargs: the fields of the record to add. This must match the number of -fields in the #GRelation. +@relation: +@Varargs: -Returns TRUE if a record with the given values exists in a #GRelation. -Note that the values are compared directly, so that, for example, two -copies of the same string will not match. + -@relation: a #GRelation. -@Varargs: the fields of the record to compare. The number must match the -number of fields in the #GRelation. -@Returns: TRUE if a record matches. +@relation: +@Varargs: +@Returns: -Returns the number of tuples in a #GRelation that have the given value -in the given field. + -@relation: a #GRelation. -@key: the value to compare with. -@field: the field of each record to match. -@Returns: the number of matches. +@relation: +@key: +@field: +@Returns: -Returns all of the tuples which have the given key in the given field. -Use g_tuples_index() to access the returned records. -The returned records should be freed with g_tuples_destroy(). + -@relation: a #GRelation. -@key: the value to compare with. -@field: the field of each record to match. -@Returns: the records (tuples) that matched. +@relation: +@key: +@field: +@Returns: -Deletes any records from a GRelation that have the given key value in -the given field. + -@relation: a #GRelation. -@key: the value to compare with. -@field: the field of each record to match. -@Returns: the number of records deleted. +@relation: +@key: +@field: +@Returns: -Destroys the #GRelation, freeing all memory allocated. -However, it does not free memory allocated for the -tuple data, so you should free that first if appropriate. + -@relation: a #GRelation. +@relation: -Outputs information about all records in a #GRelation, as well as the indexes. -It is for debugging. + -@relation: a #GRelation. +@relation: -The #GTuples struct is used to return records (or tuples) from the -#GRelation by g_relation_select(). -It only contains one public member - the number of records that matched. -To access the matched records, you must use g_tuples_index(). + @len: -Frees the records which were returned by g_relation_select(). -This should always be called after g_relation_select() when you are -finished with the records. -The records are not removed from the #GRelation. + -@tuples: the tuple data to free. +@tuples: -Gets a field from the records returned by g_relation_select(). -It returns the given field of the record at the given index. -The returned value should not be changed. + -@tuples: the tuple data, returned by g_relation_select(). -@index: the index of the record. -@field: the field to return. -@Returns: the field of the record. +@tuples: +@index: +@field: +@Returns: diff --git a/docs/reference/glib/tmpl/scanner.sgml b/docs/reference/glib/tmpl/scanner.sgml index 9940cc028..0b42f475a 100644 --- a/docs/reference/glib/tmpl/scanner.sgml +++ b/docs/reference/glib/tmpl/scanner.sgml @@ -2,41 +2,23 @@ Lexical Scanner -a general purpose lexical scanner. + -The #GScanner and its associated functions provide a general purpose -lexical scanner. - - -FIXME: really needs an example and more detail, but I don't completely -understand it myself. Look at gtkrc.c for some code using the scanner. + + + -The data structure representing a lexical scanner. - - -You should set input_name after creating the scanner, since it is used -by the default message handler when displaying warnings and errors. -If you are scanning a file, the file name would be a good choice. - - -The user_data and -derived_data fields are not used. -If you need to associate extra data with the scanner you can place them here. - - -If you want to use your own message handler you can set the -msg_handler field. The type of the message -handler function is declared by #GScannerMsgFunc. + @user_data: @@ -63,50 +45,16 @@ handler function is declared by #GScannerMsgFunc. -Creates a new #GScanner. -The @config_templ structure specifies the initial settings of the scanner, -which are copied into the #GScanner config field. -If you pass NULL then the default settings are used. -(See g_scanner_config_template in gscanner.c for the defaults.) + -@config_templ: the initial scanner settings. -@Returns: the new #GScanner. +@config_templ: +@Returns: -Specifies the #GScanner settings. - - -cset_skip_characters specifies which characters -should be skipped by the scanner (the default is the whitespace characters: -space, tab, carriage-return and line-feed). - - -cset_identifier_first specifies the characters -which can start identifiers. -(the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z). - - -cset_identifier_nth specifies the characters -which can be used in identifiers, after the first character. -The default is #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS, -#G_CSET_LATINC. - - -cpair_comment_single specifies the characters -at the start and end of single-line comments. The default is "#\n" which -means that single-line comments start with a '#' and continue until a '\n' -(end of line). - - -case_sensitive specifies if symbols are -case sensitive. - - -The rest of the fields are flags which turn features on or off. -FIXME: should describe these. + @cset_skip_characters: @@ -137,11 +85,11 @@ FIXME: should describe these. -Prepares to scan a file. + -@scanner: a #GScanner. -@input_fd: a file descriptor. +@scanner: +@input_fd: @@ -154,122 +102,105 @@ Prepares to scan a file. -Gets the file attributes. -This is the st_mode field from the -stat structure. See the stat() -documentation. + -@filename: the file name. -@Returns: the file attributes. +@filename: +@Returns: -Prepares to scan a text buffer. + -@scanner: a #GScanner. -@text: the text buffer to scan. -@text_len: the length of the text buffer. +@scanner: +@text: +@text_len: -Gets the next token, without removing it from the input stream. -The token data is placed in the -next_token, -next_value, -next_line, and -next_position fields of the #GScanner structure. + -@scanner: a #GScanner. -@Returns: the type of the token. +@scanner: +@Returns: -Gets the next token, removing it from the input stream. -The token data is placed in the -token, -value, -line, and -position fields of the #GScanner structure. + -@scanner: a #GScanner. -@Returns: the type of the token. +@scanner: +@Returns: -Gets the current line in the input stream (counting from 1). + -@scanner: a #GScanner. -@Returns: the current line. +@scanner: +@Returns: -Gets the current position in the current line (counting from 0). + -@scanner: a #GScanner. -@Returns: the current position on the line. +@scanner: +@Returns: -Gets the current token type. -This is simply the token field in the #GScanner -structure. + -@scanner: a #GScanner. -@Returns: the current token type. +@scanner: +@Returns: -Gets the current token value. -This is simply the value field in the #GScanner -structure. + -@scanner: a #GScanner. -@Returns: the current token value. +@scanner: +@Returns: -Returns TRUE if the scanner has reached the end of the file or text buffer. + -@scanner: a #GScanner. -@Returns: TRUE if the scanner has reached the end of the file or text buffer. +@scanner: +@Returns: -Sets the current scope. + -@scanner: a #GScanner. -@scope_id: the new scope id. -@Returns: the old scope id. +@scanner: +@scope_id: +@Returns: -Adds a symbol to the given scope. + -@scanner: a #GScanner. -@scope_id: the scope id. -@symbol: the symbol to add. -@value: the value of the symbol. +@scanner: +@scope_id: +@symbol: +@value: @@ -281,8 +212,6 @@ Adds a symbol to the given scope. @scope_id: @func: @user_data: - -@func_data: @@ -334,42 +263,36 @@ Adds a symbol to the given scope. -Outputs a warning message, via the #GScanner message handler. + -@scanner: a #GScanner. -@format: the message format. See the printf() -documentation. -@Varargs: the parameters to insert into the format string. +@scanner: +@format: +@Varargs: -Outputs an error message, via the #GScanner message handler. + -@scanner: a #GScanner. -@format: the message format. See the printf() -documentation. -@Varargs: the parameters to insert into the format string. +@scanner: +@format: +@Varargs: -Outputs a message resulting from an unexpected token in the input stream. -FIXME: I don't understand the arguments here. + -@scanner: a #GScanner. -@expected_token: the expected token. -@identifier_spec: a string describing the expected type of identifier, -or NULL to use the default "identifier" string. -@symbol_spec: a string describing the expected type of identifier, -or NULL to use the default "symbol" string. +@scanner: +@expected_token: +@identifier_spec: +@symbol_spec: @symbol_name: -@message: a message string to output at the end of the warning/error, or NULL. -@is_error: if TRUE it is output as an error. If False it is output as a -warning. +@message: +@is_error: @@ -384,33 +307,31 @@ warning. -Frees all memory used by the #GScanner. + -@scanner: a #GScanner. +@scanner: -The possible types of token returned from each g_scanner_get_next_token() call. + @G_TOKEN_EOF: @G_TOKEN_LEFT_PAREN: -@G_TOKEN_RIGHT_PAREN: @G_TOKEN_LEFT_CURLY: @G_TOKEN_RIGHT_CURLY: -A union holding the value of the token. + -The possible errors, used in the v_error field -of #GTokenValue, when the token is a G_TOKEN_ERROR. + @G_ERR_UNKNOWN: @@ -424,67 +345,65 @@ of #GTokenValue, when the token is a G_TOKEN_ERROR. -The set of lower-case ASCII alphabet characters. -Used for specifying valid identifier characters in #GScannerConfig. + -The set of upper-case ASCII alphabet characters. -Used for specifying valid identifier characters in #GScannerConfig. + + + + + + + + -Part of the set of extended characters in the Latin character sets. -FIXME: lower case? -Used for specifying valid identifier characters in #GScannerConfig. + -Part of the set of extended characters in the Latin character sets. -FIXME: upper case? -Used for specifying valid identifier characters in #GScannerConfig. + -Adds a symbol to the default scope. -Deprecated in favour of g_scanner_scope_add_symbol(). + -@scanner: a #GScanner. -@symbol: the symbol to add. -@value: the value of the symbol. +@scanner: +@symbol: +@value: -Removes a symbol from the default scope. -Deprecated in favour of g_scanner_scope_remove_symbol(). + -@scanner: a #GScanner. -@symbol: the symbol to remove. +@scanner: +@symbol: -Calls a function for each symbol in the default scope. -Deprecated in favour of g_scanner_scope_foreach_symbol(). + -@scanner: a #GScanner. -@func: the function to call with each symbol. -@data: data to pass to the function. +@scanner: +@func: +@data: diff --git a/docs/reference/glib/tmpl/string_chunks.sgml b/docs/reference/glib/tmpl/string_chunks.sgml index 85961aedb..de2462828 100644 --- a/docs/reference/glib/tmpl/string_chunks.sgml +++ b/docs/reference/glib/tmpl/string_chunks.sgml @@ -2,109 +2,60 @@ String Chunks -efficient storage of groups of strings. + -String chunks are used to store groups of strings. -Memory is allocated in blocks, and as strings are added to the #GStringChunk -they are copied into the next free position in a block. When a block is -full a new block is allocated. - - -When storing a large number of strings, string chunks are more efficient -than using g_strdup() since fewer calls to malloc() -are needed, and less memory is wasted in memory allocation overheads. - - -By adding strings with g_string_chunk_insert_const() it is also possible -to remove duplicates. - - -To create a new #GStringChunk use g_string_chunk_new(). - - -To add strings to a #GStringChunk use g_string_chunk_insert(). - - -To add strings to a #GStringChunk, but without duplicating strings which are -already in the #GStringChunk, use g_string_chunk_insert_const(). - - -To free the entire #GStringChunk use g_string_chunk_free(). -It is not possible to free individual strings. + + + -An opaque data structure representing String Chunks. -It should only be accessed by using the following functions. + -Creates a new #GStringChunk. + -@size: the default size of the blocks of memory which are allocated to store -the strings. If a particular string is larger than this default size, a larger -block of memory will be allocated for it. -@Returns: a new #GStringChunk. +@size: +@Returns: -Adds a copy of @string to the #GStringChunk. -It returns a pointer to the new copy of the string in the #GStringChunk. -The characters in the string can be changed, if necessary, though you -should not change anything after the end of the string. - - -Unlike g_string_chunk_insert_const(), this function does not check for -duplicates. Also strings added with g_string_chunk_insert() will not be -searched by g_string_chunk_insert_const() when looking for duplicates. + -@chunk: a #GStringChunk. -@string: the string to add. -@Returns: a pointer to the copy of @string within the #GStringChunk. +@chunk: +@string: +@Returns: -Adds a copy of @string to the #GStringChunk, unless the same string has -already been added to the #GStringChunk with g_string_chunk_insert_const(). - - -This function is useful if you need to copy a large number of strings -but do not want to waste space storing duplicates. But you must remember -that there may be several pointers to the same string, and so any changes -made to the strings should be done very carefully. - - -Note that g_string_chunk_insert_const() will not return a pointer to a string -added with g_string_chunk_insert(), even if they do match. + -@chunk: a #GStringChunk. -@string: the string to add. -@Returns: a pointer to the new or existing copy of @string within the -#GStringChunk. +@chunk: +@string: +@Returns: -Frees all memory allocated by the #GStringChunk. -After calling g_string_chunk_free() it is not safe to -access any of the strings which were contained within it. + -@chunk: a #GStringChunk. +@chunk: diff --git a/docs/reference/glib/tmpl/string_utils.sgml b/docs/reference/glib/tmpl/string_utils.sgml index fe8566f37..2da378827 100644 --- a/docs/reference/glib/tmpl/string_utils.sgml +++ b/docs/reference/glib/tmpl/string_utils.sgml @@ -2,353 +2,321 @@ String Utility Functions -various string-related functions. + -This section describes a number of utility functions for creating, -duplicating, and manipulating strings. + + + -Duplicates a string. -The returned string should be freed when no longer needed. + -@str: the string to duplicate. -@Returns: a newly-allocated copy of @str. +@str: +@Returns: -Duplicates the first @n characters of a string, returning a newly-allocated -buffer @n + 1 characters long which will always be null-terminated. -If @str is less than @n characters long the buffer is padded with nulls. -The returned value should be freed when no longer needed. + -@str: the string to duplicate part of. -@n: the maximum number of characters to copy from @str. -@Returns: a newly-allocated buffer containing the first @n characters of @str, -null-terminated. +@str: +@n: +@Returns: -Creates a new string @length characters long filled with @fill_char. -The returned string should be freed when no longer needed. + -@length: the length of the new string. -@fill_char: the character to fill the string with. -@Returns: a newly-allocated string filled the @fill_char. +@length: +@fill_char: +@Returns: + + + + + + + +@dest: +@src: +@dest_size: +@Returns: + + + + + + + +@dest: +@src: +@dest_size: +@Returns: -Similar to the standard C sprintf() function -but safer, since it calculates the maximum space required and allocates -memory to hold the result. -The returned string should be freed when no longer needed. + -@format: the standard sprintf() format string. -@Varargs: the parameters to insert into the format string. -@Returns: a newly-allocated string holding the result. +@format: +@Varargs: +@Returns: -Similar to the standard C vsprintf() function -but safer, since it calculates the maximum space required and allocates -memory to hold the result. -The returned string should be freed when no longer needed. + -@format: the standard sprintf() format string. -@args: the list of parameters to insert into the format string. -@Returns: a newly-allocated string holding the result. +@format: +@args: +@Returns: -A safer form of the standard sprintf() function. -The output is guaranteed to not exceed @n characters (including the -terminating NULL character), so it is easy to ensure that a buffer overflow -cannot occur. - - -See also g_strdup_printf(). - - - -In versions of GLib prior to 1.2.3, this function may return -1 if the output -was truncated, and the truncated string may not be NULL-terminated. - - -@string: the buffer to hold the output. -@n: the maximum number of characters to produce (including the terminating null -character). -@format: the format string. See the sprintf() -documentation. -@Varargs: the arguments to insert in the output. -@Returns: the length of the output string. + + +@string: +@n: +@format: +@Varargs: +@Returns: -A safer form of the standard vsprintf() function. -The output is guaranteed to not exceed @n characters (including the -terminating NULL character), so it is easy to ensure that a buffer overflow -cannot occur. - - -See also g_strdup_vprintf(). - - - -In versions of GLib prior to 1.2.3, this function may return -1 if the output -was truncated, and the truncated string may not be NULL-terminated. - - -@string: the buffer to hold the output. -@n: the maximum number of characters to produce (including the terminating null -character). -@format: the format string. See the sprintf() -documentation. -@args: the list of arguments to insert in the output. -@Returns: the length of the output string. + + +@string: +@n: +@format: +@args: +@Returns: -Calculates the maximum space needed to store the output of the -sprintf() function. + -@format: the format string. See the printf() -documentation. -@args: the parameters to be inserted into the format string. -@Returns: the maximum space needed to store the formatted string. +@format: +@args: +@Returns: -Converts a string to upper case. + -@string: the string to convert. +@string: +@Returns: -Converts a string to lower case. + -@string: the string to convert. +@string: +@Returns: -A case-insensitive string comparison, corresponding to the standard -strcasecmp() function on platforms which support it. + -@s1: a string. -@s2: a string to compare with @s1. -@Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive -value if @s1 > @s2. +@s1: +@s2: +@Returns: -A case-insensitive string comparison, corresponding to the standard -strncasecmp() function on platforms which support it. -It is similar to g_strcasecmp() except it only compares the first @n characters -of the strings. + -@s1: a string. -@s2: a string to compare with @s1. -@n: the maximum number of characters to compare. -@Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive -value if @s1 > @s2. +@s1: +@s2: +@n: +@Returns: -Reverses all of the characters in a string. -For example, g_strreverse ("abcdef") would be "fedcba". + -@string: the string to reverse. +@string: +@Returns: -Converts a string to a gdouble value. -It calls the standard strtod() function -to handle the conversion, but if the string is not completely converted -it attempts the conversion again in the "C" locale, and returns the best -match. + -@nptr: the string to convert to a numeric value. -@endptr: if non-NULL, it returns the character after the last character used -in the conversion. -@Returns: the gdouble value. +@nptr: +@endptr: +@Returns: -Removes leading whitespace from a string, by moving the rest of the -characters forward. + -@string: a string to remove the leading whitespace from. -@Returns: @string. +@string: +@Returns: -Removes trailing whitespace from a string. + -@string: a string to remove the trailing whitespace from. -@Returns: @string. +@string: +@Returns: -Removes leading and trailing whitespace from a string. + -@string: a string to remove the leading and trailing whitespace from. +@string: -Converts any delimiter characters in @string to @new_delimiter. -Any characters in @string which are found in @delimiters are changed -to the @new_delimiter character. + -@string: the string to convert. -@delimiters: a string containing the current delimiters, or NULL to use the -standard delimiters defined in #G_STR_DELIMITERS. -@new_delimiter: the new delimiter character. +@string: +@delimiters: +@new_delimiter: @Returns: -The standard delimiters, used in #g_strdelimit. + -Escapes all backslash characters, '\' in a string, by inserting a second '\'. + -@string: a string to escape the backslashes in. -@Returns: a newly allocated copy of @string, with all backslash characters -escaped using a second backslash. +@source: +@exceptions: +@Returns: + + + + + + + +@source: +@Returns: + + + + + + + +@string: +@valid_chars: +@subsitutor: +@Returns: -Splits a string into a maximum of @max_tokens pieces, using the given -@delimiter. If @max_tokens is reached, the final string in the returned -string array contains the remainder of @string. + -@string: a string to split. -@delimiter: a string which specifies the places at which to split the string. -The delimiter is not included in any of the resulting strings, unless -max_tokens is reached. -@max_tokens: the maximum number of strings to split @string into. If this is -less than 1, the string is split completely. -@Returns: a newly-allocated array of strings. Use g_strfreev() to free it. +@string: +@delimiter: +@max_tokens: +@Returns: -Frees a NULL-terminated array of strings, and the array itself. + -@str_array: a NULL-terminated array of strings to free. +@str_array: -Concatenates all of the given strings into one long string. -The returned string should be freed when no longer needed. + -@string1: The first string to add, which must not be NULL. -@Varargs: a NULL-terminated list of strings to append to the string. -@Returns: a newly-allocated string containing all the string arguments. +@string1: +@Varargs: +@Returns: -Joins a number of strings together to form one long string, with the optional -@separator inserted between each of them. + -@separator: a string to insert between each of the strings, or NULL. -@Varargs: a NULL-terminated list of strings to join. -@Returns: a newly-allocated string containing all of the strings joined -together, with @separator between them. +@separator: +@Varargs: +@Returns: -Joins a number of strings together to form one long string, with the optional -@separator inserted between each of them. + -@separator: a string to insert between each of the strings, or NULL. -@str_array: a NULL-terminated array of strings to join. -@Returns: a newly-allocated string containing all of the strings joined -together, with @separator between them. +@separator: +@str_array: +@Returns: -Returns a string corresponding to the given error code, e.g. "no such process". -This function is included since not all platforms support the -strerror() function. + -@errnum: the system error number. See the standard C %errno -documentation. -@Returns: a string describing the error code. -If the error code is unknown, it returns "unknown error (<code>)". -The string can only be used until the next call to g_strerror. +@errnum: +@Returns: -Returns a string describing the given signal, e.g. "Segmentation fault". -This function is included since not all platforms support the -strsignal() function. + -@signum: the signal number. See the signal -documentation. -@Returns: a string describing the signal. -If the signal is unknown, it returns "unknown signal (<signum>)". -The string can only be used until the next call to g_strsignal. +@signum: +@Returns: diff --git a/docs/reference/glib/tmpl/strings.sgml b/docs/reference/glib/tmpl/strings.sgml index f621d180b..c9167c23e 100644 --- a/docs/reference/glib/tmpl/strings.sgml +++ b/docs/reference/glib/tmpl/strings.sgml @@ -2,35 +2,23 @@ Strings -text buffers which grow automatically as text is added. + -A #GString is similar to a standard C string, except that it grows -automatically as text is appended or inserted. - - -The space allocated for the string is always a power of two, so as the -string grows it will occupy 2, 4, 8, 16, 32, 64, 128 etc. characters. + + + -The #GString struct contains the public fields of a #GString. -The str field points to the character data. -It may move as text is added. -The len field contains the length of the string, -not including the terminating null character. - - -The str field is zero-terminated and so can be used as an ordinary C -string. But it may be moved when text is appended or inserted into the -string. + @str: @@ -38,172 +26,213 @@ string. -Creates a new #GString, initialized with the given string. + -@init: the initial text to copy into the string. -@Returns: the new #GString. +@init: +@Returns: -Creates a new GString, with enough space for @dfl_size characters. -This is useful if you are going to add a lot of text to the string and -don't want it to be reallocated too often. + -@dfl_size: the default size of the space allocated to hold the string. -@Returns: the new #GString. +@dfl_size: +@Returns: -Copies the characters from one #GString into another, destroying any previous -contents. It is rather like the standard strcpy() function, except that -you do not have to worry about having enough space to copy the string. + -@lval: the destination #GString. Its current contents are destroyed. -@rval: the source #GString. -@Returns: the destination #GString. +@string: +@rval: +@Returns: -Writes a formatted string into a #GString. -This is similar to the standard sprintf() function, -except that the GString buffer automatically expands to contain the results. -The previous contents of the GString are destroyed. + -@string: a #GString. -@format: the string format. See the sprintf() -documentation. -@Varargs: the parameters to insert into the format string. +@string: +@format: +@Varargs: -Appends a formatted string onto the end of a #GString. -This function is is similar to g_string_sprintf() except that -the text is appended to the GString. + -@string: a #GString. -@format: the string format. See the sprintf() -documentation. -@Varargs: the parameters to insert into the format string. +@string: +@format: +@Varargs: -Adds a string onto the end of a #GString, expanding it if necessary. + -@string: a #GString. -@val: the string to append onto the end of the #GString. -@Returns: the #GString. +@string: +@val: +@Returns: -Adds a character onto the end of a #GString, expanding it if necessary. + -@string: a #GString. -@c: the character to append onto the end of the #GString. -@Returns: the #GString. +@string: +@c: +@Returns: + + + + + + + +@string: +@val: +@len: +@Returns: -Adds a string on to the start of a #GString, expanding it if necessary. + -@string: a #GString. -@val: the string to prepend on the start of the #GString. -@Returns: the #GString. +@string: +@val: +@Returns: -Adds a character onto the start of a #GString, expanding it if necessary. + -@string: a #GString. -@c: the character to prepend on the start of the #GString. -@Returns: the #GString. +@string: +@c: +@Returns: + + + + + + + +@string: +@val: +@len: +@Returns: -Inserts a copy of a string into a #GString, expanding it if necessary. + -@string: a #GString. -@pos: the position to insert the copy of the string. -@val: the string to insert. -@Returns: the #GString. +@string: +@pos: +@val: +@Returns: -Inserts a character into a #GString, expanding it if necessary. + -@string: a #GString. -@pos: the position to insert the character. -@c: the character to insert. -@Returns: the #GString. +@string: +@pos: +@c: +@Returns: + + + + + + + +@string: +@pos: +@val: +@len: +@Returns: -Removes @len characters from a #GString, starting at position @pos. -The rest of the #GString is shifted down to fill the gap. + -@string: a #GString. -@pos: the position of the characters to remove. -@len: the number of characters to remove. -@Returns: the #GString. +@string: +@pos: +@len: +@Returns: -Cuts off the end of the GString, leaving the first @len characters. + -@string: a #GString. -@len: the new size of the #GString. -@Returns: the #GString. +@string: +@len: +@Returns: -Frees the memory allocated for the #GString. -If free_segment is TRUE it also frees the character data. + -@string: a #GString. -@free_segment: if TRUE the actual character data is freed as well. +@string: +@free_segment: +@Returns: -Converts a #GString to upper case. + -@string: a #GString. -@Returns: the #GString. +@string: +@Returns: -Converts a #GString to lower case. + -@string: a #GString. -@Returns: the #GString. +@string: +@Returns: + + + + + + + +@str: +@Returns: + + + + + + + +@v: +@v2: +@Returns: diff --git a/docs/reference/glib/tmpl/threads.sgml b/docs/reference/glib/tmpl/threads.sgml index 0b577d17a..dc1c24561 100644 --- a/docs/reference/glib/tmpl/threads.sgml +++ b/docs/reference/glib/tmpl/threads.sgml @@ -1,101 +1,67 @@ - Threads -thread abstraction; including mutexes, conditions and thread private data. - -Threads act almost like processes, but unlike processes all threads of -one process share the same memory. This is good, as it provides easy -communication between the involved threads via this shared memory, and -it is bad, because strange things (so called Heisenbugs) might happen, -when the program is not carefully designed. Especially bad is, that due -to the concurrent nature of threads no assumptions on the order of -execution of different threads can be done unless explictly forced by -the programmer through synchronization primitives. + - -The aim of the thread related functions in GLib is to provide a -portable means for writing multithread safe software. There are -primitives for mutexes to protect the access to portions of memory -(#GMutex, #GStaticMutex, #G_LOCK_DEFINE and friends), there are -primitives for condition variables to allow synchronization of threads -(#GCond) and finally there are primitives for thread-private data, -that every thread has a private instance of (#GPrivate, -#GStaticPrivate). - - - -Currently there is only as much thread support included in GLib as is -necessary to make GLib itself multithread safe. Version 1.4 of GLib -will contain full thread support. For now the most portable way to -create threads is to require the macro #G_THREADS_IMPL_POSIX to be -defined and use POSIX threads then. This will work on almost all -platforms (except most notably Solaris and DCE threads.). - - + -This macro is defined, if GLib was compiled with thread support. This -does not necessarily mean, that there is a thread implementation -available, but the infrastructure is in place and once you provide a -thread implementation to g_thread_init(), GLib will be multithread -safe. It isn't and can't be, if #G_THREADS_ENABLED is not defined. + - -This macro is defined, if POSIX style threads are used. + - -This macro is defined, if the SOLARIS thread system is used. + - -This macro is defined, if no thread implementation is used. You can -however provide one to g_thread_init() to make GLib multithread safe. + + + + + + + + + + + + + +@G_THREAD_ERROR_AGAIN: + - -This function table is used by g_thread_init() to initialize the -thread system. The functions in that table are directly used by their -g_* prepended counterparts, that are described here, e.g. if you call -g_mutex_new() then mutex_new() from the table provided to -g_thread_init() will be called. - - - -This struct should only be used, if you know, what you are doing. - @mutex_new: @mutex_lock: @@ -111,818 +77,530 @@ This struct should only be used, if you know, what you are doing. @private_new: @private_get: @private_set: +@thread_create: +@thread_yield: +@thread_join: +@thread_exit: +@thread_set_priority: +@thread_self: - -Before you use a thread related function in GLib, you should -initialize the thread system. This is done by calling -g_thread_init(). Most of the time you will only have to call -g_thread_init(NULL). + - - -You should only call g_thread_init() with a non-NULL parameter, if you -really know, what you are doing. - - +@vtable: - - -g_thread_init() must not be called directly or indirectly as a -callback from GLib. - - + -g_thread_init() might only be called once. On the second call -it will abort with an error. If you want to make sure, that the thread -system is initialized, you can do that too: + +@Returns: + + + - - -if (!g_thread_supported ()) g_thread_init (NULL); - - + +@value: + + + -After that line either the thread system is initialized or the program -will abort, if no thread system is available in GLib, i.e. either -#G_THREADS_ENABLED is not defined or #G_THREADS_IMPL_NONE is defined. + +@G_THREAD_PRIORITY_LOW: +@G_THREAD_PRIORITY_NORMAL: +@G_THREAD_PRIORITY_HIGH: +@G_THREAD_PRIORITY_URGENT: + + -If no thread system is available and @vtable is NULL or if not all -elements of @vtable are non-NULL, then g_thread_init() will abort. + - +@priority: +@bound: +@joinable: + + -To use g_thread_init() in your program, you have to link with the -libraries, that the command "glib-config --libs gthread" outputs. This -is not the case for all the other thread related functions of -GLib. Those can be used without having to link with the thread -libraries. - - -@vtable: a function table of type #GThreadFunctions, that provides the -entry points to the thread system to be used. - - - - -This function returns, whether the thread system is initialized or -not. - - -This function is actually a macro. Apart from taking the address of it -you can however use it as if it was a function. - - +@thread_func: +@arg: +@stack_size: +@joinable: +@bound: +@priority: +@error: +@Returns: + + + + + + + +@Returns: + + + + + + + +@thread: + + + + + + + +@thread: +@priority: + + + + + + + + + + + + + -@Returns: TRUE, if the thread system is initialized. - -The #GMutex struct is an opaque data structure to represent a mutex -(mutual exclusion). It can be used to protect data against shared -access. Take for example the following function: - -A function which will not work in a threaded environment - - int give_me_next_number () - { - static int current_number = 0; - - /* now do a very complicated calculation to calculate the new number, - this might for example be a random number generator */ - current_number = calc_next_number (current_number); - return current_number; - } - - + + -It is easy to see, that this won't work in a multithreaded -application. There current_number must be protected against shared -access. A first naive implementation would be: + - - -The wrong way to write a thread-safe function - - int give_me_next_number () - { - static int current_number = 0; - int ret_val; - static GMutex * mutex = NULL; +@Returns: + + + + - if (!mutex) - mutex = g_mutex_new (); - g_mutex_lock (mutex); - ret_val = current_number = calc_next_number (current_number); - g_mutex_unlock (mutex); - return ret_val; - } - - +@mutex: + + + -This looks like it would work, but there is a race condition while -constructing the mutex and this code can't work reliable. So please do -not use such constructs in your own programs. One working solution is: + +@mutex: +@Returns: + + + - -A correct thread-safe function - - static GMutex *give_me_next_number_mutex = NULL; - /* this function must be called before any call to give_me_next_number () - it must be called exactly once. */ - void init_give_me_next_number () - { - g_assert (give_me_next_number_mutex == NULL); - give_me_next_number_mutex = g_mutex_new (); - } - - int give_me_next_number () - { - static int current_number = 0; - int ret_val; - - g_mutex_lock (give_me_next_number_mutex); - ret_val = current_number = calc_next_number (current_number); - g_mutex_unlock (give_me_next_number_mutex); - return ret_val; - } - - +@mutex: + + + -#GStaticMutex provides a simpler and safer way of doing this. + - -A #GMutex should only be accessed via the following functions. - - - - -All of the g_mutex_* functions are actually macros. Apart from taking -the addresses of them, you can however use them as if they were functions. - - - - - - - -Creates a new #GMutex. - - - - -This function will abort, if g_thread_init() has not been called yet. - - - -@Returns: a new #GMutex. - - - - - -Locks the #GMutex. If the #GMutex is already locked by another thread, -the current thread will block until the #GMutex is unlocked by the -other thread. - - - -This function can also be used, if g_thread_init() has not yet been -called and will do nothing then. - - - - -#GMutex is not guaranteed to be recursive, i.e. a thread might block, -if it already has locked the #GMutex. It will deadlock then, of -course. - - - -@mutex: a #GMutex. - - - - - -Tries to lock the #GMutex. If the #GMutex is already locked by another -thread, it immediately returns FALSE. Otherwise it locks the #GMutex -and returns TRUE. - - - -This function can also be used, if g_thread_init() has not yet been -called and will immediately return TRUE then. - - -@mutex: a #GMutex. -@Returns: TRUE, if the #GMutex could be locked. - - - - - -Unlocks the #GMutex. If another thread is blocked in a g_mutex_lock() -call, it will be woken and can lock the #GMutex itself. This function -can also be used, if g_thread_init() has not yet been called and will -do nothing then. - - -@mutex: a #GMutex. - - - - - -Destroys the #GMutex. - - -@mutex: a #GMutex. +@mutex: - -A #GStaticMutex works like a #GMutex, but it has one significant -advantage. It doesn't need to be created at run-time like a #GMutex, -but can be defined at compile-time. Here is a shorter, easier and -safer version of our give_me_next_number() example: + - - -Using GStaticMutex to simplify thread-safe programming - - int give_me_next_number () - { - static int current_number = 0; - int ret_val; - static GStaticMutex mutex = G_STATIC_MUTEX_INIT; - - g_static_mutex_lock (&mutex); - ret_val = current_number = calc_next_number (current_number); - g_static_mutex_unlock (&mutex); - return ret_val; - } - - - - - -Even though #GStaticMutex is not opaque, it should only be used with -the following functions, as it is defined differently on different -platforms. - - -All of the g_static_mutex_* functions can also be used, if -g_thread_init() has not yet. - - - - -All of the g_static_mutex_* functions are actually macros. Apart from -taking the addresses of them, you can however use them as if they were -functions. - - - -@runtime_mutex: - -Every #GStaticMutex must be initialized with this macro, before it can -be used. - - - -Initializing a GStaticMutext - -GStaticMutex my_mutex = G_STATIC_MUTEX_INIT; - - - + -works like g_mutex_lock(), but for a #GStaticMutex. + -@mutex: a #GStaticMutex. +@mutex: - - + -works like g_mutex_trylock(), but for a #GStaticMutex. + -@mutex: a #GStaticMutex. -@Returns: TRUE, if the #GStaticMutex could be locked. +@mutex: +@Returns: - - + -works like g_mutex_unlock(), but for a #GStaticMutex. + -@mutex: a #GStaticMutex. +@mutex: - - + -For some operations (like g_cond_wait()) you must have a #GMutex -instead of a #GStaticMutex. This function will return the -corresponding #GMutex for every #GStaticMutex. + -@mutex: a #GStaticMutex. -@Returns: the corresponding #GMutex. +@mutex: +@Returns: - -The G_LOCK_* macros provide a convenient interface to #GStaticMutex -with the advantage that they will expand to nothing in programs -compiled against a thread-disabled GLib, saving code and memory -there. #G_LOCK_DEFINE defines a lock. It can occur, where variable -definitions may occur in programs, i.e. in the first block of a -function or outside of functions. The @name parameter will be mangled -to get the name of the #GStaticMutex. This means, that you can use -names of existing variables as the parameter, e.g. the name of the -variable you intent to protect with the lock. Look at our -give_me_next_number() example using the G_LOCK_* macros: + - - -Using the G_LOCK_* convenience macros - -G_LOCK_DEFINE (current_number); - -int give_me_next_number () - { - static int current_number = 0; - int ret_val; - - G_LOCK (current_number); - ret_val = current_number = calc_next_number (current_number); - G_UNLOCK (current_number); - return ret_val; - } - - - - -@name: the name of the lock. +@name: - -This works like #G_LOCK_DEFINE, but it creates a static object. + -@name: the name of the lock. +@name: - -This declares a lock, that is defined with #G_LOCK_DEFINE in another module. + -@name: the name of the lock. +@name: - -works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE. + -@name: the name of the lock. +@name: - -works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE. + -@name: the name of the lock. -@Returns: TRUE, if the lock could be locked. +@name: - -works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE. + -@name: the name of the lock. +@name: + + + + + + + +@mutex: +@depth: +@owner: + + + + + + + + + + + + + +@mutex: + + + + + + + +@mutex: +@Returns: + + + + + + + +@mutex: + + + + + + + +@mutex: +@depth: + + + + + + + +@mutex: +@Returns: + + + + + + + +@mutex: +@read_cond: +@write_cond: +@read_counter: +@write: +@want_to_write: + + + + + + + + + + + + + +@lock: + + + + + + + +@lock: +@Returns: + + + + + + + +@lock: + + + + + + + +@lock: + + + + + + + +@lock: +@Returns: + + + + + + + +@lock: + + + + + + + +@lock: - -The #GCond struct is an opaque data structure to represent a -condition. A #GCond is an object, that threads can block on, if they -find a certain condition to be false. If other threads change the -state of this condition they can signal the #GCond, such that the -waiting thread is woken up. + + + - -Using GCond to block a thread until a condition is satisfied - -GCond* data_cond = NULL; /* Must be initialized somewhere */ -GMutex* data_mutex = NULL; /* Must be initialized somewhere */ -gpointer current_data = NULL; -void push_data (gpointer data) -{ - g_mutex_lock (data_mutex); - current_data = data; - g_cond_signal (data_cond); - g_mutex_unlock (data_mutex); -} - -gpointer pop_data () -{ - gpointer data; - - g_mutex_lock (data_mutex); - while (!current_data) - g_cond_wait (data_cond, data_mutex); - data = current_data; - current_data = NULL; - g_mutex_unlock (data_mutex); - return data; -} - - +@Returns: + + + -Whenever a thread calls pop_data() now, it will wait until -current_data is non-NULL, i.e. until some other thread has called -push_data(). + - - -It is important to use the g_cond_wait() and g_cond_timed_wait() -functions only inside a loop, which checks for the condition to be -true as it is not guaranteed that the waiting thread will find it -fulfilled, even if the signaling thread left the condition -in that state. This is because another thread can have altered the -condition, before the waiting thread got the chance to be woken up, -even if the condition itself is protected by a #GMutex, like above. - - +@cond: + + -A #GCond should only be accessed via the following functions. + - +@cond: + + + -All of the g_cond_* functions are actually macros. Apart from taking -the addresses of them, you can however use them as if they were functions. - - - - - - -Creates a new #GCond. This function will abort, if g_thread_init() -has not been called yet. -@Returns: a new #GCond. +@cond: +@mutex: - + -If threads are waiting for @cond, exactly one of them is woken up. It -is good practice to hold the same lock as the waiting thread, while -calling this function, though not required. + +@cond: +@mutex: +@abs_time: +@Returns: + + + -This function can also be used, if g_thread_init() has -not yet been called and will do nothing then. + -@cond: a #GCond. - - - - - -If threads are waiting for @cond, all of them are woken up. It is good -practice to lock the same mutex as the waiting threads, while calling -this function, though not required. - - - -This function can also be used, if g_thread_init() has -not yet been called and will do nothing then. - - -@cond: a #GCond. - - - - - -Waits until this thread is woken up on the #GCond. The #GMutex is -unlocked before falling asleep and locked again before resuming. - - - -This function can also be used, if g_thread_init() has not yet been -called and will immediately return then. - - -@cond: a #GCond. -@mutex: the #GMutex, that is currently locked. - - - - - -Waits until this thread is woken up on the #GCond, but not longer than -until the time, that is specified by @abs_time. The #GMutex is -unlocked before falling asleep and locked again before resuming. - - - -If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait(). - - - -This function can also be used, if g_thread_init() has not yet been -called and will immediately return TRUE then. - - -@cond: a #GCond. -@mutex: the #GMutex, that is currently locked. -@abs_time: a #GTimeVal, determining the final time. -@Returns: TRUE, if the thread is woken up in time. - - - - - -Destroys the #GCond. - - -@cond: a #GCond. +@cond: -The #GPrivate struct is an opaque data structure to represent a thread -private data key. Threads can thereby obtain and set a pointer, which -is private to the current thread. Take our give_me_next_number() -example from above. Now we don't want current_number to be shared -between the threads, but to be private to each thread. This can be -done as follows: - -Using GPrivate for per-thread data - - GPrivate* current_number_key = NULL; /* Must be initialized somewhere */ - /* with g_private_new (g_free); */ - - int give_me_next_number () - { - int *current_number = g_private_get (current_number_key); - - if (!current_number) - { - current_number = g_new (int,1); - *current_number = 0; - g_private_set (current_number_key, current_number); - } - *current_number = calc_next_number (*current_number); - return *current_number; - } - - + + -Here the pointer belonging to the key current_number_key is read. If -it is NULL, it has not been set yet. Then get memory for an integer -value, assign this memory to the pointer and write the pointer -back. Now we have an integer value, that is private to the current -thread. + +@destructor: +@Returns: + + + -The #GPrivate struct should only be accessed via the following functions. + - +@private_key: +@Returns: + + + -All of the g_private_* functions are actually macros. Apart from taking -the addresses of them, you can however use them as if they were functions. - - - - - - -Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer -to a destructor function. Whenever a thread ends and the corresponding -pointer keyed to this instance of #GPrivate is non-NULL, the -destructor is called with this pointer as the argument. - - -The @destructor is working quite differently from @notify in -g_static_private_set(). - - - - - -A #GPrivate can not be destroyed. Reuse it instead, if you can to -avoid shortage. - - - - - -This function will abort, if g_thread_init() has not been called yet. - - - -@destructor: a function to handle the data keyed to #GPrivate, when a -thread ends. - - - - - -Returns the pointer keyed to @private_key for the current thread. This -pointer is NULL, when g_private_set() hasn't been called for the -current @private_key and thread yet. - - - -This function can also be used, if g_thread_init() has not yet been -called and will return the value of @private_key casted to #gpointer then. - - -@private_key: a #GPrivate. -@Returns: the corresponding pointer. - - - - - -Sets the pointer keyed to @private_key for the current thread. - - - -This function can also be used, if g_thread_init() has not yet been -called and will set @private_key to @data casted to #GPrivate* then. - - -@private_key: a #GPrivate. -@value: - -@data: the new pointer. +@private_key: +@data: - -A #GStaticPrivate works almost like a #GPrivate, but it has one -significant advantage. It doesn't need to be created at run-time like -a #GPrivate, but can be defined at compile-time. This is similar to -the difference between #GMutex and #GStaticMutex. Now look at our -give_me_next_number() example with #GStaticPrivate: - - - -Using GStaticPrivate for per-thread data - - int give_me_next_number () - { - static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT; - int *current_number = g_static_private_get (&current_number_key); - - if (!current_number) - { - current_number = g_new (int,1); - *current_number = 0; - g_static_private_set (&current_number_key, current_number, g_free); - } - *current_number = calc_next_number (*current_number); - return *current_number; - } - - @index: -Every #GStaticPrivate must be initialized with this macro, before it can -be used. - - - - -GStaticPrivate my_private = G_STATIC_PRIVATE_INIT; - - -Works like g_private_get() only for a #GStaticPrivate. + +@private_key: +@Returns: + + + -This function also works, if g_thread_init() has not yet been called. + -@private_key: a #GStaticPrivate. -@Returns: the corresponding pointer. +@private_key: +@thread: +@Returns: -Sets the pointer keyed to @private_key for the current thread and the -function @notify to be called with that pointer (NULL or non-NULL), -whenever the pointer is set again or whenever the current thread ends. + +@private_key: +@data: +@notify: + + + -This function also works, if g_thread_init() has not yet been -called. If g_thread_init() is called later, the @data keyed to -@private_key will be inherited only by the main thread, i.e. the one that -called g_thread_init(). + - - -The @notify is working quite differently from @destructor in -g_private_new(). - - - -@private_key: a #GStaticPrivate. -@data: the new pointer. -@notify: a function to be called with the pointer, whenever the -current thread ends or sets this pointer again. +@private_key: +@thread: +@data: +@notify: diff --git a/docs/reference/glib/tmpl/timers.sgml b/docs/reference/glib/tmpl/timers.sgml index 87cba3791..621998dc7 100644 --- a/docs/reference/glib/tmpl/timers.sgml +++ b/docs/reference/glib/tmpl/timers.sgml @@ -2,49 +2,48 @@ Timers -functions to time operations. + -Timers can be used to time operations, in a similar way to a stopwatch. -Call g_timer_new () to create the timer, g_timer_start () to start it, -g_timer_elapsed () to determine the time which has elapsed since the timer -was started, and g_timer_stop () to stop the timer. + + + -An opaque data structure which holds the timer information. + -Creates a new timer. + -@Returns: the new timer. +@Returns: -Starts the timer. + -@timer: the timer. +@timer: -Stops the timer. + -@timer: the timer. +@timer: @@ -52,25 +51,24 @@ Stops the timer. -@timer: the timer. -@microseconds: if non-NULL, this will be set to the microseconds component -of the elapsed time (it does not include the number of seconds elapsed). -@Returns: the elapsed time in seconds, as a double. +@timer: +@microseconds: +@Returns: -Resets the elapsed time to 0, leaving the timer running. + -@timer: the timer. +@timer: -Destroys the timer, freeing the memory allocated for it. + -@timer: the timer. +@timer: diff --git a/docs/reference/glib/tmpl/trees-binary.sgml b/docs/reference/glib/tmpl/trees-binary.sgml index ef2f9e110..2e9e50fc0 100644 --- a/docs/reference/glib/tmpl/trees-binary.sgml +++ b/docs/reference/glib/tmpl/trees-binary.sgml @@ -2,203 +2,109 @@ Balanced Binary Trees -a sorted collection of key/value pairs optimised for searching -and traversing in order. + -The #GTree structure and its associated functions provide a sorted collection -of key/value pairs optimised for searching and traversing in order. - - -To create a new #GTree use g_tree_new(). - - -To insert a key/value pair into a #GTree use g_tree_insert(). - - -To lookup the value corresponding to a given key, use g_tree_lookup(). - - -To find out the number of nodes in a #GTree, use g_tree_nnodes(). -To get the height of a #GTree, use g_tree_height(). - - -To traverse a #GTree, calling a function for each node visited in the -traversal, use g_tree_traverse(). - - -To remove a key/value pair use g_tree_remove(). - - -To destroy a #GTree, use g_tree_destroy(). + + + -The #GTree struct is an opaque data structure representing a -Balanced Binary Tree. -It should be accessed only by using the following functions. + -Creates a new GTree. + -@key_compare_func: the function used to order the nodes in the #GTree. -It should return values similar to the standard strcmp() -function - -0 if the two arguments are equal, a negative value if the first argument comes -before the second, or a positive value if the first argument comes after the -second. -@Returns: a new #GTree. +@key_compare_func: +@Returns: -Inserts a key/value pair into a #GTree. -If the given key already exists in the #GTree it is set to the new value. -(If you are using dynamically allocated keys and values you should be careful -to ensure that the old values are freed.) - - -The tree is automatically 'balanced' as new key/value pairs are added, -so that the distance from the root to every leaf is as small as possible. + -@tree: a #GTree. -@key: the key to insert. -@value: the value corresponding to the key. +@tree: +@key: +@value: -Gets the number of nodes in a #GTree. + -@tree: a #GTree. -@Returns: the number of nodes in the #GTree. +@tree: +@Returns: -Gets the height of a #GTree. - - -If the #GTree contains no nodes, the height is 0. -If the #GTree contains only one root node the height is 1. -If the root node has children the height is 2, etc. + -@tree: a #GTree. -@Returns: the height of the #GTree. +@tree: +@Returns: -Gets the value corresponding to the given key. -Since a #GTree is automatically balanced as key/value pairs are -added, key lookup is very fast. + -@tree: a #GTree. -@key: the key to look up. -@Returns: the value corresponding to the key. +@tree: +@key: +@Returns: -Searches a #GTree using an alternative form of the comparison function. - - -This function is not as useful as it sounds. -It allows you to use a different function for performing the lookup of -a key. However, since the tree is ordered according to the @key_compare_func -function passed to g_tree_new(), the function you pass to g_tree_search() must -return exactly the same value as would be returned by the comparison function, -for each pair of tree nodes, or the search will not work. - - -To search for a specific value, you can use g_tree_traverse(). + -@tree: a #GTree. -@search_func: the comparison function used to search the #GTree. -@data: the data passed as the second argument to the @search_func function. -@Returns: the value corresponding to the found key, or NULL if the key is -not found. - - - - -Specifies the type of function passed to g_tree_search(). - - -@key: a key from a #GTree. -@data: the data to compare with the key. -@Returns: 0 if the desired key has been found, a negative number if the -desired key comes before @key in the sort order of the #GTree, or a positive -value if the desired key comes after @key. +@tree: +@search_func: +@data: +@Returns: -Calls the given function for each node in the GTree. + -@tree: a #GTree. -@traverse_func: the function to call for each node visited. If this function -returns TRUE, the traversal is stopped. -@traverse_type: the order in which nodes are visited, one of %G_IN_ORDER, -%G_PRE_ORDER and %G_POST_ORDER. -@data: user data to pass to the traverse function. +@tree: +@traverse_func: +@traverse_type: +@data: -Specifies the type of function passed to g_tree_traverse(). -It is passed the key and value of each node, together with -the @user_data parameter passed to g_tree_traverse(). -If the function returns TRUE, the traversal is stopped. + -@key: a key of a #GTree node. -@value: the value corresponding to the key. -@data: user data passed to g_tree_traverse(). -@Returns: TRUE to stop the traversal. +@key: +@value: +@data: +@Returns: -Specifies the type of traveral performed by g_tree_traverse(), -g_node_traverse() and g_node_find(). - - -%G_PRE_ORDER visits a node, then its children. - - -%G_IN_ORDER vists a node's left child first, then the node itself, then its -right child. This is the one to use if you want the output sorted according -to the compare function. - - -%G_POST_ORDER visits the node's children, then the node itself. - - -%G_LEVEL_ORDER is not implemented for -Balanced Binary Trees. -For N-ary Trees -it calls the function for each child of the node, then it recursively visits -each child. - - + @G_IN_ORDER: @@ -208,21 +114,18 @@ each child. -Removes a key/value pair from a #GTree. -If the key or value is dynamically allocated you must remember to free them -yourself. + -@tree: a #GTree. -@key: the key to remove. +@tree: +@key: -Destroys the #GTree, freeing all of the memory allocated. -But it doesn't free keys or values. + -@tree: a #GTree. +@tree: diff --git a/docs/reference/glib/tmpl/trees-nary.sgml b/docs/reference/glib/tmpl/trees-nary.sgml index 7a8aca2e8..a7589e1af 100644 --- a/docs/reference/glib/tmpl/trees-nary.sgml +++ b/docs/reference/glib/tmpl/trees-nary.sgml @@ -2,66 +2,23 @@ N-ary Trees -trees of data with any number of branches. + -The #GNode struct and its associated functions provide a N-ary tree data -structure, where nodes in the tree can contain arbitrary data. - - -To create a new tree use g_node_new(). - - -To insert a node into a tree use g_node_insert(), g_node_insert_before(), -g_node_append() and g_node_prepend(). - - -To create a new node and insert it into a tree use g_node_insert_data(), -g_node_insert_data_before(), g_node_append_data() and g_node_prepend_data(). - - -To reverse the children of a node use g_node_reverse_children(). - - -To find a node use g_node_get_root(), g_node_find(), g_node_find_child(), -g_node_child_index(), g_node_child_position(), -g_node_first_child(), g_node_last_child(), -g_node_nth_child(), g_node_first_sibling(), g_node_prev_sibling(), -g_node_next_sibling() or g_node_last_sibling(). - - -To get information about a node or tree use G_NODE_IS_LEAF(), -G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), g_node_n_children(), -g_node_is_ancestor() or g_node_max_height(). - - -To traverse a tree, calling a function for each node visited in the -traversal, use g_node_traverse() or g_node_children_foreach(). - - -To remove a node or subtree from a tree use g_node_unlink() or -g_node_destroy(). + + + -The #GNode struct represents one node in a -N-ary Tree. -The data field contains the actual data of the node. -The next and prev -fields point to the node's siblings (a sibling is another #GNode with the -same parent). -The parent field points to the parent of the #GNode, -or is NULL if the #GNode is the root of the tree. -The children field points to the first child of the -#GNode. The other children are accessed by using the -next pointer of each child. + @data: @@ -72,145 +29,125 @@ The children field points to the first child of the -Creates a new #GNode containing the given data. -Used to create the first node in a tree. + -@data: the data of the new node. -@Returns: a new #GNode. +@data: +@Returns: + + + + + + + +@node: +@Returns: -Inserts a #GNode beneath the parent at the given position. + -@parent: the #GNode to place @node under. -@position: the position to place @node at, with respect to its siblings. -If position is -1, @node is inserted as the last child of @parent. -@node: the #GNode to insert. -@Returns: the inserted #GNode. +@parent: +@position: +@node: +@Returns: -Inserts a #GNode beneath the parent before the given sibling. + -@parent: the #GNode to place @node under. -@sibling: the sibling #GNode to place @node before. If sibling is NULL, -the node is inserted as the last child of @parent. -@node: the #GNode to insert. -@Returns: the inserted #GNode. +@parent: +@sibling: +@node: +@Returns: -Inserts a #GNode as the last child of the given parent. + -@parent: the #GNode to place the new #GNode under. -@node: the #GNode to insert. -@Returns: the inserted #GNode. +@parent: +@node: -Inserts a #GNode as the first child of the given parent. + -@parent: the #GNode to place the new #GNode under. -@node: the #GNode to insert. -@Returns: the inserted #GNode. +@parent: +@node: +@Returns: -Inserts a new #GNode at the given position. + -@parent: the #GNode to place the new #GNode under. -@position: the position to place the new #GNode at. -If position is -1, the new #GNode is inserted as the last child of @parent. -@data: the data for the new #GNode. -@Returns: the new #GNode. +@parent: +@position: +@data: -Inserts a new #GNode before the given sibling. + -@parent: the #GNode to place the new #GNode under. -@sibling: the sibling #GNode to place the new #GNode before. -@data: the data for the new #GNode. -@Returns: the new #GNode. +@parent: +@sibling: +@data: -Inserts a new #GNode as the last child of the given parent. + -@parent: the #GNode to place the new #GNode under. -@data: the data for the new #GNode. -@Returns: the new #GNode. +@parent: +@data: -Inserts a new #GNode as the first child of the given parent. + -@parent: the #GNode to place the new #GNode under. -@data: the data for the new #GNode. -@Returns: the new #GNode. +@parent: +@data: -Reverses the order of the children of a #GNode. -(It doesn't change the order of the grandchildren.) + -@node: a #GNode. +@node: -Traverses a tree starting at the given root #GNode. -It calls the given function for each node visited. -The traversal can be halted at any point by returning TRUE from @func. + -@root: the root #GNode of the tree to traverse. -@order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, -%G_POST_ORDER, or %G_LEVEL_ORDER. -@flags: which types of children are to be visited, one of %G_TRAVERSE_ALL, -%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS. -@max_depth: the maximum depth of the traversal. Nodes below this -depth will not be visited. If max_depth is -1 all nodes in the tree are -visited. If depth is 1, only the root is visited. If depth is 2, the root -and its children are visited. And so on. -@func: the function to call for each visited #GNode. -@data: user data to pass to the function. +@root: +@order: +@flags: +@max_depth: +@func: +@data: -Specifies which nodes are visited during several of the tree functions, -including g_node_traverse() and g_node_find(). - - -%G_TRAVERSE_LEAFS specifies that only leaf nodes should be visited. - - -%G_TRAVERSE_NON_LEAFS specifies that only non-leaf nodes should be visited. - - -%G_TRAVERSE_ALL specifies that all nodes should be visited. - - + @G_TRAVERSE_LEAFS: @@ -220,275 +157,238 @@ including g_node_traverse() and g_node_find(). -Specifies the type of function passed to g_node_traverse(). -The function is called with each of the nodes visited, together with the -user data passed to g_node_traverse(). -If the function returns TRUE, then the traversal is stopped. + -@node: a #GNode. -@data: user data passed to g_node_traverse(). -@Returns: TRUE to stop the traversal. +@node: +@data: +@Returns: -Calls a function for each of the children of a #GNode. -Note that it doesn't descend beneath the child nodes. + -@node: a #GNode. -@flags: which types of children are to be visited, one of %G_TRAVERSE_ALL, -%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS. -@func: the function to call for each visited node. -@data: user data to pass to the function. +@node: +@flags: +@func: +@data: -Specifies the type of function passed to g_node_children_foreach(). -The function is called with each child node, together with the user data -passed to g_node_children_foreach(). + -@node: a #GNode. -@data: user data passed to g_node_children_foreach(). +@node: +@data: -Gets the root of a tree. + -@node: a #GNode. -@Returns: the root of the tree. +@node: +@Returns: -Finds a #GNode in a tree. + -@root: the root #GNode of the tree to search. -@order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, -%G_POST_ORDER, or %G_LEVEL_ORDER. -@flags: which types of children are to be searched, one of %G_TRAVERSE_ALL, -%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS. -@data: the data to find. -@Returns: the found #GNode, or NULL if the data is not found. +@root: +@order: +@flags: +@data: +@Returns: -Finds the first child of a #GNode with the given data. + -@node: a #GNode. -@flags: which types of children are to be searched, one of %G_TRAVERSE_ALL, -%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS. -@data: the data to find. -@Returns: the found child #GNode, or NULL if the data is not found. +@node: +@flags: +@data: +@Returns: -Gets the position of the first child of a #GNode which contains the given data. + -@node: a #GNode. -@data: the data to find. -@Returns: the index of the child of @node which contains @data, or -1 -if the data is not found. +@node: +@data: +@Returns: -Gets the position of a #GNode with respect to its siblings. -@child must be a child of @node. -The first child is numbered 0, the second 1, and so on. + -@node: a #GNode. -@child: a child of @node. -@Returns: the position of @child with respect to its siblings. +@node: +@child: +@Returns: -Gets the first child of a #GNode. + -@node: a #GNode. -@Returns: the last child of @node, or NULL if @node is NULL or has no children. +@node: -Gets the last child of a #GNode. + -@node: a #GNode (must not be NULL). -@Returns: the last child of @node, or NULL if @node has no children. +@node: +@Returns: -Gets a child of a #GNode, using the given index. -The first child is at index 0. If the index is too big, NULL is returned. + -@node: a #GNode. -@n: the index of the desired child. -@Returns: the child of @node at index @n. +@node: +@n: +@Returns: -Gets the first sibling of a #GNode. -This could possibly be the node itself. + -@node: a #GNode. -@Returns: the first sibling of @node. +@node: +@Returns: -Gets the next sibling of a #GNode. + -@node: a #GNode. -@Returns: the next sibling of @node, or NULL if @node is NULL. +@node: -Gets the previous sibling of a #GNode. + -@node: a #GNode. -@Returns: the previous sibling of @node, or NULL if @node is NULL. +@node: -Gets the last sibling of a #GNode. -This could possibly be the node itself. + -@node: a #GNode. -@Returns: the last sibling of @node. +@node: +@Returns: -Returns TRUE if a #GNode is a leaf node. + -@node: a #GNode. -@Returns: TRUE if the #GNode is a leaf node (i.e. it has no children). +@node: -Returns TRUE if a #GNode is the root of a tree. + -@node: a #GNode. -@Returns: TRUE if the #GNode is the root of a tree (i.e. it has no parent -or siblings). +@node: -Gets the depth of a #GNode. - - -If @node is NULL the depth is 0. -The root node has a depth of 1. -For the children of the root node the depth is 2. And so on. + -@node: a #GNode. -@Returns: the depth of the #GNode. +@node: +@Returns: -Gets the number of nodes in a tree. + -@root: a #GNode. -@flags: which types of children are to be counted, one of %G_TRAVERSE_ALL, -%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS. -@Returns: the number of nodes in the tree. +@root: +@flags: +@Returns: -Gets the number of children of a #GNode. + -@node: a #GNode. -@Returns: the number of children of @node. +@node: +@Returns: -Returns TRUE if @node is an ancestor of @descendant. -This is true if node is the parent of descendant, or if node is the -grandparent of descendant etc. + -@node: a #GNode. -@descendant: a #GNode. -@Returns: TRUE if @node is an ancestor of @descendant. +@node: +@descendant: +@Returns: -Gets the maximum height of all branches beneath a #GNode. -This is the maximum distance from the #GNode to all leaf nodes. - - -If @root is NULL, 0 is returned. If @root has no children, 1 is returned. -If @root has children, 2 is returned. And so on. + -@root: a #GNode. -@Returns: the maximum height of the tree beneath @root. +@root: +@Returns: -Unlinks a #GNode from a tree, resulting in two separate trees. + -@node: the #GNode to unlink, which becomes the root of a new tree. +@node: -Removes the #GNode and its children from the tree, freeing any memory -allocated. - - -@root: the root of the tree/subtree to destroy. - - - - -Restores the previous #GAllocator, used when allocating #GNode elements. + +@root: -Sets the allocator to use to allocate #GNode elements. -Use g_node_pop_allocator() to restore the previous allocator. + + + +@allocator: + + + + + -@allocator: the #GAllocator to use when allocating #GNode elements. diff --git a/docs/reference/glib/tmpl/type_conversion.sgml b/docs/reference/glib/tmpl/type_conversion.sgml index 45138be50..d63aee644 100644 --- a/docs/reference/glib/tmpl/type_conversion.sgml +++ b/docs/reference/glib/tmpl/type_conversion.sgml @@ -2,77 +2,49 @@ Type Conversion Macros -a portable method for storing #gint & #guint values in #gpointer variables. + -These macros provide a portable method of storing #gint and #guint values in -#gpointer variables. - - -Many of the GLib data types are based on storing #gpointer values, -e.g. #GHashTable, #GList, #GSList, #GTree, and #GNode. -By using the type conversion macros described below you can store #gint and -#guint values inside a #gpointer. So you can, for example, create -a hash table of #gint values, or a linked list of #guint values. - - -The type conversion macros are necessary because the size of a #gpointer can -vary across different platforms. So the type conversion has to be done -carefully. - - -Note that the reverse operation, storing #gpointer values in -integer variables, is not supported, since an integer is not guaranteed to -be large enough to store #gpointer values across all platforms. - - -To convert an integer value, a #gint, to a #gpointer, use #GINT_TO_POINTER. -To convert it back to a #gint, use #GPOINTER_TO_INT. - - -To convert an unsigned integer, a #guint, to a #gpointer, use -#GUINT_TO_POINTER. To convert it back to a #guint, use #GPOINTER_TO_UINT. + + + -Converts a #gint to a #gpointer. + -@i: a #gint value. -@Returns: the value converted to a #gpointer. +@i: -Converts a #gpointer to a #gint. + -@p: a #gpointer value. -@Returns: the value converted to a #gint. +@p: -Converts a #guint to a #gpointer. + -@u: a #guint value. -@Returns: the value converted to a #gpointer. +@u: -Converts a #gpointer to a #guint. + -@p: a #gpointer value. -@Returns: the value converted to a #guint. +@p: diff --git a/docs/reference/glib/tmpl/types.sgml b/docs/reference/glib/tmpl/types.sgml index b3d63a401..fa276e06b 100644 --- a/docs/reference/glib/tmpl/types.sgml +++ b/docs/reference/glib/tmpl/types.sgml @@ -1,216 +1,761 @@ -Basic Types +GType -standard GLib types, defined for ease-of-use and portability. + -GLib defines a number of commonly used types, which can be divided into -4 groups: - - - -New types which are not part of standard C - #gboolean, #gsize, #gssize. - - - -Integer types which are guaranteed to be the same size across all platforms - -#gint8, #guint8, #gint16, #guint16, #gint32, #guint32, #gint64, #guint64. - - - -Types which are easier to use than their standard C counterparts - -#gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong. - - - -Types which correspond exactly to standard C types, but are included -for completeness - #gchar, #gint, #gshort, #glong, #gfloat, #gdouble. - - + - + + -A standard boolean type. -Variables of this type should only contain the value #TRUE or #FALSE. + - + -An untyped pointer. -#gpointer looks better and is easier to use than void*. + +@type: - + + -An untyped pointer to constant data. -The data pointed to should not be changed. - - -This is typically used in function prototypes to indicate that the -data pointed to will not be altered by the function. - - - - -Corresponds to the standard C char type. - - - - - -Corresponds to the standard C unsigned char type. - - - - - -Corresponds to the standard C int type. -Values of this type can range from #G_MININT to #G_MAXINT. - - - - - -Corresponds to the standard C unsigned int type. - - - - - -Corresponds to the standard C short type. -Values of this type can range from #G_MINSHORT to #G_MAXSHORT. - - - - - -Corresponds to the standard C unsigned short type. - - - - - -Corresponds to the standard C long type. -Values of this type can range from #G_MINLONG to #G_MAXLONG. - - - - - -Corresponds to the standard C unsigned long type. - - - - - -A signed integer guaranteed to be 8 bits on all platforms. -Values of this type can range from -128 to 127. - - - - - -An unsigned integer guaranteed to be 8 bits on all platforms. -Values of this type can range from 0 to 255. - - - - - -A signed integer guaranteed to be 16 bits on all platforms. -Values of this type can range from -32,768 to 32,767. - - - - - -An unsigned integer guaranteed to be 16 bits on all platforms. -Values of this type can range from 0 to 65,535. - - - - - -A signed integer guaranteed to be 32 bits on all platforms. -Values of this type can range from -2,147,483,648 to 2,147,483,647. - - - - - -An unsigned integer guaranteed to be 32 bits on all platforms. -Values of this type can range from 0 to 4,294,967,295. - - - - - -This macro is defined if 64-bit signed and unsigned integers are available -on the platform. - + -A signed integer guaranteed to be 64 bits on all platforms on which it is -available (see #G_HAVE_GINT64). -Values of this type can range from -9,223,372,036,854,775,808 to -9,223,372,036,854,775,807. + + + +@ptype: +@branch_seqno: + + + + + + + +@type: + + + + + - + + -An unsigned integer guaranteed to be 64 bits on all platforms on which it is -available (see #G_HAVE_GINT64). -Values of this type can range from 0 to 18,446,744,073,709,551,615. + + + +@G_TYPE_INVALID: +@G_TYPE_NONE: +@G_TYPE_INTERFACE: +@G_TYPE_CHAR: +@G_TYPE_UCHAR: +@G_TYPE_BOOLEAN: +@G_TYPE_INT: +@G_TYPE_UINT: +@G_TYPE_LONG: +@G_TYPE_ULONG: +@G_TYPE_ENUM: +@G_TYPE_FLAGS: +@G_TYPE_FLOAT: +@G_TYPE_DOUBLE: +@G_TYPE_STRING: +@G_TYPE_PARAM: +@G_TYPE_OBJECT: +@G_TYPE_GTK_BOXED: +@G_TYPE_GTK_POINTER: +@G_TYPE_GTK_SIGNAL: +@G_TYPE_BSE_PROCEDURE: +@G_TYPE_BSE_TIME: +@G_TYPE_BSE_NOTE: +@G_TYPE_BSE_DOTS: +@G_TYPE_GLE_GOBJECT: +@G_TYPE_LAST_RESERVED_FUNDAMENTAL: +@G_TYPE_PARAM_CHAR: +@G_TYPE_PARAM_UCHAR: +@G_TYPE_PARAM_BOOLEAN: +@G_TYPE_PARAM_INT: +@G_TYPE_PARAM_UINT: +@G_TYPE_PARAM_LONG: +@G_TYPE_PARAM_ULONG: +@G_TYPE_PARAM_ENUM: +@G_TYPE_PARAM_FLAGS: +@G_TYPE_PARAM_FLOAT: +@G_TYPE_PARAM_DOUBLE: +@G_TYPE_PARAM_STRING: +@G_TYPE_PARAM_OBJECT: + + + + + + +@type: + + + + + + + +@type: + + + + + + + +@type: + + + + + + + +@type: + + + + + + + +@type: + + + + + + + +@type: + + + + + + + +@vtable: + + + + + + +@plugin_ref: +@plugin_unref: +@complete_type_info: +@complete_interface_info: + + + + - + -This macro is used to insert 64-bit integer literals into the source code. - -@val: a literal integer value, e.g. 0x1d636b02300a7aa7U. - - - - -Corresponds to the standard C float type. -Values of this type can range from #G_MINFLOAT to #G_MAXFLOAT. - + -Corresponds to the standard C double type. -Values of this type can range from #G_MINDOUBLE to #G_MAXDOUBLE. + + + +@class_size: +@base_init: +@base_finalize: +@class_init: +@class_finalize: +@class_data: +@instance_size: +@n_preallocs: +@instance_init: +@value_table: + + + + + + +@type_flags: + + + + + + +@interface_init: +@interface_finalize: +@interface_data: + + + + + + +@value_init: +@value_free: +@value_copy: +@collect_type: +@collect_value: +@lcopy_type: +@lcopy_value: + + + + + + +@instance: +@g_type: +@c_type: + + + + + + + +@g_class: +@g_type: +@c_type: + + + + + + + +@instance: +@g_type: + + + + + + + +@g_class: +@g_type: + + + + + + + +@instance: +@g_type: +@c_type: + + + + + + + +@instance: + + + + + + + +@g_class: + + + + + + + +@g_iface: + + + + + - + + -An unsigned 32-bit integer intended to represent sizes of data structures. + +@type: +@Returns: - + + -A signed 32-bit integer intended to represent sizes of data structures. + +@type: +@Returns: + + + + + + + +@name: +@Returns: + + + + + + + +@type: +@Returns: + + + + + + + +@type: +@base_type: +@Returns: + + + + + + + +@type: +@is_a_type: +@Returns: + + + + + + + +@type: +@iface_type: +@Returns: + + + + + + + +@type: +@Returns: + + + + + + + +@type: +@Returns: + + + + + + + +@type: +@Returns: + + + + + + + +@g_class: + + + + + + + +@g_class: +@Returns: + + + + + + + +@instance_class: +@iface_type: +@Returns: + + + + + + + +@type: +@n_children: +@Returns: + + + + + + + +@type: +@n_interfaces: +@Returns: + + + + + + + +@type: +@quark: +@data: + + + + + + + +@type: +@quark: +@Returns: + + + + + + + +@g_class: + + + + + + + +@g_class: + + + + + + + +@g_class: +@class_data: + + + + + + + +@g_class: +@class_data: + + + + + + + +@instance: +@g_class: + + + + + + + +@g_iface: +@iface_data: + + + + + + + +@g_iface: +@iface_data: + + + + + + + +@plugin: + + + + + + + +@plugin: + + + + + + + +@plugin: +@g_type: +@info: +@value_table: + + + + + + + +@plugin: +@interface_type: +@instance_type: +@info: + + + + + + + +@cache_data: +@g_class: +@Returns: + + + + + + + +@G_TYPE_FLAG_CLASSED: +@G_TYPE_FLAG_INSTANTIATABLE: +@G_TYPE_FLAG_DERIVABLE: +@G_TYPE_FLAG_DEEP_DERIVABLE: + + + + + + +@parent_type: +@type_name: +@info: +@Returns: + + + + + + + +@parent_type: +@type_name: +@plugin: +@Returns: + + + + + + + +@type_id: +@type_name: +@info: +@finfo: +@Returns: + + + + + + + +@instance_type: +@interface_type: +@info: + + + + + + + +@instance_type: +@interface_type: +@plugin: + + + + + + + +@g_class: +@is_a_type: +@Returns: + + + + + + + +@g_class: +@is_a_type: +@Returns: + + + + + + + +@instance: +@iface_type: +@Returns: + + + + + + + +@instance: +@iface_type: +@Returns: + + + + + + + +@type: +@flags: +@Returns: + + + + + + + +@type: +@Returns: + + + + + + + +@instance: + + + + + + + +@type: +@Returns: + + + + + + + +@cache_data: +@cache_func: + + + + + + + +@cache_data: +@cache_func: + + + + + + + +@g_class: + + + + + + + +@type: +@Returns: + + + + + + + +@Returns: + diff --git a/docs/reference/glib/tmpl/warnings.sgml b/docs/reference/glib/tmpl/warnings.sgml index 2cca15265..ca360571e 100644 --- a/docs/reference/glib/tmpl/warnings.sgml +++ b/docs/reference/glib/tmpl/warnings.sgml @@ -1,186 +1,131 @@ -Message Output and Debugging Functions +Warnings and Assertions -functions to output messages and help debug applications. + -These functions provide support for outputting messages. + + + -Outputs a formatted message via the print handler. -The default print handler simply outputs the message to stdout. - - -g_print() should not be used from within libraries for debugging messages, -since it may be redirected by applications to special purpose message -windows or even files. -Instead, libraries should use g_log(), or the convenience functions -g_message(), g_warning() and g_error(). + -@format: the message format. See the printf() -documentation. -@Varargs: the parameters to insert into the format string. +@format: +@Varargs: -Sets the print handler. -Any messages passed to g_print() will be output via the new handler. -The default handler simply outputs the message to stdout. -By providing your own handler you can redirect the output, to a GTK -widget or a log file for example. + -@func: the new print handler. -@Returns: the old print handler. +@func: +@Returns: -Specifies the type of the print handler functions. -These are called with the complete formatted string to output. + -@string: the message to be output. +@string: -Outputs a formatted message via the error message handler. -The default handler simply outputs the message to stderr. - - -g_printerr() should not be used from within libraries. Instead g_log() should -be used, or the convenience functions g_message(), g_warning() and g_error(). + -@format: the message format. See the printf() -documentation. -@Varargs: the parameters to insert into the format string. +@format: +@Varargs: -Sets the handler for printing error messages. -Any messages passed to g_printerr() will be output via the new handler. -The default handler simply outputs the message to stderr. -By providing your own handler you can redirect the output, to a GTK -widget or a log file for example. + -@func: the new error message handler. -@Returns: the old error message handler. +@func: +@Returns: -Returns from the current function if the expression is not true. -If the expression evaluates to FALSE, a critical message is logged and -the function returns. This can only be used in functions which do not return -a value. + -@expr: the expression to check. +@expr: -Returns from the current function, returning the value @val, if the expression -is not true. -If the expression evaluates to FALSE, a critical message is logged and -@val is returned. + -@expr: the expression to check. -@val: the value to return from the current function if the expression is not -true. +@expr: +@val: + + + + + + + + + + + + + + +@val: -Debugging macro to terminate the application if the assertion fails. -If the assertion fails (i.e. the expression is not true), an error message -is logged and the application is terminated. - - -The macro can be turned off in final releases of code by defining -G_DISABLE_ASSERT when compiling the application. + -@expr: the expression to check. +@expr: -Debugging macro to terminate the application if it is ever reached. -If it is reached, an error message is logged and the application is terminated. - - -The macro can be turned off in final releases of code by defining -G_DISABLE_ASSERT when compiling the application. + -Prompts the user with "[E]xit, [H]alt, show [S]tack trace or [P]roceed". -This function is intended to be used for debugging use only. -FIXME: How do you set it up? - - -If Exit is selected, the application terminates with a call to -_exit(0). - - -If Halt is selected, the application enters an infinite loop. -The infinite loop can only be stopped by killing the application, -or by setting glib_on_error_halt to FALSE (possibly via a debugger). - - -If Stack trace is selected, g_on_error_stack_trace() is called. This -invokes gdb, which attaches to the current process and shows a stack trace. -The prompt is then shown again. - - -If Proceed is selected, the function returns. - - -This function may cause different actions on non-unix platforms. + -@prg_name: the program name, needed by gdb for the [S]tack trace option. -If @prg_name is NULL, g_get_prgname() is called to get the program name -(which will work correctly if gdk_init() or gtk_init() has been called). +@prg_name: -Invokes gdb, which attaches to the current process and shows a stack trace. -Called by g_on_error_query() when the [S]tack trace option is selected. - - -This function may cause different actions on non-unix platforms. + -@prg_name: the program name, needed by gdb for the [S]tack trace option. -If @prg_name is NULL, g_get_prgname() is called to get the program name -(which will work correctly if gdk_init() or gtk_init() has been called). +@prg_name: -Inserts a breakpoint instruction into the code (on x86 machines only). + diff --git a/docs/reference/glib/tmpl/windows.sgml b/docs/reference/glib/tmpl/windows.sgml index 475782f84..16d841a9b 100644 --- a/docs/reference/glib/tmpl/windows.sgml +++ b/docs/reference/glib/tmpl/windows.sgml @@ -2,30 +2,20 @@ Windows Compatability Functions -functions to support portability to the Windows environment. + -These functions and macros are provided in the GLib library when compiled -on the Windows platform. - - -Many of the macros simply rename available windows functions -so that they use the same name as the standard Unix functions. -This means that code written for the Unix platform will work without change -under Windows. - - -A few additional constants, types, and functions are also provided, -to provide a common base set of functions across both the Unix and Windows -environments. + + + @@ -40,68 +30,12 @@ environments. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -110,27 +44,6 @@ environments. @phandles: - - - - - - - - - - - - - - - - - - - - - @@ -168,3 +81,20 @@ environments. + + + + + +@error: +@Returns: + + + + + + + +@Returns: + +