Attachment 'gtk-docify-some-stuff.diff'
Download 1 Index: glib/gutils.h
2 ===================================================================
3 --- glib/gutils.h (revision 7087)
4 +++ glib/gutils.h (working copy)
5 @@ -34,6 +34,14 @@
6 #include <glib/gtypes.h>
7 #include <stdarg.h>
8
9 +/**
10 + * SECTION:misc_utils
11 + * @Short_description: a selection of portable utility functions
12 + * @Title: Miscellaneous Utility Functions
13 + *
14 + * These are portable utility functions.
15 + */
16 +
17 G_BEGIN_DECLS
18
19 #ifdef G_OS_WIN32
20 @@ -52,10 +60,45 @@
21
22 /* Unix */
23
24 +/**
25 + * G_DIR_SEPARATOR:
26 + *
27 + * The directory separator character.
28 + * This is '/' on UNIX machines and '\' under Windows.
29 + */
30 #define G_DIR_SEPARATOR '/'
31 +/**
32 + * G_DIR_SEPARATOR_S:
33 + *
34 + * The directory separator as a string.
35 + * This is "/" on UNIX machines and "\" under Windows.
36 + */
37 #define G_DIR_SEPARATOR_S "/"
38 +
39 +/**
40 + * G_IS_DIR_SEPARATOR:
41 + * @c: a character
42 + *
43 + * Checks whether a character is a directory
44 + * separator. It returns %TRUE for '/' on UNIX
45 + * machines and for '\' or '/' under Windows.
46 + *
47 + * Since: 2.6
48 + */
49 #define G_IS_DIR_SEPARATOR(c) ((c) == G_DIR_SEPARATOR)
50 +/**
51 + * G_SEARCHPATH_SEPARATOR:
52 + *
53 + * The search path separator character.
54 + * This is ':' on UNIX machines and ';' under Windows.
55 + */
56 #define G_SEARCHPATH_SEPARATOR ':'
57 +/**
58 + * G_SEARCHPATH_SEPARATOR_S:
59 + *
60 + * The search path separator as a string.
61 + * This is ":" on UNIX machines and ";" under Windows.
62 + */
63 #define G_SEARCHPATH_SEPARATOR_S ":"
64
65 #endif /* !G_OS_WIN32 */
66 @@ -63,6 +106,17 @@
67 /* Define G_VA_COPY() to do the right thing for copying va_list variables.
68 * glibconfig.h may have already defined G_VA_COPY as va_copy or __va_copy.
69 */
70 +/**
71 + * G_VA_COPY:
72 + * @ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
73 + * @ap2: a <type>va_list</type>.
74 + *
75 + * Portable way to copy <type>va_list</type> variables.
76 + *
77 + * In order to use this function, you must include <filename>string.h</filename>
78 + * yourself, because this macro may use <function>memmove()</function> and GLib
79 + * does not include <function>string.h</function> for you.
80 + */
81 #if !defined (G_VA_COPY)
82 # if defined (__GNUC__) && defined (__PPC__) && (defined (_CALL_SYSV) || defined (_WIN32))
83 # define G_VA_COPY(ap1, ap2) (*(ap1) = *(ap2))
84 @@ -186,6 +240,14 @@
85
86 G_CONST_RETURN gchar* g_get_user_special_dir (GUserDirectory directory);
87
88 +/**
89 + * GDebugKey:
90 + * @key: the string
91 + * @value: the flag
92 + *
93 + * Associates a string with a bit flag.
94 + * Used in g_parse_debug_string().
95 + */
96 typedef struct _GDebugKey GDebugKey;
97 struct _GDebugKey
98 {
99 @@ -221,6 +283,20 @@
100 * instead. Whatch out! The string returned by g_path_get_basename
101 * must be g_freed, while the string returned by g_basename must not.*/
102 G_CONST_RETURN gchar* g_basename (const gchar *file_name);
103 +
104 +/**
105 + * g_dirname:
106 + *
107 + * This function is deprecated and will be removed in the next major
108 + * release of GLib. Use g_path_get_dirname() instead.
109 + *
110 + *
111 + * Gets the directory components of a file name.
112 + * If the file name has no directory components "." is returned.
113 + * The returned string should be freed when no longer needed.
114 + *
115 + * Returns: the directory components of the file.
116 + */
117 #define g_dirname g_path_get_dirname
118
119 #endif /* G_DISABLE_DEPRECATED */
120 @@ -261,6 +337,12 @@
121 * not defined, but use is actually abandoned. people should
122 * use g_atexit() instead.
123 */
124 +/**
125 + * GVoidFunc:
126 + *
127 + * Declares a type of function which takes no arguments and has no return value.
128 + * It is used to specify the type function passed to g_atexit().
129 + */
130 typedef void (*GVoidFunc) (void);
131 #ifndef ATEXIT
132 # define ATEXIT(proc) g_ATEXIT(proc)
133 @@ -314,6 +396,18 @@
134 /* inline function implementations
135 */
136 #if defined (G_CAN_INLINE) || defined (__G_UTILS_C__)
137 +/**
138 + * g_bit_nth_lsf:
139 + * @mask: a #gulong containing flags.
140 + * @nth_bit: the index of the bit to start the search from.
141 + *
142 + * Find the position of the first bit set in @mask, searching from (but not
143 + * including) @nth_bit upwards. Bits are numbered from 0 (least significant)
144 + * to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the
145 + * 0th bit, set @nth_bit to -1.
146 + *
147 + * Returns: the index of the first bit set which is higher than @nth_bit.
148 + */
149 G_INLINE_FUNC gint
150 g_bit_nth_lsf (gulong mask,
151 gint nth_bit)
152 @@ -328,6 +422,19 @@
153 }
154 return -1;
155 }
156 +
157 +/**
158 + * g_bit_nth_msf:
159 + * @mask: a #gulong containing flags.
160 + * @nth_bit: the index of the bit to start the search from.
161 + *
162 + * Find the position of the first bit set in @mask, searching from (but not
163 + * including) @nth_bit downwards. Bits are numbered from 0 (least significant)
164 + * to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the
165 + * last bit, set @nth_bit to -1 or GLIB_SIZEOF_LONG * 8.
166 + *
167 + * Returns: the index of the first bit set which is lower than @nth_bit.
168 + */
169 G_INLINE_FUNC gint
170 g_bit_nth_msf (gulong mask,
171 gint nth_bit)
172 @@ -342,6 +449,16 @@
173 }
174 return -1;
175 }
176 +
177 +/**
178 + * g_bit_storage:
179 + * @number: a guint.
180 + *
181 + * Gets the number of bits used to hold @number,
182 + * e.g. if @number is 4, 3 bits are needed.
183 + *
184 + * Returns: the number of bits used to hold @number.
185 + */
186 G_INLINE_FUNC guint
187 g_bit_storage (gulong number)
188 {
189 Index: glib/gmessages.c
190 ===================================================================
191 --- glib/gmessages.c (revision 7087)
192 +++ glib/gmessages.c (working copy)
193 @@ -56,6 +56,19 @@
194 # undef STRICT
195 #endif
196
197 +/**
198 + * SECTION:messages
199 + * @Short_description: versatile support for logging messages with different levels of importance
200 + * @Title: Message Logging
201 + *
202 + * These functions provide support for logging error messages or messages
203 + * used for debugging.
204 + *
205 + *
206 + * There are several built-in levels of messages, defined in #GLogLevelFlags.
207 + * These can be extended with user-defined levels.
208 + */
209 +
210 /* --- structures --- */
211 typedef struct _GLogDomain GLogDomain;
212 typedef struct _GLogHandler GLogHandler;
213 @@ -243,6 +256,23 @@
214 return default_log_func;
215 }
216
217 +/**
218 + * g_log_set_always_fatal:
219 + * @fatal_mask: the mask containing bits set for each level of error which is
220 + * to be fatal.
221 + *
222 + * Sets the message levels which are always fatal, in any log domain.
223 + * When a message with any of these levels is logged the program terminates.
224 + * You can only set the levels defined by GLib to be fatal.
225 + * %G_LOG_LEVEL_ERROR is always fatal.
226 + *
227 + *
228 + * You can also make some message levels
229 + * fatal at runtime by setting the %G_DEBUG environment variable (see
230 + * <ulink url="glib-running.html">Running GLib Applications</ulink>).
231 + *
232 + * Returns: the old fatal mask.
233 + */
234 GLogLevelFlags
235 g_log_set_always_fatal (GLogLevelFlags fatal_mask)
236 {
237 @@ -265,6 +295,16 @@
238 return old_mask;
239 }
240
241 +/**
242 + * g_log_set_fatal_mask:
243 + * @log_domain: the log domain.
244 + * @fatal_mask: the new fatal mask.
245 + *
246 + * Sets the log levels which are fatal in the given domain.
247 + * %G_LOG_LEVEL_ERROR is always fatal.
248 + *
249 + * Returns: the old fatal mask for the log domain.
250 + */
251 GLogLevelFlags
252 g_log_set_fatal_mask (const gchar *log_domain,
253 GLogLevelFlags fatal_mask)
254 @@ -295,6 +335,53 @@
255 return old_flags;
256 }
257
258 +/**
259 + * g_log_set_handler:
260 + * @log_domain: the log domain, or %NULL for the default "" application domain.
261 + * @log_levels: the log levels to apply the log handler for. To handle fatal
262 + * and recursive messages as well, combine the log levels with the
263 + * #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION bit flags.
264 + * @log_func: the log handler function.
265 + * @user_data: data passed to the log handler.
266 + *
267 + * Sets the log handler for a domain and a set of log levels.
268 + * To handle fatal and recursive messages the @log_levels parameter
269 + * must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION
270 + * bit flags.
271 + *
272 + * Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if
273 + * you want to set a handler for this log level you must combine it with
274 + * #G_LOG_FLAG_FATAL.
275 + *
276 + *
277 + * <example>
278 + * <title>Adding a log handler for all warning messages in the default
279 + * (application) domain</title>
280 + * <programlisting>
281 + * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
282 + * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
283 + * </programlisting>
284 + * </example>
285 + *
286 + * <example>
287 + * <title>Adding a log handler for all critical messages from GTK+</title>
288 + * <programlisting>
289 + * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
290 + * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
291 + * </programlisting>
292 + * </example>
293 + *
294 + * <example>
295 + * <title>Adding a log handler for <emphasis>all</emphasis> messages from
296 + * GLib</title>
297 + * <programlisting>
298 + * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
299 + * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
300 + * </programlisting>
301 + * </example>
302 + *
303 + * Returns: the id of the new handler.
304 + */
305 guint
306 g_log_set_handler (const gchar *log_domain,
307 GLogLevelFlags log_levels,
308 @@ -331,6 +418,19 @@
309 return handler_id;
310 }
311
312 +/**
313 + * g_log_set_default_handler:
314 + * @log_func: the log handler function.
315 + * @user_data: data passed to the log handler.
316 + *
317 + * Installs a default log handler which is used if no
318 + * log handler has been set for the particular log domain
319 + * and log level combination. By default, GLib uses
320 + * g_log_default_handler() as default log handler.
321 + *
322 + * Since: 2.6
323 + * Returns: the previous default log handler
324 + */
325 GLogFunc
326 g_log_set_default_handler (GLogFunc log_func,
327 gpointer user_data)
328 @@ -346,6 +446,13 @@
329 return old_log_func;
330 }
331
332 +/**
333 + * g_log_remove_handler:
334 + * @log_domain: the log domain.
335 + * @handler_id: the id of the handler, which was returned in g_log_set_handler().
336 + *
337 + * Removes the log handler.
338 + */
339 void
340 g_log_remove_handler (const gchar *log_domain,
341 guint handler_id)
342 @@ -387,6 +494,18 @@
343 G_STRLOC, handler_id, log_domain);
344 }
345
346 +/**
347 + * g_logv:
348 + * @log_domain: the log domain.
349 + * @log_level: the log level.
350 + * @format: the message format. See the printf()
351 + * documentation.
352 + * @args: the parameters to insert into the format string.
353 + *
354 + * Logs an error or debugging message.
355 + * If the log level has been set as fatal, the abort()
356 + * function is called to terminate the program.
357 + */
358 void
359 g_logv (const gchar *log_domain,
360 GLogLevelFlags log_level,
361 @@ -505,6 +624,18 @@
362 }
363 }
364
365 +/**
366 + * g_log:
367 + * @log_domain: the log domain, usually #G_LOG_DOMAIN.
368 + * @log_level: the log level, either from #GLogLevelFlags or a user-defined level.
369 + * @format: the message format. See the printf()
370 + * documentation.
371 + * @...: the parameters to insert into the format string.
372 + *
373 + * Logs an error or debugging message.
374 + * If the log level has been set as fatal, the abort()
375 + * function is called to terminate the program.
376 + */
377 void
378 g_log (const gchar *log_domain,
379 GLogLevelFlags log_level,
380 @@ -873,6 +1004,22 @@
381 }
382 }
383
384 +/**
385 + * g_log_default_handler:
386 + * @log_domain: the log domain of the message.
387 + * @log_level: the level of the message.
388 + * @message: the message.
389 + * @unused_data: data passed from g_log() which is unused.
390 + *
391 + * The default log handler set up by GLib; g_log_set_default_handler()
392 + * allows to install an alternate default log handler.
393 + * This is used if no log handler has been set for the particular log domain
394 + * and log level combination. It outputs the message to stderr or stdout
395 + * and if the log level is fatal it calls abort().
396 + *
397 + * stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL,
398 + * %G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for the rest.
399 + */
400 void
401 g_log_default_handler (const gchar *log_domain,
402 GLogLevelFlags log_level,
403 Index: glib/gatomic.c
404 ===================================================================
405 --- glib/gatomic.c (revision 7087)
406 +++ glib/gatomic.c (working copy)
407 @@ -31,10 +31,76 @@
408 #include "gthreadprivate.h"
409 #include "galias.h"
410
411 +/**
412 + * SECTION:atomic_operations
413 + * @Short_description: basic atomic integer and pointer operations
414 + * @Title: Atomic Operations
415 + * @See_also:<variablelist>
416 + *
417 + * <varlistentry>
418 + * <term>#GMutex</term>
419 + * <listitem><para>GLib mutual exclusions.</para></listitem>
420 + * </varlistentry>
421 + *
422 + * </variablelist>
423 + *
424 + * The following functions can be used to atomically access integers and
425 + * pointers. They are implemented as inline assembler function on most
426 + * platforms and use slower fall-backs otherwise. Using them can sometimes
427 + * save you from using a performance-expensive #GMutex to protect the
428 + * integer or pointer.
429 + *
430 + *
431 + * The most important usage is reference counting. Using
432 + * g_atomic_int_inc() and g_atomic_int_dec_and_test() makes reference
433 + * counting a very fast operation.
434 + *
435 + *
436 + * <note>
437 + * You must not directly read integers or pointers concurrently accessed
438 + * by multiple threads, but use the atomic accessor functions instead.
439 + * That is, always use g_atomic_int_get() and g_atomic_pointer_get() for
440 + * read outs.
441 + * They provide the neccessary synchonization mechanisms like memory
442 + * barriers to access memory locations concurrently.
443 + *
444 + * </note>
445 + *
446 + * <note>
447 + * If you are using those functions for anything apart from simple
448 + * reference counting, you should really be aware of the implications of
449 + * doing that. There are literally thousands of ways to shoot yourself in
450 + * the foot. So if in doubt, use a #GMutex. If you don't know, what
451 + * memory barriers are, do not use anything but g_atomic_int_inc() and
452 + * g_atomic_int_dec_and_test().
453 + *
454 + * </note>
455 + *
456 + * <note>
457 + * It is not safe to set an integer or pointer just by assigning to it,
458 + * when it is concurrently accessed by other threads with the following
459 + * functions. Use g_atomic_int_compare_and_exchange() or
460 + * g_atomic_pointer_compare_and_exchange() respectively.
461 + *
462 + * </note>
463 + */
464 +
465 #if defined (__GNUC__)
466 # if defined (G_ATOMIC_I486)
467 /* Adapted from CVS version 1.10 of glibc's sysdeps/i386/i486/bits/atomic.h
468 */
469 +/**
470 + * g_atomic_int_exchange_and_add:
471 + * @atomic: a pointer to an integer.
472 + * @val: the value to add to *@atomic.
473 + *
474 + * Atomically adds @val to the integer pointed to by @atomic. It returns
475 + * the value of *@atomic just before the addition took place.
476 + * Also acts as a memory barrier.
477 + *
478 + * Since: 2.4
479 + * Returns: the value of *@atomic before the addition.
480 + */
481 gint
482 g_atomic_int_exchange_and_add (volatile gint *atomic,
483 gint val)
484 @@ -56,6 +122,19 @@
485 : "ir" (val), "m" (*atomic));
486 }
487
488 +/**
489 + * g_atomic_int_compare_and_exchange:
490 + * @atomic: a pointer to an integer.
491 + * @oldval: the assumed old value of *@atomic.
492 + * @newval: the new value of *@atomic.
493 + *
494 + * Compares @oldval with the integer pointed to by @atomic and
495 + * if they are equal, atomically exchanges *@atomic with @newval.
496 + * Also acts as a memory barrier.
497 + *
498 + * Since: 2.4
499 + * Returns: %TRUE, if *@atomic was equal @oldval. %FALSE otherwise.
500 + */
501 gboolean
502 g_atomic_int_compare_and_exchange (volatile gint *atomic,
503 gint oldval,
504 @@ -73,7 +152,19 @@
505 /* The same code as above, as on i386 gpointer is 32 bit as well.
506 * Duplicating the code here seems more natural than casting the
507 * arguments and calling the former function */
508 -
509 +/**
510 + * g_atomic_pointer_compare_and_exchange:
511 + * @atomic: a pointer to a #gpointer.
512 + * @oldval: the assumed old value of *@atomic.
513 + * @newval: the new value of *@atomic.
514 + *
515 + * Compares @oldval with the pointer pointed to by @atomic and
516 + * if they are equal, atomically exchanges *@atomic with @newval.
517 + * Also acts as a memory barrier.
518 + *
519 + * Since: 2.4
520 + * Returns: %TRUE, if *@atomic was equal @oldval. %FALSE otherwise.
521 + */
522 gboolean
523 g_atomic_pointer_compare_and_exchange (volatile gpointer *atomic,
524 gpointer oldval,
525 @@ -790,6 +881,17 @@
526 }
527
528 #ifdef G_ATOMIC_OP_MEMORY_BARRIER_NEEDED
529 +
530 +/**
531 + * g_atomic_int_get:
532 + * @atomic: a pointer to an integer
533 + *
534 + * Reads the value of the integer pointed to by @atomic. Also acts as
535 + * a memory barrier.
536 + *
537 + * Since: 2.4
538 + * Returns: the value of *@atomic
539 + */
540 gint
541 g_atomic_int_get (volatile gint *atomic)
542 {
543 @@ -802,6 +904,16 @@
544 return result;
545 }
546
547 +/**
548 + * g_atomic_int_set:
549 + * @atomic: a pointer to an integer
550 + * @newval: the new value
551 + *
552 + * Sets the value of the integer pointed to by @atomic.
553 + * Also acts as a memory barrier.
554 + *
555 + * Since: 2.10
556 + */
557 void
558 g_atomic_int_set (volatile gint *atomic,
559 gint newval)
560 @@ -811,6 +923,16 @@
561 g_mutex_unlock (g_atomic_mutex);
562 }
563
564 +/**
565 + * g_atomic_pointer_get:
566 + * @atomic: a pointer to a #gpointer.
567 + *
568 + * Reads the value of the pointer pointed to by @atomic. Also acts as
569 + * a memory barrier.
570 + *
571 + * Since: 2.4
572 + * Returns: the value to add to *@atomic.
573 + */
574 gpointer
575 g_atomic_pointer_get (volatile gpointer *atomic)
576 {
577 @@ -823,6 +945,16 @@
578 return result;
579 }
580
581 +/**
582 + * g_atomic_pointer_set:
583 + * @atomic: a pointer to a #gpointer
584 + * @newval: the new value
585 + *
586 + * Sets the value of the pointer pointed to by @atomic.
587 + * Also acts as a memory barrier.
588 + *
589 + * Since: 2.10
590 + */
591 void
592 g_atomic_pointer_set (volatile gpointer *atomic,
593 gpointer newval)
594 @@ -885,6 +1017,16 @@
595 return result;
596 }
597
598 +/**
599 + * g_atomic_int_add:
600 + * @atomic: a pointer to an integer.
601 + * @val: the value to add to *@atomic.
602 + *
603 + * Atomically adds @val to the integer pointed to by @atomic.
604 + * Also acts as a memory barrier.
605 + *
606 + * Since: 2.4
607 + */
608 void
609 g_atomic_int_add (volatile gint *atomic,
610 gint val)
611 Index: glib/gmessages.h
612 ===================================================================
613 --- glib/gmessages.h (revision 7087)
614 +++ glib/gmessages.h (working copy)
615 @@ -48,12 +48,31 @@
616 gsize g_printf_string_upper_bound (const gchar* format,
617 va_list args);
618
619 -/* Log level shift offset for user defined
620 - * log levels (0-7 are used by GLib).
621 +/**
622 + * G_LOG_LEVEL_USER_SHIFT:
623 + *
624 + * Log level shift offset for user defined log levels (0-7 are used by GLib).
625 */
626 #define G_LOG_LEVEL_USER_SHIFT (8)
627
628 -/* Glib log levels and flags.
629 +/**
630 + * GLogLevelFlags:
631 + * @G_LOG_FLAG_RECURSION: internal flag
632 + * @G_LOG_FLAG_FATAL: internal flag
633 + * @G_LOG_LEVEL_ERROR: log level for errors, see g_error().
634 + * This level is also used for messages produced by g_assert().
635 + * @G_LOG_LEVEL_CRITICAL: log level for critical messages, see g_critical().
636 + * This level is also used for messages produced by g_return_if_fail() and
637 + * g_return_val_if_fail().
638 + * @G_LOG_LEVEL_WARNING: log level for warnings, see g_warning()
639 + * @G_LOG_LEVEL_MESSAGE: log level for messages, see g_message()
640 + * @G_LOG_LEVEL_INFO: log level for informational messages
641 + * @G_LOG_LEVEL_DEBUG: log level for debug messages, see g_debug()
642 + * @G_LOG_LEVEL_MASK: a mask including all log levels.
643 + *
644 + * Flags specifying the level of log messages. It is possible to change
645 + * how GLib treats messages of the various levels using g_log_set_handler()
646 + * and g_log_set_fatal_mask().
647 */
648 typedef enum
649 {
650 @@ -72,9 +91,23 @@
651 G_LOG_LEVEL_MASK = ~(G_LOG_FLAG_RECURSION | G_LOG_FLAG_FATAL)
652 } GLogLevelFlags;
653
654 -/* GLib log levels that are considered fatal by default */
655 +/**
656 + * G_LOG_FATAL_MASK:
657 + *
658 + * GLib log levels that are considered fatal by default.
659 + */
660 #define G_LOG_FATAL_MASK (G_LOG_FLAG_RECURSION | G_LOG_LEVEL_ERROR)
661
662 +/**
663 + * GLogFunc:
664 + * @log_domain: the log domain of the message.
665 + * @log_level: the log level of the message (including the fatal and recursion
666 + * flags).
667 + * @message: the message to process.
668 + * @user_data: user data, set in g_log_set_handler().
669 + *
670 + * Specifies the prototype of log handler functions.
671 + */
672 typedef void (*GLogFunc) (const gchar *log_domain,
673 GLogLevelFlags log_level,
674 const gchar *message,
675 @@ -129,7 +162,21 @@
676 const char *expression) G_GNUC_NORETURN;
677 #endif /* !G_DISABLE_DEPRECATED */
678
679 -
680 +/**
681 + * G_LOG_DOMAIN:
682 + *
683 + * Defines the log domain.
684 + * For applications, this is typically left as the default %NULL (or "") domain.
685 + * Libraries should define this so that any messages which they log can
686 + * be differentiated from messages from other libraries and application code.
687 + * But be careful not to define it in any public header files.
688 + *
689 + * For example, GTK+ uses this in its Makefile.am:
690 + *
691 + * <informalexample><programlisting>
692 + * INCLUDES = -DG_LOG_DOMAIN=\"Gtk\"
693 + * </programlisting></informalexample>
694 + */
695 #ifndef G_LOG_DOMAIN
696 #define G_LOG_DOMAIN ((gchar*) 0)
697 #endif /* G_LOG_DOMAIN */
698 @@ -175,6 +222,18 @@
699 G_LOG_LEVEL_DEBUG, \
700 format)
701 #else /* no varargs macros */
702 +
703 +/**
704 + * g_error:
705 + * @...: format string, followed by parameters to insert into the format string (as with printf())
706 + *
707 + * A convenience function/macro to log an error message.
708 + * Error messages are always fatal, resulting in a call to
709 + * abort() to terminate the application.
710 + * This function will result in a core dump; don't use it for errors you
711 + * expect. Using this function indicates a bug in your program, i.e. an
712 + * assertion failure.
713 + */
714 static void
715 g_error (const gchar *format,
716 ...)
717 @@ -186,6 +245,13 @@
718
719 for(;;);
720 }
721 +
722 +/**
723 + * g_message:
724 + * @...: format string, followed by parameters to insert into the format string (as with printf())
725 + *
726 + * A convenience function/macro to log a normal message.
727 + */
728 static void
729 g_message (const gchar *format,
730 ...)
731 @@ -195,6 +261,21 @@
732 g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_MESSAGE, format, args);
733 va_end (args);
734 }
735 +
736 +/**
737 + * g_critical:
738 + * @...: format string, followed by parameters to insert into the format string (as with printf())
739 + *
740 + * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). It's more or less
741 + * application-defined what constitutes a critical vs. a regular
742 + * warning. You could call g_log_set_always_fatal() to make critical
743 + * warnings exit the program, then use g_critical() for fatal errors, for
744 + * example.
745 + *
746 + * You can also make critical warnings fatal at runtime by setting
747 + * the %G_DEBUG environment variable (see
748 + * <ulink url="glib-running.html">Running GLib Applications</ulink>).
749 + */
750 static void
751 g_critical (const gchar *format,
752 ...)
753 @@ -204,6 +285,16 @@
754 g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, format, args);
755 va_end (args);
756 }
757 +
758 +/**
759 + * g_warning:
760 + * @...: format string, followed by parameters to insert into the format string (as with printf())
761 + *
762 + * A convenience function/macro to log a warning message.
763 + *
764 + * You can make warnings fatal at runtime by setting the %G_DEBUG environment
765 + * variable (see <ulink url="glib-running.html">Running GLib Applications</ulink>).
766 + */
767 static void
768 g_warning (const gchar *format,
769 ...)
770 @@ -213,6 +304,15 @@
771 g_logv (G_LOG_DOMAIN, G_LOG_LEVEL_WARNING, format, args);
772 va_end (args);
773 }
774 +
775 +/**
776 + * g_debug:
777 + * @...: format string, followed by parameters to insert into the format string (as with printf())
778 + *
779 + * A convenience function/macro to log a debug message.
780 + *
781 + * Since: 2.6
782 + */
783 static void
784 g_debug (const gchar *format,
785 ...)
786 Index: glib/gatomic.h
787 ===================================================================
788 --- glib/gatomic.h (revision 7087)
789 +++ glib/gatomic.h (working copy)
790 @@ -63,7 +63,26 @@
791 # define g_atomic_pointer_set(atomic, newval) ((void) (*(atomic) = (newval)))
792 #endif /* G_ATOMIC_OP_MEMORY_BARRIER_NEEDED */
793
794 +/**
795 + * g_atomic_int_inc:
796 + * @atomic: a pointer to an integer.
797 + *
798 + * Atomically increments the integer pointed to by @atomic by 1.
799 + *
800 + * Since: 2.4
801 + */
802 #define g_atomic_int_inc(atomic) (g_atomic_int_add ((atomic), 1))
803 +
804 +/**
805 + * g_atomic_int_dec_and_test:
806 + * @atomic: a pointer to an integer.
807 + *
808 + * Atomically decrements the integer pointed to by @atomic by 1.
809 + *
810 + * Since: 2.4
811 + * Returns: %TRUE, if the integer pointed to by @atomic is 0 after
812 + * decrementing it.
813 + */
814 #define g_atomic_int_dec_and_test(atomic) \
815 (g_atomic_int_exchange_and_add ((atomic), -1) == 1)
816
817 Index: glib/gerror.c
818 ===================================================================
819 --- glib/gerror.c (revision 7087)
820 +++ glib/gerror.c (working copy)
821 @@ -29,7 +29,354 @@
822 #include "glib.h"
823 #include "galias.h"
824
825 +/**
826 + * SECTION:error_reporting
827 + * @Short_description: a system for reporting errors
828 + * @Title: Error Reporting
829 + *
830 + *
831 + * GLib provides a standard method of reporting errors from a called function to
832 + * the calling code. (This is the same problem solved by exceptions in other
833 + * languages.) It's important to understand that this method is both a
834 + * <emphasis>data type</emphasis> (the #GError object) and a <emphasis>set of
835 + * rules.</emphasis> If you use #GError incorrectly, then your code will not
836 + * properly interoperate with other code that uses #GError, and users of your API
837 + * will probably get confused.
838 + *
839 + *
840 + * First and foremost: <emphasis>#GError should only be used to report
841 + * recoverable runtime errors, never to report programming errors.</emphasis> If
842 + * the programmer has screwed up, then you should use g_warning(),
843 + * g_return_if_fail(), g_assert(), g_error(), or some similar facility.
844 + * (Incidentally, remember that the g_error() function should
845 + * <emphasis>only</emphasis> be used for programming errors, it should not be used
846 + * to print any error reportable via #GError.)
847 + *
848 + *
849 + * Examples of recoverable runtime errors are "file not found" or "failed to parse
850 + * input." Examples of programming errors are "NULL passed to strcmp()" or
851 + * "attempted to free the same pointer twice." These two kinds of errors are
852 + * fundamentally different: runtime errors should be handled or reported to the
853 + * user, programming errors should be eliminated by fixing the bug in the program.
854 + * This is why most functions in GLib and GTK+ do not use the #GError facility.
855 + *
856 + *
857 + * Functions that can fail take a return location for a #GError as their last argument.
858 + * For example:
859 + * <informalexample><programlisting>
860 + * gboolean g_file_get_contents (const gchar *filename,
861 + * gchar **contents,
862 + * gsize *length,
863 + * GError **error);
864 + * </programlisting></informalexample>
865 + * If you pass a non-%NULL value for the <literal>error</literal> argument, it should
866 + * point to a location where an error can be placed. For example:
867 + * <informalexample><programlisting>
868 + * gchar *contents;
869 + * GError *err = NULL;
870 + * g_file_get_contents ("foo.txt", &contents, NULL, &err);
871 + * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
872 + * if (err != NULL)
873 + * {
874 + * // Report error to user, and free error
875 + * g_assert (contents == NULL);
876 + * fprintf (stderr, "Unable to read file: %s\n", err->message);
877 + * g_error_free (err);
878 + * }
879 + * else
880 + * {
881 + * // Use file contents
882 + * g_assert (contents != NULL);
883 + * }
884 + * </programlisting></informalexample>
885 + * Note that <literal>err != NULL</literal> in this example is a
886 + * <emphasis>reliable</emphasis> indicator of whether
887 + * g_file_get_contents() failed. Additionally, g_file_get_contents() returns
888 + * a boolean which indicates whether it was successful.
889 + *
890 + *
891 + * Because g_file_get_contents() returns %FALSE on failure, if you are only
892 + * interested in whether it failed and don't need to display an error message, you
893 + * can pass %NULL for the <literal>error</literal> argument:
894 + * <informalexample><programlisting>
895 + * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors
896 + * // no error occurred ;
897 + * else
898 + * // error ;
899 + * </programlisting></informalexample>
900 + *
901 + *
902 + * The #GError object contains three fields: <literal>domain</literal> indicates
903 + * the module the error-reporting function is located in, <literal>code</literal>
904 + * indicates the specific error that occurred, and <literal>message</literal> is a
905 + * user-readable error message with as many details as possible. Several functions
906 + * are provided to deal with an error received from a called function:
907 + * g_error_matches() returns %TRUE if the error matches a given domain and code,
908 + * g_propagate_error() copies an error into an error location (so the calling
909 + * function will receive it), and g_clear_error() clears an error location by
910 + * freeing the error and resetting the location to %NULL. To display an error to the
911 + * user, simply display <literal>error->message</literal>, perhaps along with
912 + * additional context known only to the calling function (the file being opened, or
913 + * whatever -- though in the g_file_get_contents() case,
914 + * <literal>error->message</literal> already contains a filename).
915 + *
916 + *
917 + * When implementing a function that can report errors, the basic tool is
918 + * g_set_error(). Typically, if a fatal error occurs you want to g_set_error(),
919 + * then return immediately. g_set_error() does nothing if the error location passed
920 + * to it is %NULL. Here's an example:
921 + * <informalexample><programlisting>
922 + * gint
923 + * foo_open_file (GError **error)
924 + * {
925 + * gint fd;
926 + *
927 + * fd = open ("file.txt", O_RDONLY);
928 + *
929 + * if (fd < 0)
930 + * {
931 + * g_set_error (error,
932 + * FOO_ERROR, // error domain
933 + * FOO_ERROR_BLAH, // error code
934 + * "Failed to open file: %s", // error message format string
935 + * g_strerror (errno));
936 + * return -1;
937 + * }
938 + * else
939 + * return fd;
940 + * }
941 + * </programlisting></informalexample>
942 + *
943 + *
944 + * Things are somewhat more complicated if you yourself call another function that
945 + * can report a #GError. If the sub-function indicates fatal errors in some way
946 + * other than reporting a #GError, such as by returning %TRUE on success, you can
947 + * simply do the following:
948 + * <informalexample><programlisting>
949 + * gboolean
950 + * my_function_that_can_fail (GError **err)
951 + * {
952 + * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
953 + *
954 + * if (!sub_function_that_can_fail (err))
955 + * {
956 + * // assert that error was set by the sub-function
957 + * g_assert (err == NULL || *err != NULL);
958 + * return FALSE;
959 + * }
960 + *
961 + * // otherwise continue, no error occurred
962 + * g_assert (err == NULL || *err == NULL);
963 + * }
964 + * </programlisting></informalexample>
965 + *
966 + *
967 + * If the sub-function does not indicate errors other than by reporting a #GError,
968 + * you need to create a temporary #GError since the passed-in one may be %NULL.
969 + * g_propagate_error() is intended for use in this case.
970 + * <informalexample><programlisting>
971 + * gboolean
972 + * my_function_that_can_fail (GError **err)
973 + * {
974 + * GError *tmp_error;
975 + *
976 + * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
977 + *
978 + * tmp_error = NULL;
979 + * sub_function_that_can_fail (&tmp_error);
980 + *
981 + * if (tmp_error != NULL)
982 + * {
983 + * /<!-- -->* store tmp_error in err, if err != NULL,
984 + * * otherwise call g_error_free(<!-- -->) on tmp_error
985 + * *<!-- -->/
986 + * g_propagate_error (err, tmp_error);
987 + * return FALSE;
988 + * }
989 + *
990 + * // otherwise continue, no error occurred
991 + * }
992 + * </programlisting></informalexample>
993 + *
994 + *
995 + * Error pileups are always a bug. For example, this code is incorrect:
996 + * <informalexample><programlisting>
997 + * gboolean
998 + * my_function_that_can_fail (GError **err)
999 + * {
1000 + * GError *tmp_error;
1001 + *
1002 + * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
1003 + *
1004 + * tmp_error = NULL;
1005 + * sub_function_that_can_fail (&tmp_error);
1006 + * other_function_that_can_fail (&tmp_error);
1007 + *
1008 + * if (tmp_error != NULL)
1009 + * {
1010 + * g_propagate_error (err, tmp_error);
1011 + * return FALSE;
1012 + * }
1013 + * }
1014 + * </programlisting></informalexample>
1015 + * <literal>tmp_error</literal> should be checked immediately after
1016 + * <function>sub_function_that_can_fail()</function>, and either cleared or propagated upward. The rule
1017 + * is: <emphasis>after each error, you must either handle the error, or return it to the
1018 + * calling function</emphasis>. Note that passing %NULL for the error location is the
1019 + * equivalent of handling an error by always doing nothing about it. So the
1020 + * following code is fine, assuming errors in <function>sub_function_that_can_fail()</function> are not
1021 + * fatal to <function>my_function_that_can_fail()</function>:
1022 + * <informalexample><programlisting>
1023 + * gboolean
1024 + * my_function_that_can_fail (GError **err)
1025 + * {
1026 + * GError *tmp_error;
1027 + *
1028 + * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
1029 + *
1030 + * sub_function_that_can_fail (NULL); // ignore errors
1031 + *
1032 + * tmp_error = NULL;
1033 + * other_function_that_can_fail (&tmp_error);
1034 + *
1035 + * if (tmp_error != NULL)
1036 + * {
1037 + * g_propagate_error (err, tmp_error);
1038 + * return FALSE;
1039 + * }
1040 + * }
1041 + * </programlisting></informalexample>
1042 + *
1043 + *
1044 + * Note that passing %NULL for the error location <emphasis>ignores</emphasis>
1045 + * errors; it's equivalent to <literal>try { sub_function_that_can_fail (); } catch
1046 + * (...) {}</literal> in C++. It does <emphasis>not</emphasis> mean to leave errors
1047 + * unhandled; it means to handle them by doing nothing.
1048 + *
1049 + *
1050 + * Error domains and codes are conventionally named as follows:
1051 + * <itemizedlist>
1052 + * <listitem>
1053 + * The error domain is called
1054 + * <literal><NAMESPACE>_<MODULE>_ERROR</literal>, for example
1055 + * %G_SPAWN_ERROR or %G_THREAD_ERROR:
1056 + * <informalexample><programlisting>
1057 + * #define G_SPAWN_ERROR g_spawn_error_quark (<!-- -->)
1058 + *
1059 + * GQuark
1060 + * g_spawn_error_quark (void)
1061 + * {
1062 + * return g_quark_from_static_string ("g-spawn-error-quark");
1063 + * }
1064 + * </programlisting></informalexample>
1065 + *
1066 + * </listitem>
1067 + * <listitem>
1068 + * The error codes are in an enumeration called
1069 + * <literal><Namespace><Module>Error</literal>; for example,
1070 + * #GThreadError or #GSpawnError.
1071 + *
1072 + * </listitem>
1073 + * <listitem>
1074 + * Members of the error code enumeration are called <literal><NAMESPACE>_<MODULE>_ERROR_<CODE></literal>, for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
1075 + *
1076 + * </listitem>
1077 + * <listitem>
1078 + * If there's a "generic" or "unknown" error code for unrecoverable errors it
1079 + * doesn't make sense to distinguish with specific codes, it should be called
1080 + * <literal><NAMESPACE>_<MODULE>_ERROR_FAILED</literal>, for
1081 + * example %G_SPAWN_ERROR_FAILED or %G_THREAD_ERROR_FAILED.
1082 + *
1083 + * </listitem>
1084 + * </itemizedlist>
1085 + *
1086 + *
1087 + * Summary of rules for use of #GError:
1088 + * <itemizedlist>
1089 + * <listitem>
1090 + * Do not report programming errors via #GError.
1091 + *
1092 + * </listitem>
1093 + *
1094 + * <listitem>
1095 + * The last argument of a function that returns an error should be a
1096 + * location where a #GError can be placed (i.e. "#GError** error"). If
1097 + * #GError is used with varargs, the #GError** should be the last
1098 + * argument before the "...".
1099 + *
1100 + * </listitem>
1101 + *
1102 + * <listitem>
1103 + * The caller may pass %NULL for the #GError** if they are not interested
1104 + * in details of the exact error that occurred.
1105 + *
1106 + * </listitem>
1107 + *
1108 + * <listitem>
1109 + * If %NULL is passed for the #GError** argument, then errors should
1110 + * not be returned to the caller, but your function should still
1111 + * abort and return if an error occurs. That is, control flow should
1112 + * not be affected by whether the caller wants to get a #GError.
1113 + *
1114 + * </listitem>
1115 + *
1116 + * <listitem>
1117 + * If a #GError is reported, then your function by definition
1118 + * <emphasis>had a fatal failure and did not complete whatever it was supposed
1119 + * to do</emphasis>. If the failure was not fatal, then you handled it
1120 + * and you should not report it. If it was fatal, then you must report it
1121 + * and discontinue whatever you were doing immediately.
1122 + *
1123 + * </listitem>
1124 + *
1125 + * <listitem>
1126 + * A #GError* must be initialized to %NULL before passing its address to
1127 + * a function that can report errors.
1128 + *
1129 + * </listitem>
1130 + *
1131 + * <listitem>
1132 + * "Piling up" errors is always a bug. That is, if you assign a new
1133 + * #GError to a #GError* that is non-%NULL, thus overwriting the previous
1134 + * error, it indicates that you should have aborted the operation instead
1135 + * of continuing. If you were able to continue, you should have cleared
1136 + * the previous error with g_clear_error(). g_set_error() will complain
1137 + * if you pile up errors.
1138 + *
1139 + * </listitem>
1140 + *
1141 + *
1142 + * <listitem>
1143 + * By convention, if you return a boolean value indicating success
1144 + * then %TRUE means success and %FALSE means failure. If %FALSE is returned,
1145 + * the error <emphasis>must</emphasis> be set to a non-%NULL value.
1146 + *
1147 + * </listitem>
1148 + *
1149 + *
1150 + * <listitem>
1151 + * A %NULL return value is also frequently used to mean that an error
1152 + * occurred. You should make clear in your documentation whether %NULL is
1153 + * a valid return value in non-error cases; if %NULL is a valid value,
1154 + * then users must check whether an error was returned to see if the
1155 + * function succeeded.
1156 + *
1157 + * </listitem>
1158 + *
1159 + * <listitem>
1160 + * When implementing a function that can report errors, you may want to
1161 + * add a check at the top of your function that the error return location
1162 + * is either %NULL or contains a %NULL error
1163 + * (e.g. <literal>g_return_if_fail (error == NULL || *error ==
1164 + * NULL);</literal>).
1165 + *
1166 + * </listitem>
1167 + *
1168 + *
1169 + * </itemizedlist>
1170 + */
1171
1172 +
1173 static GError*
1174 g_error_new_valist (GQuark domain,
1175 gint code,
1176 Index: glib/gerror.h
1177 ===================================================================
1178 --- glib/gerror.h (revision 7087)
1179 +++ glib/gerror.h (working copy)
1180 @@ -29,6 +29,15 @@
1181
1182 G_BEGIN_DECLS
1183
1184 +/**
1185 + * GError:
1186 + * @domain: error domain, e.g. #G_FILE_ERROR.
1187 + * @code: error code, e.g. %G_FILE_ERROR_NOENT.
1188 + * @message: human-readable informative error message.
1189 + *
1190 + * The <structname>GError</structname> structure contains
1191 + * information about an error that has occurred.
1192 + */
1193 typedef struct _GError GError;
1194
1195 struct _GError
1196 Index: glib/gfileutils.c
1197 ===================================================================
1198 --- glib/gfileutils.c (revision 7087)
1199 +++ glib/gfileutils.c (working copy)
1200 @@ -54,6 +54,35 @@
1201
1202 #include "galias.h"
1203
1204 +/**
1205 + * SECTION:fileutils
1206 + * @Short_description: various file-related functions
1207 + * @Title: File Utilities
1208 + *
1209 + * There is a group of functions which wrap the common POSIX functions
1210 + * dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(),
1211 + * g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these
1212 + * wrappers is to make it possible to handle file names with any Unicode
1213 + * characters in them on Windows without having to use ifdefs and the
1214 + * wide character API in the application code.
1215 + *
1216 + * The pathname argument should be in the GLib file name encoding. On
1217 + * POSIX this is the actual on-disk encoding which might correspond to
1218 + * the locale settings of the process (or the
1219 + * <envar>G_FILENAME_ENCODING</envar> environment variable), or not.
1220 + *
1221 + * On Windows the GLib file name encoding is UTF-8. Note that the
1222 + * Microsoft C library does not use UTF-8, but has separate APIs for
1223 + * current system code page and wide characters (UTF-16). The GLib
1224 + * wrappers call the wide character API if present (on modern Windows
1225 + * systems), otherwise convert to/from the system code page.
1226 + *
1227 + *
1228 + * Another group of functions allows to open and read directories
1229 + * in the GLib file name encoding. These are g_dir_open(),
1230 + * g_dir_read_name(), g_dir_rewind(), g_dir_close().
1231 + */
1232 +
1233 static gint create_temp_file (gchar *tmpl,
1234 int permissions);
1235
1236 Index: glib/gfileutils.h
1237 ===================================================================
1238 --- glib/gfileutils.h (revision 7087)
1239 +++ glib/gfileutils.h (working copy)
1240 @@ -29,8 +29,99 @@
1241
1242 G_BEGIN_DECLS
1243
1244 +/**
1245 + * G_FILE_ERROR:
1246 + *
1247 + * Error domain for file operations. Errors in this domain will
1248 + * be from the #GFileError enumeration. See #GError for information on
1249 + * error domains.
1250 + */
1251 #define G_FILE_ERROR g_file_error_quark ()
1252
1253 +/**
1254 + * GFileError:
1255 + * @G_FILE_ERROR_EXIST: Operation not permitted; only the owner of the
1256 + * file (or other resource) or processes with special privileges can
1257 + * perform the operation.
1258 + * @G_FILE_ERROR_ISDIR: File is a directory; you cannot open a directory
1259 + * for writing, or create or remove hard links to it.
1260 + * @G_FILE_ERROR_ACCES: Permission denied; the file permissions do not
1261 + * allow the attempted operation.
1262 + * @G_FILE_ERROR_NAMETOOLONG: Filename too long.
1263 + * @G_FILE_ERROR_NOENT: No such file or directory. This is a "file
1264 + * doesn't exist" error for ordinary files that are referenced in
1265 + * contexts where they are expected to already exist.
1266 + * @G_FILE_ERROR_NOTDIR: A file that isn't a directory was specified when
1267 + * a directory is required.
1268 + * @G_FILE_ERROR_NXIO: No such device or address. The system tried to
1269 + * use the device represented by a file you specified, and it
1270 + * couldn't find the device. This can mean that the device file was
1271 + * installed incorrectly, or that the physical device is missing or
1272 + * not correctly attached to the computer.
1273 + * @G_FILE_ERROR_NODEV: This file is of a type that doesn't support
1274 + * mapping.
1275 + * @G_FILE_ERROR_ROFS: The directory containing the new link can't be
1276 + * modified because it's on a read-only file system.
1277 + * @G_FILE_ERROR_TXTBSY: Text file busy.
1278 + * @G_FILE_ERROR_FAULT: You passed in a pointer to bad memory.
1279 + * (GLib won't reliably return this, don't pass in pointers to bad
1280 + * memory.)
1281 + * @G_FILE_ERROR_LOOP: Too many levels of symbolic links were encountered
1282 + * in looking up a file name. This often indicates a cycle of symbolic
1283 + * links.
1284 + * @G_FILE_ERROR_NOSPC: No space left on device; write operation on a
1285 + * file failed because the disk is full.
1286 + * @G_FILE_ERROR_NOMEM: No memory available. The system cannot allocate
1287 + * more virtual memory because its capacity is full.
1288 + * @G_FILE_ERROR_MFILE: The current process has too many files open and
1289 + * can't open any more. Duplicate descriptors do count toward this
1290 + * limit.
1291 + * @G_FILE_ERROR_NFILE: There are too many distinct file openings in the
1292 + * entire system.
1293 + * @G_FILE_ERROR_BADF: Bad file descriptor; for example, I/O on a
1294 + * descriptor that has been closed or reading from a descriptor open
1295 + * only for writing (or vice versa).
1296 + * @G_FILE_ERROR_INVAL: Invalid argument. This is used to indicate
1297 + * various kinds of problems with passing the wrong argument to a
1298 + * library function.
1299 + * @G_FILE_ERROR_PIPE: Broken pipe; there is no process reading from the
1300 + * other end of a pipe. Every library function that returns this
1301 + * error code also generates a `SIGPIPE' signal; this signal
1302 + * terminates the program if not handled or blocked. Thus, your
1303 + * program will never actually see this code unless it has handled or
1304 + * blocked `SIGPIPE'.
1305 + * @G_FILE_ERROR_AGAIN: Resource temporarily unavailable; the call might
1306 + * work if you try again later.
1307 + * @G_FILE_ERROR_INTR: Interrupted function call; an asynchronous signal
1308 + * occurred and prevented completion of the call. When this
1309 + * happens, you should try the call again.
1310 + * @G_FILE_ERROR_IO: Input/output error; usually used for physical read
1311 + * or write errors. i.e. the disk or other physical device hardware
1312 + * is returning errors.
1313 + * @G_FILE_ERROR_PERM: Operation not permitted; only the owner of the
1314 + * file (or other resource) or processes with special privileges can
1315 + * perform the operation.
1316 + * @G_FILE_ERROR_NOSYS: Function not implemented; this indicates that the
1317 + * system is missing some functionality.
1318 + * @G_FILE_ERROR_FAILED: Does not correspond to a UNIX error code; this
1319 + * is the standard "failed for unspecified reason" error code present in
1320 + * all #GError error code enumerations. Returned if no specific
1321 + * code applies.
1322 + *
1323 + * Values corresponding to <literal>errno</literal> codes returned from file operations
1324 + * on UNIX. Unlike <literal>errno</literal> codes, #GFileError values are available on
1325 + * all systems, even Windows. The exact meaning of each code depends on what
1326 + * sort of file operation you were performing; the UNIX documentation
1327 + * gives more details. The following error code descriptions come
1328 + * from the GNU C Library manual, and are under the copyright
1329 + * of that manual.
1330 + *
1331 + *
1332 + * It's not very portable to make detailed assumptions about exactly
1333 + * which errors will be returned from a given operation. Some errors
1334 + * don't occur on some systems, etc., sometimes there are subtle
1335 + * differences in when a system will report a given error, etc.
1336 + */
1337 typedef enum
1338 {
1339 G_FILE_ERROR_EXIST,
1340 @@ -64,6 +155,19 @@
1341 * anonymous enum in libgnome. But don't use that enum
1342 * in new code.
1343 */
1344 +/**
1345 + * GFileTest:
1346 + * @G_FILE_TEST_IS_REGULAR: %TRUE if the file is a regular file (not a directory).
1347 + * Note that this test will also return %TRUE if the tested file is a symlink
1348 + * to a regular file.
1349 + * @G_FILE_TEST_IS_SYMLINK: %TRUE if the file is a symlink.
1350 + * @G_FILE_TEST_IS_DIR: %TRUE if the file is a directory.
1351 + * @G_FILE_TEST_IS_EXECUTABLE: %TRUE if the file is executable.
1352 + * @G_FILE_TEST_EXISTS: %TRUE if the file exists.
1353 + * It may or may not be a regular file.
1354 + *
1355 + * A test to perform on a file using g_file_test().
1356 + */
1357 typedef enum
1358 {
1359 G_FILE_TEST_IS_REGULAR = 1 << 0,
1360 Index: glib/ghash.c
1361 ===================================================================
1362 --- glib/ghash.c (revision 7087)
1363 +++ glib/ghash.c (working copy)
1364 @@ -33,7 +33,46 @@
1365 #include "glib.h"
1366 #include "galias.h"
1367
1368 +/**
1369 + * SECTION:hash_tables
1370 + * @Short_description: associations between keys and values so that given a key
1371 + * the value can be found quickly
1372 + * @Title: Hash Tables
1373 + *
1374 + * A #GHashTable provides associations between keys and values which
1375 + * is optimized so that given a key, the associated value can be found
1376 + * very quickly.
1377 + *
1378 + * Note that neither keys nor values are copied when inserted into the
1379 + * #GHashTable, so they must exist for the lifetime of the #GHashTable.
1380 + * This means that the use of static strings is OK, but temporary
1381 + * strings (i.e. those created in buffers and those returned by GTK+ widgets)
1382 + * should be copied with g_strdup() before being inserted.
1383 + *
1384 + * If keys or values are dynamically allocated, you must be careful to ensure
1385 + * that they are freed when they are removed from the #GHashTable, and also
1386 + * when they are overwritten by new insertions into the #GHashTable.
1387 + * It is also not advisable to mix static strings and dynamically-allocated
1388 + * strings in a #GHashTable, because it then becomes difficult to determine
1389 + * whether the string should be freed.
1390 + *
1391 + * To create a #GHashTable, use g_hash_table_new().
1392 + *
1393 + * To insert a key and value into a #GHashTable, use g_hash_table_insert().
1394 + *
1395 + * To lookup a value corresponding to a given key, use g_hash_table_lookup()
1396 + * and g_hash_table_lookup_extended().
1397 + *
1398 + * To remove a key and value, use g_hash_table_remove().
1399 + *
1400 + * To call a function for each key and value pair use g_hash_table_foreach()
1401 + * or use a iterator to iterate over the key/value pairs in the hash table, see
1402 + * #GHashTableIter.
1403 + *
1404 + * To destroy a #GHashTable use g_hash_table_destroy().
1405 + */
1406
1407 +
1408 #define HASH_TABLE_MIN_SIZE 11
1409 #define HASH_TABLE_MAX_SIZE 13845163
1410
1411 Index: glib/ghash.h
1412 ===================================================================
1413 --- glib/ghash.h (revision 7087)
1414 +++ glib/ghash.h (working copy)
1415 @@ -36,12 +36,41 @@
1416
1417 G_BEGIN_DECLS
1418
1419 +/**
1420 + * GHashTable:
1421 + *
1422 + * The <structname>GHashTable</structname> struct is an opaque data structure
1423 + * to represent a <link linkend="glib-Hash-Tables">Hash Table</link>.
1424 + * It should only be accessed via the following functions.
1425 + */
1426 typedef struct _GHashTable GHashTable;
1427
1428 +/**
1429 + * GHRFunc:
1430 + * @key: a key.
1431 + * @value: the value associated with the key.
1432 + * @user_data: user data passed to g_hash_table_remove().
1433 + *
1434 + * Specifies the type of the function passed to g_hash_table_foreach_remove().
1435 + * It is called with each key/value pair, together with the @user_data parameter
1436 + * passed to g_hash_table_foreach_remove().
1437 + * It should return %TRUE if the key/value pair should be removed from the
1438 + * #GHashTable.
1439 + *
1440 + * Returns: %TRUE if the key/value pair should be removed from the #GHashTable.
1441 + */
1442 typedef gboolean (*GHRFunc) (gpointer key,
1443 gpointer value,
1444 gpointer user_data);
1445
1446 +/**
1447 + * GHashTableIter:
1448 + *
1449 + * A GHashTableIter structure represents an iterator that can be
1450 + * used to iterate over the elements of a #GHashTable. GHashTableIter
1451 + * structures are typically allocated on the stack and then initialized
1452 + * with g_hash_table_iter_init().
1453 + */
1454 typedef struct _GHashTableIter GHashTableIter;
1455
1456 struct _GHashTableIter
1457 @@ -113,9 +142,22 @@
1458
1459 #ifndef G_DISABLE_DEPRECATED
1460
1461 -/* The following two functions are deprecated and will be removed in
1462 - * the next major release. They do no good. */
1463 +/**
1464 + * g_hash_table_freeze:
1465 + * @hash_table: a #GHashTable
1466 + *
1467 + * This function is deprecated and will be removed in the next major
1468 + * release of GLib. It does nothing.
1469 + */
1470 #define g_hash_table_freeze(hash_table) ((void)0)
1471 +
1472 +/**
1473 + * g_hash_table_thaw:
1474 + * @hash_table: a #GHashTable
1475 + *
1476 + * This function is deprecated and will be removed in the next major
1477 + * release of GLib. It does nothing.
1478 + */
1479 #define g_hash_table_thaw(hash_table) ((void)0)
1480
1481 #endif /* G_DISABLE_DEPRECATED */
1482 Index: glib/gchecksum.c
1483 ===================================================================
1484 --- glib/gchecksum.c (revision 7087)
1485 +++ glib/gchecksum.c (working copy)
1486 @@ -29,6 +29,28 @@
1487
1488 #include "galias.h"
1489
1490 +/**
1491 + * SECTION:checksum
1492 + * @Short_description: Computes the checksum for data
1493 + * @Title: Data Checksums
1494 + *
1495 + * GLib provides a generic API for computing checksums (or "digests") for a
1496 + * sequence of arbitrary bytes, using various hashing algorithms like MD5,
1497 + * SHA-1 and SHA-256. Checksums are commonly used in various environments and
1498 + * specifications.
1499 + *
1500 + *
1501 + * GLib supports incremental checksums using the GChecksum data structure, by
1502 + * calling g_checksum_update() as long as there's data available and then using
1503 + * g_checksum_get_string() or g_checksum_get_digest() to compute the checksum
1504 + * and return it either as a string in hexadecimal form, or as a raw sequence
1505 + * of bytes. To compute the checksum for binary blobs and NUL-terminated strings
1506 + * in one go, use the convenience functions g_compute_checksum_for_data() and
1507 + * g_compute_checksum_for_string(), respectively.
1508 + *
1509 + * Support for checksums has been added in GLib 2.16
1510 + */
1511 +
1512 #define IS_VALID_TYPE(type) ((type) >= G_CHECKSUM_MD5 && (type) <= G_CHECKSUM_SHA256)
1513
1514 static const gchar hex_digits[] = "0123456789abcdef";
1515 Index: glib/gtypes.h
1516 ===================================================================
1517 --- glib/gtypes.h (revision 7087)
1518 +++ glib/gtypes.h (working copy)
1519 @@ -35,6 +35,26 @@
1520
1521 G_BEGIN_DECLS
1522
1523 +/**
1524 + * SECTION:types
1525 + * @Short_description: standard GLib types, defined for ease-of-use and portability
1526 + * @Title: Basic Types
1527 + *
1528 + * GLib defines a number of commonly used types, which can be divided into
1529 + * 4 groups:
1530 + *
1531 + * New types which are not part of standard C - #gboolean, #gsize, #gssize.
1532 + *
1533 + * Integer types which are guaranteed to be the same size across all platforms -
1534 + * #gint8, #guint8, #gint16, #guint16, #gint32, #guint32, #gint64, #guint64.
1535 + *
1536 + * Types which are easier to use than their standard C counterparts -
1537 + * #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
1538 + *
1539 + * Types which correspond exactly to standard C types, but are included
1540 + * for completeness - #gchar, #gint, #gshort, #glong, #gfloat, #gdouble.
1541 + */
1542 +
1543 /* Provide type definitions for commonly used types.
1544 * These are useful because a "gint8" can be adjusted
1545 * to be 1 byte (8 bits) on all platforms. Similarly and
1546 @@ -42,20 +62,168 @@
1547 * 4 bytes (32 bits) on all platforms.
1548 */
1549
1550 +/**
1551 + * gchar:
1552 + *
1553 + * Corresponds to the standard C <type>char</type> type.
1554 + */
1555 typedef char gchar;
1556 +
1557 +/**
1558 + * gshort:
1559 + *
1560 + * Corresponds to the standard C <type>short</type> type.
1561 + * Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
1562 + */
1563 typedef short gshort;
1564 +
1565 +/**
1566 + * glong:
1567 + *
1568 + * Corresponds to the standard C <type>long</type> type.
1569 + * Values of this type can range from #G_MINLONG to #G_MAXLONG.
1570 + */
1571 typedef long glong;
1572 +
1573 +/**
1574 + * gint:
1575 + *
1576 + * Corresponds to the standard C <type>int</type> type.
1577 + * Values of this type can range from #G_MININT to #G_MAXINT.
1578 + */
1579 typedef int gint;
1580 +
1581 +/**
1582 + * gboolean:
1583 + *
1584 + * A standard <type>boolean</type> type.
1585 + * Variables of this type should only contain the value %TRUE or %FALSE.
1586 + */
1587 typedef gint gboolean;
1588
1589 +/**
1590 + * guchar:
1591 + *
1592 + * Corresponds to the standard C <type>unsigned char</type> type.
1593 + */
1594 typedef unsigned char guchar;
1595 +
1596 +/**
1597 + * gushort:
1598 + *
1599 + * Corresponds to the standard C <type>unsigned short</type> type.
1600 + * Values of this type can range from 0 to #G_MAXUSHORT.
1601 + */
1602 typedef unsigned short gushort;
1603 +
1604 +/**
1605 + * gulong:
1606 + *
1607 + * Corresponds to the standard C <type>unsigned long</type> type.
1608 + * Values of this type can range from 0 to #G_MAXULONG.
1609 + */
1610 typedef unsigned long gulong;
1611 +
1612 +/**
1613 + * guint:
1614 + *
1615 + * Corresponds to the standard C <type>unsigned int</type> type.
1616 + * Values of this type can range from 0 to #G_MAXUINT.
1617 + */
1618 typedef unsigned int guint;
1619
1620 +/**
1621 + * gfloat:
1622 + *
1623 + * Corresponds to the standard C <type>float</type> type.
1624 + * Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT.
1625 + */
1626 typedef float gfloat;
1627 +
1628 +/**
1629 + * gdouble:
1630 + *
1631 + * Corresponds to the standard C <type>double</type> type.
1632 + * Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE.
1633 + */
1634 typedef double gdouble;
1635
1636 +/* Note: The following exists within glibconfig.h,
1637 + * but we can't comment them there due to that file being automatically
1638 + * generated. */
1639 +/**
1640 + * gint8:
1641 + *
1642 + * A signed integer guaranteed to be 8 bits on all platforms.
1643 + * Values of this type can range from -128 to 127.
1644 + */
1645 +/**
1646 + * gint16:
1647 + *
1648 + * A signed integer guaranteed to be 16 bits on all platforms.
1649 + * Values of this type can range from -32,768 to 32,767.
1650 + */
1651 +/**
1652 + * gint32:
1653 + *
1654 + * A signed integer guaranteed to be 32 bits on all platforms.
1655 + * Values of this type can range from -2,147,483,648 to 2,147,483,647.
1656 + */
1657 +/**
1658 + * gint64:
1659 + *
1660 + * A signed integer guaranteed to be 64 bits on all platforms.
1661 + * Values of this type can range from -9,223,372,036,854,775,808 to
1662 + * 9,223,372,036,854,775,807.
1663 + */
1664 +
1665 +/**
1666 + * guint8:
1667 + *
1668 + * An unsigned integer guaranteed to be 8 bits on all platforms.
1669 + * Values of this type can range from 0 to 255.
1670 + */
1671 +/**
1672 + * guint16:
1673 + *
1674 + * An unsigned integer guaranteed to be 16 bits on all platforms.
1675 + * Values of this type can range from 0 to 65,535.
1676 + */
1677 +/**
1678 + * guint32:
1679 + *
1680 + * An unsigned integer guaranteed to be 32 bits on all platforms.
1681 + * Values of this type can range from 0 to 4,294,967,295.
1682 + */
1683 +/**
1684 + * guint64:
1685 + *
1686 + * An unsigned integer guaranteed to be 64 bits on all platforms.
1687 + * Values of this type can range from 0 to 18,446,744,073,709,551,615.
1688 + */
1689 +
1690 +/**
1691 + * gsize:
1692 + *
1693 + * An unsigned integer type of the result of the sizeof operator, corresponding
1694 + * to the size_t type defined in C99. This type is wide enough to hold the numeric
1695 + * value of a pointer, so it is usually 32bit wide on a 32bit platform and
1696 + * 64bit wide on a 64bit platform.
1697 + */
1698 +/**
1699 + * gssize:
1700 + *
1701 + * A signed variant of gsize, corresponding to the ssize_t defined on most platforms.
1702 + */
1703 +/**
1704 + * goffset:
1705 + *
1706 + * A signed integer type that is used for file offsets, corresponding to the
1707 + * C99 type off64_t.
1708 + *
1709 + * Since: 2.14
1710 + */
1711 +
1712 /* Define min and max constants for the fixed size numerical types */
1713 #define G_MININT8 ((gint8) 0x80)
1714 #define G_MAXINT8 ((gint8) 0x7f)
1715 @@ -73,23 +241,137 @@
1716 #define G_MAXINT64 G_GINT64_CONSTANT(0x7fffffffffffffff)
1717 #define G_MAXUINT64 G_GINT64_CONSTANT(0xffffffffffffffffU)
1718
1719 +/**
1720 + * gpointer:
1721 + *
1722 + * An untyped pointer.
1723 + * #gpointer looks better and is easier to use than <type>void*</type>.
1724 + */
1725 typedef void* gpointer;
1726 +
1727 +/**
1728 + * gconstpointer:
1729 + *
1730 + * An untyped pointer to constant data.
1731 + * The data pointed to should not be changed.
1732 + *
1733 + * This is typically used in function prototypes to indicate that the
1734 + * data pointed to will not be altered by the function.
1735 + */
1736 typedef const void *gconstpointer;
1737
1738 +/**
1739 + * GCompareDataFunc:
1740 + * @a: a value.
1741 + * @b: a value to compare with.
1742 + * @user_data: user data to pass to comparison function.
1743 + *
1744 + * Specifies the type of a comparison function used to compare two
1745 + * values. The function should return a negative integer if the first
1746 + * value comes before the second, 0 if they are equal, or a positive
1747 + * integer if the first value comes after the second.
1748 + *
1749 + * Returns: negative value if @a < @b; zero if @a = @b; positive value
1750 + * if @a > @b.
1751 + */
1752 typedef gint (*GCompareFunc) (gconstpointer a,
1753 gconstpointer b);
1754 +
1755 +/**
1756 + * GCompareFunc:
1757 + * @a: a value.
1758 + * @b: a value to compare with.
1759 + *
1760 + * Specifies the type of a comparison function used to compare two
1761 + * values. The function should return a negative integer if the first
1762 + * value comes before the second, 0 if they are equal, or a positive
1763 + * integer if the first value comes after the second.
1764 + *
1765 + * Returns: negative value if @a < @b; zero if @a = @b; positive value
1766 + * if @a > @b.
1767 + */
1768 typedef gint (*GCompareDataFunc) (gconstpointer a,
1769 gconstpointer b,
1770 gpointer user_data);
1771 +/**
1772 + * GEqualFunc:
1773 + * @a: a value.
1774 + * @b: a value to compare with.
1775 + *
1776 + * Specifies the type of a function used to test two values for
1777 + * equality. The function should return %TRUE if both values are equal and
1778 + * %FALSE otherwise.
1779 + *
1780 + * Returns: %TRUE if @a = @b; %FALSE otherwise.
1781 + */
1782 typedef gboolean (*GEqualFunc) (gconstpointer a,
1783 gconstpointer b);
1784 +
1785 +/**
1786 + * GDestroyNotify:
1787 + * @data: the data element.
1788 + *
1789 + * Specifies the type of function which is called when a data element is
1790 + * destroyed. It is passed the pointer to the data element and should free
1791 + * any memory and resources allocated for it.
1792 + */
1793 typedef void (*GDestroyNotify) (gpointer data);
1794 +
1795 +/**
1796 + * GFunc:
1797 + * @data: the element's data.
1798 + * @user_data: user data passed to g_list_foreach() or g_slist_foreach().
1799 + *
1800 + * Specifies the type of functions passed to g_list_foreach() and
1801 + * g_slist_foreach().
1802 + */
1803 typedef void (*GFunc) (gpointer data,
1804 gpointer user_data);
1805 +
1806 +/**
1807 + * GHashFunc:
1808 + * @key: a key.
1809 + *
1810 + * Specifies the type of the hash function which is passed to
1811 + * g_hash_table_new() when a #GHashTable is created.
1812 + *
1813 + * The function is passed a key and should return a #guint hash value.
1814 + * The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
1815 + * hash functions which can be used when the key is a #gpointer, #gint, and
1816 + * #gchar* respectively.
1817 + *
1818 + * <!-- FIXME: Need more here. -->
1819 + * The hash values should be evenly distributed over a fairly large range?
1820 + * The modulus is taken with the hash table size (a prime number)
1821 + * to find the 'bucket' to place each key into.
1822 + * The function should also be very fast, since it is called for each key
1823 + * lookup.
1824 + *
1825 + * Returns: the hash value corresponding to the key.
1826 + */
1827 typedef guint (*GHashFunc) (gconstpointer key);
1828 +
1829 +/**
1830 + * GHFunc:
1831 + * @key: a key.
1832 + * @value: the value corresponding to the key.
1833 + * @user_data: user data passed to g_hash_table_foreach().
1834 + *
1835 + * Specifies the type of the function passed to g_hash_table_foreach().
1836 + * It is called with each key/value pair, together with the @user_data parameter
1837 + * which is passed to g_hash_table_foreach().
1838 + */
1839 typedef void (*GHFunc) (gpointer key,
1840 gpointer value,
1841 gpointer user_data);
1842 +
1843 +/**
1844 + * GFreeFunc:
1845 + * @data: a data pointer.
1846 + *
1847 + * Declares a type of function which takes an arbitrary data pointer argument
1848 + * and has no return value. It is not currently used in GLib or GTK+.
1849 + */
1850 typedef void (*GFreeFunc) (gpointer data);
1851 typedef const gchar * (*GTranslateFunc) (const gchar *str,
1852 gpointer data);
1853 @@ -396,6 +678,15 @@
1854 #error unknown ENDIAN type
1855 #endif /* !G_LITTLE_ENDIAN && !G_BIG_ENDIAN */
1856
1857 +/**
1858 + * GTimeVal:
1859 + * @tv_sec: seconds
1860 + * @tv_usec: microseconds
1861 + *
1862 + * Represents a precise time, with seconds and microseconds.
1863 + * Similar to the <structname>struct timeval</structname> returned by
1864 + * the <function>gettimeofday()</function> UNIX call.
1865 + */
1866 typedef struct _GTimeVal GTimeVal;
1867
1868 struct _GTimeVal
1869 Index: glib/gcompletion.c
1870 ===================================================================
1871 --- glib/gcompletion.c (revision 7087)
1872 +++ glib/gcompletion.c (working copy)
1873 @@ -35,9 +35,44 @@
1874 #include "glib.h"
1875 #include "galias.h"
1876
1877 +/**
1878 + * SECTION:completion
1879 + * @Short_description: support for automatic completion using a group of target strings
1880 + * @Title: Automatic String Completion
1881 + *
1882 + * #GCompletion provides support for automatic completion of a string using
1883 + * any group of target strings. It is typically used for file name completion
1884 + * as is common in many UNIX shells.
1885 + *
1886 + * A #GCompletion is created using g_completion_new().
1887 + * Target items are added and removed with
1888 + * g_completion_add_items(), g_completion_remove_items() and
1889 + * g_completion_clear_items().
1890 + * A completion attempt is requested with g_completion_complete() or
1891 + * g_completion_complete_utf8().
1892 + * When no longer needed, the #GCompletion is freed with g_completion_free().
1893 + *
1894 + * Items in the completion can be simple strings (e.g. filenames),
1895 + * or pointers to arbitrary data structures. If data structures are used
1896 + * you must provide a #GCompletionFunc in g_completion_new(),
1897 + * which retrieves the item's string from the data structure.
1898 + * You can change the way in which strings are compared by setting
1899 + * a different #GCompletionStrncmpFunc in g_completion_set_compare().
1900 + */
1901 +
1902 static void completion_check_cache (GCompletion* cmp,
1903 gchar** new_prefix);
1904
1905 +/**
1906 + * g_completion_new:
1907 + * @func: the function to be called to return the string representing an item
1908 + * in the #GCompletion, or %NULL if strings are going to be used as the
1909 + * #GCompletion items.
1910 + *
1911 + * Creates a new #GCompletion.
1912 + *
1913 + * Returns: the new #GCompletion.
1914 + */
1915 GCompletion*
1916 g_completion_new (GCompletionFunc func)
1917 {
1918 @@ -53,6 +88,13 @@
1919 return gcomp;
1920 }
1921
1922 +/**
1923 + * g_completion_add_items:
1924 + * @cmp: the #GCompletion.
1925 + * @items: the list of items to add.
1926 + *
1927 + * Adds items to the #GCompletion.
1928 + */
1929 void
1930 g_completion_add_items (GCompletion* cmp,
1931 GList* items)
1932 @@ -82,6 +124,13 @@
1933 }
1934 }
1935
1936 +/**
1937 + * g_completion_remove_items:
1938 + * @cmp: the #GCompletion.
1939 + * @items: the items to remove.
1940 + *
1941 + * Removes items from a #GCompletion.
1942 + */
1943 void
1944 g_completion_remove_items (GCompletion* cmp,
1945 GList* items)
1946 @@ -105,6 +154,12 @@
1947 }
1948 }
1949
1950 +/**
1951 + * g_completion_clear_items:
1952 + * @cmp: the #GCompletion.
1953 + *
1954 + * Removes all items from the #GCompletion.
1955 + */
1956 void
1957 g_completion_clear_items (GCompletion* cmp)
1958 {
1959 @@ -213,6 +268,20 @@
1960 return list;
1961 }
1962
1963 +/**
1964 + * g_completion_complete:
1965 + * @cmp: the #GCompletion.
1966 + * @prefix: the prefix string, typically typed by the user, which is compared
1967 + * with each of the items.
1968 + * @new_prefix: if non-%NULL, returns the longest prefix which is common to all
1969 + * items that matched @prefix, or %NULL if no items matched @prefix.
1970 + * This string should be freed when no longer needed.
1971 + *
1972 + * Attempts to complete the string @prefix using the #GCompletion target items.
1973 + *
1974 + * Returns: the list of items whose strings begin with @prefix. This should
1975 + * not be changed.
1976 + */
1977 GList*
1978 g_completion_complete (GCompletion* cmp,
1979 const gchar* prefix,
1980 @@ -275,6 +344,12 @@
1981 return *prefix ? cmp->cache : cmp->items;
1982 }
1983
1984 +/**
1985 + * g_completion_free:
1986 + * @cmp: the #GCompletion.
1987 + *
1988 + * Frees all memory used by the #GCompletion.
1989 + */
1990 void
1991 g_completion_free (GCompletion* cmp)
1992 {
1993 @@ -284,6 +359,14 @@
1994 g_free (cmp);
1995 }
1996
1997 +/**
1998 + * g_completion_set_compare:
1999 + * @cmp: a #GCompletion.
2000 + * @strncmp_func: the string comparison function.
2001 + *
2002 + * Sets the function to use for string comparisons. The default
2003 + * string comparison function is strncmp().
2004 + */
2005 void
2006 g_completion_set_compare(GCompletion *cmp,
2007 GCompletionStrncmpFunc strncmp_func)
2008 Index: glib/gdate.c
2009 ===================================================================
2010 --- glib/gdate.c (revision 7087)
2011 +++ glib/gdate.c (working copy)
2012 @@ -48,6 +48,68 @@
2013
2014 #include "galias.h"
2015
2016 +/**
2017 + * SECTION:date
2018 + * @Short_description: calendrical calculations and miscellaneous time stuff
2019 + * @Title: Date and Time Functions
2020 + *
2021 + * The #GDate data structure represents a day between January 1, Year 1,
2022 + * and sometime a few thousand years in the future (right now it will go
2023 + * to the year 65535 or so, but g_date_set_parse() only parses up to the
2024 + * year 8000 or so - just count on "a few thousand"). #GDate is meant to
2025 + * represent everyday dates, not astronomical dates or historical dates
2026 + * or ISO timestamps or the like. It extrapolates the current Gregorian
2027 + * calendar forward and backward in time; there is no attempt to change
2028 + * the calendar to match time periods or locations. #GDate does not store
2029 + * time information; it represents a <emphasis>day</emphasis>.
2030 + *
2031 + *
2032 + * The #GDate implementation has several nice features; it is only a
2033 + * 64-bit struct, so storing large numbers of dates is very efficient. It
2034 + * can keep both a Julian and day-month-year representation of the date,
2035 + * since some calculations are much easier with one representation or the
2036 + * other. A Julian representation is simply a count of days since some
2037 + * fixed day in the past; for #GDate the fixed day is January 1, 1 AD.
2038 + * ("Julian" dates in the #GDate API aren't really Julian dates in the
2039 + * technical sense; technically, Julian dates count from the start of the
2040 + * Julian period, Jan 1, 4713 BC).
2041 + *
2042 + *
2043 + * #GDate is simple to use. First you need a "blank" date; you can get a
2044 + * dynamically allocated date from g_date_new(), or you can declare an
2045 + * automatic variable or array and initialize it to a sane state by
2046 + * calling g_date_clear(). A cleared date is sane; it's safe to call
2047 + * g_date_set_dmy() and the other mutator functions to initialize the
2048 + * value of a cleared date. However, a cleared date is initially
2049 + * <emphasis>invalid</emphasis>, meaning that it doesn't represent a day
2050 + * that exists. It is undefined to call any of the date calculation
2051 + * routines on an invalid date. If you obtain a date from a user or other
2052 + * unpredictable source, you should check its validity with the
2053 + * g_date_valid() predicate. g_date_valid() is also used to check for
2054 + * errors with g_date_set_parse() and other functions that can
2055 + * fail. Dates can be invalidated by calling g_date_clear() again.
2056 + *
2057 + *
2058 + * <emphasis>It is very important to use the API to access the #GDate
2059 + * struct.</emphasis> Often only the day-month-year or only the Julian
2060 + * representation is valid. Sometimes neither is valid. Use the API.
2061 + *
2062 + *
2063 + * GLib doesn't contain any time-manipulation functions; however, there
2064 + * is a #GTime typedef and a #GTimeVal struct which represents a more
2065 + * precise time (with microseconds). You can request the current time as
2066 + * a #GTimeVal with g_get_current_time().
2067 + */
2068 +
2069 +/**
2070 + * g_date_new:
2071 + *
2072 + * Allocates a #GDate and initializes it to a sane state. The new date will
2073 + * be cleared (as if you'd called g_date_clear()) but invalid (it won't
2074 + * represent an existing day). Free the return value with g_date_free().
2075 + *
2076 + * Returns: a newly-allocated #GDate
2077 + */
2078 GDate*
2079 g_date_new (void)
2080 {
2081 @@ -56,6 +118,18 @@
2082 return d;
2083 }
2084
2085 +/**
2086 + * g_date_new_dmy:
2087 + * @day: day of the month
2088 + * @month: month of the year
2089 + * @year: year
2090 + *
2091 + * Like g_date_new(), but also sets the value of the date. Assuming the
2092 + * day-month-year triplet you pass in represents an existing day, the
2093 + * returned date will be valid.
2094 + *
2095 + * Returns: a newly-allocated #GDate initialized with @day, @month, and @year
2096 + */
2097 GDate*
2098 g_date_new_dmy (GDateDay day,
2099 GDateMonth m,
2100 @@ -78,6 +152,16 @@
2101 return d;
2102 }
2103
2104 +/**
2105 + * g_date_new_julian:
2106 + * @julian_day: days since January 1, Year 1
2107 + *
2108 + * Like g_date_new(), but also sets the value of the date. Assuming the
2109 + * Julian day number you pass in is valid (greater than 0, less than an
2110 + * unreasonably large number), the returned date will be valid.
2111 + *
2112 + * Returns: a newly-allocated #GDate initialized with @julian_day
2113 + */
2114 GDate*
2115 g_date_new_julian (guint32 j)
2116 {
2117 @@ -96,6 +180,13 @@
2118 return d;
2119 }
2120
2121 +
2122 +/**
2123 + * g_date_free:
2124 + * @date: a #GDate
2125 + *
2126 + * Frees a #GDate returned from g_date_new().
2127 + */
2128 void
2129 g_date_free (GDate *d)
2130 {
2131 @@ -104,6 +195,16 @@
2132 g_free (d);
2133 }
2134
2135 +/**
2136 + * g_date_valid:
2137 + * @date: a #GDate to check
2138 + *
2139 + * Returns %TRUE if the #GDate represents an existing day. The date must not
2140 + * contain garbage; it should have been initialized with g_date_clear()
2141 + * if it wasn't allocated by one of the g_date_new() variants.
2142 + *
2143 + * Returns: Whether the date is valid
2144 + */
2145 gboolean
2146 g_date_valid (const GDate *d)
2147 {
2148 @@ -124,36 +225,94 @@
2149 { 0, 0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335, 366 }
2150 };
2151
2152 +/**
2153 + * g_date_valid_month:
2154 + * @month: month
2155 + *
2156 + * Returns %TRUE if the month value is valid. The 12 #GDateMonth
2157 + * enumeration values are the only valid months.
2158 + *
2159 + * Returns: %TRUE if the month is valid
2160 + */
2161 gboolean
2162 g_date_valid_month (GDateMonth m)
2163 {
2164 return ( (m > G_DATE_BAD_MONTH) && (m < 13) );
2165 }
2166
2167 +/**
2168 + * g_date_valid_year:
2169 + * @year: year
2170 + *
2171 + * Returns %TRUE if the year is valid. Any year greater than 0 is valid,
2172 + * though there is a 16-bit limit to what #GDate will understand.
2173 + *
2174 + * Returns: %TRUE if the year is valid
2175 + */
2176 gboolean
2177 g_date_valid_year (GDateYear y)
2178 {
2179 return ( y > G_DATE_BAD_YEAR );
2180 }
2181
2182 +/**
2183 + * g_date_valid_day:
2184 + * @day: day to check
2185 + *
2186 + * Returns %TRUE if the day of the month is valid (a day is valid if it's
2187 + * between 1 and 31 inclusive).
2188 + *
2189 + * Returns: %TRUE if the day is valid
2190 + */
2191 gboolean
2192 g_date_valid_day (GDateDay d)
2193 {
2194 return ( (d > G_DATE_BAD_DAY) && (d < 32) );
2195 }
2196
2197 +/**
2198 + * g_date_valid_weekday:
2199 + * @weekday: weekday
2200 + *
2201 + * Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration
2202 + * values are the only valid weekdays.
2203 + *
2204 + * Returns: %TRUE if the weekday is valid
2205 + */
2206 gboolean
2207 g_date_valid_weekday (GDateWeekday w)
2208 {
2209 return ( (w > G_DATE_BAD_WEEKDAY) && (w < 8) );
2210 }
2211
2212 +/**
2213 + * g_date_valid_julian:
2214 + * @julian_date: Julian day to check
2215 + *
2216 + * Returns %TRUE if the Julian day is valid. Anything greater than zero
2217 + * is basically a valid Julian, though there is a 32-bit limit.
2218 + *
2219 + * Returns: %TRUE if the Julian day is valid
2220 + */
2221 gboolean
2222 g_date_valid_julian (guint32 j)
2223 {
2224 return (j > G_DATE_BAD_JULIAN);
2225 }
2226
2227 +
2228 +/**
2229 + * g_date_valid_dmy:
2230 + * @day: day
2231 + * @month: month
2232 + * @year: year
2233 + *
2234 + * Returns %TRUE if the day-month-year triplet forms a valid, existing day
2235 + * in the range of days #GDate understands (Year 1 or later, no more than
2236 + * a few thousand years in the future).
2237 + *
2238 + * Returns: %TRUE if the date is a valid one
2239 + */
2240 gboolean
2241 g_date_valid_dmy (GDateDay d,
2242 GDateMonth m,
2243 @@ -253,6 +412,14 @@
2244 d->dmy = TRUE;
2245 }
2246
2247 +/**
2248 + * g_date_get_weekday:
2249 + * @date: a #GDate.
2250 + *
2251 + * Returns the day of the week for a #GDate. The date must be valid.
2252 + *
2253 + * Returns: day of the week as a #GDateWeekday.
2254 + */
2255 GDateWeekday
2256 g_date_get_weekday (const GDate *d)
2257 {
2258 @@ -266,6 +433,14 @@
2259 return ((d->julian_days - 1) % 7) + 1;
2260 }
2261
2262 +/**
2263 + * g_date_get_month:
2264 + * @date: a #GDate to get the month from
2265 + *
2266 + * Returns the month of the year. The date must be valid.
2267 + *
2268 + * Returns: month of the year as a #GDateMonth
2269 + */
2270 GDateMonth
2271 g_date_get_month (const GDate *d)
2272 {
2273 @@ -279,6 +454,14 @@
2274 return d->month;
2275 }
2276
2277 +/**
2278 + * g_date_get_year:
2279 + * @date: a #GDate
2280 + *
2281 + * Returns the year of a #GDate. The date must be valid.
2282 + *
2283 + * Returns: year in which the date falls
2284 + */
2285 GDateYear
2286 g_date_get_year (const GDate *d)
2287 {
2288 @@ -292,6 +475,14 @@
2289 return d->year;
2290 }
2291
2292 +/**
2293 + * g_date_get_day:
2294 + * @date: a #GDate to extract the day of the month from
2295 + *
2296 + * Returns the day of the month. The date must be valid.
2297 + *
2298 + * Returns: day of the month
2299 + */
2300 GDateDay
2301 g_date_get_day (const GDate *d)
2302 {
2303 @@ -305,6 +496,18 @@
2304 return d->day;
2305 }
2306
2307 +
2308 +/**
2309 + * g_date_get_julian:
2310 + * @date: a #GDate to extract the Julian day from
2311 + *
2312 + * Returns the Julian day or "serial number" of the #GDate. The
2313 + * Julian day is simply the number of days since January 1, Year 1; i.e.,
2314 + * January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,
2315 + * etc. The date must be valid.
2316 + *
2317 + * Returns: Julian day
2318 + */
2319 guint32
2320 g_date_get_julian (const GDate *d)
2321 {
2322 @@ -318,6 +521,15 @@
2323 return d->julian_days;
2324 }
2325
2326 +/**
2327 + * g_date_get_day_of_year:
2328 + * @date: a #GDate to extract day of year from
2329 + *
2330 + * Returns the day of the year, where Jan 1 is the first day of the
2331 + * year. The date must be valid.
2332 + *
2333 + * Returns: day of the year
2334 + */
2335 guint
2336 g_date_get_day_of_year (const GDate *d)
2337 {
2338 @@ -335,6 +547,16 @@
2339 return (days_in_year[index][d->month] + d->day);
2340 }
2341
2342 +/**
2343 + * g_date_get_monday_week_of_year:
2344 + * @date: a #GDate
2345 + *
2346 + * Returns the week of the year, where weeks are understood to start on
2347 + * Monday. If the date is before the first Monday of the year, return
2348 + * 0. The date must be valid.
2349 + *
2350 + * Returns: week of the year
2351 + */
2352 guint
2353 g_date_get_monday_week_of_year (const GDate *d)
2354 {
2355 @@ -359,6 +581,16 @@
2356 return ((day + wd)/7U + (wd == 0 ? 1 : 0));
2357 }
2358
2359 +/**
2360 + * g_date_get_sunday_week_of_year:
2361 + * @date: a #GDate
2362 + *
2363 + * Returns the week of the year during which this date falls, if weeks
2364 + * are understood to being on Sunday. The date must be valid. Can return 0 if
2365 + * the day is before the first Sunday of the year.
2366 + *
2367 + * Returns: week number
2368 + */
2369 guint
2370 g_date_get_sunday_week_of_year (const GDate *d)
2371 {
2372 @@ -420,6 +652,17 @@
2373 return w;
2374 }
2375
2376 +/**
2377 + * g_date_days_between:
2378 + * @date1: the first date
2379 + * @date2: the second date
2380 + *
2381 + * Computes the number of days between two dates.
2382 + * If @date2 is prior to @date1, the returned value is negative.
2383 + * Both dates must be valid.
2384 + *
2385 + * Returns: the number of days between @date1 and @date2
2386 + */
2387 gint
2388 g_date_days_between (const GDate *d1,
2389 const GDate *d2)
2390 @@ -430,6 +673,16 @@
2391 return (gint)g_date_get_julian (d2) - (gint)g_date_get_julian (d1);
2392 }
2393
2394 +/**
2395 + * g_date_clear:
2396 + * @date: pointer to one or more dates to clear
2397 + * @n_dates: number of dates to clear
2398 + *
2399 + * Initializes one or more #GDate structs to a sane but invalid
2400 + * state. The cleared dates will not represent an existing date, but will
2401 + * not contain garbage. Useful to init a date declared on the stack.
2402 + * Validity can be tested with g_date_valid().
2403 + */
2404 void
2405 g_date_clear (GDate *d, guint ndates)
2406 {
2407 @@ -704,6 +957,24 @@
2408 g_date_fill_parse_tokens (str, pt);
2409 }
2410
2411 +/**
2412 + * g_date_set_parse:
2413 + * @date: a #GDate to fill in
2414 + * @str: string to parse
2415 + *
2416 + * Parses a user-inputted string @str, and try to figure out what date it
2417 + * represents, taking the <link linkend="setlocale">current locale</link>
2418 + * into account. If the string is successfully parsed, the date will be
2419 + * valid after the call. Otherwise, it will be invalid. You should check
2420 + * using g_date_valid() to see whether the parsing succeeded.
2421 + *
2422 + *
2423 + * This function is not appropriate for file formats and the like; it
2424 + * isn't very precise, and its exact behavior varies with the
2425 + * locale. It's intended to be a heuristic routine that guesses what the
2426 + * user means by a given string (and it does work pretty well in that
2427 + * capacity).
2428 + */
2429 void
2430 g_date_set_parse (GDate *d,
2431 const gchar *str)
2432 @@ -948,6 +1219,14 @@
2433 g_date_set_time_t (date, (time_t) timeval->tv_sec);
2434 }
2435
2436 +/**
2437 + * g_date_set_month:
2438 + * @date: a #GDate
2439 + * @month: month to set
2440 + *
2441 + * Sets the month of the year for a #GDate. If the resulting
2442 + * day-month-year triplet is invalid, the date will be invalid.
2443 + */
2444 void
2445 g_date_set_month (GDate *d,
2446 GDateMonth m)
2447 @@ -966,6 +1245,14 @@
2448 d->dmy = FALSE;
2449 }
2450
2451 +/**
2452 + * g_date_set_day:
2453 + * @date: a #GDate
2454 + * @day: day to set
2455 + *
2456 + * Sets the day of the month for a #GDate. If the resulting day-month-year
2457 + * triplet is invalid, the date will be invalid.
2458 + */
2459 void
2460 g_date_set_day (GDate *d,
2461 GDateDay day)
2462 @@ -984,6 +1271,14 @@
2463 d->dmy = FALSE;
2464 }
2465
2466 +/**
2467 + * g_date_set_year:
2468 + * @date: a #GDate
2469 + * @year: year to set
2470 + *
2471 + * Sets the year for a #GDate. If the resulting day-month-year triplet is
2472 + * invalid, the date will be invalid.
2473 + */
2474 void
2475 g_date_set_year (GDate *d,
2476 GDateYear y)
2477 @@ -1002,6 +1297,17 @@
2478 d->dmy = FALSE;
2479 }
2480
2481 +/**
2482 + * g_date_set_dmy:
2483 + * @date: a #GDate
2484 + * @day: day
2485 + * @month: month
2486 + * @y: year
2487 + *
2488 + * Sets the value of a #GDate from a day, month, and year. The day-month-year
2489 + * triplet must be valid; if you aren't sure it is, call g_date_valid_dmy() to
2490 + * check before you set it.
2491 + */
2492 void
2493 g_date_set_dmy (GDate *d,
2494 GDateDay day,
2495 @@ -1020,6 +1326,13 @@
2496 d->dmy = TRUE;
2497 }
2498
2499 +/**
2500 + * g_date_set_julian:
2501 + * @date: a #GDate
2502 + * @julian_date: Julian day number (days since January 1, Year 1)
2503 + *
2504 + * Sets the value of a #GDate from a Julian day number.
2505 + */
2506 void
2507 g_date_set_julian (GDate *d,
2508 guint32 j)
2509 @@ -1032,7 +1345,14 @@
2510 d->dmy = FALSE;
2511 }
2512
2513 -
2514 +/**
2515 + * g_date_is_first_of_month:
2516 + * @date: a #GDate to check
2517 + *
2518 + * Returns %TRUE if the date is on the first of a month. The date must be valid.
2519 + *
2520 + * Returns: %TRUE if the date is the first of the month
2521 + */
2522 gboolean
2523 g_date_is_first_of_month (const GDate *d)
2524 {
2525 @@ -1047,6 +1367,15 @@
2526 else return FALSE;
2527 }
2528
2529 +/**
2530 + * g_date_is_last_of_month:
2531 + * @date: a #GDate to check
2532 + *
2533 + * Returns %TRUE if the date is the last day of the month.
2534 + * The date must be valid.
2535 + *
2536 + * Returns: %TRUE if the date is the last day of the month
2537 + */
2538 gboolean
2539 g_date_is_last_of_month (const GDate *d)
2540 {
2541 @@ -1065,6 +1394,14 @@
2542 else return FALSE;
2543 }
2544
2545 +/**
2546 + * g_date_add_days:
2547 + * @date: a #GDate to increment
2548 + * @n_days: number of days to move the date forward
2549 + *
2550 + * Increments a date some number of days. To move forward by weeks, add
2551 + * weeks*7 days. The date must be valid.
2552 + */
2553 void
2554 g_date_add_days (GDate *d,
2555 guint ndays)
2556 @@ -1080,6 +1417,14 @@
2557 d->dmy = FALSE;
2558 }
2559
2560 +/**
2561 + * g_date_subtract_days:
2562 + * @date: a #GDate to decrement
2563 + * @n_days: number of days to move
2564 + *
2565 + * Moves a date some number of days into the past. To move by weeks, just
2566 + * move by weeks*7 days. The date must be valid.
2567 + */
2568 void
2569 g_date_subtract_days (GDate *d,
2570 guint ndays)
2571 @@ -1096,6 +1441,16 @@
2572 d->dmy = FALSE;
2573 }
2574
2575 +/**
2576 + * g_date_add_months:
2577 + * @date: a #GDate to increment
2578 + * @n_months: number of months to move forward
2579 + *
2580 + * Increments a date by some number of months. If the day of the month is
2581 + * greater than 28, this routine may change the day of the month (because
2582 + * the destination month may not have the current day in it). The date
2583 + * must be valid.
2584 + */
2585 void
2586 g_date_add_months (GDate *d,
2587 guint nmonths)
2588 @@ -1128,6 +1483,15 @@
2589 g_return_if_fail (g_date_valid (d));
2590 }
2591
2592 +/**
2593 + * g_date_subtract_months:
2594 + * @date: a #GDate to decrement
2595 + * @n_months: number of months to move
2596 + *
2597 + * Moves a date some number of months into the past. If the current day of
2598 + * the month doesn't exist in the destination month, the day of the month
2599 + * may change. The date must be valid.
2600 + */
2601 void
2602 g_date_subtract_months (GDate *d,
2603 guint nmonths)
2604 @@ -1167,6 +1531,15 @@
2605 g_return_if_fail (g_date_valid (d));
2606 }
2607
2608 +/**
2609 + * g_date_add_years:
2610 + * @date: a #GDate to increment
2611 + * @n_years: number of years to move forward
2612 + *
2613 + * Increments a date by some number of years. If the date is February 29,
2614 + * and the destination year is not a leap year, the date will be changed
2615 + * to February 28. The date must be valid.
2616 + */
2617 void
2618 g_date_add_years (GDate *d,
2619 guint nyears)
2620 @@ -1189,6 +1562,16 @@
2621 d->julian = FALSE;
2622 }
2623
2624 +/**
2625 + * g_date_subtract_years:
2626 + * @date: a #GDate to decrement
2627 + * @n_years: number of years to move
2628 + *
2629 + * Moves a date some number of years into the past. If the current day
2630 + * doesn't exist in the destination year (i.e. it's February 29 and you
2631 + * move to a non-leap-year) then the day is changed to February 29. The date
2632 + * must be valid.
2633 + */
2634 void
2635 g_date_subtract_years (GDate *d,
2636 guint nyears)
2637 @@ -1212,6 +1595,16 @@
2638 d->julian = FALSE;
2639 }
2640
2641 +/**
2642 + * g_date_is_leap_year:
2643 + * @year: year to check
2644 + *
2645 + * For the purposes of this function, leap year is every year divisible by
2646 + * 4 unless that year is divisible by 100. If it is divisible by 100 it would
2647 + * be a leap year only if that year is also divisible by 400.</para></footnote>
2648 + *
2649 + * Returns: %TRUE if the year is a leap year
2650 + */
2651 gboolean
2652 g_date_is_leap_year (GDateYear year)
2653 {
2654 @@ -1221,6 +1614,15 @@
2655 (year % 400) == 0 );
2656 }
2657
2658 +/**
2659 + * g_date_get_days_in_month:
2660 + * @month: month
2661 + * @year: year
2662 + *
2663 + * Returns the number of days in a month, taking leap years into account.
2664 + *
2665 + * Returns: number of days in @month during the @year
2666 + */
2667 guint8
2668 g_date_get_days_in_month (GDateMonth month,
2669 GDateYear year)
2670 @@ -1235,6 +1637,19 @@
2671 return days_in_months[index][month];
2672 }
2673
2674 +/**
2675 + * g_date_get_monday_weeks_in_year:
2676 + * @year: a year
2677 + *
2678 + * Returns the number of weeks in the year, where weeks are taken to start
2679 + * on Monday. Will be 52 or 53. The date must be valid. (Years always have 52
2680 + * 7-day periods, plus 1 or 2 extra days depending on whether it's a leap
2681 + * year. This function is basically telling you how many Mondays are in
2682 + * the year, i.e. there are 53 Mondays if one of the extra days happens
2683 + * to be a Monday.)
2684 + *
2685 + * Returns: number of Mondays in the year
2686 + */
2687 guint8
2688 g_date_get_monday_weeks_in_year (GDateYear year)
2689 {
2690 @@ -1257,6 +1672,19 @@
2691 return 52;
2692 }
2693
2694 +/**
2695 + * g_date_get_sunday_weeks_in_year:
2696 + * @year: year to count weeks in
2697 + *
2698 + * Returns the number of weeks in the year, where weeks are taken to start
2699 + * on Sunday. Will be 52 or 53. The date must be valid. (Years always have 52
2700 + * 7-day periods, plus 1 or 2 extra days depending on whether it's a leap
2701 + * year. This function is basically telling you how many Sundays are in
2702 + * the year, i.e. there are 53 Sundays if one of the extra days happens
2703 + * to be a Sunday.)
2704 + *
2705 + * Returns: number of weeks
2706 + */
2707 guint8
2708 g_date_get_sunday_weeks_in_year (GDateYear year)
2709 {
2710 @@ -1279,6 +1707,17 @@
2711 return 52;
2712 }
2713
2714 +/**
2715 + * g_date_compare:
2716 + * @lhs: first date to compare
2717 + * @rhs: second date to compare
2718 + *
2719 + * qsort()-style comparsion function for dates. Both
2720 + * dates must be valid.
2721 + *
2722 + * Returns: 0 for equal, less than zero if @lhs is less than @rhs,
2723 + * greater than zero if @lhs is greater than @rhs
2724 + */
2725 gint
2726 g_date_compare (const GDate *lhs,
2727 const GDate *rhs)
2728 @@ -1328,7 +1767,15 @@
2729 return 0; /* warnings */
2730 }
2731
2732 -
2733 +/**
2734 + * g_date_to_struct_tm:
2735 + * @date: a #GDate to set the <structname>struct tm</structname> from.
2736 + * @tm: <structname>struct tm</structname> to fill.
2737 + *
2738 + * Fills in the date-related bits of a <structname>struct tm</structname>
2739 + * using the @date value. Initializes the non-date parts with something
2740 + * sane but meaningless.
2741 + */
2742 void
2743 g_date_to_struct_tm (const GDate *d,
2744 struct tm *tm)
2745 @@ -1366,6 +1813,18 @@
2746 tm->tm_isdst = -1; /* -1 means "information not available" */
2747 }
2748
2749 +/**
2750 + * g_date_clamp:
2751 + * @date: a #GDate to clamp
2752 + * @min_date: minimum accepted value for @date
2753 + * @max_date: maximum accepted value for @date
2754 + *
2755 + * If @date is prior to @min_date, sets @date equal to @min_date.
2756 + * If @date falls after @max_date, sets @date equal to @max_date.
2757 + * Otherwise, @date is unchanged.
2758 + * Either of @min_date and @max_date may be %NULL. All non-%NULL dates
2759 + * must be valid.
2760 + */
2761 void
2762 g_date_clamp (GDate *date,
2763 const GDate *min_date,
2764 @@ -1389,6 +1848,14 @@
2765 *date = *max_date;
2766 }
2767
2768 +/**
2769 + * g_date_order:
2770 + * @date1: the first date
2771 + * @date2: the second date
2772 + *
2773 + * Checks if @date1 is less than or equal to @date2,
2774 + * and swap the values if this is not the case.
2775 + */
2776 void
2777 g_date_order (GDate *date1,
2778 GDate *date2)
2779 @@ -1782,6 +2249,28 @@
2780
2781 #endif
2782
2783 +/**
2784 + * g_date_strftime:
2785 + * @s: destination buffer
2786 + * @slen: buffer size
2787 + * @format: format string
2788 + * @date: valid #GDate
2789 + *
2790 + * Generates a printed representation of the date, in a
2791 + * <link linkend="setlocale">locale</link>-specific way. Works just like
2792 + * the platform's C library strftime() function, but only accepts date-related
2793 + * formats; time-related formats give undefined results. Date must be valid.
2794 + * Unlike strftime() (which uses the locale encoding), works on a UTF-8 format
2795 + * string and stores a UTF-8 result.
2796 + *
2797 + *
2798 + * This function does not provide any conversion specifiers in addition
2799 + * to those implemented by the platform's C library. For example, don't
2800 + * expect that using g_date_strftime() would make the %F provided by the C99
2801 + * strftime() work on Windows where the C library only complies to C89.
2802 + *
2803 + * Returns: number of characters written to the buffer, or 0 the buffer was too small
2804 + */
2805 gsize
2806 g_date_strftime (gchar *s,
2807 gsize slen,
2808 Index: glib/gcompletion.h
2809 ===================================================================
2810 --- glib/gcompletion.h (revision 7087)
2811 +++ glib/gcompletion.h (working copy)
2812 @@ -35,13 +35,46 @@
2813
2814 G_BEGIN_DECLS
2815
2816 +/**
2817 + * GCompletion:
2818 + * @items: list of target items (strings or data structures).
2819 + * @func: function which is called to get the string associated with a target
2820 + * item. It is %NULL if the target items are strings.
2821 + * @prefix: the last prefix passed to g_completion_complete() or
2822 + * g_completion_complete_utf8().
2823 + * @cache: the list of items which begin with @prefix.
2824 + * @strncmp_func: The function to use when comparing strings.
2825 + * Use g_completion_set_compare() to modify this function.
2826 + *
2827 + * The data structure used for automatic completion.
2828 + */
2829 typedef struct _GCompletion GCompletion;
2830
2831 +/**
2832 + * GCompletionFunc:
2833 + * @Param1: the completion item.
2834 + *
2835 + * Specifies the type of the function passed to g_completion_new().
2836 + * It should return the string corresponding to the given target item.
2837 + * This is used when you use data structures as #GCompletion items.
2838 + *
2839 + * Returns: the string corresponding to the item.
2840 + */
2841 typedef gchar* (*GCompletionFunc) (gpointer);
2842
2843 -/* GCompletion
2844 +/**
2845 + * GCompletionStrncmpFunc:
2846 + * @s1: string to compare with @s2.
2847 + * @s2: string to compare with @s1.
2848 + * @n: maximal number of bytes to compare.
2849 + *
2850 + * Specifies the type of the function passed to g_completion_set_compare().
2851 + * This is used when you use strings as #GCompletion items.
2852 + *
2853 + * Returns: an integer less than, equal to, or greater than zero if the
2854 + * first @n bytes of @s1 is found, respectively, to be less than, to match,
2855 + * or to be greater than the first @n bytes of @s2.
2856 */
2857 -
2858 typedef gint (*GCompletionStrncmpFunc) (const gchar *s1,
2859 const gchar *s2,
2860 gsize n);
2861 Index: glib/gdate.h
2862 ===================================================================
2863 --- glib/gdate.h (revision 7087)
2864 +++ glib/gdate.h (working copy)
2865 @@ -47,12 +47,80 @@
2866 * Pennington <hp@pobox.com>
2867 */
2868
2869 +/**
2870 + * GTime:
2871 + *
2872 + * Simply a replacement for <type>time_t</type>. It has been deprecated
2873 + * since it is <emphasis>not</emphasis> equivalent to <type>time_t</type>
2874 + * on 64-bit platforms with a 64-bit <type>time_t</type>.
2875 + * Unrelated to #GTimer.
2876 + *
2877 + * Note that <type>GTime</type> is defined to always be a 32bit integer,
2878 + * unlike <type>time_t</type> which may be 64bit on some systems.
2879 + * Therefore, <type>GTime</type> will overflow in the year 2038, and
2880 + * you cannot use the address of a <type>GTime</type> variable as argument
2881 + * to the UNIX time() function. Instead, do the following:
2882 + * <informalexample>
2883 + * <programlisting>
2884 + * time_t ttime;
2885 + * GTime gtime;
2886 + *
2887 + * time (&ttime);
2888 + * gtime = (GTime)ttime;
2889 + * </programlisting>
2890 + * </informalexample>
2891 + */
2892 typedef gint32 GTime;
2893 +
2894 +/**
2895 + * GDateYear:
2896 + *
2897 + * Integer representing a year; #G_DATE_BAD_YEAR is the invalid
2898 + * value. The year must be 1 or higher; negative (BC) years are not
2899 + * allowed. The year is represented with four digits.
2900 + */
2901 typedef guint16 GDateYear;
2902 -typedef guint8 GDateDay; /* day of the month */
2903 +
2904 +/**
2905 + * GDateDay:
2906 + *
2907 + * Integer representing a day of the month; between 1 and
2908 + * 31. #G_DATE_BAD_DAY represents an invalid day of the month.
2909 + */
2910 +typedef guint8 GDateDay;
2911 +
2912 +/**
2913 + * GDate:
2914 + * @julian_days: the Julian representation of the date
2915 + * @julian: this bit is set if @julian_days is valid
2916 + * @dmy: this is set if @day, @month and @year are valid
2917 + * @day: the day of the day-month-year representation of the date, as
2918 + * a number between 1 and 31
2919 + * @month: the day of the day-month-year representation of the date, as
2920 + * a number between 1 and 12
2921 + * @year: the day of the day-month-year representation of the date
2922 + *
2923 + * Represents a day between January 1, Year 1 and a few thousand years in
2924 + * the future. None of its members should be accessed directly. If the
2925 + * <structname>GDate</structname> is obtained from g_date_new(), it will
2926 + * be safe to mutate but invalid and thus not safe for calendrical computations.
2927 + * If it's declared on the stack, it will contain garbage so must be
2928 + * initialized with g_date_clear(). g_date_clear() makes the date invalid
2929 + * but sane. An invalid date doesn't represent a day, it's "empty." A
2930 + * date becomes valid after you set it to a Julian day or you set a day,
2931 + * month, and year.
2932 + */
2933 typedef struct _GDate GDate;
2934
2935 -/* enum used to specify order of appearance in parsed date strings */
2936 +/**
2937 + * GDateDMY:
2938 + * @G_DATE_DAY: a day
2939 + * @G_DATE_MONTH: a month
2940 + * @G_DATE_YEAR: a year
2941 + *
2942 + * This enumeration isn't used in the API, but may be useful if you need
2943 + * to mark a number as a day, month, or year.
2944 + */
2945 typedef enum
2946 {
2947 G_DATE_DAY = 0,
2948 @@ -60,7 +128,20 @@
2949 G_DATE_YEAR = 2
2950 } GDateDMY;
2951
2952 -/* actual week and month values */
2953 +/**
2954 + * GDateWeekday:
2955 + * @G_DATE_BAD_WEEKDAY: invalid value
2956 + * @G_DATE_MONDAY: Monday
2957 + * @G_DATE_TUESDAY: Tuesday
2958 + * @G_DATE_WEDNESDAY: Wednesday
2959 + * @G_DATE_THURSDAY: Thursday
2960 + * @G_DATE_FRIDAY: Friday
2961 + * @G_DATE_SATURDAY: Saturday
2962 + * @G_DATE_SUNDAY: Sunday
2963 + *
2964 + * Enumeration representing a day of the week; #G_DATE_MONDAY,
2965 + * #G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday.
2966 + */
2967 typedef enum
2968 {
2969 G_DATE_BAD_WEEKDAY = 0,
2970 @@ -72,6 +153,26 @@
2971 G_DATE_SATURDAY = 6,
2972 G_DATE_SUNDAY = 7
2973 } GDateWeekday;
2974 +
2975 +/**
2976 + * GDateMonth:
2977 + * @G_DATE_BAD_MONTH: invalid value
2978 + * @G_DATE_JANUARY: January
2979 + * @G_DATE_FEBRUARY: February
2980 + * @G_DATE_MARCH: March
2981 + * @G_DATE_APRIL: April
2982 + * @G_DATE_MAY: May
2983 + * @G_DATE_JUNE: June
2984 + * @G_DATE_JULY: July
2985 + * @G_DATE_AUGUST: August
2986 + * @G_DATE_SEPTEMBER: September
2987 + * @G_DATE_OCTOBER: October
2988 + * @G_DATE_NOVEMBER: November
2989 + * @G_DATE_DECEMBER: December
2990 + *
2991 + * Enumeration representing a month; values are #G_DATE_JANUARY,
2992 + * #G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value.
2993 + */
2994 typedef enum
2995 {
2996 G_DATE_BAD_MONTH = 0,
2997 @@ -89,8 +190,25 @@
2998 G_DATE_DECEMBER = 12
2999 } GDateMonth;
3000
3001 +/**
3002 + * G_DATE_BAD_JULIAN:
3003 + *
3004 + * Represents an invalid Julian day number.
3005 + */
3006 #define G_DATE_BAD_JULIAN 0U
3007 +
3008 +/**
3009 + * G_DATE_BAD_DAY:
3010 + *
3011 + * Represents an invalid #GDateDay.
3012 + */
3013 #define G_DATE_BAD_DAY 0U
3014 +
3015 +/**
3016 + * G_DATE_BAD_YEAR:
3017 + *
3018 + * Represents an invalid year.
3019 + */
3020 #define G_DATE_BAD_YEAR 0U
3021
3022 /* Note: directly manipulating structs is generally a bad idea, but
3023 Index: glib/gdataset.c
3024 ===================================================================
3025 --- glib/gdataset.c (revision 7087)
3026 +++ glib/gdataset.c (working copy)
3027 @@ -38,7 +38,75 @@
3028 #include "gdatasetprivate.h"
3029 #include "galias.h"
3030
3031 +/**
3032 + * SECTION:datasets
3033 + * @Short_description: associate groups of data elements with particular memory locations
3034 + * @Title: Datasets
3035 + *
3036 + * Datasets associate groups of data elements with particular memory locations.
3037 + * These are useful if you need to associate data with a structure returned
3038 + * from an external library. Since you cannot modify the structure, you use
3039 + * its location in memory as the key into a dataset, where you can associate
3040 + * any number of data elements with it.
3041 + *
3042 + * There are two forms of most of the dataset functions.
3043 + * The first form uses strings to identify the data elements associated with
3044 + * a location. The second form uses #GQuark identifiers, which are created
3045 + * with a call to g_quark_from_string() or g_quark_from_static_string().
3046 + * The second form is quicker, since it does not require looking up the string
3047 + * in the hash table of #GQuark identifiers.
3048 + *
3049 + * There is no function to create a dataset. It is automatically created as
3050 + * soon as you add elements to it.
3051 + *
3052 + * To add data elements to a dataset use g_dataset_id_set_data(),
3053 + * g_dataset_id_set_data_full(), g_dataset_set_data()
3054 + * and g_dataset_set_data_full().
3055 + *
3056 + * To get data elements from a dataset use g_dataset_id_get_data() and
3057 + * g_dataset_get_data().
3058 + *
3059 + * To iterate over all data elements in a dataset use g_dataset_foreach() (not thread-safe).
3060 + *
3061 + * To remove data elements from a dataset use g_dataset_id_remove_data() and
3062 + * g_dataset_remove_data().
3063 + *
3064 + * To destroy a dataset, use g_dataset_destroy().
3065 + */
3066
3067 +/**
3068 + * SECTION:datalist
3069 + * @Short_description: lists of data elements which are accessible by a string or GQuark identifier
3070 + * @Title: Keyed Data Lists
3071 + *
3072 + * Keyed data lists provide lists of arbitrary data elements which can be accessed
3073 + * either with a string or with a #GQuark corresponding to the
3074 + * string.
3075 + *
3076 + * The #GQuark methods are quicker, since the strings have to be converted to
3077 + * #GQuarks anyway.
3078 + *
3079 + * Data lists are used for associating arbitrary data with
3080 + * #GObjects, using g_object_set_data() and related functions.
3081 + *
3082 + *
3083 + * To create a datalist, use g_datalist_init().
3084 + *
3085 + * To add data elements to a datalist use g_datalist_id_set_data(),
3086 + * g_datalist_id_set_data_full(), g_datalist_set_data()
3087 + * and g_datalist_set_data_full().
3088 + *
3089 + * To get data elements from a datalist use g_datalist_id_get_data() and
3090 + * g_datalist_get_data().
3091 + *
3092 + * To iterate over all data elements in a datalist use g_datalist_foreach() (not thread-safe).
3093 + *
3094 + * To remove data elements from a datalist use g_datalist_id_remove_data() and
3095 + * g_datalist_remove_data().
3096 + *
3097 + * To remove all data elements from a datalist, use g_datalist_clear().
3098 + */
3099 +
3100 /* --- defines --- */
3101 #define G_QUARK_BLOCK_SIZE (512)
3102
3103 @@ -125,6 +193,13 @@
3104 }
3105 }
3106
3107 +/**
3108 + * g_datalist_clear:
3109 + * @datalist: a datalist.
3110 + *
3111 + * Frees all the data elements of the datalist.
3112 + * The data elements' destroy functions are called if they have been set.
3113 + */
3114 void
3115 g_datalist_clear (GData **datalist)
3116 {
3117 @@ -178,6 +253,14 @@
3118 }
3119 }
3120
3121 +
3122 +/**
3123 + * g_dataset_destroy:
3124 + * @dataset_location: the location identifying the dataset.
3125 + *
3126 + * Destroys the dataset, freeing all memory allocated, and calling any
3127 + * destroy functions set for data elements.
3128 + */
3129 void
3130 g_dataset_destroy (gconstpointer dataset_location)
3131 {
3132 @@ -300,6 +383,20 @@
3133 return NULL;
3134 }
3135
3136 +/**
3137 + * g_dataset_id_set_data_full:
3138 + * @dataset_location: the location identifying the dataset.
3139 + * @key_id: the #GQuark id to identify the data element.
3140 + * @data: the data element.
3141 + * @destroy_func: the function to call when the data element is removed. This
3142 + * function will be called with the data element and can be used to free any
3143 + * memory allocated for it.
3144 + *
3145 + * Sets the data element associated with the given #GQuark id, and also the
3146 + * function to call when the data element is destroyed.
3147 + * Any previous data with the same key is removed, and its
3148 + * destroy function is called.
3149 + */
3150 void
3151 g_dataset_id_set_data_full (gconstpointer dataset_location,
3152 GQuark key_id,
3153 @@ -338,6 +435,22 @@
3154 G_UNLOCK (g_dataset_global);
3155 }
3156
3157 +/**
3158 + * g_datalist_id_set_data_full:
3159 + * @datalist: a datalist.
3160 + * @key_id: the #GQuark to identify the data element.
3161 + * @data: the data element or %NULL to remove any previous element
3162 + * corresponding to @key_id.
3163 + * @destroy_func: the function to call when the data element is removed. This
3164 + * function will be called with the data element and can be used to free any
3165 + * memory allocated for it. If @data is %NULL, then @destroy_func must
3166 + * also be %NULL.
3167 + *
3168 + * Sets the data corresponding to the given #GQuark id, and the function to
3169 + * be called when the element is removed from the datalist.
3170 + * Any previous data with the same key is removed, and its
3171 + * destroy function is called.
3172 + */
3173 void
3174 g_datalist_id_set_data_full (GData **datalist,
3175 GQuark key_id,
3176 @@ -363,6 +476,16 @@
3177 G_UNLOCK (g_dataset_global);
3178 }
3179
3180 +
3181 +/**
3182 + * g_dataset_id_remove_no_notify:
3183 + * @dataset_location: the location identifying the dataset.
3184 + * @key_id: the #GQuark ID identifying the data element.
3185 + *
3186 + * Removes an element, without calling its destroy notification function.
3187 + *
3188 + * Returns: the data previously stored at @key_id, or %NULL if none.
3189 + */
3190 gpointer
3191 g_dataset_id_remove_no_notify (gconstpointer dataset_location,
3192 GQuark key_id)
3193 @@ -385,6 +508,15 @@
3194 return ret_data;
3195 }
3196
3197 +/**
3198 + * g_datalist_id_remove_no_notify:
3199 + * @datalist: a datalist.
3200 + * @key_id: the #GQuark identifying a data element.
3201 + *
3202 + * Removes an element, without calling its destroy notification function.
3203 + *
3204 + * Returns: the data previously stored at @key_id, or %NULL if none.
3205 + */
3206 gpointer
3207 g_datalist_id_remove_no_notify (GData **datalist,
3208 GQuark key_id)
3209 @@ -401,6 +533,16 @@
3210 return ret_data;
3211 }
3212
3213 +/**
3214 + * g_dataset_id_get_data:
3215 + * @dataset_location: the location identifying the dataset.
3216 + * @key_id: the #GQuark id to identify the data element.
3217 + *
3218 + * Gets the data element corresponding to a #GQuark.
3219 + *
3220 + * Returns: the data element corresponding to the #GQuark,
3221 + * or %NULL if it is not found.
3222 + */
3223 gpointer
3224 g_dataset_id_get_data (gconstpointer dataset_location,
3225 GQuark key_id)
3226 @@ -430,6 +572,15 @@
3227 return NULL;
3228 }
3229
3230 +/**
3231 + * g_datalist_id_get_data:
3232 + * @datalist: a datalist.
3233 + * @key_id: the #GQuark identifying a data element.
3234 + *
3235 + * Retrieves the data element corresponding to @key_id.
3236 + *
3237 + * Returns: the data element, or %NULL if it is not found.
3238 + */
3239 gpointer
3240 g_datalist_id_get_data (GData **datalist,
3241 GQuark key_id)
3242 @@ -451,6 +602,18 @@
3243 return data;
3244 }
3245
3246 +/**
3247 + * g_dataset_foreach:
3248 + * @dataset_location: the location identifying the dataset.
3249 + * @func: the function to call for each data element.
3250 + * @user_data: user data to pass to the function.
3251 + *
3252 + * Calls the given function for each data element which is associated with the
3253 + * given location.
3254 + * Note that this function is NOT thread-safe. So unless @datalist
3255 + * can be protected from any modifications during invocation of this
3256 + * function, it should not be called.
3257 + */
3258 void
3259 g_dataset_foreach (gconstpointer dataset_location,
3260 GDataForeachFunc func,
3261 @@ -483,6 +646,19 @@
3262 }
3263 }
3264
3265 +/**
3266 + * g_datalist_foreach:
3267 + * @datalist: a datalist.
3268 + * @func: the function to call for each data element.
3269 + * @user_data: user data to pass to the function.
3270 + *
3271 + * Calls the given function for each data element of the datalist.
3272 + * The function is called with each data element's #GQuark id and data,
3273 + * together with the given @user_data parameter.
3274 + * Note that this function is NOT thread-safe. So unless @datalist
3275 + * can be protected from any modifications during invocation of this
3276 + * function, it should not be called.
3277 + */
3278 void
3279 g_datalist_foreach (GData **datalist,
3280 GDataForeachFunc func,
3281 @@ -500,6 +676,13 @@
3282 }
3283 }
3284
3285 +/**
3286 + * g_datalist_init:
3287 + * @datalist: a pointer to a pointer to a datalist.
3288 + *
3289 + * Resets the datalist to %NULL.
3290 + * It does not free any memory or call any destroy functions.
3291 + */
3292 void
3293 g_datalist_init (GData **datalist)
3294 {
3295 Index: glib/gdataset.h
3296 ===================================================================
3297 --- glib/gdataset.h (revision 7087)
3298 +++ glib/gdataset.h (working copy)
3299 @@ -35,8 +35,25 @@
3300
3301 G_BEGIN_DECLS
3302
3303 +/**
3304 + * GData:
3305 + *
3306 + * The #GData struct is an opaque data structure to represent a
3307 + * <link linkend="glib-Keyed-Data-Lists">Keyed Data List</link>.
3308 + * It should only be accessed via the following functions.
3309 + */
3310 typedef struct _GData GData;
3311
3312 +/**
3313 + * GDataForeachFunc:
3314 + * @key_id: the #GQuark id to identifying the data element.
3315 + * @data: the data element.
3316 + * @user_data: user data passed to g_dataset_foreach().
3317 + *
3318 + * Specifies the type of function passed to g_dataset_foreach().
3319 + * It is called with each #GQuark id and associated data element,
3320 + * together with the @user_data parameter supplied to g_dataset_foreach().
3321 + */
3322 typedef void (*GDataForeachFunc) (GQuark key_id,
3323 gpointer data,
3324 gpointer user_data);
3325 @@ -72,18 +89,90 @@
3326 guint flags);
3327 guint g_datalist_get_flags (GData **datalist);
3328
3329 +/**
3330 + * g_datalist_id_set_data:
3331 + * @dl: a datalist.
3332 + * @q: the #GQuark to identify the data element.
3333 + * @d: the data element, or %NULL to remove any previous element
3334 + * corresponding to @q.
3335 + *
3336 + * Sets the data corresponding to the given #GQuark id.
3337 + * Any previous data with the same key is removed, and its
3338 + * destroy function is called.
3339 + */
3340 #define g_datalist_id_set_data(dl, q, d) \
3341 g_datalist_id_set_data_full ((dl), (q), (d), NULL)
3342 +
3343 +/**
3344 + * g_datalist_id_remove_data:
3345 + * @dl: a datalist.
3346 + * @q: the #GQuark identifying the data element.
3347 + *
3348 + * Removes an element, using its #GQuark identifier.
3349 + */
3350 #define g_datalist_id_remove_data(dl, q) \
3351 g_datalist_id_set_data ((dl), (q), NULL)
3352 +
3353 +/**
3354 + * g_datalist_get_data:
3355 + * @dl: a datalist.
3356 + * @k: the string identifying a data element.
3357 + *
3358 + * Gets a data element, using its string identifer.
3359 + * This is slower than g_datalist_id_get_data() because the string is first
3360 + * converted to a #GQuark.
3361 + *
3362 + * Returns: the data element, or %NULL if it is not found.
3363 + */
3364 #define g_datalist_get_data(dl, k) \
3365 (g_datalist_id_get_data ((dl), g_quark_try_string (k)))
3366 +
3367 +/**
3368 + * g_datalist_set_data_full:
3369 + * @dl: a datalist.
3370 + * @k: the string to identify the data element.
3371 + * @d: the data element, or %NULL to remove any previous element corresponding to
3372 + * @k.
3373 + * @f: the function to call when the data element is removed. This
3374 + * function will be called with the data element and can be used to free any
3375 + * memory allocated for it. If @d is %NULL, then @f must also be %NULL.
3376 + *
3377 + * Sets the data element corresponding to the given string identifier, and the
3378 + * function to be called when the data element is removed.
3379 + */
3380 #define g_datalist_set_data_full(dl, k, d, f) \
3381 g_datalist_id_set_data_full ((dl), g_quark_from_string (k), (d), (f))
3382 +
3383 +/**
3384 + * g_datalist_remove_no_notify:
3385 + * @dl: a datalist.
3386 + * @k: the string identifying the data element.
3387 + *
3388 + * Removes an element, without calling its destroy notifier.
3389 + */
3390 #define g_datalist_remove_no_notify(dl, k) \
3391 g_datalist_id_remove_no_notify ((dl), g_quark_try_string (k))
3392 +
3393 +/**
3394 + * g_datalist_set_data:
3395 + * @dl: a datalist.
3396 + * @k: the string to identify the data element.
3397 + * @d: the data element, or %NULL to remove any previous element
3398 + * corresponding to @k.
3399 + *
3400 + * Sets the data element corresponding to the given string identifier.
3401 + */
3402 #define g_datalist_set_data(dl, k, d) \
3403 g_datalist_set_data_full ((dl), (k), (d), NULL)
3404 +
3405 +/**
3406 + * g_datalist_remove_data:
3407 + * @dl: a datalist.
3408 + * @k: the string identifying the data element.
3409 + *
3410 + * Removes an element using its string identifier.
3411 + * The data element's destroy function is called if it has been set.
3412 + */
3413 #define g_datalist_remove_data(dl, k) \
3414 g_datalist_id_set_data ((dl), g_quark_try_string (k), NULL)
3415
3416 @@ -102,18 +191,90 @@
3417 void g_dataset_foreach (gconstpointer dataset_location,
3418 GDataForeachFunc func,
3419 gpointer user_data);
3420 +
3421 +
3422 +
3423 +/**
3424 + * g_dataset_id_set_data:
3425 + * @l: the location identifying the dataset.
3426 + * @k: the #GQuark id to identify the data element.
3427 + * @d: the data element.
3428 + *
3429 + * Sets the data element associated with the given #GQuark id.
3430 + * Any previous data with the same key is removed, and its destroy function
3431 + * is called.
3432 + */
3433 #define g_dataset_id_set_data(l, k, d) \
3434 g_dataset_id_set_data_full ((l), (k), (d), NULL)
3435 +
3436 +/**
3437 + * g_dataset_id_remove_data:
3438 + * @l: the location identifying the dataset.
3439 + * @k: the #GQuark id identifying the data element.
3440 + *
3441 + * Removes a data element from a dataset.
3442 + * The data element's destroy function is called if it has been set.
3443 + */
3444 #define g_dataset_id_remove_data(l, k) \
3445 g_dataset_id_set_data ((l), (k), NULL)
3446 +
3447 +/**
3448 + * g_dataset_get_data:
3449 + * @l: the location identifying the dataset.
3450 + * @k: the string identifying the data element.
3451 + *
3452 + * Gets the data element corresponding to a string.
3453 + *
3454 + * Returns: the data element corresponding to the string, or %NULL if it is not
3455 + * found.
3456 + */
3457 #define g_dataset_get_data(l, k) \
3458 (g_dataset_id_get_data ((l), g_quark_try_string (k)))
3459 +
3460 +/**
3461 + * g_dataset_set_data_full:
3462 + * @l: the location identifying the dataset.
3463 + * @k: the string to identify the data element.
3464 + * @d: the data element.
3465 + * @f: the function to call when the data element is removed. This
3466 + * function will be called with the data element and can be used to free any
3467 + * memory allocated for it.
3468 + *
3469 + * Sets the data corresponding to the given string identifier, and the function
3470 + * to call when the data element is destroyed.
3471 + */
3472 #define g_dataset_set_data_full(l, k, d, f) \
3473 g_dataset_id_set_data_full ((l), g_quark_from_string (k), (d), (f))
3474 +
3475 +/**
3476 + * g_dataset_remove_no_notify:
3477 + * @l: the location identifying the dataset.
3478 + * @k: the string identifying the data element.
3479 + *
3480 + * Removes an element, without calling its destroy notifier.
3481 + */
3482 #define g_dataset_remove_no_notify(l, k) \
3483 g_dataset_id_remove_no_notify ((l), g_quark_try_string (k))
3484 +
3485 +/**
3486 + * g_dataset_set_data:
3487 + * @l: the location identifying the dataset.
3488 + * @k: the string to identify the data element.
3489 + * @d: the data element.
3490 + *
3491 + * Sets the data corresponding to the given string identifier.
3492 + */
3493 #define g_dataset_set_data(l, k, d) \
3494 g_dataset_set_data_full ((l), (k), (d), NULL)
3495 +
3496 +/**
3497 + * g_dataset_remove_data:
3498 + * @l: the location identifying the dataset.
3499 + * @k: the string identifying the data element.
3500 + *
3501 + * Removes a data element corresponding to a string.
3502 + * Its destroy function is called if it has been set.
3503 + */
3504 #define g_dataset_remove_data(l, k) \
3505 g_dataset_id_set_data ((l), g_quark_try_string (k), NULL)
3506
3507 Index: glib/gslist.c
3508 ===================================================================
3509 --- glib/gslist.c (revision 7087)
3510 +++ glib/gslist.c (working copy)
3511 @@ -33,14 +33,95 @@
3512 #include "glib.h"
3513 #include "galias.h"
3514
3515 +/**
3516 + * SECTION:linked_lists_single
3517 + * @Short_description: linked lists containing integer values or pointers
3518 + * to data, limited to iterating over the list in one direction
3519 + * @Title: Singly-Linked Lists
3520 + *
3521 + * The #GSList structure and its associated functions provide a standard
3522 + * singly-linked list data structure.
3523 + *
3524 + * Each element in the list contains a piece of data, together with a pointer
3525 + * which links to the next element in the list.
3526 + * Using this pointer it is possible to move through the list in one
3527 + * direction only (unlike the
3528 + * <link linkend="glib-Doubly-Linked-lists">Doubly-Linked Lists</link>
3529 + * which allow movement in both directions).
3530 + *
3531 + * The data contained in each element can be either integer values, by using one
3532 + * of the
3533 + * <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
3534 + * or simply pointers to any type of data.
3535 + *
3536 + * List elements are allocated from the <link linkend="glib-Memory-Slices">slice
3537 + * allocator</link>, which is more efficient than allocating elements
3538 + * individually.
3539 + *
3540 + * Note that most of the #GSList functions expect to be passed a pointer to
3541 + * the first element in the list. The functions which insert elements return
3542 + * the new start of the list, which may have changed.
3543 + *
3544 + * There is no function to create a #GSList. %NULL is considered to be the empty
3545 + * list so you simply set a #GSList* to %NULL.
3546 + *
3547 + * To add elements, use g_slist_append(), g_slist_prepend(), g_slist_insert()
3548 + * and g_slist_insert_sorted().
3549 + *
3550 + * To remove elements, use g_slist_remove().
3551 + *
3552 + * To find elements in the list use g_slist_last(), g_slist_next(),
3553 + * g_slist_nth(), g_slist_nth_data(), g_slist_find() and
3554 + * g_slist_find_custom().
3555 + *
3556 + * To find the index of an element use g_slist_position() and g_slist_index().
3557 + *
3558 + * To call a function for each element in the list use g_slist_foreach().
3559 + *
3560 + * To free the entire list, use g_slist_free().
3561 + */
3562
3563 +/**
3564 + * g_slist_push_allocator:
3565 + * @dummy: the #GAllocator to use when allocating #GSList elements.
3566 + *
3567 + * Sets the allocator to use to allocate #GSList elements.
3568 + * Use g_slist_pop_allocator() to restore the previous allocator.
3569 + *
3570 + * Note that this function is not available if GLib has been compiled
3571 + * with <option>--disable-mem-pools</option>
3572 + *
3573 + * Deprecated: 2.10: It does nothing, since #GSList has been
3574 + * converted to the <link linkend="glib-Memory-Slices">slice allocator</link>
3575 + */
3576 void g_slist_push_allocator (gpointer dummy) { /* present for binary compat only */ }
3577 +
3578 +/**
3579 + * g_slist_pop_allocator:
3580 + *
3581 + * Restores the previous #GAllocator, used when allocating #GSList elements.
3582 + *
3583 + * Note that this function is not available if GLib has been compiled
3584 + * with <option>--disable-mem-pools</option>
3585 + *
3586 + * Deprecated: 2.10: It does nothing, since #GSList has been
3587 + * converted to the <link linkend="glib-Memory-Slices">slice allocator</link>
3588 + */
3589 void g_slist_pop_allocator (void) { /* present for binary compat only */ }
3590
3591 #define _g_slist_alloc0() g_slice_new0 (GSList)
3592 #define _g_slist_alloc() g_slice_new (GSList)
3593 #define _g_slist_free1(slist) g_slice_free (GSList, slist)
3594
3595 +/**
3596 + * g_slist_alloc:
3597 + *
3598 + * Allocates space for one #GSList element.
3599 + * It is called by the g_slist_append(), g_slist_prepend(), g_slist_insert() and
3600 + * g_slist_insert_sorted() functions and so is rarely used on its own.
3601 + *
3602 + * Returns: a pointer to the newly-allocated #GSList element.
3603 + */
3604 GSList*
3605 g_slist_alloc (void)
3606 {
3607 Index: glib/galloca.h
3608 ===================================================================
3609 --- glib/galloca.h (revision 7087)
3610 +++ glib/galloca.h (working copy)
3611 @@ -57,7 +57,50 @@
3612 # endif /* !_MSC_VER && !__DMC__ */
3613 #endif /* !__GNUC__ && !GLIB_HAVE_ALLOCA_H */
3614
3615 +/**
3616 + * g_alloca:
3617 + * @size: number of bytes to allocate.
3618 + *
3619 + * Allocates @size bytes on the stack; these bytes will be freed when the current
3620 + * stack frame is cleaned up. This macro essentially just wraps the alloca()
3621 + * function present on most UNIX variants.
3622 + * Thus it provides the same advantages and pitfalls as alloca():
3623 + * <variablelist>
3624 + * + alloca() is very fast, as on most systems it's implemented by just adjusting
3625 + * the stack pointer register.
3626 + * </para></listitem></varlistentry>
3627 + * + It doesn't cause any memory fragmentation, within its scope, separate alloca()
3628 + * blocks just build up and are released together at function end.
3629 + * </para></listitem></varlistentry>
3630 + * - Allocation sizes have to fit into the current stack frame. For instance in a
3631 + * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
3632 + * so be sparse with alloca() uses.
3633 + * </para></listitem></varlistentry>
3634 + * - Allocation failure due to insufficient stack space is not indicated with a %NULL
3635 + * return like e.g. with malloc(). Instead, most systems probably handle it the same
3636 + * way as out of stack space situations from infinite function recursion, i.e.
3637 + * with a segmentation fault.
3638 + * </para></listitem></varlistentry>
3639 + * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
3640 + * Stack space allocated with alloca() in the same scope as a variable sized array
3641 + * will be freed together with the variable sized array upon exit of that scope, and
3642 + * not upon exit of the enclosing function scope.
3643 + * </para></listitem></varlistentry>
3644 + * </variablelist>
3645 + *
3646 + * Returns: space for @size bytes, allocated on the stack
3647 + */
3648 #define g_alloca(size) alloca (size)
3649 +
3650 +/**
3651 + * g_newa:
3652 + * @struct_type: Type of memory chunks to be allocated
3653 + * @n_structs: Number of chunks to be allocated
3654 + *
3655 + * Wraps g_alloca() in a more typesafe manner.
3656 + *
3657 + * Returns: Pointer to stack space for @n_structs chunks of type @struct_type
3658 + */
3659 #define g_newa(struct_type, n_structs) ((struct_type*) g_alloca (sizeof (struct_type) * (gsize) (n_structs)))
3660
3661 #endif /* __G_ALLOCA_H__ */
3662 Index: glib/gcache.c
3663 ===================================================================
3664 --- glib/gcache.c (revision 7087)
3665 +++ glib/gcache.c (working copy)
3666 @@ -33,6 +33,23 @@
3667 #include "glib.h"
3668 #include "galias.h"
3669
3670 +/**
3671 + * SECTION:caches
3672 + * @Short_description: caches allow sharing of complex data structures to save resources
3673 + * @Title: Caches
3674 + *
3675 + * A #GCache allows sharing of complex data structures, in order to save
3676 + * system resources.
3677 + *
3678 + * GTK+ uses caches for #GtkStyles and #GdkGCs. These consume a lot of
3679 + * resources, so a #GCache is used to see if a #GtkStyle or #GdkGC with the
3680 + * required properties already exists. If it does, then the existing
3681 + * object is used instead of creating a new one.
3682 + *
3683 + * #GCache uses keys and values.
3684 + * A #GCache key describes the properties of a particular resource.
3685 + * A #GCache value is the actual resource.
3686 + */
3687
3688 typedef struct _GCacheNode GCacheNode;
3689
3690 @@ -79,6 +96,28 @@
3691 g_slice_free (GCacheNode, node);
3692 }
3693
3694 +/**
3695 + * g_cache_new:
3696 + * @value_new_func: a function to create a new object given a key.
3697 + * This is called by g_cache_insert() if an object with the given key
3698 + * does not already exist.
3699 + * @value_destroy_func: a function to destroy an object. It is
3700 + * called by g_cache_remove() when the object is no longer needed (i.e. its
3701 + * reference count drops to 0).
3702 + * @key_dup_func: a function to copy a key. It is called by
3703 + * g_cache_insert() if the key does not already exist in the #GCache.
3704 + * @key_destroy_func: a function to destroy a key. It is
3705 + * called by g_cache_remove() when the object is no longer needed (i.e. its
3706 + * reference count drops to 0).
3707 + * @hash_key_func: a function to create a hash value from a key.
3708 + * @hash_value_func: a function to create a hash value from a value.
3709 + * @key_equal_func: a function to compare two keys. It should return %TRUE if
3710 + * the two keys are equivalent.
3711 + *
3712 + * Creates a new #GCache.
3713 + *
3714 + * Returns: a new #GCache.
3715 + */
3716 GCache*
3717 g_cache_new (GCacheNewFunc value_new_func,
3718 GCacheDestroyFunc value_destroy_func,
3719 @@ -109,6 +148,15 @@
3720 return cache;
3721 }
3722
3723 +/**
3724 + * g_cache_destroy:
3725 + * @cache: a #GCache.
3726 + *
3727 + * Frees the memory allocated for the #GCache.
3728 + *
3729 + * Note that it does not destroy the keys and values which were contained in the
3730 + * #GCache.
3731 + */
3732 void
3733 g_cache_destroy (GCache *cache)
3734 {
3735 @@ -119,6 +167,23 @@
3736 g_slice_free (GCache, cache);
3737 }
3738
3739 +/**
3740 + * g_cache_insert:
3741 + * @cache: a #GCache.
3742 + * @key: a key describing a #GCache object.
3743 + *
3744 + * Gets the value corresponding to the given key, creating it if necessary.
3745 + * It first checks if the value already exists in the #GCache, by using
3746 + * the @key_equal_func function passed to g_cache_new().
3747 + * If it does already exist it is returned, and its reference count is increased
3748 + * by one.
3749 + * If the value does not currently exist, if is created by calling the
3750 + * @value_new_func. The key is duplicated by calling
3751 + * @key_dup_func and the duplicated key and value are inserted
3752 + * into the #GCache.
3753 + *
3754 + * Returns: a pointer to a #GCache value.
3755 + */
3756 gpointer
3757 g_cache_insert (GCache *cache,
3758 gpointer key)
3759 @@ -145,6 +210,15 @@
3760 return node->value;
3761 }
3762
3763 +/**
3764 + * g_cache_remove:
3765 + * @cache: a #GCache.
3766 + * @value: the value to remove.
3767 + *
3768 + * Decreases the reference count of the given value.
3769 + * If it drops to 0 then the value and its corresponding key are destroyed,
3770 + * using the @value_destroy_func and @key_destroy_func passed to g_cache_new().
3771 + */
3772 void
3773 g_cache_remove (GCache *cache,
3774 gconstpointer value)
3775 @@ -171,6 +245,20 @@
3776 }
3777 }
3778
3779 +/**
3780 + * g_cache_key_foreach:
3781 + * @cache: a #GCache.
3782 + * @func: the function to call with each #GCache key.
3783 + * @user_data: user data to pass to the function.
3784 + *
3785 + * Calls the given function for each of the keys in the #GCache.
3786 + *
3787 + * <note><para>@func is passed three parameters, the value and key of a
3788 + * cache entry and the @user_data. The order of value and key is different
3789 + * from the order in which g_hash_table_foreach() passes key-value pairs
3790 + * to its callback function !
3791 + * </para></note>
3792 + */
3793 void
3794 g_cache_key_foreach (GCache *cache,
3795 GHFunc func,
3796 @@ -182,6 +270,17 @@
3797 g_hash_table_foreach (cache->value_table, func, user_data);
3798 }
3799
3800 +/**
3801 + * g_cache_value_foreach:
3802 + * @cache: a #GCache.
3803 + * @func: the function to call with each #GCache value.
3804 + * @user_data: user data to pass to the function.
3805 + *
3806 + * Calls the given function for each of the values in the #GCache.
3807 + *
3808 + * Deprecated: 2.10: The reason is that it passes pointers to internal data
3809 + * structures to @func; use g_cache_key_foreach() instead
3810 + */
3811 void
3812 g_cache_value_foreach (GCache *cache,
3813 GHFunc func,
3814 Index: glib/gslist.h
3815 ===================================================================
3816 --- glib/gslist.h (revision 7087)
3817 +++ glib/gslist.h (working copy)
3818 @@ -35,6 +35,15 @@
3819
3820 G_BEGIN_DECLS
3821
3822 +/**
3823 + * GSList:
3824 + * @data: holds the element's data, which can be a pointer to any kind of data,
3825 + * or any integer value using the
3826 + * <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>.
3827 + * @next: contains the link to the next element in the list.
3828 + *
3829 + * The #GSList struct is used for each element in the singly-linked list.
3830 + */
3831 typedef struct _GSList GSList;
3832
3833 struct _GSList
3834 @@ -48,6 +57,14 @@
3835 GSList* g_slist_alloc (void) G_GNUC_WARN_UNUSED_RESULT;
3836 void g_slist_free (GSList *list);
3837 void g_slist_free_1 (GSList *list);
3838 +
3839 +/**
3840 + * g_slist_free1:
3841 + *
3842 + * A macro which does the same as g_slist_free_1().
3843 + *
3844 + * Since: 2.10
3845 + */
3846 #define g_slist_free1 g_slist_free_1
3847 GSList* g_slist_append (GSList *list,
3848 gpointer data) G_GNUC_WARN_UNUSED_RESULT;
3849 @@ -102,6 +119,14 @@
3850 gpointer g_slist_nth_data (GSList *list,
3851 guint n);
3852
3853 +/**
3854 + * g_slist_next:
3855 + * @slist: an element in a #GSList.
3856 + *
3857 + * A convenience macro to gets the next element in a #GSList.
3858 + *
3859 + * Returns: the next element, or %NULL if there are no more elements.
3860 + */
3861 #define g_slist_next(slist) ((slist) ? (((GSList *)(slist))->next) : NULL)
3862
3863 #ifndef G_DISABLE_DEPRECATED
3864 Index: glib/gcache.h
3865 ===================================================================
3866 --- glib/gcache.h (revision 7087)
3867 +++ glib/gcache.h (working copy)
3868 @@ -35,10 +35,46 @@
3869
3870 G_BEGIN_DECLS
3871
3872 +/**
3873 + * GCache:
3874 + *
3875 + * The #GCache struct is an opaque data structure containing information about
3876 + * a #GCache. It should only be accessed via the following functions.
3877 + */
3878 typedef struct _GCache GCache;
3879 +/**
3880 + * GCacheNewFunc:
3881 + * @key: a #GCache key.
3882 + *
3883 + * Specifies the type of the @value_new_func function passed to g_cache_new().
3884 + * It is passed a #GCache key and should create the value corresponding to the
3885 + * key.
3886 + *
3887 + * Returns: a new #GCache value corresponding to the key.
3888 + */
3889 +typedef gpointer (*GCacheNewFunc) (gpointer key);
3890
3891 -typedef gpointer (*GCacheNewFunc) (gpointer key);
3892 +/**
3893 + * GCacheDupFunc:
3894 + * @value: the #GCache key to destroy (<emphasis>not</emphasis> a #GCache value as it seems).
3895 + *
3896 + * Specifies the type of the @key_dup_func function passed to g_cache_new().
3897 + * The function is passed a key (<emphasis>not</emphasis> a value as the prototype implies) and
3898 + * should return a duplicate of the key.
3899 + *
3900 + * Returns: a copy of the #GCache key.
3901 + */
3902 typedef gpointer (*GCacheDupFunc) (gpointer value);
3903 +
3904 +/**
3905 + * GCacheDestroyFunc:
3906 + * @value: the #GCache value to destroy.
3907 + *
3908 + * Specifies the type of the @value_destroy_func and @key_destroy_func functions
3909 + * passed to g_cache_new().
3910 + * The functions are passed a pointer to the #GCache key or #GCache value and
3911 + * should free any memory and other resources associated with it.
3912 + */
3913 typedef void (*GCacheDestroyFunc) (gpointer value);
3914
3915 /* Caches
3916 Index: glib/gtimer.c
3917 ===================================================================
3918 --- glib/gtimer.c (revision 7087)
3919 +++ glib/gtimer.c (working copy)
3920 @@ -55,6 +55,23 @@
3921
3922 #define GETTIME(v) (v = g_thread_gettime ())
3923
3924 +/**
3925 + * SECTION:timers
3926 + * @Short_description: keep track of elapsed time
3927 + * @Title: Timers
3928 + *
3929 + * #GTimer records a start time, and counts microseconds elapsed since that time.
3930 + * This is done somewhat differently on different platforms, and can be tricky to
3931 + * get exactly right, so #GTimer provides a portable/convenient interface.
3932 + *
3933 + * #GTimer uses a higher-quality clock when thread support is available.
3934 + * Therefore, calling g_thread_init() while timers are running may lead to
3935 + * unreliable results. It is best to call g_thread_init() before starting
3936 + * any timers, if you are using threads at all.
3937 + * </para></note>
3938 + */
3939 +
3940 +
3941 struct _GTimer
3942 {
3943 guint64 start;
3944 @@ -63,7 +80,14 @@
3945 guint active : 1;
3946 };
3947
3948 -
3949 +/**
3950 + * g_timer_new:
3951 + *
3952 + * Creates a new timer, and starts timing (i.e. g_timer_start() is implicitly
3953 + * called for you).
3954 + *
3955 + * Returns: a new #GTimer.
3956 + */
3957 GTimer*
3958 g_timer_new (void)
3959 {
3960 @@ -77,6 +101,12 @@
3961 return timer;
3962 }
3963
3964 +/**
3965 + * g_timer_destroy:
3966 + * @timer: a #GTimer to destroy.
3967 + *
3968 + * Destroys a timer, freeing associated resources.
3969 + */
3970 void
3971 g_timer_destroy (GTimer *timer)
3972 {
3973 @@ -85,6 +115,15 @@
3974 g_free (timer);
3975 }
3976
3977 +/**
3978 + * g_timer_start:
3979 + * @timer: a #GTimer.
3980 + *
3981 + * Marks a start time, so that future calls to g_timer_elapsed() will report the
3982 + * time since g_timer_start() was called. g_timer_new() automatically marks the
3983 + * start time, so no need to call g_timer_start() immediately after creating the
3984 + * timer.
3985 + */
3986 void
3987 g_timer_start (GTimer *timer)
3988 {
3989 @@ -95,6 +134,13 @@
3990 GETTIME (timer->start);
3991 }
3992
3993 +/**
3994 + * g_timer_stop:
3995 + * @timer: a #GTimer.
3996 + *
3997 + * Marks an end time, so calls to g_timer_elapsed() will return the difference
3998 + * between this end time and the start time.
3999 + */
4000 void
4001 g_timer_stop (GTimer *timer)
4002 {
4003 @@ -105,6 +151,14 @@
4004 GETTIME (timer->end);
4005 }
4006
4007 +/**
4008 + * g_timer_reset:
4009 + * @timer: a #GTimer.
4010 + *
4011 + * This function is useless; it's fine to call g_timer_start() on an
4012 + * already-started timer to reset the start time, so g_timer_reset() serves no
4013 + * purpose.
4014 + */
4015 void
4016 g_timer_reset (GTimer *timer)
4017 {
4018 @@ -113,6 +167,15 @@
4019 GETTIME (timer->start);
4020 }
4021
4022 +/**
4023 + * g_timer_continue:
4024 + * @timer: a #GTimer.
4025 + *
4026 + * Resumes a timer that has previously been stopped with g_timer_stop().
4027 + * g_timer_stop() must be called before using this function.
4028 + *
4029 + * Since: 2.4
4030 + */
4031 void
4032 g_timer_continue (GTimer *timer)
4033 {
4034 @@ -135,6 +198,25 @@
4035 timer->active = TRUE;
4036 }
4037
4038 +/**
4039 + * g_timer_elapsed:
4040 + * @timer: a #GTimer.
4041 + * @microseconds: return location for the fractional part of seconds elapsed,
4042 + * in microseconds (that is, the total number of microseconds elapsed, modulo
4043 + * 1000000), or %NULL
4044 + *
4045 + * If @timer has been started but not stopped, obtains the time since the timer was
4046 + * started. If @timer has been stopped, obtains the elapsed time between the time
4047 + * it was started and the time it was stopped. The return value is the number of
4048 + * seconds elapsed, including any fractional part. The @microseconds
4049 + * out parameter is essentially useless.
4050 + * <warning><para>Calling initialization functions, in particular g_thread_init(),
4051 + * while a timer is running will cause invalid return values from this function.
4052 + * </para></warning>
4053 + *
4054 + * Returns: seconds elapsed as a floating point value, including
4055 + * any fractional part.
4056 + */
4057 gdouble
4058 g_timer_elapsed (GTimer *timer,
4059 gulong *microseconds)
4060 @@ -157,6 +239,16 @@
4061 return total;
4062 }
4063
4064 +/**
4065 + * g_usleep:
4066 + * @microseconds: number of microseconds to pause
4067 + *
4068 + * Pauses the current thread for the given number of microseconds. There
4069 + * are 1 million microseconds per second (represented by the
4070 + * #G_USEC_PER_SEC macro). g_usleep() may have limited precision,
4071 + * depending on hardware and operating system; don't rely on the exact
4072 + * length of the sleep.
4073 + */
4074 void
4075 g_usleep (gulong microseconds)
4076 {
4077 Index: glib/gtimer.h
4078 ===================================================================
4079 --- glib/gtimer.h (revision 7087)
4080 +++ glib/gtimer.h (working copy)
4081 @@ -35,12 +35,19 @@
4082
4083 G_BEGIN_DECLS
4084
4085 -/* Timer
4086 +/**
4087 + * GTimer:
4088 + *
4089 + * Opaque datatype that records a start time.
4090 */
4091 -
4092 -/* microseconds per second */
4093 typedef struct _GTimer GTimer;
4094
4095 +/**
4096 + * G_USEC_PER_SEC:
4097 + *
4098 + * Number of microseconds in one second (1 million). This macro is provided for
4099 + * code readability.
4100 + */
4101 #define G_USEC_PER_SEC 1000000
4102
4103 GTimer* g_timer_new (void);
4104 Index: glib/gprimes.c
4105 ===================================================================
4106 --- glib/gprimes.c (revision 7087)
4107 +++ glib/gprimes.c (working copy)
4108 @@ -74,6 +74,20 @@
4109
4110 static const guint g_nprimes = sizeof (g_primes) / sizeof (g_primes[0]);
4111
4112 +/**
4113 + * g_spaced_primes_closest:
4114 + * @num: a #guint.
4115 + *
4116 + * Gets the smallest prime number from a built-in array of primes which
4117 + * is larger than @num. This is used within GLib to calculate the optimum
4118 + * size of a #GHashTable.
4119 + *
4120 + * The built-in array of primes ranges from 11 to 13845163 such that
4121 + * each prime is approximately 1.5-2 times the previous prime.
4122 + *
4123 + * Returns: the smallest prime number from a built-in array of primes which is
4124 + * larger than @num.
4125 + */
4126 guint
4127 g_spaced_primes_closest (guint num)
4128 {
4129 Index: glib/giochannel.c
4130 ===================================================================
4131 --- glib/giochannel.c (revision 7087)
4132 +++ glib/giochannel.c (working copy)
4133 @@ -50,6 +50,60 @@
4134
4135 #include "galias.h"
4136
4137 +/**
4138 + * SECTION:iochannels
4139 + * @Short_description: portable support for using files, pipes and sockets
4140 + * @Title: IO Channels
4141 + * @See_also:<variablelist>
4142 + *
4143 + * <varlistentry>
4144 + * <term>gtk_input_add_full(), gtk_input_remove(), gdk_input_add(),
4145 + * gdk_input_add_full(), gdk_input_remove()</term>
4146 + * Convenience functions for creating #GIOChannel instances and adding them to the
4147 + * <link linkend="glib-The-Main-Event-Loop">main event loop</link>.
4148 + * </para></listitem>
4149 + * </varlistentry>
4150 + *
4151 + * </variablelist>
4152 + *
4153 + * The #GIOChannel data type aims to provide a portable method for using file
4154 + * descriptors, pipes, and sockets, and integrating them into the
4155 + * <link linkend="glib-The-Main-Event-Loop">main event loop</link>.
4156 + * Currently full support is available on UNIX platforms, support for
4157 + * Windows is only partially complete.
4158 + *
4159 + * To create a new #GIOChannel on UNIX systems use g_io_channel_unix_new().
4160 + * This works for plain file descriptors, pipes and sockets.
4161 + * Alternatively, a channel can be created for a file in a system independent
4162 + * manner using g_io_channel_new_file().
4163 + *
4164 + * Once a #GIOChannel has been created, it can be used in a generic manner
4165 + * with the functions g_io_channel_read_chars(), g_io_channel_write_chars(),
4166 + * g_io_channel_seek_position(), and g_io_channel_shutdown().
4167 + *
4168 + * To add a #GIOChannel to the
4169 + * <link linkend="glib-The-Main-Event-Loop">main event loop</link>
4170 + * use g_io_add_watch() or g_io_add_watch_full(). Here you specify which events
4171 + * you are interested in on the #GIOChannel, and provide a function to be
4172 + * called whenever these events occur.
4173 + *
4174 + * #GIOChannel instances are created with an initial reference count of 1.
4175 + * g_io_channel_ref() and g_io_channel_unref() can be used to increment or
4176 + * decrement the reference count respectively. When the reference count falls
4177 + * to 0, the #GIOChannel is freed. (Though it isn't closed automatically,
4178 + * unless it was created using g_io_channel_new_from_file().)
4179 + * Using g_io_add_watch() or g_io_add_watch_full() increments a channel's
4180 + * reference count.
4181 + *
4182 + * The new functions g_io_channel_read_chars(), g_io_channel_read_line(),
4183 + * g_io_channel_read_line_string(), g_io_channel_read_to_end(),
4184 + * g_io_channel_write_chars(), g_io_channel_seek_position(),
4185 + * and g_io_channel_flush() should not be mixed with the
4186 + * deprecated functions g_io_channel_read(), g_io_channel_write(),
4187 + * and g_io_channel_seek() on the same channel.
4188 + */
4189 +
4190 +
4191 #define G_IO_NICE_BUF_SIZE 1024
4192
4193 /* This needs to be as wide as the largest character in any possible encoding */
4194 @@ -73,6 +127,15 @@
4195 gsize *terminator_pos,
4196 GError **error);
4197
4198 +/**
4199 + * g_io_channel_init:
4200 + * @channel: a #GIOChannel
4201 + *
4202 + * Initializes a #GIOChannel struct. This is called by each of the
4203 + * above functions when creating a #GIOChannel, and so is not often
4204 + * needed by the application programmer (unless you are creating a
4205 + * new type of #GIOChannel).
4206 + */
4207 void
4208 g_io_channel_init (GIOChannel *channel)
4209 {
4210 @@ -92,6 +155,14 @@
4211 channel->close_on_unref = FALSE;
4212 }
4213
4214 +/**
4215 + * g_io_channel_ref:
4216 + * @channel: a #GIOChannel.
4217 + *
4218 + * Increments the reference count of a #GIOChannel.
4219 + *
4220 + * Returns: the @channel that was passed in (since 2.6)
4221 + */
4222 GIOChannel *
4223 g_io_channel_ref (GIOChannel *channel)
4224 {
4225 @@ -102,6 +173,12 @@
4226 return channel;
4227 }
4228
4229 +/**
4230 + * g_io_channel_unref:
4231 + * @channel: a #GIOChannel.
4232 + *
4233 + * Decrements the reference count of a #GIOChannel.
4234 + */
4235 void
4236 g_io_channel_unref (GIOChannel *channel)
4237 {
4238 @@ -465,6 +542,23 @@
4239 }
4240 }
4241
4242 +/**
4243 + * g_io_create_watch:
4244 + * @channel: a #GIOChannel to watch
4245 + * @condition: conditions to watch for
4246 + *
4247 + * Creates a #GSource that's dispatched when @condition is met for the given
4248 + * @channel. For example, if condition is #G_IO_IN, the source will be dispatched
4249 + * when there's data available for reading. g_io_add_watch() is a simpler
4250 + * interface to this same functionality, for the case where you want to add the
4251 + * source to the default main loop at the default priority.
4252 + *
4253 + * On Windows, polling a #GSource created to watch a channel for a socket
4254 + * puts the socket in non-blocking mode. This is a side-effect of the
4255 + * implementation and unavoidable.
4256 + *
4257 + * Returns: a new #GSource
4258 + */
4259 GSource *
4260 g_io_create_watch (GIOChannel *channel,
4261 GIOCondition condition)
4262 @@ -474,6 +568,21 @@
4263 return channel->funcs->io_create_watch (channel, condition);
4264 }
4265
4266 +/**
4267 + * g_io_add_watch_full:
4268 + * @channel: a #GIOChannel
4269 + * @priority: the priority of the #GIOChannel source
4270 + * @condition: the condition to watch for
4271 + * @func: the function to call when the condition is satisfied
4272 + * @user_data: user data to pass to @func
4273 + * @notify: the function to call when the source is removed
4274 + *
4275 + * Adds the #GIOChannel into the
4276 + * <link linkend="glib-The-Main-Event-Loop">main event loop</link>
4277 + * with the given priority.
4278 + *
4279 + * Returns: the event source id
4280 + */
4281 guint
4282 g_io_add_watch_full (GIOChannel *channel,
4283 gint priority,
4284 @@ -499,6 +608,19 @@
4285 return id;
4286 }
4287
4288 +/**
4289 + * g_io_add_watch:
4290 + * @channel: a #GIOChannel
4291 + * @condition: the condition to watch for
4292 + * @func: the function to call when the condition is satisfied
4293 + * @user_data: user data to pass to @func
4294 + *
4295 + * Adds the #GIOChannel into the
4296 + * <link linkend="glib-The-Main-Event-Loop">main event loop</link>
4297 + * with the default priority.
4298 + *
4299 + * Returns: the event source id
4300 + */
4301 guint
4302 g_io_add_watch (GIOChannel *channel,
4303 GIOCondition condition,
4304 Index: glib/ghook.c
4305 ===================================================================
4306 --- glib/ghook.c (revision 7087)
4307 +++ glib/ghook.c (working copy)
4308 @@ -36,6 +36,15 @@
4309 #include "glib.h"
4310 #include "galias.h"
4311
4312 +/**
4313 + * SECTION:hooks
4314 + * @Short_description: support for manipulating lists of hook functions
4315 + * @Title: Hook Functions
4316 + *
4317 + * The #GHookList, #GHook and their related functions provide support for
4318 + * lists of hook functions. Functions can be added and removed from the lists,
4319 + * and the list of hook functions can be invoked.
4320 + */
4321
4322 /* --- functions --- */
4323 static void
4324 @@ -51,6 +60,15 @@
4325 }
4326 }
4327
4328 +/**
4329 + * g_hook_list_init:
4330 + * @hook_list: a #GHookList
4331 + * @hook_size: the size of each element in the #GHookList, typically
4332 + * <literal>sizeof (GHook)</literal>
4333 + *
4334 + * Initializes a #GHookList.
4335 + * This must be called before the #GHookList is used.
4336 + */
4337 void
4338 g_hook_list_init (GHookList *hook_list,
4339 guint hook_size)
4340 @@ -68,6 +86,12 @@
4341 hook_list->dummy[1] = NULL;
4342 }
4343
4344 +/**
4345 + * g_hook_list_clear:
4346 + * @hook_list: a #GHookList
4347 + *
4348 + * Removes all the #GHook elements from a #GHookList.
4349 + */
4350 void
4351 g_hook_list_clear (GHookList *hook_list)
4352 {
4353 @@ -99,6 +123,14 @@
4354 }
4355 }
4356
4357 +/**
4358 + * g_hook_alloc:
4359 + * @hook_list: a #GHookList
4360 + *
4361 + * Allocates space for a #GHook and initializes it.
4362 + *
4363 + * Returns: a new #GHook
4364 + */
4365 GHook*
4366 g_hook_alloc (GHookList *hook_list)
4367 {
4368 @@ -120,6 +152,14 @@
4369 return hook;
4370 }
4371
4372 +/**
4373 + * g_hook_free:
4374 + * @hook_list: a #GHookList
4375 + * @hook: the #GHook to free
4376 + *
4377 + * Calls the #GHookList @finalize_hook function if it exists, and frees the memory
4378 + * allocated for the #GHook.
4379 + */
4380 void
4381 g_hook_free (GHookList *hook_list,
4382 GHook *hook)
4383 @@ -135,6 +175,14 @@
4384 g_slice_free1 (hook_list->hook_size, hook);
4385 }
4386
4387 +/**
4388 + * g_hook_destroy_link:
4389 + * @hook_list: a #GHookList
4390 + * @hook: the #GHook to remove
4391 + *
4392 + * Removes one #GHook from a #GHookList, marking it inactive and calling
4393 + * g_hook_unref() on it.
4394 + */
4395 void
4396 g_hook_destroy_link (GHookList *hook_list,
4397 GHook *hook)
4398 @@ -150,6 +198,15 @@
4399 }
4400 }
4401
4402 +/**
4403 + * g_hook_destroy:
4404 + * @hook_list: a #GHookList
4405 + * @hook_id: a hook ID
4406 + *
4407 + * Destroys a #GHook, given its ID.
4408 + *
4409 + * Returns: %TRUE if the #GHook was found in the #GHookList and destroyed
4410 + */
4411 gboolean
4412 g_hook_destroy (GHookList *hook_list,
4413 gulong hook_id)
4414 @@ -169,6 +226,15 @@
4415 return FALSE;
4416 }
4417
4418 +/**
4419 + * g_hook_unref:
4420 + * @hook_list: a #GHookList
4421 + * @hook: the #GHook to unref
4422 + *
4423 + * Decrements the reference count of a #GHook.
4424 + * If the reference count falls to 0, the #GHook is removed from the #GHookList
4425 + * and g_hook_free() is called to free it.
4426 + */
4427 void
4428 g_hook_unref (GHookList *hook_list,
4429 GHook *hook)
4430 @@ -210,6 +276,15 @@
4431 }
4432 }
4433
4434 +/**
4435 + * g_hook_ref:
4436 + * @hook_list: a #GHookList
4437 + * @hook: the #GHook to increment the reference count of
4438 + *
4439 + * Increments the reference count for a #GHook.
4440 + *
4441 + * Returns: the @hook that was passed in (since 2.6)
4442 + */
4443 GHook *
4444 g_hook_ref (GHookList *hook_list,
4445 GHook *hook)
4446 @@ -223,6 +298,13 @@
4447 return hook;
4448 }
4449
4450 +/**
4451 + * g_hook_prepend:
4452 + * @hook_list: a #GHookList
4453 + * @hook: the #GHook to add to the start of @hook_list
4454 + *
4455 + * Prepends a #GHook on the start of a #GHookList.
4456 + */
4457 void
4458 g_hook_prepend (GHookList *hook_list,
4459 GHook *hook)
4460 @@ -232,6 +314,14 @@
4461 g_hook_insert_before (hook_list, hook_list->hooks, hook);
4462 }
4463
4464 +/**
4465 + * g_hook_insert_before:
4466 + * @hook_list: a #GHookList
4467 + * @sibling: the #GHook to insert the new #GHook before
4468 + * @hook: the #GHook to insert
4469 + *
4470 + * Inserts a #GHook into a #GHookList, before a given #GHook.
4471 + */
4472 void
4473 g_hook_insert_before (GHookList *hook_list,
4474 GHook *sibling,
4475 @@ -277,6 +367,14 @@
4476 }
4477 }
4478
4479 +/**
4480 + * g_hook_list_invoke:
4481 + * @hook_list: a #GHookList
4482 + * @may_recurse: %TRUE if functions which are already running (e.g. in another
4483 + * thread) can be called. If set to %FALSE, these are skipped
4484 + *
4485 + * Calls all of the #GHook functions in a #GHookList.
4486 + */
4487 void
4488 g_hook_list_invoke (GHookList *hook_list,
4489 gboolean may_recurse)
4490 @@ -304,6 +402,15 @@
4491 }
4492 }
4493
4494 +/**
4495 + * g_hook_list_invoke_check:
4496 + * @hook_list: a #GHookList
4497 + * @may_recurse: %TRUE if functions which are already running (e.g. in another
4498 + * thread) can be called. If set to %FALSE, these are skipped
4499 + *
4500 + * Calls all of the #GHook functions in a #GHookList.
4501 + * Any function which returns %FALSE is removed from the #GHookList.
4502 + */
4503 void
4504 g_hook_list_invoke_check (GHookList *hook_list,
4505 gboolean may_recurse)
4506 @@ -334,6 +441,17 @@
4507 }
4508 }
4509
4510 +/**
4511 + * g_hook_list_marshal_check:
4512 + * @hook_list: a #GHookList
4513 + * @may_recurse: %TRUE if hooks which are currently running (e.g. in another
4514 + * thread) are considered valid. If set to %FALSE, these are skipped
4515 + * @marshaller: the function to call for each #GHook
4516 + * @marshal_data: data to pass to @marshaller
4517 + *
4518 + * Calls a function on each valid #GHook and destroys it if the
4519 + * function returns %FALSE.
4520 + */
4521 void
4522 g_hook_list_marshal_check (GHookList *hook_list,
4523 gboolean may_recurse,
4524 @@ -364,6 +482,16 @@
4525 }
4526 }
4527
4528 +/**
4529 + * g_hook_list_marshal:
4530 + * @hook_list: a #GHookList
4531 + * @may_recurse: %TRUE if hooks which are currently running (e.g. in another
4532 + * thread) are considered valid. If set to %FALSE, these are skipped
4533 + * @marshaller: the function to call for each #GHook
4534 + * @marshal_data: data to pass to @marshaller
4535 + *
4536 + * Calls a function on each valid #GHook.
4537 + */
4538 void
4539 g_hook_list_marshal (GHookList *hook_list,
4540 gboolean may_recurse,
4541 @@ -391,6 +519,19 @@
4542 }
4543 }
4544
4545 +/**
4546 + * g_hook_first_valid:
4547 + * @hook_list: a #GHookList
4548 + * @may_be_in_call: %TRUE if hooks which are currently running (e.g. in another
4549 + * thread) are considered valid. If set to %FALSE, these are skipped
4550 + *
4551 + * Returns the first #GHook in a #GHookList which has not been destroyed.
4552 + * The reference count for the #GHook is incremented, so you must call
4553 + * g_hook_unref() to restore it when no longer needed. (Or call
4554 + * g_hook_next_valid() if you are stepping through the #GHookList.)
4555 + *
4556 + * Returns: the first valid #GHook, or %NULL if none are valid
4557 + */
4558 GHook*
4559 g_hook_first_valid (GHookList *hook_list,
4560 gboolean may_be_in_call)
4561 @@ -415,6 +556,20 @@
4562 return NULL;
4563 }
4564
4565 +/**
4566 + * g_hook_next_valid:
4567 + * @hook_list: a #GHookList
4568 + * @hook: the current #GHook
4569 + * @may_be_in_call: %TRUE if hooks which are currently running (e.g. in another
4570 + * thread) are considered valid. If set to %FALSE, these are skipped
4571 + *
4572 + * Returns the next #GHook in a #GHookList which has not been destroyed.
4573 + * The reference count for the #GHook is incremented, so you must call
4574 + * g_hook_unref() to restore it when no longer needed. (Or continue to call
4575 + * g_hook_next_valid() until %NULL is returned.)
4576 + *
4577 + * Returns: the next valid #GHook, or %NULL if none are valid
4578 + */
4579 GHook*
4580 g_hook_next_valid (GHookList *hook_list,
4581 GHook *hook,
4582 @@ -444,6 +599,15 @@
4583 return NULL;
4584 }
4585
4586 +/**
4587 + * g_hook_get:
4588 + * @hook_list: a #GHookList
4589 + * @hook_id: a hook id
4590 + *
4591 + * Returns the #GHook with the given id, or %NULL if it is not found.
4592 + *
4593 + * Returns: the #GHook with the given id, or %NULL if it is not found
4594 + */
4595 GHook*
4596 g_hook_get (GHookList *hook_list,
4597 gulong hook_id)
4598 @@ -464,6 +628,19 @@
4599 return NULL;
4600 }
4601
4602 +/**
4603 + * g_hook_find:
4604 + * @hook_list: a #GHookList
4605 + * @need_valids: %TRUE if #GHook elements which have been destroyed should be
4606 + * skipped
4607 + * @func: the function to call for each #GHook, which should return %TRUE when
4608 + * the #GHook has been found
4609 + * @data: the data to pass to @func
4610 + *
4611 + * Finds a #GHook in a #GHookList using the given function to test for a match.
4612 + *
4613 + * Returns: the found #GHook or %NULL if no matching #GHook is found
4614 + */
4615 GHook*
4616 g_hook_find (GHookList *hook_list,
4617 gboolean need_valids,
4618 @@ -504,6 +681,18 @@
4619 return NULL;
4620 }
4621
4622 +/**
4623 + * g_hook_find_data:
4624 + * @hook_list: a #GHookList
4625 + * @need_valids: %TRUE if #GHook elements which have been destroyed should be
4626 + * skipped
4627 + * @data: the data to find
4628 + *
4629 + * Finds a #GHook in a #GHookList with the given data.
4630 + *
4631 + * Returns: the #GHook with the given @data or %NULL if no matching
4632 + * #GHook is found
4633 + */
4634 GHook*
4635 g_hook_find_data (GHookList *hook_list,
4636 gboolean need_valids,
4637 @@ -528,6 +717,18 @@
4638 return NULL;
4639 }
4640
4641 +/**
4642 + * g_hook_find_func:
4643 + * @hook_list: a #GHookList
4644 + * @need_valids: %TRUE if #GHook elements which have been destroyed should be
4645 + * skipped
4646 + * @func: the function to find
4647 + *
4648 + * Finds a #GHook in a #GHookList with the given function.
4649 + *
4650 + * Returns: the #GHook with the given @func or %NULL if no matching
4651 + * #GHook is found
4652 + */
4653 GHook*
4654 g_hook_find_func (GHookList *hook_list,
4655 gboolean need_valids,
4656 @@ -553,6 +754,19 @@
4657 return NULL;
4658 }
4659
4660 +/**
4661 + * g_hook_find_func_data:
4662 + * @hook_list: a #GHookList
4663 + * @need_valids: %TRUE if #GHook elements which have been destroyed should be
4664 + * skipped
4665 + * @func: the function to find
4666 + * @data: the data to find
4667 + *
4668 + * Finds a #GHook in a #GHookList with the given function and data.
4669 + *
4670 + * Returns: the #GHook with the given @func and @data or %NULL if no matching
4671 + * #GHook is found
4672 + */
4673 GHook*
4674 g_hook_find_func_data (GHookList *hook_list,
4675 gboolean need_valids,
4676 @@ -580,6 +794,14 @@
4677 return NULL;
4678 }
4679
4680 +/**
4681 + * g_hook_insert_sorted:
4682 + * @hook_list: a #GHookList
4683 + * @hook: the #GHook to insert
4684 + * @func: the comparison function used to sort the #GHook elements
4685 + *
4686 + * Inserts a #GHook into a #GHookList, sorted by the given function.
4687 + */
4688 void
4689 g_hook_insert_sorted (GHookList *hook_list,
4690 GHook *hook,
4691 @@ -622,6 +844,16 @@
4692 g_hook_insert_before (hook_list, sibling, hook);
4693 }
4694
4695 +/**
4696 + * g_hook_compare_ids:
4697 + * @new_hook: a #GHook
4698 + * @sibling: a #GHook to compare with @new_hook
4699 + *
4700 + * Compares the ids of two #GHook elements, returning a negative value
4701 + * if the second id is greater than the first.
4702 + *
4703 + * Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook
4704 + */
4705 gint
4706 g_hook_compare_ids (GHook *new_hook,
4707 GHook *sibling)
4708 Index: glib/giochannel.h
4709 ===================================================================
4710 --- glib/giochannel.h (revision 7087)
4711 +++ glib/giochannel.h (working copy)
4712 @@ -37,12 +37,40 @@
4713
4714 G_BEGIN_DECLS
4715
4716 -/* GIOChannel
4717 +/**
4718 + * GIOChannel:
4719 + *
4720 + * A data structure representing an IO Channel. The fields should be considered
4721 + * private and should only be accessed with the following functions.
4722 */
4723 +typedef struct _GIOChannel GIOChannel;
4724
4725 -typedef struct _GIOChannel GIOChannel;
4726 +/**
4727 + * GIOFuncs:
4728 + * @io_read:
4729 + * @io_write:
4730 + * @io_seek:
4731 + * @io_close:
4732 + * @io_create_watch:
4733 + * @io_free:
4734 + * @io_set_flags:
4735 + * @io_get_flags:
4736 + *
4737 + * A table of functions used to handle different types of #GIOChannel
4738 + * in a generic way.
4739 + */
4740 typedef struct _GIOFuncs GIOFuncs;
4741
4742 +/**
4743 + * GIOError:
4744 + * @G_IO_ERROR_NONE: no error
4745 + * @G_IO_ERROR_AGAIN: an EAGAIN error occurred
4746 + * @G_IO_ERROR_INVAL: an EINVAL error occurred
4747 + * @G_IO_ERROR_UNKNOWN: another error occurred
4748 + *
4749 + * #GIOError is only used by the deprecated functions g_io_channel_read(),
4750 + * g_io_channel_write(), and g_io_channel_seek().
4751 + */
4752 typedef enum
4753 {
4754 G_IO_ERROR_NONE,
4755 @@ -51,8 +79,29 @@
4756 G_IO_ERROR_UNKNOWN
4757 } GIOError;
4758
4759 +/**
4760 + * G_IO_CHANNEL_ERROR:
4761 + *
4762 + * Error domain for #GIOChannel operations. Errors in this domain will
4763 + * be from the #GIOChannelError enumeration. See #GError for information on
4764 + * error domains.
4765 + */
4766 #define G_IO_CHANNEL_ERROR g_io_channel_error_quark()
4767
4768 +/**
4769 + * GIOChannelError:
4770 + * @G_IO_CHANNEL_ERROR_FBIG: File too large.
4771 + * @G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
4772 + * @G_IO_CHANNEL_ERROR_IO: IO error.
4773 + * @G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
4774 + * @G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
4775 + * @G_IO_CHANNEL_ERROR_NXIO: No such device or address.
4776 + * @G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
4777 + * @G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
4778 + * @G_IO_CHANNEL_ERROR_FAILED: Some other error.
4779 + *
4780 + * Error codes returned by #GIOChannel operations.
4781 + */
4782 typedef enum
4783 {
4784 /* Derived from errno */
4785 @@ -68,6 +117,15 @@
4786 G_IO_CHANNEL_ERROR_FAILED
4787 } GIOChannelError;
4788
4789 +/**
4790 + * GIOStatus:
4791 + * @G_IO_STATUS_ERROR: An error occurred.
4792 + * @G_IO_STATUS_NORMAL: Success.
4793 + * @G_IO_STATUS_EOF: End of file.
4794 + * @G_IO_STATUS_AGAIN: Resource temporarily unavailable.
4795 + *
4796 + * Stati returned by most of the #GIOFuncs functions.
4797 + */
4798 typedef enum
4799 {
4800 G_IO_STATUS_ERROR,
4801 @@ -76,6 +134,15 @@
4802 G_IO_STATUS_AGAIN
4803 } GIOStatus;
4804
4805 +/**
4806 + * GSeekType:
4807 + * @G_SEEK_CUR: the current position in the file.
4808 + * @G_SEEK_SET: the start of the file.
4809 + * @G_SEEK_END: the end of the file.
4810 + *
4811 + * An enumeration specifying the base position for a
4812 + * g_io_channel_seek_position() operation.
4813 + */
4814 typedef enum
4815 {
4816 G_SEEK_CUR,
4817 @@ -83,6 +150,19 @@
4818 G_SEEK_END
4819 } GSeekType;
4820
4821 +/**
4822 + * GIOCondition:
4823 + * @G_IO_IN: There is data to read.
4824 + * @G_IO_OUT: Data can be written (without blocking).
4825 + * @G_IO_PRI: There is urgent data to read.
4826 + * @G_IO_ERR: Error condition.
4827 + * @G_IO_HUP: Hung up (the connection has been broken, usually for pipes
4828 + * and sockets).
4829 + * @G_IO_NVAL: Invalid request. The file descriptor is not open.
4830 + *
4831 + * A bitwise combination representing a condition to watch for on
4832 + * an event source.
4833 + */
4834 typedef enum
4835 {
4836 G_IO_IN GLIB_SYSDEF_POLLIN,
4837 @@ -93,6 +173,28 @@
4838 G_IO_NVAL GLIB_SYSDEF_POLLNVAL
4839 } GIOCondition;
4840
4841 +/**
4842 + * GIOFlags:
4843 + * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
4844 + * (see the documentation of the UNIX open() syscall).
4845 + * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
4846 + * %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open()
4847 + * syscall).
4848 + * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
4849 + * This flag can not be changed.
4850 + * @G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable.
4851 + * This flag can not be changed.
4852 + * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
4853 + * i.e. that g_io_channel_seek_position() can be used on it.
4854 + * This flag can not be changed.
4855 + * @G_IO_FLAG_MASK:
4856 + * @G_IO_FLAG_GET_MASK:
4857 + * @G_IO_FLAG_SET_MASK:
4858 + *
4859 + * Specifies properties of a #GIOChannel. Some of the flags can only
4860 + * be read with g_io_channel_get_flags(), but not changed with
4861 + * g_io_channel_set_flags().
4862 + */
4863 typedef enum
4864 {
4865 G_IO_FLAG_APPEND = 1 << 0,
4866 @@ -136,6 +238,19 @@
4867 gpointer reserved2;
4868 };
4869
4870 +/**
4871 + * GIOFunc:
4872 + * @source: the #GIOChannel event source
4873 + * @condition: the condition which has been satisfied
4874 + * @data: user data set in g_io_add_watch() or g_io_add_watch_full()
4875 + *
4876 + * Specifies the type of function passed to g_io_add_watch() or
4877 + * g_io_add_watch_full(), which is called when the requested
4878 + * condition on a #GIOChannel is satisfied.
4879 + *
4880 + * Returns: the function should return %FALSE if the event source
4881 + * should be removed
4882 + */
4883 typedef gboolean (*GIOFunc) (GIOChannel *source,
4884 GIOCondition condition,
4885 gpointer data);
4886 Index: glib/ghook.h
4887 ===================================================================
4888 --- glib/ghook.h (revision 7087)
4889 +++ glib/ghook.h (working copy)
4890 @@ -36,28 +36,142 @@
4891 G_BEGIN_DECLS
4892
4893
4894 -/* --- typedefs --- */
4895 +/**
4896 + * GHook:
4897 + * @data: data which is passed to func when this hook is invoked
4898 + * @next: pointer to the next hook in the list
4899 + * @prev: pointer to the previous hook in the list
4900 + * @ref_count: the reference count of this hook
4901 + * @hook_id: the id of this hook, which is unique within its list
4902 + * @flags: flags which are set for this hook. See #GHookFlagMask for
4903 + * predefined flags
4904 + * @func: the function to call when this hook is invoked. The possible
4905 + * signatures for this function are #GHookFunc and #GHookCheckFunc
4906 + * @destroy: the default <function>finalize_hook</function> function of a
4907 + * #GHookList calls this member of the hook that is being finalized
4908 + *
4909 + * The <structname>GHook</structname> struct represents a single hook
4910 + * function in a #GHookList.
4911 + */
4912 typedef struct _GHook GHook;
4913 +
4914 +/**
4915 + * GHookList:
4916 + * @seq_id: the next free #GHook id
4917 + * @hook_size: the size of the #GHookList elements, in bytes
4918 + * @is_setup: 1 if the #GHookList has been initialized
4919 + * @hooks: the first #GHook element in the list
4920 + * @dummy3: unused
4921 + * @finalize_hook: the function to call to finalize a #GHook element. The
4922 + * default behaviour is to call the hooks <function>destroy</function> function
4923 + * @dummy: unused
4924 + *
4925 + * The <structname>GHookList</structname> struct represents a
4926 + * list of hook functions.
4927 + */
4928 typedef struct _GHookList GHookList;
4929
4930 +/**
4931 + * GHookCompareFunc:
4932 + * @new_hook: the #GHook being inserted
4933 + * @sibling: the #GHook to compare with @new_hook
4934 + *
4935 + * Defines the type of function used to compare #GHook elements in
4936 + * g_hook_insert_sorted().
4937 + *
4938 + * Returns: a value <= 0 if @new_hook should be before @sibling
4939 + */
4940 typedef gint (*GHookCompareFunc) (GHook *new_hook,
4941 GHook *sibling);
4942 +/**
4943 + * GHookFindFunc:
4944 + * @hook: a #GHook
4945 + * @data: user data passed to g_hook_find_func()
4946 + *
4947 + * Defines the type of the function passed to g_hook_find().
4948 + *
4949 + * Returns: %TRUE if the required #GHook has been found
4950 + */
4951 typedef gboolean (*GHookFindFunc) (GHook *hook,
4952 gpointer data);
4953 +
4954 +/**
4955 + * GHookMarshaller:
4956 + * @hook: a #GHook
4957 + * @marshal_data: user data
4958 + *
4959 + * Defines the type of function used by g_hook_list_marshal().
4960 + */
4961 typedef void (*GHookMarshaller) (GHook *hook,
4962 gpointer marshal_data);
4963 +
4964 +/**
4965 + * GHookCheckMarshaller:
4966 + * @hook: a #GHook
4967 + * @marshal_data: user data
4968 + *
4969 + * Defines the type of function used by g_hook_list_marshal_check().
4970 + *
4971 + * Returns: %FALSE if @hook should be destroyed
4972 + */
4973 typedef gboolean (*GHookCheckMarshaller) (GHook *hook,
4974 gpointer marshal_data);
4975 +
4976 +/**
4977 + * GHookFunc:
4978 + * @data: the data field of the #GHook is passed to the hook function here
4979 + *
4980 + * Defines the type of a hook function that can be invoked
4981 + * by g_hook_list_invoke().
4982 + */
4983 typedef void (*GHookFunc) (gpointer data);
4984 +
4985 +/**
4986 + * GHookCheckFunc:
4987 + * @data: the data field of the #GHook is passed to the hook function here
4988 + *
4989 + * Defines the type of a hook function that can be invoked
4990 + * by g_hook_list_invoke_check().
4991 + *
4992 + * Returns: %FALSE if the #GHook should be destroyed
4993 + */
4994 typedef gboolean (*GHookCheckFunc) (gpointer data);
4995 +
4996 +/**
4997 + * GHookFinalizeFunc:
4998 + * @hook_list: a #GHookList
4999 + * @hook: the hook in @hook_list that gets finalized
5000 + *
5001 + * Defines the type of function to be called when a hook in a
5002 + * list of hooks gets finalized.
5003 + */
5004 typedef void (*GHookFinalizeFunc) (GHookList *hook_list,
5005 GHook *hook);
5006 +
5007 +/**
5008 + * GHookFlagMask:
5009 + * @G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed
5010 + * @G_HOOK_FLAG_IN_CALL: set if the hook is currently being run
5011 + * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for
5012 + * hook flags; see #G_HOOK_FLAGS_USER_SHIFT
5013 + *
5014 + * Flags used internally in the #GHook implementation.
5015 + */
5016 typedef enum
5017 {
5018 G_HOOK_FLAG_ACTIVE = 1 << 0,
5019 G_HOOK_FLAG_IN_CALL = 1 << 1,
5020 G_HOOK_FLAG_MASK = 0x0f
5021 } GHookFlagMask;
5022 +
5023 +/**
5024 + * G_HOOK_FLAG_USER_SHIFT:
5025 + *
5026 + * The position of the first bit which is not reserved for internal
5027 + * use be the #GHook implementation, i.e.
5028 + * <literal>1 << G_HOOK_FLAG_USER_SHIFT</literal> is the first bit
5029 + * which can be used for application-defined flags.
5030 + */
5031 #define G_HOOK_FLAG_USER_SHIFT (4)
5032
5033
5034 @@ -86,15 +200,65 @@
5035
5036
5037 /* --- macros --- */
5038 +/**
5039 + * G_HOOK:
5040 + * @hook: a pointer
5041 + *
5042 + * Casts a pointer to a <literal>GHook*</literal>.
5043 + */
5044 #define G_HOOK(hook) ((GHook*) (hook))
5045 +
5046 +/**
5047 + * G_HOOK_FLAGS:
5048 + * @hook: a #GHook
5049 + *
5050 + * Returns the flags of a hook.
5051 + */
5052 #define G_HOOK_FLAGS(hook) (G_HOOK (hook)->flags)
5053 +
5054 +/**
5055 + * G_HOOK_ACTIVE:
5056 + * @hook: a #GHook
5057 + *
5058 + * Returns %TRUE if the #GHook is active, which is normally %TRUE until the #GHook
5059 + * is destroyed.
5060 + *
5061 + * Returns: %TRUE if the #GHook is active
5062 + */
5063 #define G_HOOK_ACTIVE(hook) ((G_HOOK_FLAGS (hook) & \
5064 G_HOOK_FLAG_ACTIVE) != 0)
5065 +/**
5066 + * G_HOOK_IN_CALL:
5067 + * @hook: a #GHook
5068 + *
5069 + * Returns %TRUE if the #GHook function is currently executing.
5070 + *
5071 + * Returns: %TRUE if the #GHook function is currently executing
5072 + */
5073 #define G_HOOK_IN_CALL(hook) ((G_HOOK_FLAGS (hook) & \
5074 G_HOOK_FLAG_IN_CALL) != 0)
5075 +
5076 +/**
5077 + * G_HOOK_IS_VALID:
5078 + * @hook: a #GHook
5079 + *
5080 + * Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active
5081 + * and it has not been destroyed.
5082 + *
5083 + * Returns: %TRUE if the #GHook is valid
5084 + */
5085 #define G_HOOK_IS_VALID(hook) (G_HOOK (hook)->hook_id != 0 && \
5086 (G_HOOK_FLAGS (hook) & \
5087 G_HOOK_FLAG_ACTIVE))
5088 +
5089 +/**
5090 + * G_HOOK_IS_UNLINKED:
5091 + * @hook: a #GHook
5092 + *
5093 + * Returns %TRUE if the #GHook is not in a #GHookList.
5094 + *
5095 + * Returns: %TRUE if the #GHook is not in a #GHookList
5096 + */
5097 #define G_HOOK_IS_UNLINKED(hook) (G_HOOK (hook)->next == NULL && \
5098 G_HOOK (hook)->prev == NULL && \
5099 G_HOOK (hook)->hook_id == 0 && \
5100 @@ -154,6 +318,13 @@
5101 gint g_hook_compare_ids (GHook *new_hook,
5102 GHook *sibling);
5103 /* convenience macros */
5104 +/**
5105 + * g_hook_append:
5106 + * @hook_list: a #GHookList
5107 + * @hook: the #GHook to add to the end of @hook_list
5108 + *
5109 + * Appends a #GHook onto the end of a #GHookList.
5110 + */
5111 #define g_hook_append( hook_list, hook ) \
5112 g_hook_insert_before ((hook_list), NULL, (hook))
5113 /* invoke all valid hooks with the (*GHookFunc) signature.
5114 Index: glib/gstrfuncs.c
5115 ===================================================================
5116 --- glib/gstrfuncs.c (revision 7087)
5117 +++ glib/gstrfuncs.c (working copy)
5118 @@ -98,6 +98,18 @@
5119 return new_str;
5120 }
5121
5122 +
5123 +/**
5124 + * g_memdup:
5125 + * @mem: the memory to copy.
5126 + * @byte_size: the number of bytes to copy.
5127 + *
5128 + * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
5129 + * from @mem. If @mem is %NULL it returns %NULL.
5130 + *
5131 + * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
5132 + * is %NULL.
5133 + */
5134 gpointer
5135 g_memdup (gconstpointer mem,
5136 guint byte_size)
5137 Index: glib/garray.c
5138 ===================================================================
5139 --- glib/garray.c (revision 7087)
5140 +++ glib/garray.c (working copy)
5141 @@ -45,6 +45,51 @@
5142
5143 #define MIN_ARRAY_SIZE 16
5144
5145 +/**
5146 + * SECTION:arrays
5147 + * @Short_description: arrays of arbitrary elements which grow automatically as elements are added
5148 + * @Title: Arrays
5149 + *
5150 + * Arrays are similar to standard C arrays, except that they grow automatically
5151 + * as elements are added.
5152 + *
5153 + * Array elements can be of any size (though all elements of one array are the
5154 + * same size), and the array can be automatically cleared to '0's and
5155 + * zero-terminated.
5156 + *
5157 + * To create a new array use g_array_new().
5158 + *
5159 + * To add elements to an array, use g_array_append_val(), g_array_append_vals(),
5160 + * g_array_prepend_val(), and g_array_prepend_vals().
5161 + *
5162 + * To access an element of an array, use g_array_index().
5163 + *
5164 + * To set the size of an array, use g_array_set_size().
5165 + *
5166 + * To free an array, use g_array_free().
5167 + *
5168 + * <example>
5169 + * <title>Using a <structname>GArray</structname> to store <type>gint</type> values</title>
5170 + * <programlisting>
5171 + * GArray *garray;
5172 + * gint i;
5173 + *
5174 + * /*<!----> We create a new array to store gint values.
5175 + * We don't want it zero-terminated or cleared to 0's. *<!---->/
5176 + * garray = g_array_new (FALSE, FALSE, sizeof (gint));
5177 + * for (i = 0; i < 10000; i++)
5178 + * g_array_append_val (garray, i);
5179 + *
5180 + * for (i = 0; i < 10000; i++)
5181 + * if (g_array_index (garray, gint, i) != i)
5182 + * g_print ("ERROR: got %d instead of %d\n",
5183 + * g_array_index (garray, gint, i), i);
5184 + *
5185 + * g_array_free (garray, TRUE);
5186 + * </programlisting></example>
5187 + */
5188 +
5189 +
5190 typedef struct _GRealArray GRealArray;
5191
5192 struct _GRealArray
5193 @@ -69,7 +114,18 @@
5194 static gint g_nearest_pow (gint num) G_GNUC_CONST;
5195 static void g_array_maybe_expand (GRealArray *array,
5196 gint len);
5197 -
5198 +/**
5199 + * g_array_new:
5200 + * @zero_terminated: %TRUE if the array should have an extra element at the end
5201 + * which is set to 0.
5202 + * @clear_: %TRUE if #GArray elements should be automatically cleared to 0
5203 + * when they are allocated.
5204 + * @element_size: the size of each element in bytes.
5205 + *
5206 + * Creates a new #GArray.
5207 + *
5208 + * Returns: the new #GArray.
5209 + */
5210 GArray*
5211 g_array_new (gboolean zero_terminated,
5212 gboolean clear,
5213 @@ -78,6 +134,20 @@
5214 return (GArray*) g_array_sized_new (zero_terminated, clear, elt_size, 0);
5215 }
5216
5217 +/**
5218 + * g_array_sized_new:
5219 + * @zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared.
5220 + * @clear_: %TRUE if all bits in the array should be cleared to 0 on allocation.
5221 + * @element_size: size of each element in the array.
5222 + * @reserved_size: number of elements preallocated.
5223 + *
5224 + * Creates a new #GArray with @reserved_size elements
5225 + * preallocated. This avoids frequent reallocation, if you are going to
5226 + * add many elements to the array. Note however that the size of the
5227 + * array is still 0.
5228 + *
5229 + * Returns: the new #GArray.
5230 + */
5231 GArray* g_array_sized_new (gboolean zero_terminated,
5232 gboolean clear,
5233 guint elt_size,
5234 @@ -101,6 +171,25 @@
5235 return (GArray*) array;
5236 }
5237
5238 +/**
5239 + * g_array_free:
5240 + * @array: a #GArray.
5241 + * @free_segment: if %TRUE the actual element data is freed as well.
5242 + *
5243 + * Frees the memory allocated for the #GArray.
5244 + * If @free_segment is %TRUE it frees the memory block holding the elements
5245 + * as well. Pass %FALSE if you want to free the #GArray wrapper but preserve
5246 + * the underlying array for use elsewhere.
5247 + *
5248 + * <note>
5249 + * If array elements contain dynamically-allocated memory, they should be freed
5250 + * separately.
5251 + *
5252 + * </note>
5253 + *
5254 + * Returns: the element data if @free_segment is %FALSE, otherwise %NULL.
5255 + * The element data should be freed using g_free().
5256 + */
5257 gchar*
5258 g_array_free (GArray *array,
5259 gboolean free_segment)
5260 @@ -122,6 +211,16 @@
5261 return segment;
5262 }
5263
5264 +/**
5265 + * g_array_append_vals:
5266 + * @array: a #GArray.
5267 + * @data: a pointer to the elements to append to the end of the array.
5268 + * @len: the number of elements to append.
5269 + *
5270 + * Adds @len elements onto the end of the array.
5271 + *
5272 + * Returns: the #GArray.
5273 + */
5274 GArray*
5275 g_array_append_vals (GArray *farray,
5276 gconstpointer data,
5277 @@ -141,6 +240,19 @@
5278 return farray;
5279 }
5280
5281 +/**
5282 + * g_array_prepend_vals:
5283 + * @array: a #GArray.
5284 + * @data: a pointer to the elements to prepend to the start of the array.
5285 + * @len: the number of elements to prepend.
5286 + *
5287 + * Adds @len elements onto the start of the array.
5288 + *
5289 + * This operation is slower than g_array_append_vals() since the existing elements
5290 + * in the array have to be moved to make space for the new elements.
5291 + *
5292 + * Returns: the #GArray.
5293 + */
5294 GArray*
5295 g_array_prepend_vals (GArray *farray,
5296 gconstpointer data,
5297 @@ -162,6 +274,17 @@
5298 return farray;
5299 }
5300
5301 +/**
5302 + * g_array_insert_vals:
5303 + * @array: a #GArray.
5304 + * @index_: the index to place the elements at.
5305 + * @data: a pointer to the elements to insert.
5306 + * @len: the number of elements to insert.
5307 + *
5308 + * Inserts @len elements into a #GArray at the given index.
5309 + *
5310 + * Returns: the #GArray.
5311 + */
5312 GArray*
5313 g_array_insert_vals (GArray *farray,
5314 guint index,
5315 @@ -185,6 +308,16 @@
5316 return farray;
5317 }
5318
5319 +/**
5320 + * g_array_set_size:
5321 + * @array: a #GArray.
5322 + * @length: the new size of the #GArray.
5323 + *
5324 + * Sets the size of the array, expanding it if necessary.
5325 + * If the array was created with @clear_ set to %TRUE, the new elements are set to 0.
5326 + *
5327 + * Returns: the #GArray.
5328 + */
5329 GArray*
5330 g_array_set_size (GArray *farray,
5331 guint length)
5332 @@ -207,6 +340,16 @@
5333 return farray;
5334 }
5335
5336 +/**
5337 + * g_array_remove_index:
5338 + * @array: a #GArray.
5339 + * @index_: the index of the element to remove.
5340 + *
5341 + * Removes the element at the given index from a #GArray.
5342 + * The following elements are moved down one place.
5343 + *
5344 + * Returns: the #GArray.
5345 + */
5346 GArray*
5347 g_array_remove_index (GArray* farray,
5348 guint index)
5349 @@ -232,6 +375,19 @@
5350 return farray;
5351 }
5352
5353 +
5354 +/**
5355 + * g_array_remove_index_fast:
5356 + * @array: a @GArray.
5357 + * @index_: the index of the element to remove.
5358 + *
5359 + * Removes the element at the given index from a #GArray.
5360 + * The last element in the array is used to fill in the space, so this function
5361 + * does not preserve the order of the #GArray. But it is faster than
5362 + * g_array_remove_index().
5363 + *
5364 + * Returns: the #GArray.
5365 + */
5366 GArray*
5367 g_array_remove_index_fast (GArray* farray,
5368 guint index)
5369 @@ -257,6 +413,18 @@
5370 return farray;
5371 }
5372
5373 +/**
5374 + * g_array_remove_range:
5375 + * @array: a @GArray.
5376 + * @index_: the index of the first element to remove.
5377 + * @length: the number of elements to remove.
5378 + *
5379 + * Removes the given number of elements starting at the given index from a
5380 + * #GArray. The following elements are moved to close the gap.
5381 + *
5382 + * Since: 2.4
5383 + * Returns: the #GArray.
5384 + */
5385 GArray*
5386 g_array_remove_range (GArray *farray,
5387 guint index_,
5388 @@ -282,6 +450,20 @@
5389 return farray;
5390 }
5391
5392 +
5393 +
5394 +/**
5395 + * g_array_sort:
5396 + * @array: a #GArray.
5397 + * @compare_func: comparison function.
5398 + *
5399 + * Sorts a #GArray using @compare_func which should be a qsort()-style comparison
5400 + * function (returns less than zero for first arg is less than second arg,
5401 + * zero for equal, greater zero if first arg is greater than second arg).
5402 + *
5403 + * If two array elements compare equal, their order in the sorted array is
5404 + * undefined.
5405 + */
5406 void
5407 g_array_sort (GArray *farray,
5408 GCompareFunc compare_func)
5409 @@ -296,6 +478,15 @@
5410 compare_func);
5411 }
5412
5413 +/**
5414 + * g_array_sort_with_data:
5415 + * @array: a #GArray.
5416 + * @compare_func: comparison function.
5417 + * @user_data: data to pass to @compare_func.
5418 + *
5419 + * Like g_array_sort(), but the comparison function receives an extra user data
5420 + * argument.
5421 + */
5422 void
5423 g_array_sort_with_data (GArray *farray,
5424 GCompareDataFunc compare_func,
5425 @@ -345,9 +536,55 @@
5426 }
5427 }
5428
5429 -/* Pointer Array
5430 +/**
5431 + * SECTION:arrays_pointer
5432 + * @Short_description: arrays of pointers to any type of data,
5433 + * which grow automatically as new elements are added
5434 + * @Title: Pointer Arrays
5435 + *
5436 + * Pointer Arrays are similar to Arrays but are used only for storing pointers.
5437 + *
5438 + * <note>
5439 + * If you remove elements from the array, elements at the end of the array
5440 + * are moved into the space previously occupied by the removed element.
5441 + * This means that you should not rely on the index of particular elements
5442 + * remaining the same. You should also be careful when deleting elements while
5443 + * iterating over the array.
5444 + *
5445 + * </note>
5446 + * To create a pointer array, use g_ptr_array_new().
5447 + *
5448 + * To add elements to a pointer array, use g_ptr_array_add().
5449 + *
5450 + * To remove elements from a pointer array, use g_ptr_array_remove(),
5451 + * g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
5452 + *
5453 + * To access an element of a pointer array, use g_ptr_array_index().
5454 + *
5455 + * To set the size of a pointer array, use g_ptr_array_set_size().
5456 + *
5457 + * To free a pointer array, use g_ptr_array_free().
5458 + *
5459 + * <example>
5460 + * <title>Using a <structname>GPtrArray</structname></title>
5461 + * <programlisting>
5462 + * GPtrArray *gparray;
5463 + * gchar *string1 = "one", *string2 = "two", *string3 = "three";
5464 + *
5465 + * gparray = g_ptr_array_new (<!-- -->);
5466 + * g_ptr_array_add (gparray, (gpointer) string1);
5467 + * g_ptr_array_add (gparray, (gpointer) string2);
5468 + * g_ptr_array_add (gparray, (gpointer) string3);
5469 + *
5470 + * if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
5471 + * g_print ("ERROR: got %p instead of %p\n",
5472 + * g_ptr_array_index (gparray, 0), string1);
5473 + *
5474 + * g_ptr_array_free (gparray, TRUE);
5475 + * </programlisting></example>
5476 */
5477
5478 +
5479 typedef struct _GRealPtrArray GRealPtrArray;
5480
5481 struct _GRealPtrArray
5482 @@ -359,13 +596,30 @@
5483
5484 static void g_ptr_array_maybe_expand (GRealPtrArray *array,
5485 gint len);
5486 -
5487 +/**
5488 + * g_ptr_array_new:
5489 + *
5490 + * Creates a new #GPtrArray.
5491 + *
5492 + * Returns: the new #GPtrArray.
5493 + */
5494 GPtrArray*
5495 g_ptr_array_new (void)
5496 {
5497 return g_ptr_array_sized_new (0);
5498 }
5499
5500 +/**
5501 + * g_ptr_array_sized_new:
5502 + * @reserved_size: number of pointers preallocated.
5503 + *
5504 + * Creates a new #GPtrArray with @reserved_size pointers
5505 + * preallocated. This avoids frequent reallocation, if you are going to
5506 + * add many pointers to the array. Note however that the size of the
5507 + * array is still 0.
5508 + *
5509 + * Returns: the new #GPtrArray.
5510 + */
5511 GPtrArray*
5512 g_ptr_array_sized_new (guint reserved_size)
5513 {
5514 @@ -381,6 +635,25 @@
5515 return (GPtrArray*) array;
5516 }
5517
5518 +/**
5519 + * g_ptr_array_free:
5520 + * @array: a #GPtrArray.
5521 + * @free_seg: if %TRUE the actual pointer array is freed as well.
5522 + *
5523 + * Frees the memory allocated for the #GPtrArray.
5524 + * If @free_segment is %TRUE it frees the memory block holding the elements
5525 + * as well. Pass %FALSE if you want to free the #GPtrArray wrapper but preserve
5526 + * the underlying array for use elsewhere.
5527 + *
5528 + * <note>
5529 + * If array contents point to dynamically-allocated memory, they should be freed
5530 + * separately.
5531 + *
5532 + * </note>
5533 + *
5534 + * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL.
5535 + * The pointer array should be freed using g_free().
5536 + */
5537 gpointer*
5538 g_ptr_array_free (GPtrArray *array,
5539 gboolean free_segment)
5540 @@ -418,6 +691,14 @@
5541 }
5542 }
5543
5544 +/**
5545 + * g_ptr_array_set_size:
5546 + * @array: a #GPtrArray.
5547 + * @length: the new length of the pointer array.
5548 + *
5549 + * Sets the size of the array, expanding it if necessary.
5550 + * New elements are set to %NULL.
5551 + */
5552 void
5553 g_ptr_array_set_size (GPtrArray *farray,
5554 gint length)
5555 @@ -449,6 +730,16 @@
5556 array->len = length;
5557 }
5558
5559 +/**
5560 + * g_ptr_array_remove_index:
5561 + * @array: a #GPtrArray.
5562 + * @index_: the index of the pointer to remove.
5563 + *
5564 + * Removes the pointer at the given index from the pointer array.
5565 + * The following elements are moved down one place.
5566 + *
5567 + * Returns: the pointer which was removed.
5568 + */
5569 gpointer
5570 g_ptr_array_remove_index (GPtrArray* farray,
5571 guint index)
5572 @@ -474,6 +765,18 @@
5573 return result;
5574 }
5575
5576 +/**
5577 + * g_ptr_array_remove_index_fast:
5578 + * @array: a #GPtrArray.
5579 + * @index_: the index of the pointer to remove.
5580 + *
5581 + * Removes the pointer at the given index from the pointer array.
5582 + * The last element in the array is used to fill in the space, so this function
5583 + * does not preserve the order of the array. But it is faster than
5584 + * g_ptr_array_remove_index().
5585 + *
5586 + * Returns: the pointer which was removed.
5587 + */
5588 gpointer
5589 g_ptr_array_remove_index_fast (GPtrArray* farray,
5590 guint index)
5591 @@ -498,6 +801,18 @@
5592 return result;
5593 }
5594
5595 +
5596 +/**
5597 + * g_ptr_array_remove_range:
5598 + * @array: a @GPtrArray.
5599 + * @index_: the index of the first pointer to remove.
5600 + * @length: the number of pointers to remove.
5601 + *
5602 + * Removes the given number of pointers starting at the given index from a
5603 + * #GPtrArray. The following elements are moved to close the gap.
5604 + *
5605 + * Since: 2.4
5606 + */
5607 void
5608 g_ptr_array_remove_range (GPtrArray* farray,
5609 guint index_,
5610 @@ -523,6 +838,20 @@
5611 }
5612 }
5613
5614 +/**
5615 + * g_ptr_array_remove:
5616 + * @array: a #GPtrArray.
5617 + * @data: the pointer to remove.
5618 + *
5619 + * Removes the first occurrence of the given pointer from the pointer array.
5620 + * The following elements are moved down one place.
5621 + *
5622 + * It returns %TRUE if the pointer was removed, or %FALSE if the pointer
5623 + * was not found.
5624 + *
5625 + * Returns: %TRUE if the pointer is removed. %FALSE if the pointer is not found
5626 + * in the array.
5627 + */
5628 gboolean
5629 g_ptr_array_remove (GPtrArray* farray,
5630 gpointer data)
5631 @@ -544,6 +873,22 @@
5632 return FALSE;
5633 }
5634
5635 +
5636 +/**
5637 + * g_ptr_array_remove_fast:
5638 + * @array: a #GPtrArray.
5639 + * @data: the pointer to remove.
5640 + *
5641 + * Removes the first occurrence of the given pointer from the pointer array.
5642 + * The last element in the array is used to fill in the space, so this function
5643 + * does not preserve the order of the array. But it is faster than
5644 + * g_ptr_array_remove().
5645 + *
5646 + * It returns %TRUE if the pointer was removed, or %FALSE if the pointer
5647 + * was not found.
5648 + *
5649 + * Returns: %TRUE if the pointer was found in the array.
5650 + */
5651 gboolean
5652 g_ptr_array_remove_fast (GPtrArray* farray,
5653 gpointer data)
5654 @@ -565,6 +910,14 @@
5655 return FALSE;
5656 }
5657
5658 +/**
5659 + * g_ptr_array_add:
5660 + * @array: a #GPtrArray.
5661 + * @data: the pointer to add.
5662 + *
5663 + * Adds a pointer to the end of the pointer array.
5664 + * The array will grow in size automatically if necessary.
5665 + */
5666 void
5667 g_ptr_array_add (GPtrArray* farray,
5668 gpointer data)
5669 @@ -578,6 +931,22 @@
5670 array->pdata[array->len++] = data;
5671 }
5672
5673 +/**
5674 + * g_ptr_array_sort:
5675 + * @array: a #GPtrArray.
5676 + * @compare_func: comparison function.
5677 + *
5678 + * Sorts the array, using @compare_func which should be a qsort()-style comparison
5679 + * function (returns less than zero for first arg is less than second arg,
5680 + * zero for equal, greater than zero if irst arg is greater than second arg).
5681 + *
5682 + * If two array elements compare equal, their order in the sorted array is
5683 + * undefined.
5684 + *
5685 + * The comparison function for g_ptr_array_sort() doesn't take the pointers
5686 + * from the array as arguments, it takes pointers to the pointers in the array.
5687 + * </para></note>
5688 + */
5689 void
5690 g_ptr_array_sort (GPtrArray *array,
5691 GCompareFunc compare_func)
5692 @@ -590,6 +959,21 @@
5693 compare_func);
5694 }
5695
5696 +/**
5697 + * g_ptr_array_sort_with_data:
5698 + * @array: a #GPtrArray.
5699 + * @compare_func: comparison function.
5700 + * @user_data: data to pass to @compare_func.
5701 + *
5702 + * Like g_ptr_array_sort(), but the comparison function has an extra user data
5703 + * argument.
5704 + *
5705 + * The comparison function for g_ptr_array_sort_with_data() doesn't take the
5706 + * pointers from the array as arguments, it takes pointers to the pointers in
5707 + * the array.
5708 + * </para></note>
5709 + */
5710 +
5711 void
5712 g_ptr_array_sort_with_data (GPtrArray *array,
5713 GCompareDataFunc compare_func,
5714 @@ -627,25 +1011,100 @@
5715 (*func) (array->pdata[i], user_data);
5716 }
5717
5718 -/* Byte arrays
5719 +/**
5720 + * SECTION:arrays_byte
5721 + * @Short_description: arrays of bytes, which grow automatically as elements are added
5722 + * @Title: Byte Arrays
5723 + *
5724 + * #GByteArray is based on #GArray, to provide arrays of bytes which grow
5725 + * automatically as elements are added.
5726 + *
5727 + * To create a new #GByteArray use g_byte_array_new().
5728 + *
5729 + * To add elements to a #GByteArray, use g_byte_array_append(), and
5730 + * g_byte_array_prepend().
5731 + *
5732 + * To set the size of a #GByteArray, use g_byte_array_set_size().
5733 + *
5734 + * To free a #GByteArray, use g_byte_array_free().
5735 + *
5736 + *
5737 + * <example>
5738 + * <title>Using a <structname>GByteArray</structname></title>
5739 + * <programlisting>
5740 + * GByteArray *gbarray;
5741 + * gint i;
5742 + *
5743 + * gbarray = g_byte_array_new (<!-- -->);
5744 + * for (i = 0; i < 10000; i++)
5745 + * g_byte_array_append (gbarray, (guint8*) "abcd", 4);
5746 + *
5747 + * for (i = 0; i < 10000; i++)
5748 + * {
5749 + * g_assert (gbarray->data[4*i] == 'a');
5750 + * g_assert (gbarray->data[4*i+1] == 'b');
5751 + * g_assert (gbarray->data[4*i+2] == 'c');
5752 + * g_assert (gbarray->data[4*i+3] == 'd');
5753 + * }
5754 + *
5755 + * g_byte_array_free (gbarray, TRUE);
5756 + * </programlisting></example>
5757 */
5758
5759 +/**
5760 + * g_byte_array_new:
5761 + *
5762 + * Creates a new #GByteArray.
5763 + *
5764 + * Returns: the new #GByteArray.
5765 + */
5766 GByteArray* g_byte_array_new (void)
5767 {
5768 return (GByteArray*) g_array_sized_new (FALSE, FALSE, 1, 0);
5769 }
5770
5771 +/**
5772 + * g_byte_array_sized_new:
5773 + * @reserved_size: number of bytes preallocated.
5774 + *
5775 + * Creates a new #GByteArray with @reserved_size bytes preallocated. This
5776 + * avoids frequent reallocation, if you are going to add many bytes to
5777 + * the array. Note however that the size of the array is still 0.
5778 + *
5779 + * Returns: the new #GByteArray.
5780 + */
5781 GByteArray* g_byte_array_sized_new (guint reserved_size)
5782 {
5783 return (GByteArray*) g_array_sized_new (FALSE, FALSE, 1, reserved_size);
5784 }
5785
5786 +/**
5787 + * g_byte_array_free:
5788 + * @array: a #GByteArray.
5789 + * @free_segment: if %TRUE the actual byte data is freed as well.
5790 + *
5791 + * Frees the memory allocated by the #GByteArray.
5792 + * If @free_segment is %TRUE it frees the actual byte data.
5793 + *
5794 + * Returns: the element data if @free_segment is %FALSE, otherwise %NULL
5795 + */
5796 guint8* g_byte_array_free (GByteArray *array,
5797 gboolean free_segment)
5798 {
5799 return (guint8*) g_array_free ((GArray*) array, free_segment);
5800 }
5801
5802 +/**
5803 + * g_byte_array_append:
5804 + * @array: a #GByteArray.
5805 + * @data: the byte data to be added.
5806 + * @len: the number of bytes to add.
5807 + *
5808 + * Adds the given bytes to the end of the #GByteArray.
5809 + * The array will grow in size automatically if necessary.
5810 + *
5811 + * Returns: the #GByteArray.
5812 + */
5813 GByteArray* g_byte_array_append (GByteArray *array,
5814 const guint8 *data,
5815 guint len)
5816 @@ -655,6 +1114,17 @@
5817 return array;
5818 }
5819
5820 +/**
5821 + * g_byte_array_prepend:
5822 + * @array: a #GByteArray.
5823 + * @data: the byte data to be added.
5824 + * @len: the number of bytes to add.
5825 + *
5826 + * Adds the given data to the start of the #GByteArray.
5827 + * The array will grow in size automatically if necessary.
5828 + *
5829 + * Returns: the #GByteArray.
5830 + */
5831 GByteArray* g_byte_array_prepend (GByteArray *array,
5832 const guint8 *data,
5833 guint len)
5834 @@ -664,6 +1134,15 @@
5835 return array;
5836 }
5837
5838 +/**
5839 + * g_byte_array_set_size:
5840 + * @array: a #GByteArray.
5841 + * @length: the new size of the #GByteArray.
5842 + *
5843 + * Sets the size of the #GByteArray, expanding it if necessary.
5844 + *
5845 + * Returns: the #GByteArray.
5846 + */
5847 GByteArray* g_byte_array_set_size (GByteArray *array,
5848 guint length)
5849 {
5850 @@ -672,6 +1151,16 @@
5851 return array;
5852 }
5853
5854 +/**
5855 + * g_byte_array_remove_index:
5856 + * @array: a #GByteArray.
5857 + * @index_: the index of the byte to remove.
5858 + *
5859 + * Removes the byte at the given index from a #GByteArray.
5860 + * The following bytes are moved down one place.
5861 + *
5862 + * Returns: the #GByteArray.
5863 + */
5864 GByteArray* g_byte_array_remove_index (GByteArray *array,
5865 guint index)
5866 {
5867 @@ -680,6 +1169,18 @@
5868 return array;
5869 }
5870
5871 +/**
5872 + * g_byte_array_remove_index_fast:
5873 + * @array: a #GByteArray.
5874 + * @index_: the index of the byte to remove.
5875 + *
5876 + * Removes the byte at the given index from a #GByteArray.
5877 + * The last element in the array is used to fill in the space, so this function
5878 + * does not preserve the order of the #GByteArray. But it is faster than
5879 + * g_byte_array_remove_index().
5880 + *
5881 + * Returns: the #GByteArray.
5882 + */
5883 GByteArray* g_byte_array_remove_index_fast (GByteArray *array,
5884 guint index)
5885 {
5886 @@ -688,6 +1189,18 @@
5887 return array;
5888 }
5889
5890 +/**
5891 + * g_byte_array_remove_range:
5892 + * @array: a @GByteArray.
5893 + * @index_: the index of the first byte to remove.
5894 + * @length: the number of bytes to remove.
5895 + *
5896 + * Removes the given number of bytes starting at the given index from a
5897 + * #GByteArray. The following elements are moved to close the gap.
5898 + *
5899 + * Since: 2.4
5900 + * Returns: the #GByteArray.
5901 + */
5902 GByteArray*
5903 g_byte_array_remove_range (GByteArray *array,
5904 guint index_,
5905 @@ -700,6 +1213,19 @@
5906 return (GByteArray *)g_array_remove_range ((GArray*) array, index_, length);
5907 }
5908
5909 +/**
5910 + * g_byte_array_sort:
5911 + * @array: a #GByteArray.
5912 + * @compare_func: comparison function.
5913 + *
5914 + * Sorts a byte array, using @compare_func which should be a qsort()-style
5915 + * comparison function (returns less than zero for first arg is less than second
5916 + * arg, zero for equal, greater than zero if first arg is greater than second
5917 + * arg).
5918 + *
5919 + * If two array elements compare equal, their order in the sorted array is
5920 + * undefined.
5921 + */
5922 void
5923 g_byte_array_sort (GByteArray *array,
5924 GCompareFunc compare_func)
5925 @@ -707,6 +1233,15 @@
5926 g_array_sort ((GArray *) array, compare_func);
5927 }
5928
5929 +/**
5930 + * g_byte_array_sort_with_data:
5931 + * @array: a #GByteArray.
5932 + * @compare_func: comparison function.
5933 + * @user_data: data to pass to @compare_func.
5934 + *
5935 + * Like g_byte_array_sort(), but the comparison function takes an extra user data
5936 + * argument.
5937 + */
5938 void
5939 g_byte_array_sort_with_data (GByteArray *array,
5940 GCompareDataFunc compare_func,
5941 Index: glib/garray.h
5942 ===================================================================
5943 --- glib/garray.h (revision 7087)
5944 +++ glib/garray.h (working copy)
5945 @@ -35,8 +35,34 @@
5946
5947 G_BEGIN_DECLS
5948
5949 +/**
5950 + * GArray:
5951 + * @data: a pointer to the element data. The data may be moved as elements are
5952 + * added to the #GArray.
5953 + * @len: the number of elements in the #GArray.
5954 + *
5955 + * Contains the public fields of an <link linkend="glib-arrays">Array</link>.
5956 + */
5957 typedef struct _GArray GArray;
5958 +
5959 +/**
5960 + * GByteArray:
5961 + * @data: a pointer to the element data. The data may be moved as elements are
5962 + * added to the #GByteArray.
5963 + * @len: the number of elements in the #GByteArray.
5964 + *
5965 + * The <structname>GByteArray</structname> struct allows access to the public
5966 + * fields of a <structname>GByteArray</structname>.
5967 + */
5968 typedef struct _GByteArray GByteArray;
5969 +
5970 +/**
5971 + * GPtrArray:
5972 + * @pdata: points to the array of pointers, which may be moved when the array grows.
5973 + * @len: number of pointers in the array.
5974 + *
5975 + * Contains the public fields of a pointer array.
5976 + */
5977 typedef struct _GPtrArray GPtrArray;
5978
5979 struct _GArray
5980 @@ -62,9 +88,88 @@
5981 * order by moving the last element to the position of the removed.
5982 */
5983
5984 +/**
5985 + * g_array_append_val:
5986 + * @a: a #GArray.
5987 + * @v: the value to append to the #GArray.
5988 + *
5989 + * Adds the value on to the end of the array.
5990 + * The array will grow in size automatically if necessary.
5991 + *
5992 + * <note>
5993 + * g_array_append_val() is a macro which uses a reference to the value
5994 + * parameter @v. This means that you cannot use it with literal values
5995 + * such as "27". You must use variables.
5996 + *
5997 + * </note>
5998 + *
5999 + * Returns: the #GArray.
6000 + */
6001 #define g_array_append_val(a,v) g_array_append_vals (a, &(v), 1)
6002 +
6003 +/**
6004 + * g_array_prepend_val:
6005 + * @a: a #GArray.
6006 + * @v: the value to prepend to the #GArray.
6007 + *
6008 + * Adds the value on to the start of the array.
6009 + * The array will grow in size automatically if necessary.
6010 + *
6011 + * This operation is slower than g_array_append_val() since the existing elements
6012 + * in the array have to be moved to make space for the new element.
6013 + *
6014 + * <note>
6015 + * g_array_prepend_val() is a macro which uses a reference to the value
6016 + * parameter @v. This means that you cannot use it with literal values
6017 + * such as "27". You must use variables.
6018 + *
6019 + * </note>
6020 + *
6021 + * Returns: the #GArray.
6022 + */
6023 #define g_array_prepend_val(a,v) g_array_prepend_vals (a, &(v), 1)
6024 +
6025 +/**
6026 + * g_array_insert_val:
6027 + * @a: a #GArray.
6028 + * @i: the index to place the element at.
6029 + * @v: the value to insert into the array.
6030 + *
6031 + * Inserts an element into an array at the given index.
6032 + *
6033 + * <note>
6034 + * g_array_insert_val() is a macro which uses a reference to the value
6035 + * parameter @v. This means that you cannot use it with literal values
6036 + * such as "27". You must use variables.
6037 + *
6038 + * </note>
6039 + *
6040 + * Returns: the #GArray.
6041 + */
6042 #define g_array_insert_val(a,i,v) g_array_insert_vals (a, i, &(v), 1)
6043 +
6044 +/**
6045 + * g_array_index:
6046 + * @a: a #GArray.
6047 + * @t: the type of the elements.
6048 + * @i: the index of the element to return.
6049 + *
6050 + * Returns the element of a #GArray at the given index.
6051 + * The return value is cast to the given type.
6052 + *
6053 + * <example>
6054 + * <title>Getting a pointer to an element in a <structname>GArray</structname></title>
6055 + * <programlisting>
6056 + * EDayViewEvent *event;
6057 + *
6058 + * /<!---->* This gets a pointer to the 4th element in the array of EDayViewEvent
6059 + * structs. *<!---->/
6060 + * event = &g_array_index (events, EDayViewEvent, 3);
6061 + * </programlisting>
6062 + * </example>
6063 + *
6064 + * Returns: the element of the #GArray at the index given by @i.
6065 + */
6066 #define g_array_index(a,t,i) (((t*) (void *) (a)->data) [(i)])
6067
6068 GArray* g_array_new (gboolean zero_terminated,
6069 @@ -105,6 +210,16 @@
6070 * than the above. Add appends a pointer. Remove fills any cleared
6071 * spot and shortens the array. remove_fast will again distort order.
6072 */
6073 +
6074 +/**
6075 + * g_ptr_array_index:
6076 + * @array: a #GPtrArray.
6077 + * @index_: the index of the pointer to return.
6078 + *
6079 + * Returns the pointer at the given index of the pointer array.
6080 + *
6081 + * Returns: the pointer at the given index.
6082 + */
6083 #define g_ptr_array_index(array,index_) ((array)->pdata)[index_]
6084 GPtrArray* g_ptr_array_new (void);
6085 GPtrArray* g_ptr_array_sized_new (guint reserved_size);
6086 Index: glib/gkeyfile.c
6087 ===================================================================
6088 --- glib/gkeyfile.c (revision 7087)
6089 +++ glib/gkeyfile.c (working copy)
6090 @@ -62,6 +62,102 @@
6091
6092 #include "galias.h"
6093
6094 +/**
6095 + * SECTION:keyfile
6096 + * @Short_description: parses <filename>.ini</filename>-like config files
6097 + * @Title: Key-value file parser
6098 + *
6099 + * #GKeyFile lets you parse, edit or create files containing groups of
6100 + * key-value pairs, which we call <firstterm>key files</firstterm> for
6101 + * lack of a better name. Several freedesktop.org specifications use
6102 + * key files now, e.g the
6103 + * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
6104 + * Entry Specification</ulink> and the
6105 + * <ulink url="http://freedesktop.org/Standards/icon-theme-spec">Icon
6106 + * Theme Specification</ulink>.
6107 + *
6108 + *
6109 + * The syntax of key files is described in detail in the
6110 + * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
6111 + * Entry Specification</ulink>, here is a quick summary: Key files
6112 + * consists of groups of key-value pairs, interspersed with comments.
6113 + *
6114 + *
6115 + * <informalexample><programlisting>
6116 + * # this is just an example
6117 + * # there can be comments before the first group
6118 + *
6119 + * [First Group]
6120 + *
6121 + * Name=Key File Example\tthis value shows\nescaping
6122 + *
6123 + * # localized strings are stored in multiple key-value pairs
6124 + * Welcome=Hello
6125 + * Welcome[de]=Hallo
6126 + * Welcome[fr]=Bonjour
6127 + * Welcome[it]=Ciao
6128 + *
6129 + * [Another Group]
6130 + *
6131 + * Numbers=2;20;-200;0
6132 + *
6133 + * Booleans=true;false;true;true
6134 + *
6135 + * </programlisting></informalexample>
6136 + *
6137 + * Lines beginning with a '#' and blank lines are considered comments.
6138 + *
6139 + *
6140 + * Groups are started by a header line containing the group name enclosed
6141 + * in '[' and ']', and ended implicitly by the start of the next group or
6142 + * the end of the file. Each key-value pair must be contained in a group.
6143 + *
6144 + *
6145 + * Key-value pairs generally have the form <literal>key=value</literal>,
6146 + * with the exception of localized strings, which have the form
6147 + * <literal>key[locale]=value</literal>. Space before and after the
6148 + * '=' character are ignored. Newline, tab, carriage return and backslash
6149 + * characters in value are escaped as \n, \t, \r, and \\, respectively.
6150 + * To preserve leading spaces in values, these can also be escaped as \s.
6151 + *
6152 + *
6153 + * Key files can store strings (possibly with localized variants), integers,
6154 + * booleans and lists of these. Lists are separated by a separator character,
6155 + * typically ';' or ','. To use the list separator character in a value in
6156 + * a list, it has to be escaped by prefixing it with a backslash.
6157 + *
6158 + *
6159 + * This syntax is obviously inspired by the <filename>.ini</filename>
6160 + * files commonly met on Windows, but there are some important differences:
6161 + * <itemizedlist>
6162 + * <filename>.ini</filename> files use the ';' character to begin comments,
6163 + * key files use the '#' character.
6164 + * </para></listitem>
6165 + * Key files do not allow for ungrouped keys meaning only comments can
6166 + * precede the first group.
6167 + * </para></listitem>
6168 + * Key files are always encoded in UTF-8.
6169 + * </para></listitem>
6170 + * Key and Group names are case-sensitive, for example a group called
6171 + * <literal>[GROUP]</literal> is a different group from <literal>[group]</literal>.
6172 + * </para></listitem>
6173 + * <filename>.ini</filename> files don't have a strongly typed boolean
6174 + * entry type, they only have <literal>GetProfileInt</literal>.
6175 + * In <structname>GKeyFile</structname> only <literal>true</literal>
6176 + * and <literal>false</literal> (in lower case) are allowed.
6177 + * </para></listitem>
6178 + * </itemizedlist>
6179 + *
6180 + *
6181 + * Note that in contrast to the
6182 + * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
6183 + * Entry Specification</ulink>, groups in key files may contain the same
6184 + * key multiple times; the last entry wins. Key files may also contain
6185 + * multiple groups with the same name; they are merged together.
6186 + * Another difference is that keys and group names in key files are not
6187 + * restricted to ASCII characters.
6188 + */
6189 +
6190 typedef struct _GKeyFileGroup GKeyFileGroup;
6191
6192 struct _GKeyFile
6193 Index: glib/gmacros.h
6194 ===================================================================
6195 --- glib/gmacros.h (revision 7087)
6196 +++ glib/gmacros.h (working copy)
6197 @@ -39,6 +39,75 @@
6198 */
6199 #include <stddef.h>
6200
6201 +/**
6202 + * SECTION:macros
6203 + * @Short_description: commonly-used macros.
6204 + * @Title: Standard Macros
6205 + *
6206 + * These macros provide a few commonly-used features.
6207 + */
6208 +
6209 +/**
6210 + * SECTION:macros_misc
6211 + * @Short_description: specialized macros which are not used often
6212 + * @Title: Miscellaneous Macros
6213 + *
6214 + * These macros provide more specialized features which are not needed so often
6215 + * by application programmers.
6216 + */
6217 +
6218 +/* These are GLib compile-time defined values. They are actually
6219 + * defined in glibconfig.h, however, that file is generated at
6220 + * compile time.
6221 + */
6222 +/**
6223 + * G_OS_BEOS:
6224 + *
6225 + * This macro is defined only on BeOS. So you can bracket
6226 + * BeOS-specific code in "#ifdef G_OS_BEOS".
6227 + */
6228 +/**
6229 + * G_OS_UNIX:
6230 + *
6231 + * This macro is defined only on UNIX. So you can bracket
6232 + * UNIX-specific code in "#ifdef G_OS_UNIX".
6233 + */
6234 +/**
6235 + * G_OS_WIN32:
6236 + *
6237 + * This macro is defined only on Windows. So you can bracket
6238 + * Windows-specific code in "#ifdef G_OS_WIN32".
6239 + */
6240 +
6241 +
6242 +/**
6243 + * G_GNUC_INTERNAL:
6244 + *
6245 + * This attribute can be used for marking library functions as being used
6246 + * internally to the library only, which may allow the compiler to handle
6247 + * function calls more efficiently.
6248 + * Note that static functions do not need to be marked as internal in this way.
6249 + * See the GNU C documentation for details.
6250 + *
6251 + * When using a compiler that supports the GNU C hidden visibility attribute,
6252 + * this macro expands to <literal>__attribute__((visibility("hidden")))</literal>.
6253 + * When using the Sun Studio compiler, it expands to <literal>__hidden</literal>.
6254 + *
6255 + * Note that for portability, the attribute should be placed before the
6256 + * function declaration. While GCC allows the macro after the declaration,
6257 + * Sun Studio does not.
6258 + *
6259 + * <informalexample><programlisting>
6260 + * G_GNUC_INTERNAL
6261 + * void _g_log_fallback_handler (const gchar *log_domain,
6262 + * GLogLevelFlags log_level,
6263 + * const gchar *message,
6264 + * gpointer unused_data);
6265 + * </programlisting></informalexample>
6266 + *
6267 + * Since: 2.6
6268 + */
6269 +
6270 /* Here we provide G_GNUC_EXTENSION as an alias for __extension__,
6271 * where this is valid. This allows for warningless compilation of
6272 * "long long" types even in the presence of '-ansi -pedantic'.
6273 @@ -51,22 +120,68 @@
6274
6275 /* Provide macros to feature the GCC function attribute.
6276 */
6277 +
6278 #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96)
6279 #define G_GNUC_PURE \
6280 __attribute__((__pure__))
6281 #define G_GNUC_MALLOC \
6282 __attribute__((__malloc__))
6283 #else
6284 +/**
6285 + * G_GNUC_PURE:
6286 + *
6287 + * Expands to the GNU C <literal>pure</literal> function attribute if the compiler is
6288 + * <command>gcc</command>. Declaring a function as pure enables better optimization of
6289 + * calls to the function. A pure function has no effects except its return value and the
6290 + * return value depends only on the parameters and/or global variables.
6291 + * See the GNU C documentation for details.
6292 + */
6293 #define G_GNUC_PURE
6294 +/**
6295 + * G_GNUC_MALLOC:
6296 + *
6297 + * Expands to the GNU C <literal>malloc</literal> function attribute if the
6298 + * compiler is <command>gcc</command>. Declaring a function as malloc enables
6299 + * better optimization of the function. A function can have the malloc attribute
6300 + * if it returns a pointer which is guaranteed to not alias with any other pointer
6301 + * when the function returns (in practice, this means newly allocated memory).
6302 + * See the GNU C documentation for details.
6303 + *
6304 + * Since: 2.6
6305 + */
6306 #define G_GNUC_MALLOC
6307 #endif
6308
6309 +/**
6310 + * G_GNUC_NULL_TERMINATED:
6311 + *
6312 + * Expands to the GNU C <literal>sentinel</literal> function attribute if the
6313 + * compiler is <command>gcc</command>, or "" if it isn't. This function attribute
6314 + * only applies to variadic functions and instructs the compiler to check that
6315 + * the argument list is terminated with an explicit %NULL.
6316 + * See the GNU C documentation for details.
6317 + *
6318 + *
6319 + * Since: 2.8
6320 + */
6321 #if __GNUC__ >= 4
6322 #define G_GNUC_NULL_TERMINATED __attribute__((__sentinel__))
6323 #else
6324 #define G_GNUC_NULL_TERMINATED
6325 #endif
6326
6327 +/**
6328 + * G_GNUC_ALLOC_SIZE:
6329 + * @x: the index of the argument specifying the allocation size
6330 + *
6331 + * Expands to the GNU C <literal>alloc_size</literal> function attribute if the
6332 + * compiler is a new enough <command>gcc</command>. This attribute tells the
6333 + * compiler that the function returns a pointer to memory of a size that is
6334 + * specified by the @x<!-- -->th function parameter.
6335 + * See the GNU C documentation for details.
6336 + *
6337 + * Since: 2.18
6338 + */
6339 #if (__GNUC__ > 4) || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)
6340 #define G_GNUC_ALLOC_SIZE(x) __attribute__((__alloc_size__(x)))
6341 #define G_GNUC_ALLOC_SIZE2(x,y) __attribute__((__alloc_size__(x,y)))
6342 @@ -75,6 +190,42 @@
6343 #define G_GNUC_ALLOC_SIZE2(x,y)
6344 #endif
6345
6346 +/**
6347 + * G_GNUC_PRINTF:
6348 + * @format_idx: the index of the argument corresponding to the format string.
6349 + * (The arguments are numbered from 1).
6350 + * @arg_idx: the index of the first of the format arguments.
6351 + *
6352 + * Expands to the GNU C <literal>format</literal> function attribute if the compiler is
6353 + * <command>gcc</command>. This is used for declaring functions which take a variable number of
6354 + * arguments, with the same syntax as printf().
6355 + * It allows the compiler to type-check the arguments passed to the function.
6356 + * See the GNU C documentation for details.
6357 + *
6358 + * <informalexample><programlisting>
6359 + * gint g_snprintf (gchar *string,
6360 + * gulong n,
6361 + * gchar const *format,
6362 + * ...) G_GNUC_PRINTF (3, 4);
6363 + * </programlisting></informalexample>
6364 + */
6365 +
6366 +/**
6367 + * G_GNUC_FORMAT:
6368 + * @arg_idx: the index of the argument.
6369 + *
6370 + * Expands to the GNU C %format_arg function attribute if the compiler is <command>gcc</command>.
6371 + * This function attribute specifies that a function takes a format
6372 + * string for a printf(), scanf(), strftime() or strfmon() style function and
6373 + * modifies it, so that the result can be passed to a printf(), scanf(),
6374 + * strftime() or strfmon() style function (with the remaining arguments to the
6375 + * format function the same as they would have been for the unmodified
6376 + * string). See the GNU C documentation for details.
6377 + *
6378 + * <informalexample><programlisting>
6379 + * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
6380 + * </programlisting></informalexample>
6381 + */
6382 #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 4)
6383 #define G_GNUC_PRINTF( format_idx, arg_idx ) \
6384 __attribute__((__format__ (__printf__, format_idx, arg_idx)))
6385 @@ -100,6 +251,18 @@
6386 #define G_GNUC_NO_INSTRUMENT
6387 #endif /* !__GNUC__ */
6388
6389 +/**
6390 + * G_GNUC_DEPRECATED:
6391 + *
6392 + * Expands to the GNU C <literal>deprecated</literal> attribute if the compiler
6393 + * is <command>gcc</command>.
6394 + * It can be used to mark typedefs, variables and functions as deprecated.
6395 + * When called with the <option>-Wdeprecated</option> option, the compiler will
6396 + * generate warnings when deprecated interfaces are used.
6397 + * See the GNU C documentation for details.
6398 + *
6399 + * Since: 2.2
6400 + */
6401 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1)
6402 #define G_GNUC_DEPRECATED \
6403 __attribute__((__deprecated__))
6404 @@ -167,6 +330,11 @@
6405 * been defined. It is assumed that if they are already
6406 * defined then the current definition is correct.
6407 */
6408 +/**
6409 + * NULL:
6410 + *
6411 + * Defines the standard %NULL pointer.
6412 + */
6413 #ifndef NULL
6414 # ifdef __cplusplus
6415 # define NULL (0L)
6416 @@ -175,29 +343,91 @@
6417 # endif /* !__cplusplus */
6418 #endif
6419
6420 +/**
6421 + * FALSE:
6422 + *
6423 + * Defines the %FALSE value for the #gboolean type.
6424 + */
6425 #ifndef FALSE
6426 #define FALSE (0)
6427 #endif
6428
6429 +/**
6430 + * TRUE:
6431 + *
6432 + * Defines the %TRUE value for the #gboolean type.
6433 + */
6434 #ifndef TRUE
6435 #define TRUE (!FALSE)
6436 #endif
6437
6438 +/**
6439 + * MAX:
6440 + * @a: a numeric value.
6441 + * @b: a numeric value.
6442 + *
6443 + * Calculates the maximum of @a and @b.
6444 + *
6445 + * Returns: the maximum of @a and @b.
6446 + */
6447 #undef MAX
6448 #define MAX(a, b) (((a) > (b)) ? (a) : (b))
6449
6450 +/**
6451 + * MIN:
6452 + * @a: a numeric value.
6453 + * @b: a numeric value.
6454 + *
6455 + * Calculates the minimum of @a and @b.
6456 + *
6457 + * Returns: the minimum of @a and @b.
6458 + */
6459 #undef MIN
6460 #define MIN(a, b) (((a) < (b)) ? (a) : (b))
6461
6462 +/**
6463 + * ABS:
6464 + * @a: a numeric value.
6465 + *
6466 + * Calculates the absolute value of @a.
6467 + * The absolute value is simply the number with any negative sign taken away.
6468 + *
6469 + * For example,
6470 + * ABS(-10) is 10.
6471 + * ABS(10) is also 10.
6472 + *
6473 + * Returns: the absolute value of @a.
6474 + */
6475 #undef ABS
6476 #define ABS(a) (((a) < 0) ? -(a) : (a))
6477
6478 +/**
6479 + * CLAMP:
6480 + * @x: the value to clamp.
6481 + * @low: the minimum value allowed.
6482 + * @high: the maximum value allowed.
6483 + *
6484 + * Ensures that @x is between the limits set by @low and @high. If @low is
6485 + * greater than @high the result is undefined.
6486 + *
6487 + * For example,
6488 + * CLAMP(5, 10, 15) is 10.
6489 + * CLAMP(15, 5, 10) is 10.
6490 + * CLAMP(20, 15, 25) is 20.
6491 + *
6492 + * Returns: the value of @x clamped to the range between @low and @high.
6493 + */
6494 #undef CLAMP
6495 #define CLAMP(x, low, high) (((x) > (high)) ? (high) : (((x) < (low)) ? (low) : (x)))
6496
6497 -/* Count the number of elements in an array. The array must be defined
6498 - * as such; using this with a dynamically allocated array will give
6499 - * incorrect results.
6500 +/**
6501 + * G_N_ELEMENTS:
6502 + * @arr: the array
6503 + *
6504 + * Determines the number of elements in an array. The array must be
6505 + * declared so the compiler knows its size at compile-time; this
6506 + * macro will not work on an array allocated on the heap, only static
6507 + * arrays or arrays on the stack.
6508 */
6509 #define G_N_ELEMENTS(arr) (sizeof (arr) / sizeof ((arr)[0]))
6510
6511 @@ -209,7 +439,15 @@
6512 /* Provide convenience macros for handling structure
6513 * fields through their offsets.
6514 */
6515 -
6516 +/**
6517 + * G_STRUCT_OFFSET:
6518 + * @struct_type: a structure type, e.g. <structname>GtkWidget</structname>.
6519 + * @member: a field in the structure, e.g. <structfield>window</structfield>.
6520 + *
6521 + * Returns the offset, in bytes, of a member of a struct.
6522 + *
6523 + * Returns: the offset of @member from the start of @struct_type.
6524 + */
6525 #if defined(__GNUC__) && __GNUC__ >= 4
6526 # define G_STRUCT_OFFSET(struct_type, member) \
6527 ((glong) __builtin_offsetof (struct_type, member))
6528 @@ -218,8 +456,28 @@
6529 ((glong) ((guint8*) &((struct_type*) 0)->member))
6530 #endif
6531
6532 +/**
6533 + * G_STRUCT_MEMBER_P:
6534 + * @struct_p: a pointer to a struct.
6535 + * @struct_offset: the offset from the start of the struct, in bytes.
6536 + *
6537 + * Returns an untyped pointer to a given offset of a struct.
6538 + *
6539 + * Returns: an untyped pointer to @struct_p plus @struct_offset bytes.
6540 + */
6541 #define G_STRUCT_MEMBER_P(struct_p, struct_offset) \
6542 ((gpointer) ((guint8*) (struct_p) + (glong) (struct_offset)))
6543 +
6544 +/**
6545 + * G_STRUCT_MEMBER:
6546 + * @member_type: the type of the struct field.
6547 + * @struct_p: a pointer to a struct.
6548 + * @struct_offset: the offset of the field from the start of the struct, in bytes.
6549 + *
6550 + * Returns a member of a structure at a given offset, using the given type.
6551 + *
6552 + * Returns: the struct member.
6553 + */
6554 #define G_STRUCT_MEMBER(member_type, struct_p, struct_offset) \
6555 (*(member_type*) G_STRUCT_MEMBER_P ((struct_p), (struct_offset)))
6556
6557 @@ -239,6 +497,19 @@
6558 * (usually char*) are const or not. Don't try using this feature for
6559 * functions with C++ linkage.
6560 */
6561 +/**
6562 + * G_CONST_RETURN:
6563 + *
6564 + * If %G_DISABLE_CONST_RETURNS is defined, this macro expands to nothing.
6565 + * By default, the macro expands to <literal>const</literal>. The macro
6566 + * should be used in place of <literal>const</literal> for functions that
6567 + * return a value that should not be modified. The purpose of this macro is
6568 + * to allow us to turn on <literal>const</literal> for returned constant
6569 + * strings by default, while allowing programmers who find that annoying to
6570 + * turn it off. This macro should only be used for return values and for
6571 + * <emphasis>out</emphasis> parameters, it doesn't make sense for
6572 + * <emphasis>in</emphasis> parameters.
6573 + */
6574 #ifdef G_DISABLE_CONST_RETURNS
6575 #define G_CONST_RETURN
6576 #else
6577 Index: glib/gkeyfile.h
6578 ===================================================================
6579 --- glib/gkeyfile.h (revision 7087)
6580 +++ glib/gkeyfile.h (working copy)
6581 @@ -31,6 +31,17 @@
6582
6583 G_BEGIN_DECLS
6584
6585 +/**
6586 + * GKeyFileError:
6587 + * @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding
6588 + * @G_KEY_FILE_ERROR_PARSE: document was ill-formed
6589 + * @G_KEY_FILE_ERROR_NOT_FOUND: the file was not found
6590 + * @G_KEY_FILE_ERROR_KEY_NOT_FOUND: a requested key was not found
6591 + * @G_KEY_FILE_ERROR_GROUP_NOT_FOUND: a requested group was not found
6592 + * @G_KEY_FILE_ERROR_INVALID_VALUE: a value could not be parsed
6593 + *
6594 + * Error codes returned by key file parsing.
6595 + */
6596 typedef enum
6597 {
6598 G_KEY_FILE_ERROR_UNKNOWN_ENCODING,
6599 @@ -41,12 +52,38 @@
6600 G_KEY_FILE_ERROR_INVALID_VALUE
6601 } GKeyFileError;
6602
6603 +
6604 +/**
6605 + * G_KEY_FILE_ERROR:
6606 + *
6607 + * Error domain for key file parsing. Errors in this domain will
6608 + * be from the #GKeyFileError enumeration. See #GError for information on
6609 + * error domains.
6610 + */
6611 #define G_KEY_FILE_ERROR g_key_file_error_quark()
6612
6613 GQuark g_key_file_error_quark (void);
6614
6615 +/**
6616 + * GKeyFile:
6617 + *
6618 + * The <structname>GKeyFile</structname> struct contains only private fields
6619 + * and should not be used directly.
6620 + */
6621 typedef struct _GKeyFile GKeyFile;
6622
6623 +/**
6624 + * GKeyFileFlags:
6625 + * @G_KEY_FILE_NONE: No flags, default behaviour
6626 + * @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the (possibly modified)
6627 + * contents of the key file back to a file; otherwise all comments will be lost when
6628 + * the key file is written back.
6629 + * @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the (possibly modified)
6630 + * contents of the key file back to a file; otherwise only the translations for the current
6631 + * language will be written back.
6632 + *
6633 + * Flags which influence the parsing.
6634 + */
6635 typedef enum
6636 {
6637 G_KEY_FILE_NONE = 0,
6638 @@ -219,30 +256,290 @@
6639 GError **error);
6640
6641 /* Defines for handling freedesktop.org Desktop files */
6642 +
6643 +/**
6644 + * G_KEY_FILE_DESKTOP_GROUP:
6645 + *
6646 + * The name of the main group of a desktop entry file, as defined in the
6647 + * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
6648 + * Entry Specification</ulink>. Consult the specification for more
6649 + * details about the meanings of the keys below.
6650 + *
6651 + * Since: 2.14
6652 + */
6653 #define G_KEY_FILE_DESKTOP_GROUP "Desktop Entry"
6654
6655 +
6656 +/**
6657 + * G_KEY_FILE_DESKTOP_KEY_TYPE:
6658 + *
6659 + * A key under <link
6660 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6661 + * whose value is a string giving the type of the desktop entry. Usually
6662 + * <link linkend="G-KEY-FILE-DESKTOP-TYPE-APPLICATION:CAPS"><literal>G_KEY_FILE_DESKTOP_TYPE_APPLICATION</literal></link>,
6663 + * <link linkend="G-KEY-FILE-DESKTOP-TYPE-LINK:CAPS"><literal>G_KEY_FILE_DESKTOP_TYPE_LINK</literal></link>, or
6664 + * <link linkend="G-KEY-FILE-DESKTOP-TYPE-DIRECTORY:CAPS"><literal>G_KEY_FILE_DESKTOP_TYPE_DIRECTORY</literal></link>.
6665 + *
6666 + * Since: 2.14
6667 + */
6668 #define G_KEY_FILE_DESKTOP_KEY_TYPE "Type"
6669 +
6670 +/**
6671 + * G_KEY_FILE_DESKTOP_KEY_VERSION:
6672 + *
6673 + * A key under <link
6674 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6675 + * whose value is a string giving the version of the Desktop
6676 + * Entry Specification used for the desktop entry file.
6677 + *
6678 + * Since: 2.14
6679 + */
6680 #define G_KEY_FILE_DESKTOP_KEY_VERSION "Version"
6681 +
6682 +/**
6683 + * G_KEY_FILE_DESKTOP_KEY_NAME:
6684 + *
6685 + * A key under <link
6686 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6687 + * whose value is a localized string giving the specific name of the
6688 + * desktop entry.
6689 + *
6690 + * Since: 2.14
6691 + */
6692 #define G_KEY_FILE_DESKTOP_KEY_NAME "Name"
6693 +
6694 +/**
6695 + * G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME:
6696 + *
6697 + * A key under <link
6698 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6699 + * whose value is a localized string giving the generic name of the
6700 + * desktop entry.
6701 + *
6702 + * Since: 2.14
6703 + */
6704 #define G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME "GenericName"
6705 +
6706 +
6707 +/**
6708 + * G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY:
6709 + *
6710 + * A key under <link
6711 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6712 + * whose value is a boolean stating whether the desktop entry should be
6713 + * shown in menus.
6714 + *
6715 + * Since: 2.14
6716 + */
6717 #define G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY "NoDisplay"
6718 +
6719 +/**
6720 + * G_KEY_FILE_DESKTOP_KEY_COMMENT:
6721 + *
6722 + * A key under <link
6723 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6724 + * whose value is a localized string giving the tooltip for the desktop
6725 + * entry.
6726 + *
6727 + * Since: 2.14
6728 + */
6729 #define G_KEY_FILE_DESKTOP_KEY_COMMENT "Comment"
6730 +
6731 +/**
6732 + * G_KEY_FILE_DESKTOP_KEY_ICON:
6733 + *
6734 + * A key under <link
6735 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6736 + * whose value is a localized string giving the name of the icon to be
6737 + * displayed for the desktop entry.
6738 + *
6739 + * Since: 2.14
6740 + */
6741 #define G_KEY_FILE_DESKTOP_KEY_ICON "Icon"
6742 +
6743 +/**
6744 + * G_KEY_FILE_DESKTOP_KEY_HIDDEN:
6745 + *
6746 + * A key under <link
6747 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6748 + * whose value is a boolean stating whether the desktop entry has been
6749 + * deleted by the user.
6750 + *
6751 + * Since: 2.14
6752 + */
6753 #define G_KEY_FILE_DESKTOP_KEY_HIDDEN "Hidden"
6754 +
6755 +/**
6756 + * G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN:
6757 + *
6758 + * A key under <link
6759 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6760 + * whose value is a list of strings identifying the environments that
6761 + * should display the desktop entry.
6762 + *
6763 + * Since: 2.14
6764 + */
6765 #define G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN "OnlyShowIn"
6766 +
6767 +/**
6768 + * G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN:
6769 + *
6770 + * A key under <link
6771 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6772 + * whose value is a list of strings identifying the environments that
6773 + * should not display the desktop entry.
6774 + *
6775 + * Since: 2.14
6776 + */
6777 #define G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN "NotShowIn"
6778 +
6779 +/**
6780 + * G_KEY_FILE_DESKTOP_KEY_TRY_EXEC:
6781 + *
6782 + * A key under <link
6783 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6784 + * whose value is a string giving the file name of a binary on disk
6785 + * used to determine if the program is actually installed. It is only
6786 + * valid for desktop entries with the <literal>Application</literal>
6787 + * type.
6788 + *
6789 + * Since: 2.14
6790 + */
6791 #define G_KEY_FILE_DESKTOP_KEY_TRY_EXEC "TryExec"
6792 +
6793 +/**
6794 + * G_KEY_FILE_DESKTOP_KEY_EXEC:
6795 + *
6796 + * A key under <link
6797 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6798 + * whose value is a string giving the command line to execute. It is only
6799 + * valid for desktop entries with the <literal>Application</literal>
6800 + * type.
6801 + *
6802 + * Since: 2.14
6803 + */
6804 #define G_KEY_FILE_DESKTOP_KEY_EXEC "Exec"
6805 +
6806 +/**
6807 + * G_KEY_FILE_DESKTOP_KEY_PATH:
6808 + *
6809 + * A key under <link
6810 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6811 + * whose value is a string containing the working directory to run the
6812 + * program in. It is only valid for desktop entries with the
6813 + * <literal>Application</literal> type.
6814 + *
6815 + * Since: 2.14
6816 + */
6817 #define G_KEY_FILE_DESKTOP_KEY_PATH "Path"
6818 +
6819 +/**
6820 + * G_KEY_FILE_DESKTOP_KEY_TERMINAL:
6821 + *
6822 + * A key under <link
6823 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6824 + * whose value is a boolean stating whether the program should be
6825 + * run in a terminal window. It is only valid for desktop entries with
6826 + * the <literal>Application</literal> type.
6827 + *
6828 + * Since: 2.14
6829 + */
6830 #define G_KEY_FILE_DESKTOP_KEY_TERMINAL "Terminal"
6831 +
6832 +/**
6833 + * G_KEY_FILE_DESKTOP_KEY_MIME_TYPE:
6834 + *
6835 + * A key under <link
6836 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6837 + * whose value is a list of strings giving the MIME types supported
6838 + * by this desktop entry.
6839 + *
6840 + * Since: 2.14
6841 + */
6842 #define G_KEY_FILE_DESKTOP_KEY_MIME_TYPE "MimeType"
6843 +
6844 +/**
6845 + * G_KEY_FILE_DESKTOP_KEY_CATEGORIES:
6846 + *
6847 + * A key under <link
6848 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6849 + * whose value is a list of strings giving the categories in which the
6850 + * desktop entry should be shown in a menu.
6851 + *
6852 + * Since: 2.14
6853 + */
6854 #define G_KEY_FILE_DESKTOP_KEY_CATEGORIES "Categories"
6855 +
6856 +/**
6857 + * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY:
6858 + *
6859 + * A key under <link
6860 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6861 + * whose value is a boolean stating whether the application supports
6862 + * the <ulink
6863 + * url="http://www.freedesktop.org/Standards/startup-notification-spec">Startup
6864 + * Notification Protocol Specification</ulink>.
6865 + *
6866 + * Since: 2.14
6867 + */
6868 #define G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY "StartupNotify"
6869 +
6870 +/**
6871 + * G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS:
6872 + *
6873 + * A key under <link
6874 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6875 + * whose value is string identifying the WM class or name hint of a
6876 + * window that the application will create, which can be used to emulate
6877 + * Startup Notification with older applications.
6878 + *
6879 + * Since: 2.14
6880 + */
6881 #define G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS "StartupWMClass"
6882 +
6883 +/**
6884 + * G_KEY_FILE_DESKTOP_KEY_URL:
6885 + *
6886 + * A key under <link
6887 + * linkend="G-KEY-FILE-DESKTOP-GROUP:CAPS"><literal>G_KEY_FILE_DESKTOP_GROUP</literal></link>
6888 + * whose value is a string giving the URL to access. It is only valid
6889 + * for desktop entries with the <literal>Link</literal> type.
6890 + *
6891 + * Since: 2.14
6892 + */
6893 #define G_KEY_FILE_DESKTOP_KEY_URL "URL"
6894
6895 +/**
6896 + * G_KEY_FILE_DESKTOP_TYPE_APPLICATION:
6897 + *
6898 + * The value of the <link
6899 + * linkend="G-KEY-FILE-DESKTOP-KEY-TYPE:CAPS"><literal>G_KEY_FILE_DESKTOP_KEY_TYPE</literal></link>
6900 + * key for desktop entries representing applications.
6901 + *
6902 + * Since: 2.14
6903 + */
6904 #define G_KEY_FILE_DESKTOP_TYPE_APPLICATION "Application"
6905 +
6906 +/**
6907 + * G_KEY_FILE_DESKTOP_TYPE_LINK:
6908 + *
6909 + * The value of the <link
6910 + * linkend="G-KEY-FILE-DESKTOP-KEY-TYPE:CAPS"><literal>G_KEY_FILE_DESKTOP_KEY_TYPE</literal></link>
6911 + * key for desktop entries representing links to documents.
6912 + *
6913 + * Since: 2.14
6914 + */
6915 #define G_KEY_FILE_DESKTOP_TYPE_LINK "Link"
6916 +
6917 +/**
6918 + * G_KEY_FILE_DESKTOP_TYPE_DIRECTORY:
6919 + *
6920 + * The value of the <link
6921 + * linkend="G-KEY-FILE-DESKTOP-KEY-TYPE:CAPS"><literal>G_KEY_FILE_DESKTOP_KEY_TYPE</literal></link>
6922 + * key for desktop entries representing directories.
6923 + *
6924 + * Since: 2.14
6925 + */
6926 #define G_KEY_FILE_DESKTOP_TYPE_DIRECTORY "Directory"
6927
6928 G_END_DECLS
6929 Index: glib/gbookmarkfile.c
6930 ===================================================================
6931 --- glib/gbookmarkfile.c (revision 7087)
6932 +++ glib/gbookmarkfile.c (working copy)
6933 @@ -57,6 +57,82 @@
6934
6935 #include "galias.h"
6936
6937 +/**
6938 + * SECTION:bookmarkfile
6939 + * @Short_description: parses files containing bookmarks
6940 + * @Title: Bookmark file parser
6941 + *
6942 + * #GBookmarkFile lets you parse, edit or create files containing bookmarks
6943 + * to URI, along with some meta-data about the resource pointed by the URI like
6944 + * its MIME type, the application that is registering the bookmark and the
6945 + * icon that should be used to represent the bookmark. The data is stored using
6946 + * the
6947 + * <ulink url="http://www.gnome.org/~ebassi/bookmark-spec">Desktop Bookmark
6948 + * Specification</ulink>.
6949 + *
6950 + *
6951 + * The syntax of the bookmark files is described in detail inside the Desktop
6952 + * Bookmark Specification, here is a quick summary: bookmark files use a sub-class
6953 + * of the
6954 + * <ulink url="">XML Bookmark Exchange Language</ulink> specification, consisting
6955 + * of valid UTF-8 encoded XML, under the <literal>xbel</literal> root element;
6956 + * each bookmark is stored inside a <literal>bookmark</literal> element, using
6957 + * its URI: no relative paths can be used inside a bookmark file. The bookmark
6958 + * may have a user defined title and description, to be used instead of the URI.
6959 + * Under the <literal>metadata</literal> element, with its <literal>owner</literal>
6960 + * attribute set to <literal>http://freedesktop.org</literal>, is stored the
6961 + * meta-data about a resource pointed by its URI. The meta-data consists of
6962 + * the resource's MIME type; the applications that have registered a bookmark;
6963 + * the groups to which a bookmark belongs to; a visibility flag, used to set
6964 + * the bookmark as "private" to the applications and groups that has it
6965 + * registered; the URI and MIME type of an icon, to be used when displaying the
6966 + * bookmark inside a GUI.
6967 + *
6968 + *
6969 + * <informalexample><programlisting>
6970 + * <![CDATA[
6971 + * <?xml version="1.0"?>
6972 + * <!DOCTYPE xbel PUBLIC
6973 + * "+//IDN python.org//DTD XML Bookmark Exchange Language 1.0//EN//XML"
6974 + * "http://www.python.org/topics/xml/dtds/xbel-1.0.dtd">
6975 + * <xbel version="1.0"
6976 + * xmlns:mime="http://www.freedesktop.org/standards/shared-mime-info"
6977 + * xmlns:bookmark="http://www.freedesktop.org/standards/desktop-bookmarks">
6978 + * <bookmark href="file:///home/ebassi/bookmark-spec/bookmark-spec.xml">
6979 + * <title>Desktop Bookmarks Spec</title>
6980 + * <info>
6981 + * <metadata owner="http://freedesktop.org">
6982 + * <mime:mime-type>text/xml</mime:mime-type>
6983 + * <bookmark:applications>
6984 + * <bookmark:application name="GEdit" count="2" exec="gedit %u" timestamp="1115726763"/>
6985 + * <bookmark:application name="GViM" count="7" exec="gvim %f" timestamp="1115726812"/>
6986 + * </bookmark:applications>
6987 + * <bookmark:groups>
6988 + * <bookmark:group>Editors</bookmark:group>
6989 + * </bookmark:groups>
6990 + * </metadata>
6991 + * </info>
6992 + * </bookmark>
6993 + * </xbel>
6994 + * ]]>
6995 + * </programlisting></informalexample>
6996 + *
6997 + * A bookmark file might contain more than one bookmark; each bookmark is accessed
6998 + * through its URI.
6999 + *
7000 + *
7001 + * The important caveat of bookmark files is that when you add a new bookmark you
7002 + * must also add the application that is registering it, using
7003 + * g_bookmark_file_add_application() or g_bookmark_file_set_app_info(). If a
7004 + * bookmark has no applications then it won't be dumped when creating the
7005 + * on disk representation, using g_bookmark_file_to_data() or
7006 + * g_bookmark_file_to_file().
7007 + *
7008 + *
7009 + * The #GBookmarkFile parser was added in GLib 2.12.
7010 + */
7011 +
7012 +
7013 /* XBEL 1.0 standard entities */
7014 #define XBEL_VERSION "1.0"
7015 #define XBEL_DTD_NICK "xbel"
7016 Index: glib/gbookmarkfile.h
7017 ===================================================================
7018 --- glib/gbookmarkfile.h (revision 7087)
7019 +++ glib/gbookmarkfile.h (working copy)
7020 @@ -29,10 +29,31 @@
7021
7022 G_BEGIN_DECLS
7023
7024 -/* GError enumeration
7025 +
7026 +/**
7027 + * G_BOOKMARK_FILE_ERROR:
7028 + *
7029 + * Error domain for bookmark file parsing. Errors in this domain will be
7030 + * from the #GBookmarkFileError enumeration. See #GError for informations
7031 + * on error domains.
7032 */
7033 #define G_BOOKMARK_FILE_ERROR (g_bookmark_file_error_quark ())
7034
7035 +/**
7036 + * GBookmarkFileError:
7037 + * @G_BOOKMARK_FILE_ERROR_INVALID_URI: URI was ill-formed
7038 + * @G_BOOKMARK_FILE_ERROR_INVALID_VALUE: a requested field was not found
7039 + * @G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED: a requested application did not
7040 + * register a bookmark
7041 + * @G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND: a requested URI was not found
7042 + * @G_BOOKMARK_FILE_ERROR_READ: document was ill formed
7043 + * @G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an
7044 + * unknown encoding
7045 + * @G_BOOKMARK_FILE_ERROR_WRITE: an error occurred while writing
7046 + * @G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND: requested file was not found
7047 + *
7048 + * Error codes returned by bookmark file parsing.
7049 + */
7050 typedef enum
7051 {
7052 G_BOOKMARK_FILE_ERROR_INVALID_URI,
7053 @@ -47,8 +68,11 @@
7054
7055 GQuark g_bookmark_file_error_quark (void);
7056
7057 -/*
7058 - * GBookmarkFile
7059 +/**
7060 + * GBookmarkFile:
7061 + *
7062 + * The <structname>GBookmarkFile</structname> struct contains only private data
7063 + * and should not be used directly.
7064 */
7065 typedef struct _GBookmarkFile GBookmarkFile;
7066
7067 Index: glib/giowin32.c
7068 ===================================================================
7069 --- glib/giowin32.c (revision 7087)
7070 +++ glib/giowin32.c (working copy)
7071 @@ -1863,6 +1863,17 @@
7072 g_io_win32_sock_get_flags,
7073 };
7074
7075 +/**
7076 + * g_io_channel_win32_new_messages:
7077 + * @hwnd: a window handle.
7078 + *
7079 + * Creates a new #GIOChannel given a window handle on Windows.
7080 + *
7081 + * This function creates a #GIOChannel that can be used to poll for
7082 + * Windows messages for the window in question.
7083 + *
7084 + * Returns: a new #GIOChannel.
7085 + */
7086 GIOChannel *
7087 g_io_channel_win32_new_messages (guint hwnd)
7088 {
7089 @@ -1922,6 +1933,35 @@
7090 return channel;
7091 }
7092
7093 +/**
7094 + * g_io_channel_win32_new_fd:
7095 + * @fd: a C library file descriptor.
7096 + *
7097 + * Creates a new #GIOChannel given a file descriptor on Windows.
7098 + * This works for file descriptors from the C runtime.
7099 + *
7100 + * This function works for file descriptors as returned by the open(),
7101 + * creat(), pipe() and fileno() calls in the Microsoft C runtime. In
7102 + * order to meaningfully use this function your code should use the same
7103 + * C runtime as GLib uses, which is msvcrt.dll. Note that in current
7104 + * Microsoft compilers it is near impossible to convince it to build code
7105 + * that would use msvcrt.dll. The last Microsoft compiler version that
7106 + * supported using msvcrt.dll as the C runtime was version 6. The GNU
7107 + * compiler and toolchain for Windows, also known as Mingw, fully
7108 + * supports msvcrt.dll.
7109 + *
7110 + * If you have created a #GIOChannel for a file descriptor and started
7111 + * watching (polling) it, you shouldn't call read() on the file
7112 + * descriptor. This is because adding polling for a file descriptor is
7113 + * implemented in GLib on Windows by starting a thread that sits blocked
7114 + * in a read() from the file descriptor most of the time. All reads from
7115 + * the file descriptor should be done by this internal GLib thread. Your
7116 + * code should call only g_io_channel_read().
7117 + *
7118 + * This function is available only in GLib on Windows.
7119 + *
7120 + * Returns: a new #GIOChannel.
7121 + */
7122 GIOChannel *
7123 g_io_channel_win32_new_fd (gint fd)
7124 {
7125 @@ -1944,6 +1984,21 @@
7126 return win32_channel->fd;
7127 }
7128
7129 +/**
7130 + * g_io_channel_win32_new_socket:
7131 + * @socket: a Winsock socket
7132 + *
7133 + * Creates a new #GIOChannel given a socket on Windows.
7134 + *
7135 + * This function works for sockets created by Winsock.
7136 + * It's available only in GLib on Windows.
7137 + *
7138 + * Polling a #GSource created to watch a channel for a socket
7139 + * puts the socket in non-blocking mode. This is a side-effect
7140 + * of the implementation and unavoidable.
7141 + *
7142 + * Returns: a new #GIOChannel
7143 + */
7144 GIOChannel *
7145 g_io_channel_win32_new_socket (int socket)
7146 {
7147 Index: glib/glist.c
7148 ===================================================================
7149 --- glib/glist.c (revision 7087)
7150 +++ glib/glist.c (working copy)
7151 @@ -33,14 +33,95 @@
7152 #include "glib.h"
7153 #include "galias.h"
7154
7155 +/**
7156 + * SECTION:linked_lists_double
7157 + * @Short_description: linked lists containing integer values or pointers to
7158 + * data, with the ability to iterate over the list in both directions
7159 + * @Title: Doubly-Linked Lists
7160 + *
7161 + * The #GList structure and its associated functions provide a standard
7162 + * doubly-linked list data structure.
7163 + *
7164 + * Each element in the list contains a piece of data, together with pointers
7165 + * which link to the previous and next elements in the list.
7166 + * Using these pointers it is possible to move through the list in both
7167 + * directions (unlike the
7168 + * <link linkend="glib-Singly-Linked-lists">Singly-Linked Lists</link>
7169 + * which only allows movement through the list in the forward direction).
7170 + *
7171 + * The data contained in each element can be either integer values, by using one
7172 + * of the
7173 + * <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
7174 + * or simply pointers to any type of data.
7175 + *
7176 + * List elements are allocated from the <link linkend="glib-Memory-Slices">slice
7177 + * allocator</link>, which is more efficient than allocating elements
7178 + * individually.
7179 + *
7180 + * Note that most of the #GList functions expect to be passed a pointer to
7181 + * the first element in the list. The functions which insert elements return
7182 + * the new start of the list, which may have changed.
7183 + *
7184 + * There is no function to create a #GList. %NULL is considered to be the empty
7185 + * list so you simply set a #GList* to %NULL.
7186 + *
7187 + * To add elements, use g_list_append(), g_list_prepend(), g_list_insert()
7188 + * and g_list_insert_sorted().
7189 + *
7190 + * To remove elements, use g_list_remove().
7191 + *
7192 + * To find elements in the list use g_list_first(), g_list_last(), g_list_next(),
7193 + * g_list_previous(), g_list_nth(), g_list_nth_data(), g_list_find() and
7194 + * g_list_find_custom().
7195 + *
7196 + * To find the index of an element use g_list_position() and g_list_index().
7197 + *
7198 + * To call a function for each element in the list use g_list_foreach().
7199 + *
7200 + * To free the entire list, use g_list_free().
7201 + */
7202
7203 +/**
7204 + * g_list_push_allocator:
7205 + * @allocator: the #GAllocator to use when allocating #GList elements.
7206 + *
7207 + * Sets the allocator to use to allocate #GList elements.
7208 + * Use g_list_pop_allocator() to restore the previous allocator.
7209 + *
7210 + * Note that this function is not available if GLib has been compiled
7211 + * with <option>--disable-mem-pools</option>
7212 + *
7213 + * Deprecated: 2.10: It does nothing, since #GList has been
7214 + * converted to the <link linkend="glib-Memory-Slices">slice allocator</link>
7215 + */
7216 void g_list_push_allocator (gpointer dummy) { /* present for binary compat only */ }
7217 +
7218 +/**
7219 + * g_list_pop_allocator:
7220 + *
7221 + * Restores the previous #GAllocator, used when allocating #GList elements.
7222 + *
7223 + * Note that this function is not available if GLib has been compiled
7224 + * with <option>--disable-mem-pools</option>
7225 + *
7226 + * Deprecated: 2.10: It does nothing, since #GList has been
7227 + * converted to the <link linkend="glib-Memory-Slices">slice allocator</link>
7228 + */
7229 void g_list_pop_allocator (void) { /* present for binary compat only */ }
7230
7231 #define _g_list_alloc() g_slice_new (GList)
7232 #define _g_list_alloc0() g_slice_new0 (GList)
7233 #define _g_list_free1(list) g_slice_free (GList, list)
7234
7235 +/**
7236 + * g_list_alloc:
7237 + *
7238 + * Allocates space for one #GList element.
7239 + * It is called by g_list_append(), g_list_prepend(), g_list_insert() and
7240 + * g_list_insert_sorted() and so is rarely used on its own.
7241 + *
7242 + * Returns: a pointer to the newly-allocated #GList element.
7243 + */
7244 GList*
7245 g_list_alloc (void)
7246 {
7247 Index: glib/glist.h
7248 ===================================================================
7249 --- glib/glist.h (revision 7087)
7250 +++ glib/glist.h (working copy)
7251 @@ -35,6 +35,16 @@
7252
7253 G_BEGIN_DECLS
7254
7255 +/**
7256 + * GList:
7257 + * @data: holds the element's data, which can be a pointer to any kind of data,
7258 + * or any integer value using the
7259 + * <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>.
7260 + * @next: contains the link to the next element in the list.
7261 + * @prev: contains the link to the previous element in the list.
7262 + *
7263 + * The #GList struct is used for each element in a doubly-linked list.
7264 + */
7265 typedef struct _GList GList;
7266
7267 struct _GList
7268 @@ -49,6 +59,12 @@
7269 GList* g_list_alloc (void) G_GNUC_WARN_UNUSED_RESULT;
7270 void g_list_free (GList *list);
7271 void g_list_free_1 (GList *list);
7272 +
7273 +/**
7274 + * g_list_free1:
7275 + *
7276 + * Another name for g_list_free_1().
7277 + */
7278 #define g_list_free1 g_list_free_1
7279 GList* g_list_append (GList *list,
7280 gpointer data) G_GNUC_WARN_UNUSED_RESULT;
7281 @@ -106,8 +122,24 @@
7282 gpointer g_list_nth_data (GList *list,
7283 guint n);
7284
7285 +/**
7286 + * g_list_previous:
7287 + * @list: an element in a #GList.
7288 + *
7289 + * A convenience macro to gets the previous element in a #GList.
7290 + *
7291 + * Returns: the previous element, or %NULL if there are no previous elements.
7292 + */
7293 +#define g_list_previous(list) ((list) ? (((GList *)(list))->prev) : NULL)
7294
7295 -#define g_list_previous(list) ((list) ? (((GList *)(list))->prev) : NULL)
7296 +/**
7297 + * g_list_next:
7298 + * @list: an element in a #GList.
7299 + *
7300 + * A convenience macro to gets the next element in a #GList.
7301 + *
7302 + * Returns: the next element, or %NULL if there are no more elements.
7303 + */
7304 #define g_list_next(list) ((list) ? (((GList *)(list))->next) : NULL)
7305
7306 #ifndef G_DISABLE_DEPRECATED
7307 Index: glib/gasyncqueue.c
7308 ===================================================================
7309 --- glib/gasyncqueue.c (revision 7087)
7310 +++ glib/gasyncqueue.c (working copy)
7311 @@ -29,6 +29,57 @@
7312 #include "glib.h"
7313 #include "galias.h"
7314
7315 +/**
7316 + * SECTION:async_queues
7317 + * @Short_description: asynchronous communication between threads
7318 + * @Title: Asynchronous Queues
7319 + *
7320 + * Often you need to communicate between different threads. In general
7321 + * it's safer not to do this by shared memory, but by explicit message
7322 + * passing. These messages only make sense asynchronously for
7323 + * multi-threaded applications though, as a synchronous operation could as
7324 + * well be done in the same thread.
7325 + *
7326 + *
7327 + * Asynchronous queues are an exception from most other GLib data
7328 + * structures, as they can be used simultaneously from multiple threads
7329 + * without explicit locking and they bring their own builtin reference
7330 + * counting. This is because the nature of an asynchronous queue is that
7331 + * it will always be used by at least 2 concurrent threads.
7332 + *
7333 + *
7334 + * For using an asynchronous queue you first have to create one with
7335 + * g_async_queue_new(). A newly-created queue will get the reference
7336 + * count 1. Whenever another thread is creating a new reference of (that
7337 + * is, pointer to) the queue, it has to increase the reference count
7338 + * (using g_async_queue_ref()). Also, before removing this reference, the
7339 + * reference count has to be decreased (using
7340 + * g_async_queue_unref()). After that the queue might no longer exist so
7341 + * you must not access it after that point.
7342 + *
7343 + *
7344 + * A thread, which wants to send a message to that queue simply calls
7345 + * g_async_queue_push() to push the message to the queue.
7346 + *
7347 + *
7348 + * A thread, which is expecting messages from an asynchronous queue
7349 + * simply calls g_async_queue_pop() for that queue. If no message is
7350 + * available in the queue at that point, the thread is now put to sleep
7351 + * until a message arrives. The message will be removed from the queue
7352 + * and returned. The functions g_async_queue_try_pop() and
7353 + * g_async_queue_timed_pop() can be used to only check for the presence
7354 + * of messages or to only wait a certain time for messages respectively.
7355 + *
7356 + *
7357 + * For almost every function there exist two variants, one that locks the
7358 + * queue and one that doesn't. That way you can hold the queue lock
7359 + * (acquire it with g_async_queue_lock() and release it with
7360 + * g_async_queue_unlock()) over multiple queue accessing
7361 + * instructions. This can be necessary to ensure the integrity of the
7362 + * queue, but should only be used when really necessary, as it can make
7363 + * your life harder if used unwisely. Normally you should only use the
7364 + * locking function variants (those without the suffix _unlocked)
7365 + */
7366
7367 struct _GAsyncQueue
7368 {
7369 Index: glib/gbase64.c
7370 ===================================================================
7371 --- glib/gbase64.c (revision 7087)
7372 +++ glib/gbase64.c (working copy)
7373 @@ -37,6 +37,28 @@
7374 "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
7375
7376 /**
7377 + * SECTION:base64
7378 + * @Short_description: encodes and decodes data in Base64 format
7379 + * @Title: Base64 Encoding
7380 + *
7381 + * Base64 is an encoding that allows to encode a sequence of arbitrary
7382 + * bytes as a sequence of printable ASCII characters. For the definition
7383 + * of Base64, see <ulink url="http://www.ietf.org/rfc/rfc1421.txt">RFC
7384 + * 1421</ulink> or <ulink url="http://www.ietf.org/rfc/rfc2045.txt">RFC
7385 + * 2045</ulink>. Base64 is most commonly used as a MIME transfer encoding
7386 + * for email.
7387 + *
7388 + *
7389 + * GLib supports incremental encoding using g_base64_encode_step() and
7390 + * g_base64_encode_close(). Incremental decoding can be done with
7391 + * g_base64_decode_step(). To encode or decode data in one go, use
7392 + * g_base64_encode() or g_base64_decode().
7393 + *
7394 + *
7395 + * Support for Base64 encoding has been added in GLib 2.12.
7396 + */
7397 +
7398 +/**
7399 * g_base64_encode_step:
7400 * @in: the binary data to encode
7401 * @len: the length of @in
7402 Index: glib/gi18n.h
7403 ===================================================================
7404 --- glib/gi18n.h (revision 7087)
7405 +++ glib/gi18n.h (working copy)
7406 @@ -24,9 +24,114 @@
7407
7408 #include <libintl.h>
7409
7410 +/**
7411 + * SECTION:i18n
7412 + * @Short_description: gettext support macros
7413 + * @Title: Internationalization
7414 + * @See_also:The gettext manual.
7415 + *
7416 + * GLib doesn't force any particular localization method upon its users.
7417 + * But since GLib itself is localized using the gettext() mechanism, it seems
7418 + * natural to offer the de-facto standard gettext() support macros in an
7419 + * easy-to-use form.
7420 + *
7421 + * In order to use these macros in an application, you must include
7422 + * <filename>glib/gi18n.h</filename>. For use in a library, must include
7423 + * <filename>glib/gi18n-lib.h</filename> <emphasis>after</emphasis> defining
7424 + * the GETTEXT_PACKAGE macro suitably for your library:
7425 + * <informalexample><programlisting>
7426 + * #define GETTEXT_PACKAGE "gtk20"
7427 + * #include <glib/gi18n-lib.h>
7428 + * </programlisting></informalexample>
7429 + * The gettext manual covers details of how to set up message extraction
7430 + * with xgettext.
7431 + */
7432 +
7433 #define _(String) gettext (String)
7434 +
7435 +/**
7436 + * Q_:
7437 + * @String: the string to be translated, with a '|'-separated prefix which
7438 + * must not be translated
7439 + *
7440 + * Like _(), but handles context in message ids. This has the advantage that
7441 + * the string can be adorned with a prefix to guarantee uniqueness and provide
7442 + * context to the translator.
7443 + *
7444 + * One use case given in the gettext manual is GUI translation, where one could
7445 + * e.g. disambiguate two "Open" menu entries as "File|Open" and "Printer|Open".
7446 + * Another use case is the string "Russian" which may have to be translated
7447 + * differently depending on whether it's the name of a character set or a
7448 + * language. This could be solved by using "charset|Russian" and
7449 + * "language|Russian".
7450 + *
7451 + * See the C_() macro for a different way to mark up translatable strings
7452 + * with context.
7453 + *
7454 + * If you are using the Q_() macro, you need to make sure that you
7455 + * pass <option>--keyword=Q_</option> to xgettext when extracting messages.
7456 + * If you are using GNU gettext >= 0.15, you can also use
7457 + * <option>--keyword=Q_:1g</option> to let xgettext split the context
7458 + * string off into a msgctxt line in the po file.
7459 + * </para></note>
7460 + *
7461 + * Since: 2.4
7462 + * Returns: the translated message
7463 + */
7464 #define Q_(String) g_dpgettext (NULL, String, 0)
7465 +
7466 +/**
7467 + * N_:
7468 + * @String: the string to be translated
7469 + *
7470 + * Only marks a string for translation.
7471 + * This is useful in situations where the translated strings can't
7472 + * be directly used, e.g. in string array initializers.
7473 + * To get the translated string, call gettext() at runtime.
7474 + *
7475 + * <informalexample><programlisting>
7476 + * {
7477 + * static const char *messages[] = {
7478 + * N_("some very meaningful message"),
7479 + * N_("and another one")
7480 + * };
7481 + * const char *string;
7482 + * ...
7483 + * string
7484 + * = index > 1 ? _("a default message") : gettext (messages[index]);
7485 + * <!-- -->
7486 + * fputs (string);
7487 + * ...
7488 + * }
7489 + * </programlisting></informalexample>
7490 + *
7491 + * Since: 2.4
7492 + */
7493 #define N_(String) (String)
7494 +
7495 +/**
7496 + * C_:
7497 + * @Context: a message context, must be a string literal
7498 + * @String: a message id, must be a string literal
7499 + *
7500 + * Uses gettext to get the translation for @msgid. @msgctxt is
7501 + * used as a context. This is mainly useful for short strings which
7502 + * may need different translations, depending on the context in which
7503 + * they are used.
7504 + * <informalexample><programlisting>
7505 + * label1 = C_("Navigation", "Back");
7506 + * label2 = C_("Body part", "Back");
7507 + * </programlisting></informalexample>
7508 + *
7509 + *
7510 + * If you are using the C_() macro, you need to make sure that you
7511 + * pass <option>--keyword=C_:1c,2</option> to xgettext when extracting
7512 + * messages. Note that this only works with GNU gettext >= 0.15.
7513 + * </para></note>
7514 + *
7515 + * Since: 2.16
7516 + * Returns: the translated message
7517 + */
7518 #define C_(Context,String) g_dpgettext (NULL, Context "\004" String, strlen (Context) + 1)
7519
7520 #endif /* __G_I18N_H__ */
7521 Index: glib/gasyncqueue.h
7522 ===================================================================
7523 --- glib/gasyncqueue.h (revision 7087)
7524 +++ glib/gasyncqueue.h (working copy)
7525 @@ -35,6 +35,13 @@
7526
7527 G_BEGIN_DECLS
7528
7529 +/**
7530 + * GAsyncQueue:
7531 + *
7532 + * The #GAsyncQueue struct is an opaque data structure, which represents
7533 + * an asynchronous queue. It should only be accessed through the
7534 + * <function>g_async_queue_*</function> functions.
7535 + */
7536 typedef struct _GAsyncQueue GAsyncQueue;
7537
7538 /* Asyncronous Queues, can be used to communicate between threads */
7539 Index: glib/gurifuncs.c
7540 ===================================================================
7541 --- glib/gurifuncs.c (revision 7087)
7542 +++ glib/gurifuncs.c (working copy)
7543 @@ -28,7 +28,8 @@
7544
7545 /**
7546 * SECTION:gurifuncs
7547 - * @short_description: URI Functions
7548 + * @Title: URI Functions
7549 + * @short_description: functions for manipulating URIs
7550 *
7551 * Functions for manipulating Universal Resource Identifiers (URIs) as
7552 * defined by RFC 3986. It is highly recommended that you have read and
7553 Index: glib/gregex.c
7554 ===================================================================
7555 --- glib/gregex.c (revision 7087)
7556 +++ glib/gregex.c (working copy)
7557 @@ -40,6 +40,67 @@
7558
7559 #include "galias.h"
7560
7561 +/**
7562 + * SECTION:gregex
7563 + * @Short_description: matches strings against regular expressions
7564 + * @Title: Perl-compatible regular expressions
7565 + *
7566 + * The <function>g_regex_*()</function> functions implement regular
7567 + * expression pattern matching using syntax and semantics similar to
7568 + * Perl regular expression.
7569 + *
7570 + * Some functions accept a <parameter>start_position</parameter> argument,
7571 + * setting it differs from just passing over a shortened string and setting
7572 + * #G_REGEX_MATCH_NOTBOL in the case of a pattern that begins with any kind
7573 + * of lookbehind assertion.
7574 + * For example, consider the pattern "\Biss\B" which finds occurrences of "iss"
7575 + * in the middle of words. ("\B" matches only if the current position in the
7576 + * subject is not a word boundary.) When applied to the string "Mississipi"
7577 + * from the fourth byte, namely "issipi", it does not match, because "\B" is
7578 + * always false at the start of the subject, which is deemed to be a word
7579 + * boundary. However, if the entire string is passed , but with
7580 + * <parameter>start_position</parameter> set to 4, it finds the second
7581 + * occurrence of "iss" because it is able to look behind the starting point
7582 + * to discover that it is preceded by a letter.
7583 + *
7584 + * Note that, unless you set the #G_REGEX_RAW flag, all the strings passed
7585 + * to these functions must be encoded in UTF-8. The lengths and the positions
7586 + * inside the strings are in bytes and not in characters, so, for instance,
7587 + * "\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a single
7588 + * character. If you set #G_REGEX_RAW the strings can be non-valid UTF-8
7589 + * strings and a byte is treated as a character, so "\xc3\xa0" is two bytes
7590 + * and two characters long.
7591 + *
7592 + * When matching a pattern, "\n" matches only against a "\n" character in the
7593 + * string, and "\r" matches only a "\r" character. To match any newline sequence
7594 + * use "\R". This particular group matches either the two-character sequence
7595 + * CR + LF ("\r\n"), or one of the single characters LF (linefeed, U+000A, "\n"), VT
7596 + * (vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"), CR (carriage return,
7597 + * U+000D, "\r"), NEL (next line, U+0085), LS (line separator, U+2028), or PS
7598 + * (paragraph separator, U+2029).
7599 + *
7600 + * The behaviour of the dot, circumflex, and dollar metacharacters are affected by
7601 + * newline characters, the default is to recognize any newline character (the same
7602 + * characters recognized by "\R"). This can be changed with #G_REGEX_NEWLINE_CR,
7603 + * #G_REGEX_NEWLINE_LF and #G_REGEX_NEWLINE_CRLF compile options,
7604 + * and with #G_REGEX_MATCH_NEWLINE_ANY, #G_REGEX_MATCH_NEWLINE_CR,
7605 + * #G_REGEX_MATCH_NEWLINE_LF and #G_REGEX_MATCH_NEWLINE_CRLF match options.
7606 + * These settings are also relevant when compiling a pattern if
7607 + * #G_REGEX_EXTENDED is set, and an unescaped "#" outside a character class is
7608 + * encountered. This indicates a comment that lasts until after the next
7609 + * newline.
7610 + *
7611 + * Creating and manipulating the same #GRegex structure from different
7612 + * threads is not a problem as #GRegex does not modify its internal
7613 + * state between creation and destruction, on the other hand #GMatchInfo is
7614 + * not threadsafe.
7615 + *
7616 + * The regular expressions low level functionalities are obtained through
7617 + * the excellent <ulink url="http://www.pcre.org/">PCRE</ulink> library
7618 + * written by Philip Hazel.
7619 + */
7620 +
7621 +
7622 /* Mask of all the possible values for GRegexCompileFlags. */
7623 #define G_REGEX_COMPILE_MASK (G_REGEX_CASELESS | \
7624 G_REGEX_MULTILINE | \
7625 Index: glib/giounix.c
7626 ===================================================================
7627 --- glib/giounix.c (revision 7087)
7628 +++ glib/giounix.c (working copy)
7629 @@ -561,6 +561,33 @@
7630 return channel;
7631 }
7632
7633 +/**
7634 + * g_io_channel_unix_new:
7635 + * @fd: a file descriptor.
7636 + *
7637 + * Creates a new #GIOChannel given a file descriptor.
7638 + * On UNIX systems this works for plain files, pipes, and sockets.
7639 + *
7640 + * The returned #GIOChannel has a reference count of 1.
7641 + *
7642 + * The default encoding for #GIOChannel is UTF-8. If your application
7643 + * is reading output from a command using via pipe, you may need to
7644 + * set the encoding to the encoding of the current locale (see
7645 + * g_get_charset()) with the g_io_channel_set_encoding() function.
7646 + *
7647 + * If you want to read raw binary data without interpretation, then
7648 + * call the g_io_channel_set_encoding() function with %NULL for the
7649 + * encoding argument.
7650 + *
7651 + * This function is available in GLib on Windows, too, but you should
7652 + * avoid using it on Windows. The domain of file descriptors and sockets
7653 + * overlap. There is no way for GLib to know which one you mean in case
7654 + * the argument you pass to this function happens to be both a valid file
7655 + * descriptor and socket. If that happens a warning is issued, and GLib
7656 + * assumes that it is the file descriptor you mean.
7657 + *
7658 + * Returns: a new #GIOChannel.
7659 + */
7660 GIOChannel *
7661 g_io_channel_unix_new (gint fd)
7662 {
7663 @@ -590,6 +617,16 @@
7664 return channel;
7665 }
7666
7667 +/**
7668 + * g_io_channel_unix_get_fd:
7669 + * @channel: a #GIOChannel, created with g_io_channel_unix_new().
7670 + *
7671 + * Returns the file descriptor of the #GIOChannel.
7672 + *
7673 + * On Windows this function returns the file descriptor or socket of the #GIOChannel.
7674 + *
7675 + * Returns: the file descriptor of the #GIOChannel.
7676 + */
7677 gint
7678 g_io_channel_unix_get_fd (GIOChannel *channel)
7679 {
7680 Index: glib/gmem.c
7681 ===================================================================
7682 --- glib/gmem.c (revision 7087)
7683 +++ glib/gmem.c (working copy)
7684 @@ -38,6 +38,42 @@
7685 #include "gthreadprivate.h"
7686 #include "galias.h"
7687
7688 +/**
7689 + * SECTION:allocators
7690 + * @Short_description: deprecated way to allocate chunks of memory for GList, GSList and GNode
7691 + * @Title: Memory Allocators
7692 + *
7693 + *
7694 + * Prior to 2.10, #GAllocator was used as an efficient way to allocate
7695 + * small pieces of memory for use with the #GList, #GSList and #GNode data
7696 + * structures. Since 2.10, it has been completely replaced by the
7697 + * <link linkend="glib-Memory-Slices">slice allocator</link> and deprecated.
7698 + */
7699 +
7700 +/**
7701 + * SECTION:memory
7702 + * @Short_description: general memory-handling
7703 + * @Title: Memory Allocation
7704 + *
7705 + * These functions provide support for allocating and freeing memory.
7706 + *
7707 + *
7708 + * <note>
7709 + * If any call to allocate memory fails, the application is terminated.
7710 + * This also means that there is no need to check if the call succeeded.
7711 + *
7712 + * </note>
7713 + *
7714 + * <note>
7715 + * It's important to match g_malloc() with g_free(), plain malloc() with free(),
7716 + * and (if you're using C++) new with delete and new[] with delete[]. Otherwise
7717 + * bad things can happen, since these allocators may use different memory
7718 + * pools (and new/delete call constructors and destructors). See also
7719 + * g_mem_set_vtable().
7720 + *
7721 + * </note>
7722 + */
7723 +
7724 #define MEM_PROFILE_TABLE_SIZE 4096
7725
7726
7727 @@ -119,6 +155,16 @@
7728
7729
7730 /* --- functions --- */
7731 +
7732 +/**
7733 + * g_malloc:
7734 + * @n_bytes: the number of bytes to allocate
7735 + *
7736 + * Allocates @n_bytes bytes of memory.
7737 + * If @n_bytes is 0 it returns %NULL.
7738 + *
7739 + * Returns: a pointer to the allocated memory
7740 + */
7741 gpointer
7742 g_malloc (gsize n_bytes)
7743 {
7744 @@ -139,6 +185,15 @@
7745 return NULL;
7746 }
7747
7748 +/**
7749 + * g_malloc0:
7750 + * @n_bytes: the number of bytes to allocate
7751 + *
7752 + * Allocates @n_bytes bytes of memory, initialized to 0's.
7753 + * If @n_bytes is 0 it returns %NULL.
7754 + *
7755 + * Returns: a pointer to the allocated memory
7756 + */
7757 gpointer
7758 g_malloc0 (gsize n_bytes)
7759 {
7760 @@ -159,6 +214,19 @@
7761 return NULL;
7762 }
7763
7764 +/**
7765 + * g_realloc:
7766 + * @mem: the memory to reallocate
7767 + * @n_bytes: new size of the memory in bytes
7768 + *
7769 + * Reallocates the memory pointed to by @mem, so that it now has space for
7770 + * @n_bytes bytes of memory. It returns the new address of the memory, which may
7771 + * have been moved. @mem may be %NULL, in which case it's considered to
7772 + * have zero-length. @n_bytes may be 0, in which case %NULL will be returned
7773 + * and @mem will be freed unless it is %NULL.
7774 + *
7775 + * Returns: the new address of the allocated memory
7776 + */
7777 gpointer
7778 g_realloc (gpointer mem,
7779 gsize n_bytes)
7780 @@ -181,6 +249,13 @@
7781 return NULL;
7782 }
7783
7784 +/**
7785 + * g_free:
7786 + * @mem: the memory to free
7787 + *
7788 + * Frees the memory pointed to by @mem.
7789 + * If @mem is %NULL it simply returns.
7790 + */
7791 void
7792 g_free (gpointer mem)
7793 {
7794 @@ -190,6 +265,15 @@
7795 glib_mem_vtable.free (mem);
7796 }
7797
7798 +/**
7799 + * g_try_malloc:
7800 + * @n_bytes: number of bytes to allocate.
7801 + *
7802 + * Attempts to allocate @n_bytes, and returns %NULL on failure.
7803 + * Contrast with g_malloc(), which aborts the program on failure.
7804 + *
7805 + * Returns: the allocated memory, or %NULL.
7806 + */
7807 gpointer
7808 g_try_malloc (gsize n_bytes)
7809 {
7810 @@ -201,6 +285,16 @@
7811 return NULL;
7812 }
7813
7814 +/**
7815 + * g_try_malloc0:
7816 + * @n_bytes: number of bytes to allocate
7817 + *
7818 + * Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
7819 + * failure. Contrast with g_malloc0(), which aborts the program on failure.
7820 + *
7821 + * Since: 2.8
7822 + * Returns: the allocated memory, or %NULL
7823 + */
7824 gpointer
7825 g_try_malloc0 (gsize n_bytes)
7826 {
7827 @@ -214,6 +308,17 @@
7828 return mem;
7829 }
7830
7831 +/**
7832 + * g_try_realloc:
7833 + * @mem: previously-allocated memory, or %NULL.
7834 + * @n_bytes: number of bytes to allocate.
7835 + *
7836 + * Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
7837 + * on failure. Contrast with g_realloc(), which aborts the program
7838 + * on failure. If @mem is %NULL, behaves the same as g_try_malloc().
7839 + *
7840 + * Returns: the allocated memory, or %NULL.
7841 + */
7842 gpointer
7843 g_try_realloc (gpointer mem,
7844 gsize n_bytes)
7845 @@ -263,6 +368,18 @@
7846 return !vtable_set;
7847 }
7848
7849 +/**
7850 + * g_mem_set_vtable:
7851 + * @vtable: table of memory allocation routines.
7852 + *
7853 + * Sets the #GMemVTable to use for memory allocation. You can use this to provide
7854 + * custom memory allocation routines. <emphasis>This function must be called
7855 + * before using any other GLib functions.</emphasis> The @vtable only needs to
7856 + * provide malloc(), realloc(), and free() functions; GLib can provide default
7857 + * implementations of the others. The malloc() and realloc() implementations
7858 + * should return %NULL on failure, GLib will handle error-checking for you.
7859 + * @vtable is copied, so need not persist after this function has been called.
7860 + */
7861 void
7862 g_mem_set_vtable (GMemVTable *vtable)
7863 {
7864 @@ -388,6 +505,20 @@
7865 g_print (" --- none ---\n");
7866 }
7867
7868 +/**
7869 + * g_mem_profile:
7870 + *
7871 + * Outputs a summary of memory usage.
7872 + *
7873 + * It outputs the frequency of allocations of different sizes,
7874 + * the total number of bytes which have been allocated,
7875 + * the total number of bytes which have been freed,
7876 + * and the difference between the previous two values, i.e. the number of bytes
7877 + * still in use.
7878 + *
7879 + * Note that this function will not output anything unless you have
7880 + * previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
7881 + */
7882 void
7883 g_mem_profile (void)
7884 {
7885 @@ -599,6 +730,116 @@
7886 #endif /* !G_DISABLE_CHECKS */
7887
7888 /* --- MemChunks --- */
7889 +/**
7890 + * SECTION:memory_chunks
7891 + * @Short_description: deprecated way to allocate groups of equal-sized chunks of memory
7892 + * @Title: Memory Chunks
7893 + *
7894 + * Memory chunks provide an space-efficient way to allocate equal-sized
7895 + * pieces of memory, called atoms. However, due to the administrative
7896 + * overhead (in particular for #G_ALLOC_AND_FREE, and when used from multiple
7897 + * threads), they are in practise often slower than direct use of g_malloc().
7898 + * Therefore, memory chunks have been deprecated in favor of the
7899 + * <link linkend="glib-Memory-Slices">slice allocator</link>,
7900 + * which has been added in 2.10. All internal uses of memory chunks in
7901 + * GLib have been converted to the <literal>g_slice</literal> API.
7902 + *
7903 + * There are two types of memory chunks, #G_ALLOC_ONLY, and #G_ALLOC_AND_FREE.
7904 + * <itemizedlist>
7905 + * #G_ALLOC_ONLY chunks only allow allocation of atoms. The atoms can never
7906 + * be freed individually. The memory chunk can only be free in its entirety.
7907 + * </para></listitem>
7908 + * #G_ALLOC_AND_FREE chunks do allow atoms to be freed individually.
7909 + * The disadvantage of this is that the memory chunk has to keep track of which
7910 + * atoms have been freed. This results in more memory being used and a slight
7911 + * degradation in performance.
7912 + * </para></listitem>
7913 + *
7914 + * </itemizedlist>
7915 + *
7916 + * To create a memory chunk use g_mem_chunk_new() or the convenience macro
7917 + * g_mem_chunk_create().
7918 + *
7919 + * To allocate a new atom use g_mem_chunk_alloc(), g_mem_chunk_alloc0(),
7920 + * or the convenience macros g_chunk_new() or g_chunk_new0().
7921 + *
7922 + * To free an atom use g_mem_chunk_free(), or the convenience macro
7923 + * g_chunk_free(). (Atoms can only be freed if the memory chunk is created
7924 + * with the type set to #G_ALLOC_AND_FREE.)
7925 + *
7926 + * To free any blocks of memory which are no longer being used, use
7927 + * g_mem_chunk_clean(). To clean all memory chunks, use g_blow_chunks().
7928 + *
7929 + * To reset the memory chunk, freeing all of the atoms, use g_mem_chunk_reset().
7930 + *
7931 + * To destroy a memory chunk, use g_mem_chunk_destroy().
7932 + *
7933 + * To help debug memory chunks, use g_mem_chunk_info() and g_mem_chunk_print().
7934 + *
7935 + *
7936 + * <example>
7937 + * <title>Using a <structname>GMemChunk</structname></title>
7938 + * <programlisting>
7939 + * GMemChunk *mem_chunk;
7940 + * gchar *mem[10000];
7941 + * gint i;
7942 + *
7943 + * /<!-- -->* Create a GMemChunk with atoms 50 bytes long, and memory blocks holding
7944 + * 100 bytes. Note that this means that only 2 atoms fit into each memory
7945 + * block and so isn't very efficient. *<!-- -->/
7946 + * mem_chunk = g_mem_chunk_new ("test mem chunk", 50, 100, G_ALLOC_AND_FREE);
7947 + *
7948 + * // Now allocate 10000 atoms.
7949 + * for (i = 0; i < 10000; i++)
7950 + * {
7951 + * mem[i] = g_chunk_new (gchar, mem_chunk);
7952 + *
7953 + * // Fill in the atom memory with some junk.
7954 + * for (j = 0; j < 50; j++)
7955 + * mem[i][j] = i * j;
7956 + * }
7957 + *
7958 + * /<!-- -->* Now free all of the atoms. Note that since we are going to destroy the
7959 + * GMemChunk, this wouldn't normally be used. *<!-- -->/
7960 + * for (i = 0; i < 10000; i++)
7961 + * {
7962 + * g_mem_chunk_free (mem_chunk, mem[i]);
7963 + * }
7964 + *
7965 + * // We are finished with the GMemChunk, so we destroy it.
7966 + * g_mem_chunk_destroy (mem_chunk);
7967 + * </programlisting></example>
7968 + *
7969 + * <example>
7970 + * <title>Using a <structname>GMemChunk</structname> with data structures</title>
7971 + * <programlisting>
7972 + * GMemChunk *array_mem_chunk;
7973 + * GRealArray *array;
7974 + *
7975 + * /<!-- -->* Create a GMemChunk to hold GRealArray structures, using the
7976 + * g_mem_chunk_create(<!-- -->) convenience macro. We want 1024 atoms in each
7977 + * memory block, and we want to be able to free individual atoms. *<!-- -->/
7978 + * array_mem_chunk = g_mem_chunk_create (GRealArray, 1024, G_ALLOC_AND_FREE);
7979 + *
7980 + * // Allocate one atom, using the g_chunk_new(<!-- -->) convenience macro.
7981 + * array = g_chunk_new (GRealArray, array_mem_chunk);
7982 + *
7983 + * // We can now use array just like a normal pointer to a structure.
7984 + * array->data = NULL;
7985 + * array->len = 0;
7986 + * array->alloc = 0;
7987 + * array->zero_terminated = (zero_terminated ? 1 : 0);
7988 + * array->clear = (clear ? 1 : 0);
7989 + * array->elt_size = elt_size;
7990 + *
7991 + * // We can free the element, so it can be reused.
7992 + * g_chunk_free (array, array_mem_chunk);
7993 + *
7994 + * // We destroy the GMemChunk when we are finished with it.
7995 + * g_mem_chunk_destroy (array_mem_chunk);
7996 + * </programlisting></example>
7997 + */
7998 +
7999 #ifndef G_ALLOC_AND_FREE
8000 typedef struct _GAllocator GAllocator;
8001 typedef struct _GMemChunk GMemChunk;
8002 @@ -610,6 +851,26 @@
8003 guint alloc_size; /* the size of an atom */
8004 };
8005
8006 +/**
8007 + * g_mem_chunk_new:
8008 + * @name: a string to identify the #GMemChunk. It is not copied so it
8009 + * should be valid for the lifetime of the #GMemChunk. It is only used in
8010 + * g_mem_chunk_print(), which is used for debugging.
8011 + * @atom_size: the size, in bytes, of each element in the #GMemChunk.
8012 + * @area_size: the size, in bytes, of each block of memory allocated to contain
8013 + * the atoms.
8014 + * @type: the type of the #GMemChunk.
8015 + * #G_ALLOC_AND_FREE is used if the atoms will be freed individually.
8016 + * #G_ALLOC_ONLY should be used if atoms will never be freed individually.
8017 + * #G_ALLOC_ONLY is quicker, since it does not need to track free atoms,
8018 + * but it obviously wastes memory if you no longer need many of the atoms.
8019 + *
8020 + * Creates a new #GMemChunk.
8021 + *
8022 + * Deprecated: 2.10: Use the <link linkend="glib-Memory-Slices">slice allocator</link>
8023 + * instead
8024 + * Returns: the new #GMemChunk.
8025 + */
8026 GMemChunk*
8027 g_mem_chunk_new (const gchar *name,
8028 gint atom_size,
8029 @@ -624,6 +885,15 @@
8030 return mem_chunk;
8031 }
8032
8033 +/**
8034 + * g_mem_chunk_destroy:
8035 + * @mem_chunk: a #GMemChunk.
8036 + *
8037 + * Frees all of the memory allocated for a #GMemChunk.
8038 + *
8039 + * Deprecated: 2.10: Use the <link linkend="glib-Memory-Slices">slice
8040 + * allocator</link> instead
8041 + */
8042 void
8043 g_mem_chunk_destroy (GMemChunk *mem_chunk)
8044 {
8045 @@ -632,6 +902,15 @@
8046 g_slice_free (GMemChunk, mem_chunk);
8047 }
8048
8049 +/**
8050 + * g_mem_chunk_alloc:
8051 + * @mem_chunk: a #GMemChunk.
8052 + *
8053 + * Allocates an atom of memory from a #GMemChunk.
8054 + *
8055 + * Deprecated: 2.10: Use g_slice_alloc() instead
8056 + * Returns: a pointer to the allocated atom.
8057 + */
8058 gpointer
8059 g_mem_chunk_alloc (GMemChunk *mem_chunk)
8060 {
8061 @@ -640,6 +919,15 @@
8062 return g_slice_alloc (mem_chunk->alloc_size);
8063 }
8064
8065 +/**
8066 + * g_mem_chunk_alloc0:
8067 + * @mem_chunk: a #GMemChunk.
8068 + *
8069 + * Allocates an atom of memory from a #GMemChunk, setting the memory to 0.
8070 + *
8071 + * Deprecated: 2.10: Use g_slice_alloc0() instead
8072 + * Returns: a pointer to the allocated atom.
8073 + */
8074 gpointer
8075 g_mem_chunk_alloc0 (GMemChunk *mem_chunk)
8076 {
8077 @@ -648,6 +936,17 @@
8078 return g_slice_alloc0 (mem_chunk->alloc_size);
8079 }
8080
8081 +/**
8082 + * g_mem_chunk_free:
8083 + * @mem_chunk: a #GMemChunk.
8084 + * @mem: a pointer to the atom to free.
8085 + *
8086 + * Frees an atom in a #GMemChunk.
8087 + * This should only be called if the #GMemChunk was created with
8088 + * #G_ALLOC_AND_FREE. Otherwise it will simply return.
8089 + *
8090 + * Deprecated: 2.10: Use g_slice_free1() instead
8091 + */
8092 void
8093 g_mem_chunk_free (GMemChunk *mem_chunk,
8094 gpointer mem)
8095 @@ -657,12 +956,78 @@
8096 g_slice_free1 (mem_chunk->alloc_size, mem);
8097 }
8098
8099 +/**
8100 + * g_mem_chunk_clean:
8101 + * @mem_chunk: a #GMemChunk.
8102 + *
8103 + * Frees any blocks in a #GMemChunk which are no longer being used.
8104 + *
8105 + * Deprecated: 2.10: Use the <link linkend="glib-Memory-Slices">slice
8106 + * allocator</link> instead
8107 + */
8108 void g_mem_chunk_clean (GMemChunk *mem_chunk) {}
8109 +
8110 +/**
8111 + * g_mem_chunk_reset:
8112 + * @mem_chunk: a #GMemChunk.
8113 + *
8114 + * Resets a GMemChunk to its initial state.
8115 + * It frees all of the currently allocated blocks of memory.
8116 + *
8117 + * Deprecated: 2.10: Use the <link linkend="glib-Memory-Slices">slice
8118 + * allocator</link> instead
8119 + */
8120 void g_mem_chunk_reset (GMemChunk *mem_chunk) {}
8121 +
8122 +/**
8123 + * g_mem_chunk_print:
8124 + * @mem_chunk: a #GMemChunk.
8125 + *
8126 + * Outputs debugging information for a #GMemChunk.
8127 + * It outputs the name of the #GMemChunk (set with g_mem_chunk_new()),
8128 + * the number of bytes used, and the number of blocks of memory allocated.
8129 + *
8130 + * Deprecated: 2.10: Use the <link linkend="glib-Memory-Slices">slice
8131 + * allocator</link> instead
8132 + */
8133 void g_mem_chunk_print (GMemChunk *mem_chunk) {}
8134 +
8135 +/**
8136 + * g_mem_chunk_info:
8137 + *
8138 + * Outputs debugging information for all #GMemChunk objects currently in use.
8139 + * It outputs the number of #GMemChunk objects currently allocated,
8140 + * and calls g_mem_chunk_print() to output information on each one.
8141 + *
8142 + * Deprecated: 2.10: Use the <link linkend="glib-Memory-Slices">slice
8143 + * allocator</link> instead
8144 + */
8145 void g_mem_chunk_info (void) {}
8146 +/**
8147 + * g_blow_chunks:
8148 + *
8149 + * Calls g_mem_chunk_clean() on all #GMemChunk objects.
8150 + *
8151 + * Deprecated: 2.10: Use the <link linkend="glib-Memory-Slices">slice
8152 + * allocator</link> instead
8153 + */
8154 void g_blow_chunks (void) {}
8155
8156 +/**
8157 + * g_allocator_new:
8158 + * @name: the name of the #GAllocator. This name is used to set the name of the
8159 + * #GMemChunk used by the #GAllocator, and is only used for debugging.
8160 + * @n_preallocs: the number of elements in each block of memory allocated.
8161 + * Larger blocks mean less calls to g_malloc(), but some memory may be wasted.
8162 + * (GLib uses 128 elements per block by default.) The value must be between 1
8163 + * and 65535.
8164 + *
8165 + * Creates a new #GAllocator.
8166 + *
8167 + * Deprecated: 2.10: Use the <link linkend="glib-Memory-Slices">slice allocator</link>
8168 + * instead
8169 + * Returns: a new #GAllocator.
8170 + */
8171 GAllocator*
8172 g_allocator_new (const gchar *name,
8173 guint n_preallocs)
8174 @@ -682,6 +1047,15 @@
8175 return (void*) &dummy;
8176 }
8177
8178 +/**
8179 + * g_allocator_free:
8180 + * @allocator: a #GAllocator.
8181 + *
8182 + * Frees all of the memory allocated by the #GAllocator.
8183 + *
8184 + * Deprecated: 2.10: Use the <link linkend="glib-Memory-Slices">slice allocator</link>
8185 + * instead
8186 + */
8187 void
8188 g_allocator_free (GAllocator *allocator)
8189 {
8190 Index: glib/gregex.h
8191 ===================================================================
8192 --- glib/gregex.h (revision 7087)
8193 +++ glib/gregex.h (working copy)
8194 @@ -31,6 +31,56 @@
8195
8196 G_BEGIN_DECLS
8197
8198 +/**
8199 + * GRegexError:
8200 + * @G_REGEX_ERROR_COMPILE: Compilation of the regular expression failed.
8201 + * @G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression failed.
8202 + * @G_REGEX_ERROR_REPLACE: Replacement failed due to an ill-formed replacement string.
8203 + * @G_REGEX_ERROR_MATCH: The match process failed.
8204 + * @G_REGEX_ERROR_INTERNAL: Internal error of the regular expression engine. Since 2.16
8205 + * @G_REGEX_ERROR_STRAY_BACKSLASH: "\\" at end of pattern. Since 2.16
8206 + * @G_REGEX_ERROR_MISSING_CONTROL_CHAR: "\\c" at end of pattern. Since 2.16
8207 + * @G_REGEX_ERROR_UNRECOGNIZED_ESCAPE: Unrecognized character follows "\\". Since 2.16
8208 + * @G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER: Numbers out of order in "{}" quantifier. Since 2.16
8209 + * @G_REGEX_ERROR_QUANTIFIER_TOO_BIG: Number too big in "{}" quantifier. Since 2.16
8210 + * @G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS: Missing terminating "]" for character class. Since 2.16
8211 + * @G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS: Invalid escape sequence in character class. Since 2.16
8212 + * @G_REGEX_ERROR_RANGE_OUT_OF_ORDER: Range out of order in character class. Since 2.16
8213 + * @G_REGEX_ERROR_NOTHING_TO_REPEAT: Nothing to repeat. Since 2.16
8214 + * @G_REGEX_ERROR_UNRECOGNIZED_CHARACTER: Unrecognized character after "(?", "(?<" or "(?P". Since 2.16
8215 + * @G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS: POSIX named classes are supported only within a class. Since 2.16
8216 + * @G_REGEX_ERROR_UNMATCHED_PARENTHESIS: Missing terminating ")" or ")" without opening "(". Since 2.16
8217 + * @G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE: Reference to non-existent subpattern. Since 2.16
8218 + * @G_REGEX_ERROR_UNTERMINATED_COMMENT: Missing terminating ")" after comment. Since 2.16
8219 + * @G_REGEX_ERROR_EXPRESSION_TOO_LARGE: Regular expression too large. Since 2.16
8220 + * @G_REGEX_ERROR_MEMORY_ERROR: Failed to get memory. Since 2.16
8221 + * @G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND: Lookbehind assertion is not fixed length. Since 2.16
8222 + * @G_REGEX_ERROR_MALFORMED_CONDITION: Malformed number or name after "(?(". Since 2.16
8223 + * @G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES: Conditional group contains more than two branches. Since 2.16
8224 + * @G_REGEX_ERROR_ASSERTION_EXPECTED: Assertion expected after "(?(". Since 2.16
8225 + * @G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME: Unknown POSIX class name. Since 2.16
8226 + * @G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED: POSIX collating elements are not supported. Since 2.16
8227 + * @G_REGEX_ERROR_HEX_CODE_TOO_LARGE: Character value in "\\x{...}" sequence is too large. Since 2.16
8228 + * @G_REGEX_ERROR_INVALID_CONDITION: Invalid condition "(?(0)". Since 2.16
8229 + * @G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND: \\C not allowed in lookbehind assertion. Since 2.16
8230 + * @G_REGEX_ERROR_INFINITE_LOOP: Recursive call could loop indefinitely. Since 2.16
8231 + * @G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR: Missing terminator in subpattern name. Since 2.16
8232 + * @G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME: Two named subpatterns have the same name. Since 2.16
8233 + * @G_REGEX_ERROR_MALFORMED_PROPERTY: Malformed "\\P" or "\\p" sequence. Since 2.16
8234 + * @G_REGEX_ERROR_UNKNOWN_PROPERTY: Unknown property name after "\\P" or "\\p". Since 2.16
8235 + * @G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG: Subpattern name is too long (maximum 32 characters). Since 2.16
8236 + * @G_REGEX_ERROR_TOO_MANY_SUBPATTERNS: Too many named subpatterns (maximum 10,000). Since 2.16
8237 + * @G_REGEX_ERROR_INVALID_OCTAL_VALUE: Octal value is greater than "\\377". Since 2.16
8238 + * @G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE: "DEFINE" group contains more than one branch. Since 2.16
8239 + * @G_REGEX_ERROR_DEFINE_REPETION: Repeating a "DEFINE" group is not allowed. Since 2.16
8240 + * @G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS: Inconsistent newline options. Since 2.16
8241 + * @G_REGEX_ERROR_MISSING_BACK_REFERENCE: "\\g" is not followed by a braced name or an
8242 + * optionally braced non-zero number. Since 2.16
8243 + *
8244 + * Error codes returned by regular expressions functions.
8245 + *
8246 + * Since: 2.14
8247 + */
8248 typedef enum
8249 {
8250 G_REGEX_ERROR_COMPILE,
8251 @@ -79,12 +129,78 @@
8252 G_REGEX_ERROR_MISSING_BACK_REFERENCE = 157
8253 } GRegexError;
8254
8255 +/**
8256 + * G_REGEX_ERROR:
8257 + *
8258 + * Error domain for regular expressions. Errors in this domain will be from the #GRegexError enumeration. See #GError for information on error domains.
8259 + *
8260 + * Since: 2.14
8261 + */
8262 #define G_REGEX_ERROR g_regex_error_quark ()
8263
8264 GQuark g_regex_error_quark (void);
8265
8266 /* Remember to update G_REGEX_COMPILE_MASK in gregex.c after
8267 * adding a new flag. */
8268 +/**
8269 + * GRegexCompileFlags:
8270 + * @G_REGEX_CASELESS: Letters in the pattern match both upper and lower case
8271 + * letters. It be changed within a pattern by a "(?i)" option setting.
8272 + * @G_REGEX_MULTILINE: By default, GRegex treats the strings as consisting
8273 + * of a single line of characters (even if it actually contains newlines).
8274 + * The "start of line" metacharacter ("^") matches only at the start of the
8275 + * string, while the "end of line" metacharacter ("$") matches only at the
8276 + * end of the string, or before a terminating newline (unless
8277 + * #G_REGEX_DOLLAR_ENDONLY is set). When #G_REGEX_MULTILINE is set,
8278 + * the "start of line" and "end of line" constructs match immediately following
8279 + * or immediately before any newline in the string, respectively, as well
8280 + * as at the very start and end. This can be changed within a pattern by a
8281 + * "(?m)" option setting.
8282 + * @G_REGEX_DOTALL: A dot metacharater (".") in the pattern matches all
8283 + * characters, including newlines. Without it, newlines are excluded. This
8284 + * option can be changed within a pattern by a ("?s") option setting.
8285 + * @G_REGEX_EXTENDED: Whitespace data characters in the pattern are
8286 + * totally ignored except when escaped or inside a character class.
8287 + * Whitespace does not include the VT character (code 11). In addition,
8288 + * characters between an unescaped "#" outside a character class and
8289 + * the next newline character, inclusive, are also ignored. This can be
8290 + * changed within a pattern by a "(?x)" option setting.
8291 + * @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is,
8292 + * it is constrained to match only at the first matching point in the string
8293 + * that is being searched. This effect can also be achieved by appropriate
8294 + * constructs in the pattern itself such as the "^" metacharater.
8295 + * @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern
8296 + * matches only at the end of the string. Without this option, a dollar also
8297 + * matches immediately before the final character if it is a newline (but
8298 + * not before any other newlines). This option is ignored if
8299 + * #G_REGEX_MULTILINE is set.
8300 + * @G_REGEX_UNGREEDY: Inverts the "greediness" of the
8301 + * quantifiers so that they are not greedy by default, but become greedy
8302 + * if followed by "?". It can also be set by a "(?U)" option setting within
8303 + * the pattern.
8304 + * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this
8305 + * flag they are considered as a raw sequence of bytes.
8306 + * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing
8307 + * parentheses in the pattern. Any opening parenthesis that is not followed
8308 + * by "?" behaves as if it were followed by "?:" but named parentheses can
8309 + * still be used for capturing (and they acquire numbers in the usual way).
8310 + * @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will
8311 + * be used many times, then it may be worth the effort to optimize it to
8312 + * improve the speed of matches.
8313 + * @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not
8314 + * be unique. This can be helpful for certain types of pattern when it is known
8315 + * that only one instance of the named subpattern can ever be matched.
8316 + * @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this
8317 + * option is set, the only recognized newline character is '\r'.
8318 + * @G_REGEX_NEWLINE_LF: Usually any newline character is recognized, if this
8319 + * option is set, the only recognized newline character is '\n'.
8320 + * @G_REGEX_NEWLINE_CRLF: Usually any newline character is recognized, if this
8321 + * option is set, the only recognized newline character sequence is '\r\n'.
8322 + *
8323 + * Flags specifying compile-time options.
8324 + *
8325 + * Since: 2.14
8326 + */
8327 typedef enum
8328 {
8329 G_REGEX_CASELESS = 1 << 0,
8330 @@ -105,6 +221,45 @@
8331
8332 /* Remember to update G_REGEX_MATCH_MASK in gregex.c after
8333 * adding a new flag. */
8334 +/**
8335 + * GRegexMatchFlags:
8336 + * @G_REGEX_MATCH_ANCHORED: The pattern is forced to be "anchored", that is,
8337 + * it is constrained to match only at the first matching point in the string
8338 + * that is being searched. This effect can also be achieved by appropriate
8339 + * constructs in the pattern itself such as the "^" metacharater.
8340 + * @G_REGEX_MATCH_NOTBOL: Specifies that first character of the string is
8341 + * not the beginning of a line, so the circumflex metacharacter should not
8342 + * match before it. Setting this without G_REGEX_MULTILINE (at compile time)
8343 + * causes circumflex never to match. This option affects only the behaviour of
8344 + * the circumflex metacharacter, it does not affect "\A".
8345 + * @G_REGEX_MATCH_NOTEOL: Specifies that the end of the subject string is
8346 + * not the end of a line, so the dollar metacharacter should not match it nor
8347 + * (except in multiline mode) a newline immediately before it. Setting this
8348 + * without G_REGEX_MULTILINE (at compile time) causes dollar never to match.
8349 + * This option affects only the behaviour of the dollar metacharacter, it does
8350 + * not affect "\Z" or "\z".
8351 + * @G_REGEX_MATCH_NOTEMPTY: An empty string is not considered to be a valid
8352 + * match if this option is set. If there are alternatives in the pattern, they
8353 + * are tried. If all the alternatives match the empty string, the entire match
8354 + * fails. For example, if the pattern "a?b?" is applied to a string not beginning
8355 + * with "a" or "b", it matches the empty string at the start of the string.
8356 + * With this flag set, this match is not valid, so GRegex searches further
8357 + * into the string for occurrences of "a" or "b".
8358 + * @G_REGEX_MATCH_PARTIAL: Turns on the partial matching feature, for more
8359 + * documentation on partial matching see g_regex_is_partial_match().
8360 + * @G_REGEX_MATCH_NEWLINE_CR: Overrides the newline definition set when creating
8361 + * a new #GRegex, setting the '\r' character as line terminator.
8362 + * @G_REGEX_MATCH_NEWLINE_LF: Overrides the newline definition set when creating
8363 + * a new #GRegex, setting the '\n' character as line terminator.
8364 + * @G_REGEX_MATCH_NEWLINE_CRLF: Overrides the newline definition set when creating
8365 + * a new #GRegex, setting the '\r\n' characters as line terminator.
8366 + * @G_REGEX_MATCH_NEWLINE_ANY: Overrides the newline definition set when creating
8367 + * a new #GRegex, any newline character or character sequence is recognized.
8368 + *
8369 + * Flags specifying match-time options.
8370 + *
8371 + * Since: 2.14
8372 + */
8373 typedef enum
8374 {
8375 G_REGEX_MATCH_ANCHORED = 1 << 4,
8376 @@ -118,9 +273,44 @@
8377 G_REGEX_MATCH_NEWLINE_ANY = 1 << 22
8378 } GRegexMatchFlags;
8379
8380 +
8381 +/**
8382 + * GRegex:
8383 + *
8384 + * A GRegex is the "compiled" form of a regular expression pattern. This
8385 + * structure is opaque and its fields cannot be accessed directly.
8386 + *
8387 + * Since: 2.14
8388 + */
8389 typedef struct _GRegex GRegex;
8390 +
8391 +/**
8392 + * GMatchInfo:
8393 + *
8394 + * #GMatchInfo is used to retrieve information about the regular expression match
8395 + * which created it.
8396 + * This structure is opaque and its fields cannot be accessed directly.
8397 + *
8398 + * Since: 2.14
8399 + */
8400 typedef struct _GMatchInfo GMatchInfo;
8401
8402 +/**
8403 + * GRegexEvalCallback:
8404 + * @match_info: the #GMatchInfo generated by the match.
8405 + * Use g_match_info_get_regex() and g_match_info_get_string() if you
8406 + * need the #GRegex or the matched string.
8407 + * @result: a #GString containing the new string
8408 + * @user_data: user data passed to g_regex_replace_eval()
8409 + *
8410 + * Specifies the type of the function passed to g_regex_replace_eval().
8411 + * It is called for each occurance of the pattern in the string passed
8412 + * to g_regex_replace_eval(), and it should append the replacement to
8413 + * @result.
8414 + *
8415 + * Since: 2.14
8416 + * Returns: %FALSE to continue the replacement process, %TRUE to stop it
8417 + */
8418 typedef gboolean (*GRegexEvalCallback) (const GMatchInfo *match_info,
8419 GString *result,
8420 gpointer user_data);
8421 Index: glib/gmem.h
8422 ===================================================================
8423 --- glib/gmem.h (revision 7087)
8424 +++ glib/gmem.h (working copy)
8425 @@ -36,9 +36,27 @@
8426
8427 G_BEGIN_DECLS
8428
8429 +/**
8430 + * GMemVTable:
8431 + * @malloc: function to use for allocating memory.
8432 + * @realloc: function to use for reallocating memory.
8433 + * @free: function to use to free memory.
8434 + * @calloc: function to use for allocating zero-filled memory.
8435 + * @try_malloc: function to use for allocating memory without a default error handler.
8436 + * @try_realloc: function to use for reallocating memory without a default error handler.
8437 + *
8438 + * A set of functions used to perform memory allocation. The same #GMemVTable must
8439 + * be used for all allocations in the same program; a call to g_mem_set_vtable(),
8440 + * if it exists, should be prior to any use of GLib.
8441 + */
8442 typedef struct _GMemVTable GMemVTable;
8443
8444 -
8445 +/**
8446 + * G_MEM_ALIGN:
8447 + *
8448 + * Indicates the number of bytes to which memory will be aligned on the
8449 + * current platform.
8450 + */
8451 #if GLIB_SIZEOF_VOID_P > GLIB_SIZEOF_LONG
8452 # define G_MEM_ALIGN GLIB_SIZEOF_VOID_P
8453 #else /* GLIB_SIZEOF_VOID_P <= GLIB_SIZEOF_LONG */
8454 @@ -61,17 +79,104 @@
8455
8456 /* Convenience memory allocators
8457 */
8458 +/**
8459 + * g_new:
8460 + * @struct_type: the type of the elements to allocate
8461 + * @n_structs: the number of elements to allocate
8462 + *
8463 + * Allocates @n_structs elements of type @struct_type.
8464 + * The returned pointer is cast to a pointer to the given type.
8465 + * If @n_structs is 0 it returns %NULL.
8466 + *
8467 + * Since the returned pointer is already casted to the right type,
8468 + * it is normally unnecessary to cast it explicitly, and doing
8469 + * so might hide memory allocation errors.
8470 + *
8471 + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
8472 + */
8473 #define g_new(struct_type, n_structs) \
8474 ((struct_type *) g_malloc (((gsize) sizeof (struct_type)) * ((gsize) (n_structs))))
8475 +
8476 +/**
8477 + * g_new0:
8478 + * @struct_type: the type of the elements to allocate.
8479 + * @n_structs: the number of elements to allocate.
8480 + *
8481 + * Allocates @n_structs elements of type @struct_type, initialized to 0's.
8482 + * The returned pointer is cast to a pointer to the given type.
8483 + * If @n_structs is 0 it returns %NULL.
8484 + *
8485 + * Since the returned pointer is already casted to the right type,
8486 + * it is normally unnecessary to cast it explicitly, and doing
8487 + * so might hide memory allocation errors.
8488 + *
8489 + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
8490 + */
8491 #define g_new0(struct_type, n_structs) \
8492 ((struct_type *) g_malloc0 (((gsize) sizeof (struct_type)) * ((gsize) (n_structs))))
8493 +
8494 +/**
8495 + * g_renew:
8496 + * @struct_type: the type of the elements to allocate
8497 + * @mem: the currently allocated memory
8498 + * @n_structs: the number of elements to allocate
8499 + *
8500 + * Reallocates the memory pointed to by @mem, so that it now has space for
8501 + * @n_structs elements of type @struct_type. It returns the new address of
8502 + * the memory, which may have been moved.
8503 + *
8504 + * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
8505 + */
8506 #define g_renew(struct_type, mem, n_structs) \
8507 ((struct_type *) g_realloc ((mem), ((gsize) sizeof (struct_type)) * ((gsize) (n_structs))))
8508 -
8509 +
8510 +/**
8511 + * g_try_new:
8512 + * @struct_type: the type of the elements to allocate
8513 + * @n_structs: the number of elements to allocate
8514 + *
8515 + * Attempts to allocate @n_structs elements of type @struct_type, and returns
8516 + * %NULL on failure. Contrast with g_new(), which aborts the program on failure.
8517 + * The returned pointer is cast to a pointer to the given type.
8518 + * If @n_structs is 0 it returns %NULL.
8519 + *
8520 + * Since: 2.8
8521 + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
8522 + */
8523 #define g_try_new(struct_type, n_structs) \
8524 ((struct_type *) g_try_malloc (((gsize) sizeof (struct_type)) * ((gsize) (n_structs))))
8525 +
8526 +/**
8527 + * g_try_new0:
8528 + * @struct_type: the type of the elements to allocate
8529 + * @n_structs: the number of elements to allocate
8530 + *
8531 + * Attempts to allocate @n_structs elements of type @struct_type, initialized
8532 + * to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts
8533 + * the program on failure.
8534 + * The returned pointer is cast to a pointer to the given type.
8535 + * The function returns %NULL when @n_structs is 0.
8536 + *
8537 + * Since: 2.8
8538 + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
8539 + */
8540 #define g_try_new0(struct_type, n_structs) \
8541 ((struct_type *) g_try_malloc0 (((gsize) sizeof (struct_type)) * ((gsize) (n_structs))))
8542 +
8543 +/**
8544 + * g_try_renew:
8545 + * @struct_type: the type of the elements to allocate
8546 + * @mem: the currently allocated memory
8547 + * @n_structs: the number of elements to allocate
8548 + *
8549 + * Attempts to reallocate the memory pointed to by @mem, so that it now has
8550 + * space for @n_structs elements of type @struct_type, and returns %NULL on
8551 + * failure. Contrast with g_renew(), which aborts the program on failure.
8552 + * It returns the new address of the memory, which may have been moved.
8553 + *
8554 + * Since: 2.8
8555 + * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
8556 + */
8557 #define g_try_renew(struct_type, mem, n_structs) \
8558 ((struct_type *) g_try_realloc ((mem), ((gsize) sizeof (struct_type)) * ((gsize) (n_structs))))
8559
8560 @@ -96,9 +201,21 @@
8561 void g_mem_set_vtable (GMemVTable *vtable);
8562 gboolean g_mem_is_system_malloc (void);
8563
8564 +/**
8565 + * g_mem_gc_friendly:
8566 + *
8567 + * This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable
8568 + * includes the key <link linkend="G_DEBUG">gc-friendly</link>.
8569 + */
8570 GLIB_VAR gboolean g_mem_gc_friendly;
8571
8572 -/* Memory profiler and checker, has to be enabled via g_mem_set_vtable()
8573 +/**
8574 + * glib_mem_profiler_table:
8575 + *
8576 + * A #GMemVTable containing profiling variants of the memory
8577 + * allocation functions. Use them together with g_mem_profile()
8578 + * in order to get information about the memory allocation pattern
8579 + * of your program. This must be set by g_mem_set_vtable().
8580 */
8581 GLIB_VAR GMemVTable *glib_mem_profiler_table;
8582 void g_mem_profile (void);
8583 @@ -106,24 +223,113 @@
8584
8585 /* deprecated memchunks and allocators */
8586 #if !defined (G_DISABLE_DEPRECATED) || defined (GTK_COMPILATION) || defined (GDK_COMPILATION)
8587 +/**
8588 + * GAllocator:
8589 + *
8590 + * The <structname>GAllocator</structname> struct contains private data. and
8591 + * should only be accessed using the following functions.
8592 + */
8593 typedef struct _GAllocator GAllocator;
8594 +
8595 +/**
8596 + * GMemChunk:
8597 + *
8598 + * The #GMemChunk struct is an opaque data structure representing a memory
8599 + * chunk. It should be accessed only through the use of the following functions.
8600 + */
8601 typedef struct _GMemChunk GMemChunk;
8602 +
8603 +
8604 +/**
8605 + * g_mem_chunk_create:
8606 + * @type: the type of the atoms, typically a structure name.
8607 + * @pre_alloc: the number of atoms to store in each block of memory.
8608 + * @alloc_type: the type of the #GMemChunk.
8609 + * #G_ALLOC_AND_FREE is used if the atoms will be freed individually.
8610 + * #G_ALLOC_ONLY should be used if atoms will never be freed individually.
8611 + * #G_ALLOC_ONLY is quicker, since it does not need to track free atoms,
8612 + * but it obviously wastes memory if you no longer need many of the atoms.
8613 + *
8614 + * A convenience macro for creating a new #GMemChunk.
8615 + * It calls g_mem_chunk_new(), using the given type to create the #GMemChunk
8616 + * name. The atom size is determined using <function>sizeof()</function>, and the
8617 + * area size is calculated by multiplying the @pre_alloc parameter with
8618 + * the atom size.
8619 + *
8620 + * Deprecated: 2.10: Use the <link linkend="glib-Memory-Slices">slice
8621 + * allocator</link> instead
8622 + * Returns: the new #GMemChunk.
8623 + */
8624 #define g_mem_chunk_create(type, pre_alloc, alloc_type) ( \
8625 g_mem_chunk_new (#type " mem chunks (" #pre_alloc ")", \
8626 sizeof (type), \
8627 sizeof (type) * (pre_alloc), \
8628 (alloc_type)) \
8629 )
8630 +
8631 +/**
8632 + * g_chunk_new:
8633 + * @type: the type of the #GMemChunk atoms, typically a structure name.
8634 + * @chunk: a #GMemChunk.
8635 + *
8636 + * A convenience macro to allocate an atom of memory from a #GMemChunk.
8637 + * It calls g_mem_chunk_alloc() and casts the returned atom to a pointer to
8638 + * the given type, avoiding a type cast in the source code.
8639 + *
8640 + * Deprecated: 2.10: Use g_slice_new() instead
8641 + * Returns: a pointer to the allocated atom, cast to a pointer to @type.
8642 + */
8643 #define g_chunk_new(type, chunk) ( \
8644 (type *) g_mem_chunk_alloc (chunk) \
8645 )
8646 +
8647 +/**
8648 + * g_chunk_new0:
8649 + * @type: the type of the #GMemChunk atoms, typically a structure name.
8650 + * @chunk: a #GMemChunk.
8651 + *
8652 + * A convenience macro to allocate an atom of memory from a #GMemChunk.
8653 + * It calls g_mem_chunk_alloc0() and casts the returned atom to a pointer to
8654 + * the given type, avoiding a type cast in the source code.
8655 + *
8656 + * Deprecated: 2.10: Use g_slice_new0() instead
8657 + * Returns: a pointer to the allocated atom, cast to a pointer to @type.
8658 + */
8659 #define g_chunk_new0(type, chunk) ( \
8660 (type *) g_mem_chunk_alloc0 (chunk) \
8661 )
8662 +/**
8663 + * g_chunk_free:
8664 + * @mem: a pointer to the atom to be freed.
8665 + * @mem_chunk: a #GMemChunk.
8666 + *
8667 + * A convenience macro to free an atom of memory from a #GMemChunk.
8668 + * It simply switches the arguments and calls g_mem_chunk_free()
8669 + * It is included simply to complement the other convenience macros, g_chunk_new()
8670 + * and g_chunk_new0().
8671 + *
8672 + * Deprecated: 2.10: Use g_slice_free() instead
8673 + */
8674 #define g_chunk_free(mem, mem_chunk) G_STMT_START { \
8675 g_mem_chunk_free ((mem_chunk), (mem)); \
8676 } G_STMT_END
8677 +
8678 +/**
8679 + * G_ALLOC_ONLY:
8680 + *
8681 + * Specifies the type of a #GMemChunk.
8682 + * Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms
8683 + * will never be freed individually.
8684 + */
8685 #define G_ALLOC_ONLY 1
8686 +
8687 +/**
8688 + * G_ALLOC_AND_FREE:
8689 + *
8690 + * Specifies the type of a #GMemChunk.
8691 + * Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms
8692 + * will be freed individually.
8693 + */
8694 #define G_ALLOC_AND_FREE 2
8695 GMemChunk* g_mem_chunk_new (const gchar *name,
8696 gint atom_size,
Attached Files
To refer to attachments on a page, use attachment:filename, as shown below in the list of files. Do NOT use the URL of the [get] link, since this is subject to change and can break easily.You are not allowed to attach a file to this page.