From abf9f5f8f852d7abf53097865fa8427dac74a3ff Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 30 Sep 2001 22:49:01 +0000 Subject: [PATCH] glib/tmpl/arrays.sgml,glib/tmpl/arrays_byte.sgml glib/tmpl/arrays_pointer.sgml, glib/tmpl/caches.sgml, glib/tmpl/datalist.sgml, glib/tmpl/date.sgml, glib/tmpl/datasets.sgml, glib/tmpl/type_conversion.sgml, glib/tmpl/memory.sgml, glib/tmpl/hash_tables.sgml: Markup fixes and a few additions. --- docs/reference/ChangeLog | 9 + docs/reference/glib/tmpl/arrays.sgml | 35 +- docs/reference/glib/tmpl/arrays_byte.sgml | 21 +- docs/reference/glib/tmpl/arrays_pointer.sgml | 25 +- docs/reference/glib/tmpl/caches.sgml | 16 +- docs/reference/glib/tmpl/datalist.sgml | 12 +- docs/reference/glib/tmpl/datasets.sgml | 4 +- docs/reference/glib/tmpl/date.sgml | 775 +++++++++++++------------- docs/reference/glib/tmpl/hash_tables.sgml | 26 +- docs/reference/glib/tmpl/memory.sgml | 117 ++-- docs/reference/glib/tmpl/type_conversion.sgml | 24 +- 11 files changed, 530 insertions(+), 534 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index e07713b..76cdcbd 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,12 @@ +2001-09-30 Matthias Clasen + + * glib/tmpl/arrays.sgml,glib/tmpl/arrays_byte.sgml + glib/tmpl/arrays_pointer.sgml, glib/tmpl/caches.sgml, + glib/tmpl/datalist.sgml, glib/tmpl/date.sgml, + glib/tmpl/datasets.sgml, glib/tmpl/type_conversion.sgml, + glib/tmpl/memory.sgml, glib/tmpl/hash_tables.sgml: + Markup fixes and a few additions. + 2001-09-27 Matthias Clasen * glib/tmpl/macros.sgml, glib/tmpl/macros_misc.sgml, diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml index 981ee5b..fa88905 100644 --- a/docs/reference/glib/tmpl/arrays.sgml +++ b/docs/reference/glib/tmpl/arrays.sgml @@ -69,9 +69,9 @@ added to the #GArray. Creates a new #GArray. -@zero_terminated: TRUE if the array should have an extra element at the end -which is set to '0'. -@clear: TRUE if #GArray elements should be automatically cleared to '0' +@zero_terminated: %TRUE if the array should have an extra element at the end +which is set to 0. +@clear: %TRUE if #GArray elements should be automatically cleared to 0 when they are allocated. @element_size: the size of each element in bytes. @Returns: the new #GArray. @@ -85,11 +85,11 @@ add many elements to the array. Note however that the size of the array is still 0. -@zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared -@clear: %TRUE if all bits in the array should be cleared to 0 on allocation -@element_size: size of each element in the array -@reserved_size: number of elements preallocated -@Returns: the new #GArray +@zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared. +@clear: %TRUE if all bits in the array should be cleared to 0 on allocation. +@element_size: size of each element in the array. +@reserved_size: number of elements preallocated. +@Returns: the new #GArray. @@ -214,13 +214,13 @@ g_array_remove_index(). -Sorts a #GArray using @compare_func which should be a qsort()-style comparison +Sorts a #GArray using @compare_func which should be a qsort()-style comparison function (returns -1 for first arg is less than second arg, 0 for equal, 1 if first arg is greater than second arg). -@array: a #GArray -@compare_func: comparison function +@array: a #GArray. +@compare_func: comparison function. @@ -229,9 +229,9 @@ Like g_array_sort(), but the comparison function receives a user data argument. -@array: a #GArray -@compare_func: a comparison function -@user_data: data to pass to @compare_func +@array: a #GArray. +@compare_func: comparison function. +@user_data: data to pass to @compare_func. @@ -260,7 +260,7 @@ The return value is cast to the given type. Sets the size of the array, expanding it if necessary. -If the array was created with clear set to TRUE, the new elements are set to 0. +If the array was created with @clear set to %TRUE, the new elements are set to 0. @array: a #GArray. @@ -271,11 +271,10 @@ If the array was created with clear set to TRUE, the new elements are set to 0. Frees the memory allocated for the #GArray. -If free_segment is TRUE it frees the actual element data as well. +If @free_segment is %TRUE it frees the actual element data as well. @array: a #GArray. -@free_segment: if TRUE the actual element data is freed as well. -@Returns: +@free_segment: if %TRUE the actual element data is freed as well. diff --git a/docs/reference/glib/tmpl/arrays_byte.sgml b/docs/reference/glib/tmpl/arrays_byte.sgml index 340f03a..4ba9330 100644 --- a/docs/reference/glib/tmpl/arrays_byte.sgml +++ b/docs/reference/glib/tmpl/arrays_byte.sgml @@ -73,8 +73,8 @@ avoids frequent reallocation, if you are going to add many bytes to the array. Note however that the size of the array is still 0. -@reserved_size: number of bytes preallocated -@Returns: the new #GByteArray +@reserved_size: number of bytes preallocated. +@Returns: the new #GByteArray. @@ -127,13 +127,13 @@ g_byte_array_remove_index(). -Sorts a byte array, using @compare_func which should be a qsort()-style +Sorts a byte array, using @compare_func which should be a qsort()-style comparison function (returns -1 for first arg is less than second arg, 0 for equal, 1 if first arg is greater than second arg). -@array: array to sort -@compare_func: comparison function +@array: a #GByteArray. +@compare_func: comparison function. @@ -141,9 +141,9 @@ equal, 1 if first arg is greater than second arg). Like g_byte_array_sort(), but the comparison function takes a user data argument. -@array: a #GByteArray -@compare_func: comparison function -@user_data: data to pass to @compare_func +@array: a #GByteArray. +@compare_func: comparison function. +@user_data: data to pass to @compare_func. @@ -159,11 +159,10 @@ Sets the size of the #GByteArray, expanding it if necessary. Frees the memory allocated by the #GByteArray. -If free_segment is TRUE it frees the actual byte data. +If free_segment is %TRUE it frees the actual byte data. @array: a #GByteArray. -@free_segment: if TRUE the actual byte data is freed as well. -@Returns: +@free_segment: if %TRUE the actual byte data is freed as well. diff --git a/docs/reference/glib/tmpl/arrays_pointer.sgml b/docs/reference/glib/tmpl/arrays_pointer.sgml index 35c3d79..48f443c 100644 --- a/docs/reference/glib/tmpl/arrays_pointer.sgml +++ b/docs/reference/glib/tmpl/arrays_pointer.sgml @@ -108,13 +108,13 @@ Removes the first occurrence of the given pointer from the pointer array. The following elements are moved down one place. -It returns TRUE if the pointer was removed, or FALSE if the pointer +It returns %TRUE if the pointer was removed, or %FALSE if the pointer was not found. @array: a #GPtrArray. @data: the pointer to remove. -@Returns: TRUE if the pointer is removed. FALSE if the pointer is not found +@Returns: %TRUE if the pointer is removed. %FALSE if the pointer is not found in the array. @@ -137,13 +137,13 @@ does not preserve the order of the array. But it is faster than g_ptr_array_remove(). -It returns TRUE if the pointer was removed, or FALSE if the pointer +It returns %TRUE if the pointer was removed, or %FALSE if the pointer was not found. @array: a #GPtrArray. @data: the pointer to remove. -@Returns: TRUE if the pointer was found in the array. +@Returns: %TRUE if the pointer was found in the array. @@ -161,13 +161,13 @@ g_ptr_array_remove_index(). -Sorts the array, using @compare_func which should be a qsort()-style comparison +Sorts the array, using @compare_func which should be a qsort()-style comparison function (returns -1 for first arg is less than second arg, 0 for equal, 1 if first arg is greater than second arg). -@array: array to sort -@compare_func: comparison function +@array: a #GPtrArray. +@compare_func: comparison function. @@ -175,15 +175,15 @@ first arg is greater than second arg). Like g_ptr_array_sort(), but the comparison function has a user data argument. -@array: array to sort -@compare_func: qsort()-style comparison function -@user_data: data to pass to @compare_func +@array: a #GPtrArray. +@compare_func: comparison function. +@user_data: data to pass to @compare_func. Sets the size of the array, expanding it if necessary. -New elements are set to NULL. +New elements are set to %NULL. @array: a #GPtrArray. @@ -206,7 +206,6 @@ Frees all of the memory allocated for the pointer array. @array: a #GPtrArray. -@free_seg: if TRUE the actual element data is freed as well. -@Returns: +@free_seg: if %TRUE the actual element data is freed as well. diff --git a/docs/reference/glib/tmpl/caches.sgml b/docs/reference/glib/tmpl/caches.sgml index 0cc4d79..8c00ae5 100644 --- a/docs/reference/glib/tmpl/caches.sgml +++ b/docs/reference/glib/tmpl/caches.sgml @@ -2,7 +2,7 @@ Caches -allows sharing of complex data structures to save resources. +caches allow sharing of complex data structures to save resources. @@ -35,7 +35,7 @@ a #GCache. It should only be accesssed via the following functions. -Creates a new GCache. +Creates a new #GCache. @value_new_func: a function to create a new object given a key. @@ -45,17 +45,15 @@ does not already exist. called by g_cache_remove() when the object is no longer needed (i.e. its reference count drops to 0). @key_dup_func: a function to copy a key. It is called by -g_cache_insert() if the key does not already exist in the GCache. +g_cache_insert() if the key does not already exist in the #GCache. @key_destroy_func: a function to destroy a key. It is called by g_cache_remove() when the object is no longer needed (i.e. its reference count drops to 0). @hash_key_func: a function to create a hash value from a key. @hash_value_func: a function to create a hash value from a value. -@key_equal_func: a function to compare two keys. It should return TRUE if +@key_equal_func: a function to compare two keys. It should return %TRUE if the two keys are equivalent. @Returns: a new #GCache. - -@key_compare_func: @@ -96,7 +94,7 @@ Note that it does not destroy the keys and values which were contained in the GCache. -@cache: +@cache: a #GCache. @@ -133,11 +131,11 @@ should free any memory and other resources associated with it. Specifies the type of the @key_dup_func function passed to g_cache_new(). -The function is passed a key (NOT a value as the prototype implies) and +The function is passed a key (not a value as the prototype implies) and should return a duplicate of the key. -@value: the #GCache key to destroy (NOT a #GCache value as it seems). +@value: the #GCache key to destroy (not a #GCache value as it seems). @Returns: a copy of the #GCache key. diff --git a/docs/reference/glib/tmpl/datalist.sgml b/docs/reference/glib/tmpl/datalist.sgml index 025c5f4..bb15c58 100644 --- a/docs/reference/glib/tmpl/datalist.sgml +++ b/docs/reference/glib/tmpl/datalist.sgml @@ -10,8 +10,8 @@ Keyed data lists provide lists of arbitrary data elements which can be accessed either with a string or with a #GQuark corresponding to the string. -The GQuark methods are quicker, since the strings have to be converted to -GQuarks anyway. +The #GQuark methods are quicker, since the strings have to be converted to +#GQuarks anyway. Data lists are used in GTK for associating arbitrary data with @@ -56,7 +56,7 @@ It should only be accessed via the following functions. -Resets the datalist to NULL. +Resets the datalist to %NULL. It does not free any memory or call any destroy functions. @@ -98,7 +98,7 @@ Gets a data element. @datalist: a datalist. @key_id: the #GQuark identifying a data element. -@Returns: the data element, or NULL if it is not found. +@Returns: the data element, or %NULL if it is not found. @@ -117,7 +117,7 @@ Removes an element, without calling its destroy notification function. @datalist: a datalist. @key_id: the #GQuark identifying a data element. -@Returns: the data previously stored at @key_id, or %NULL if none +@Returns: the data previously stored at @key_id, or %NULL if none. @@ -153,7 +153,7 @@ converted to a #GQuark. @dl: a datalist. @k: the string identifying a data element. -@Returns: the data element, or NULL if it is not found. +@Returns: the data element, or %NULL if it is not found. diff --git a/docs/reference/glib/tmpl/datasets.sgml b/docs/reference/glib/tmpl/datasets.sgml index b6329b2..1afdf6c 100644 --- a/docs/reference/glib/tmpl/datasets.sgml +++ b/docs/reference/glib/tmpl/datasets.sgml @@ -94,7 +94,7 @@ Gets the data element corresponding to a #GQuark. @dataset_location: the location identifying the dataset. @key_id: the #GQuark id to identify the data element. -@Returns: the data element corresponding to the #GQuark, or NULL if it is +@Returns: the data element corresponding to the #GQuark, or %NULL if it is not found. @@ -149,7 +149,7 @@ Gets the data element corresponding to a string. @l: the location identifying the dataset. @k: the string identifying the data element. -@Returns: the data element corresponding to the string, or NULL if it is not +@Returns: the data element corresponding to the string, or %NULL if it is not found. diff --git a/docs/reference/glib/tmpl/date.sgml b/docs/reference/glib/tmpl/date.sgml index 7d65991..ad739e7 100644 --- a/docs/reference/glib/tmpl/date.sgml +++ b/docs/reference/glib/tmpl/date.sgml @@ -5,62 +5,62 @@ Date and Time Functions calendrical calculations and miscellaneous time stuff. - -The #GDate data structure represents a day between January 1, Year 1, -and sometime a few thousand years in the future (right now it will go -to the year 65535 or so, but g_date_set_parse() only parses up to the -year 8000 or so - just count on "a few thousand"). #GDate is meant to -represent everyday dates, not astronomical dates or historical dates -or ISO timestamps or the like. It extrapolates the current Gregorian -calendar forward and backward in time; there is no attempt to change -the calendar to match time periods or locations. #GDate does not store -time information; it represents a day. - - - -The #GDate implementation has several nice features; it is only a -64-bit struct, so storing large numbers of dates is very efficient. It -can keep both a Julian and Day-Month-Year representation of the date, -since some calculations are much easier with one representation or the -other. A Julian representation is simply a count of days since some -fixed day in the past; for #GDate the fixed day is January 1, 1 AD. -("Julian" dates in the #GDate API aren't really Julian dates in the -technical sense; technically, Julian dates count from the start of the -Julian period, Jan 1, 4713 BC). - - - -#GDate is simple to use. First you need a "blank" date; you can get a -dynamically allocated date from g_date_new(), or you can declare an -automatic variable or array and initialize it to a sane state by -calling g_date_clear(). A cleared date is sane; it's safe to call -g_date_set_dmy() and the other mutator functions to initialize the -value of a cleared date. However, a cleared date is initially -invalid, meaning that it doesn't represent a day -that exists. It is undefined to call any of the date calculation -routines on an invalid date. If you obtain a date from a user or other -unpredictable source, you should check its validity with the -g_date_valid() predicate. g_date_valid() is also used to check for -errors with g_date_set_parse() and other functions that can -fail. Dates can be invalidated by calling g_date_clear() again. - - - -It is very important to use the API to access the #GDate -struct. Often only the DMY or only the Julian -representation is valid. Sometimes neither is valid. Use the API. - - - -glib doesn't contain any time-manipulation functions; however, there -is a #GTime typedef which is equivalent to time_t, and a #GTimeVal -struct which represents a more precise time (with microseconds). You -can request the current time as a #GTimeVal with g_get_current_time(). + +The #GDate data structure represents a day between January 1, Year 1, +and sometime a few thousand years in the future (right now it will go +to the year 65535 or so, but g_date_set_parse() only parses up to the +year 8000 or so - just count on "a few thousand"). #GDate is meant to +represent everyday dates, not astronomical dates or historical dates +or ISO timestamps or the like. It extrapolates the current Gregorian +calendar forward and backward in time; there is no attempt to change +the calendar to match time periods or locations. #GDate does not store +time information; it represents a day. + + + +The #GDate implementation has several nice features; it is only a +64-bit struct, so storing large numbers of dates is very efficient. It +can keep both a Julian and Day-Month-Year representation of the date, +since some calculations are much easier with one representation or the +other. A Julian representation is simply a count of days since some +fixed day in the past; for #GDate the fixed day is January 1, 1 AD. +("Julian" dates in the #GDate API aren't really Julian dates in the +technical sense; technically, Julian dates count from the start of the +Julian period, Jan 1, 4713 BC). + + + +#GDate is simple to use. First you need a "blank" date; you can get a +dynamically allocated date from g_date_new(), or you can declare an +automatic variable or array and initialize it to a sane state by +calling g_date_clear(). A cleared date is sane; it's safe to call +g_date_set_dmy() and the other mutator functions to initialize the +value of a cleared date. However, a cleared date is initially +invalid, meaning that it doesn't represent a day +that exists. It is undefined to call any of the date calculation +routines on an invalid date. If you obtain a date from a user or other +unpredictable source, you should check its validity with the +g_date_valid() predicate. g_date_valid() is also used to check for +errors with g_date_set_parse() and other functions that can +fail. Dates can be invalidated by calling g_date_clear() again. + + + +It is very important to use the API to access the #GDate +struct. Often only the DMY or only the Julian +representation is valid. Sometimes neither is valid. Use the API. + + + +GLib doesn't contain any time-manipulation functions; however, there +is a #GTime typedef which is equivalent to time_t, and a #GTimeVal +struct which represents a more precise time (with microseconds). You +can request the current time as a #GTimeVal with g_get_current_time(). - - + + @@ -72,22 +72,22 @@ code readability. - -Represents a precise time, with seconds and microseconds. Same as the -struct timeval returned by the -gettimeofday() UNIX call. + +Represents a precise time, with seconds and microseconds. Same as the +struct timeval returned by the +gettimeofday() UNIX call. -@tv_sec: -@tv_usec: +@tv_sec: seconds. +@tv_usec: microseconds. - -Equivalent to gettimeofday(), but also works on -Win32. Returns the current time. + +Equivalent to gettimeofday(), but also works on +Win32. Returns the current time. -@result: +@result: @@ -98,7 +98,7 @@ may have limited precision, depending on hardware and operating system; don't rely on the exact length of the sleep. -@microseconds: number of microseconds to pause +@microseconds: number of microseconds to pause. @@ -111,16 +111,16 @@ rely on the exact length of the sleep. - -Represents a day between January 1, Year 1 and a few thousand years in -the future. None of its members should be accessed directly. If the -GDate is obtained from g_date_new(), it will -be safe to mutate but invalid and thus not safe for calendrical computations. -If it's declared on the stack, it will contain garbage so must be -initialized with g_date_clear(). g_date_clear() makes the date invalid -but sane. An invalid date doesn't represent a day, it's "empty." A -date becomes valid after you set it to a Julian day or you set a day, -month, and year. + +Represents a day between January 1, Year 1 and a few thousand years in +the future. None of its members should be accessed directly. If the +GDate is obtained from g_date_new(), it will +be safe to mutate but invalid and thus not safe for calendrical computations. +If it's declared on the stack, it will contain garbage so must be +initialized with g_date_clear(). g_date_clear() makes the date invalid +but sane. An invalid date doesn't represent a day, it's "empty." A +date becomes valid after you set it to a Julian day or you set a day, +month, and year. @julian_days: @@ -131,15 +131,15 @@ month, and year. @year: - -Simply a replacement for time_t. Unrelated to GTimer. + +Simply a replacement for time_t. Unrelated to #GTimer. - -This enumeration isn't used in the API, but may be useful if you need -to mark a number as a day, month, or year. + +This enumeration isn't used in the API, but may be useful if you need +to mark a number as a day, month, or year. @G_DATE_DAY: @@ -147,571 +147,572 @@ to mark a number as a day, month, or year. @G_DATE_YEAR: - -Integer representing a day of the month; between 1 and -31. #G_DATE_BAD_DAY represents an invalid day of the month. + +Integer representing a day of the month; between 1 and +31. #G_DATE_BAD_DAY represents an invalid day of the month. - -Enumeration representing a month; values are #G_DATE_JANUARY, -#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the "invalid" value. - - -@G_DATE_BAD_MONTH: -@G_DATE_JANUARY: -@G_DATE_FEBRUARY: -@G_DATE_MARCH: -@G_DATE_APRIL: -@G_DATE_MAY: -@G_DATE_JUNE: -@G_DATE_JULY: -@G_DATE_AUGUST: -@G_DATE_SEPTEMBER: -@G_DATE_OCTOBER: -@G_DATE_NOVEMBER: -@G_DATE_DECEMBER: + +Enumeration representing a month; values are #G_DATE_JANUARY, +#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value. + + +@G_DATE_BAD_MONTH: invalid value. +@G_DATE_JANUARY: January. +@G_DATE_FEBRUARY: February. +@G_DATE_MARCH: March. +@G_DATE_APRIL: April. +@G_DATE_MAY: May. +@G_DATE_JUNE: June. +@G_DATE_JULY: July. +@G_DATE_AUGUST: August. +@G_DATE_SEPTEMBER: September. +@G_DATE_OCTOBER: October. +@G_DATE_NOVEMBER: November. +@G_DATE_DECEMBER: December. - -Integer representing a year; #G_DATE_BAD_YEAR is the invalid -value. The year must be 1 or higher; negative (BC) years are not -allowed. The year is represented with four digits. + +Integer representing a year; #G_DATE_BAD_YEAR is the invalid +value. The year must be 1 or higher; negative (BC) years are not +allowed. The year is represented with four digits. - -Enumeration representing a day of the week; #G_DATE_MONDAY, -#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday. + +Enumeration representing a day of the week; #G_DATE_MONDAY, +#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday. -@G_DATE_BAD_WEEKDAY: -@G_DATE_MONDAY: -@G_DATE_TUESDAY: -@G_DATE_WEDNESDAY: -@G_DATE_THURSDAY: -@G_DATE_FRIDAY: -@G_DATE_SATURDAY: -@G_DATE_SUNDAY: +@G_DATE_BAD_WEEKDAY: invalid value. +@G_DATE_MONDAY: Monday. +@G_DATE_TUESDAY: Tuesday. +@G_DATE_WEDNESDAY: Wednesday. +@G_DATE_THURSDAY: Thursday. +@G_DATE_FRIDAY: Friday. +@G_DATE_SATURDAY: Saturday. +@G_DATE_SUNDAY: Sunday. - -Represents an invalid #GDateDay. + +Represents an invalid #GDateDay. - -Represents an invalid Julian day number. + +Represents an invalid Julian day number. - -Represents an invalid year. + +Represents an invalid year. - -Allocate a #GDate and initialize it to a sane state. The new date will -be cleared (as if you'd called g_date_clear()) but invalid (it won't -represent an existing day). Free the return value with g_date_free(). + +Allocates a #GDate and initializes it to a sane state. The new date will +be cleared (as if you'd called g_date_clear()) but invalid (it won't +represent an existing day). Free the return value with g_date_free(). -@Returns: The newly-allocated #GDate +@Returns: a newly-allocated #GDate. - -Like g_date_new(), but also sets the value of the date. Assuming the -day/month/year triplet you pass in represents an existing day, the -returned date will be valid. + +Like g_date_new(), but also sets the value of the date. Assuming the +day/month/year triplet you pass in represents an existing day, the +returned date will be valid. -@day: Day of the month -@month: Month of the year -@year: Year -@Returns: Allocated date initialized with @day, @month, and @year +@day: day of the month. +@month: month of the year. +@year: year +@Returns: a newly-allocated #GDate initialized with @day, @month, and @year. - -Like g_date_new(), but also sets the value of the date. Assuming the -Julian day number you pass in is valid (greater than 0, less than an -unreasonably large number), the returned date will be valid. + +Like g_date_new(), but also sets the value of the date. Assuming the +Julian day number you pass in is valid (greater than 0, less than an +unreasonably large number), the returned date will be valid. -@julian_day: Days since January 1, Year 1 -@Returns: Allocated date initialized with @julian_day +@julian_day: days since January 1, Year 1. +@Returns: a newly-allocated #GDate initialized with @julian_day. - -Initialize one or more #GDate structs to a sane but invalid -state. The cleared dates will not represent an existing date, but will -not contain garbage. Useful to init a date declared on the stack. -Validity can be tested with g_date_valid(). + +Initializes one or more #GDate structs to a sane but invalid +state. The cleared dates will not represent an existing date, but will +not contain garbage. Useful to init a date declared on the stack. +Validity can be tested with g_date_valid(). -@date: Pointer to one or more dates to clear -@n_dates: Number of dates to clear +@date: pointer to one or more dates to clear. +@n_dates: number of dates to clear. - -Free a #GDate returned from g_date_new() + +Frees a #GDate returned from g_date_new(). -@date: Date to free +@date: a #GDate. - -Set the day of the month for a #GDate. If the resulting day-month-year -triplet is invalid, the date will be invalid. + +Sets the day of the month for a #GDate. If the resulting day-month-year +triplet is invalid, the date will be invalid. -@date: Date to set the day for -@day: Day to set +@date: a #GDate. +@day: day to set. - -Set the month of the year for a #GDate. If the resulting - day-month-year triplet is invalid, the date will be invalid. + +Sets the month of the year for a #GDate. If the resulting +day-month-year triplet is invalid, the date will be invalid. -@date: Date -@month: Month to set +@date: a #GDate. +@month: month to set. - -Set the year for a #GDate. If the resulting day-month-year triplet is - invalid, the date will be invalid. + +Sets the year for a #GDate. If the resulting day-month-year triplet is +invalid, the date will be invalid. -@date: Date -@year: Year to set +@date: a #GDate. +@year: year to set. - -Set the value of a #GDate from a day, month, and year. The DMY triplet -must be valid; if you aren't sure it is, call g_date_valid_dmy() to -check before you set it. + +Sets the value of a #GDate from a day, month, and year. The day-month-year +triplet must be valid; if you aren't sure it is, call g_date_valid_dmy() to +check before you set it. -@date: Date to set the value of -@day: Day -@month: Month -@y: Year +@date: a #GDate. +@day: day. +@month: month. +@y: year. - -Set the value of a #GDate from a Julian day number. + +Sets the value of a #GDate from a Julian day number. -@date: Date to set -@julian_date: Julian day number (days since January 1, Year 1) +@date: a #GDate. +@julian_date: Julian day number (days since January 1, Year 1). - -Set the value of a date from a #GTime (time_t) value. To set the value -of a date to the current day, you could write: - - g_date_set_time(date, time(NULL)); - + +Sets the value of a date from a #GTime (time_t) value. +To set the value of a date to the current day, you could write: + +g_date_set_time(date, time(NULL)); + -@date: Date to update -@time: #GTime value to set +@date: a #GDate. +@time: #GTime value to set. - -Parse a user-inputted string @str, and try to figure out what date it -represents, taking the current locale into account. If the string is -successfully parsed, the date will be valid after the call. Otherwise, -it will be invalid. You should check using g_date_valid() to see -whether the parsing succeeded. - - - -This function is not appropriate for file formats and the like; it -isn't very precise, and its exact behavior varies with the -locale. It's intended to be a heuristic routine that guesses what the -user means by a given string (and it does work pretty well in that -capacity). - - -@date: Date to fill in -@str: String to parse + +Parses a user-inputted string @str, and try to figure out what date it +represents, taking the current locale into account. If the string is +successfully parsed, the date will be valid after the call. Otherwise, +it will be invalid. You should check using g_date_valid() to see +whether the parsing succeeded. + + + +This function is not appropriate for file formats and the like; it +isn't very precise, and its exact behavior varies with the +locale. It's intended to be a heuristic routine that guesses what the +user means by a given string (and it does work pretty well in that +capacity). + + +@date: a #GDate to fill in. +@str: string to parse. - -Increment a date some number of days. To move forward by weeks, add -weeks*7 days. The date must be valid. + +Increments a date some number of days. To move forward by weeks, add +weeks*7 days. The date must be valid. -@date: The date to increment -@n_days: Number of days to move the date forward +@date: a #GDate to increment. +@n_days: number of days to move the date forward. - -Move a date some number of days into the past. To move by weeks, just -move by weeks*7 days. Date must be valid. + +Moves a date some number of days into the past. To move by weeks, just +move by weeks*7 days. The date must be valid. -@date: Date to decrement -@n_days: Number of days to move +@date: a #GDate to decrement. +@n_days: number of days to move. - -Increment a date by some number of months. If the day of the month is -greater than 28, this routine may change the day of the month (because -the destination month may not have the current day in it). The date -must be valid. + +Increments a date by some number of months. If the day of the month is +greater than 28, this routine may change the day of the month (because +the destination month may not have the current day in it). The date +must be valid. -@date: Date to increment -@n_months: Number of months to move forward +@date: a #GDate to increment. +@n_months: number of months to move forward. - -Move a date some number of months into the past. If the current day of -the month doesn't exist in the destination month, the day of the month -may change. Date must be valid. + +Moves a date some number of months into the past. If the current day of +the month doesn't exist in the destination month, the day of the month +may change. The date must be valid. -@date: Date to decrement -@n_months: Number of months to move +@date: a #GDate to decrement. +@n_months: number of months to move. - -Increment a date by some number of years. If the date is February 29, -and the destination year is not a leap year, the date will be changed -to February 28. The date must be valid. + +Increments a date by some number of years. If the date is February 29, +and the destination year is not a leap year, the date will be changed +to February 28. The date must be valid. -@date: Date to increment -@n_years: Number of years to move forward +@date: a #GDate to increment. +@n_years: number of years to move forward. - -Move a date some number of years into the past. If the current day -doesn't exist in the destination year (i.e. it's February 29 and you -move to a non-leap-year) then the day is changed to February 29. Date -must be valid. + +Moves a date some number of years into the past. If the current day +doesn't exist in the destination year (i.e. it's February 29 and you +move to a non-leap-year) then the day is changed to February 29. The date +must be valid. -@date: Date to decrement -@n_years: Number of years to move +@date: a #GDate to decrement. +@n_years: number of years to move. -Compute the number of days between two dates. +Computes the number of days between two dates. If @date2 is prior to @date1, the returned value is negative. Both dates must be valid. -@date1: The first date -@date2: The second date -@Returns: The number of days between @date1 and @date2 +@date1: the first date. +@date2: the second date. +@Returns: the number of days between @date1 and @date2. - -qsort()-style comparsion function for dates. Both -dates must be valid. + +qsort()-style comparsion function for dates. Both +dates must be valid. -@lhs: First date to compare -@rhs: Second date to compare -@Returns: 0 for equal, less than zero if @lhs is less than @rhs, -greater than zero if @lhs is greater than @rhs +@lhs: first date to compare. +@rhs: second date to compare. +@Returns: 0 for equal, less than zero if @lhs is less than @rhs, +greater than zero if @lhs is greater than @rhs. -If @date is prior to @min_date, set @date equal to @min_date. -If @date falls after @max_date, set @date equal to @max_date. +If @date is prior to @min_date, sets @date equal to @min_date. +If @date falls after @max_date, sets @date equal to @max_date. Either @min_date and @max_date may be %NULL. All non-%NULL dates must be valid. -@date: Date to clamp -@min_date: Minimum accepted value for @date -@max_date: Maximum accepted value for @date +@date: a #GDate to clamp. +@min_date: minimum accepted value for @date. +@max_date: maximum accepted value for @date. -Check if @date1 is less than or equal to @date2, +Checks if @date1 is less than or equal to @date2, and swap the values if this is not the case. -@date1: The first date -@date2: The second date +@date1: the first date. +@date2: the second date. - -Return the day of the month; the #GDate must be valid. + +Returns the day of the month. The date must be valid. -@date: Date to extract the day of the month from -@Returns: Day of the month +@date: a #GDate to extract the day of the month from. +@Returns: day of the month. - -Accessor for the month of the year. Date must be valid. + +Returns the month of the year. The date must be valid. -@date: Date to get the month from -@Returns: A #GDateMonth +@date: a #GDate to get the month from. +@Returns: month of the year as a #GDateMonth. - -Accessor; returns the year of a #GDate. The date must be valid. + +Returns the year of a #GDate. The date must be valid. -@date: Date -@Returns: Year in which the date falls +@date: a #GDate. +@Returns: year in which the date falls. - -Accessor, returns the Julian day or "serial number" of the #GDate. The -Julian day is simply the number of days since January 1, Year 1; i.e., -January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, -etc. Date must be valid. + +Returns the Julian day or "serial number" of the #GDate. The +Julian day is simply the number of days since January 1, Year 1; i.e., +January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, +etc. The date must be valid. -@date: Date to extract the Julian day from -@Returns: Julian day +@date: a #GDate to extract the Julian day from. +@Returns: Julian day. - -Returns the day of the week for a #GDate. The date must be valid. + +Returns the day of the week for a #GDate. The date must be valid. -@date: Date -@Returns: Day of the week as a #GDateWeekday +@date: a #GDate. +@Returns: day of the week as a #GDateWeekday. - -Return the day of the year, where Jan 1 is the first day of the -year. Date must be valid. + +Returns the day of the year, where Jan 1 is the first day of the +year. The date must be valid. -@date: Date to extract day of year from -@Returns: Day of the year +@date: a #GDate to extract day of year from. +@Returns: day of the year. - -Return the number of days in a month, taking leap years into account. + +Returns the number of days in a month, taking leap years into account. -@month: Month -@year: Year -@Returns: Number of days in @month during the year @year. +@month: month. +@year: year. +@Returns: number of days in @month during the @year. - -Returns TRUE if the date is on the first of a month. Date must be valid. + +Returns %TRUE if the date is on the first of a month. The date must be valid. -@date: Date to check -@Returns: Boolean, if the date is the first of the month +@date: a #GDate to check. +@Returns: %TRUE if the date is the first of the month. - -Returns TRUE if the date is the last day of the month. Date must be valid. + +Returns %TRUE if the date is the last day of the month. The date must be valid. -@date: Date to check -@Returns: Boolean, if the date is the last day of the month +@date: a #GDate to check. +@Returns: %TRUE if the date is the last day of the month. + - -Returns TRUE if the year is a leap year + +Returns %TRUE if the year is a leap year. -@year: Year to check -@Returns: Boolean, if the year is a leap year +@year: year to check. +@Returns: %TRUE if the year is a leap year. - -Return the week of the year, where weeks are understood to start on -Monday. If the date is before the first Monday of the year, return -0. Date must be valid. + +Returns the week of the year, where weeks are understood to start on +Monday. If the date is before the first Monday of the year, return +0. The date must be valid. -@date: Date to use -@Returns: Week of the year +@date: a #GDate. +@Returns: week of the year. - -Return the number of weeks in the year, where weeks are taken to start -on Monday. Will be 52 or 53. Date must be valid. (Years always have 52 -7-day periods, plus 1 or 2 extra days depending on whether it's a leap -year. This function is basically telling you how many Mondays are in -the year, i.e. there are 53 Mondays if one of the extra days happens -to be a Monday.) + +Returns the number of weeks in the year, where weeks are taken to start +on Monday. Will be 52 or 53. The date must be valid. (Years always have 52 +7-day periods, plus 1 or 2 extra days depending on whether it's a leap +year. This function is basically telling you how many Mondays are in +the year, i.e. there are 53 Mondays if one of the extra days happens +to be a Monday.) -@year: Year -@Returns: Number of Mondays in the year +@year: a year. +@Returns: number of Mondays in the year. - -Week of the year during which this date falls, if weeks are understood -to being on Sunday. Date must be valid. Can return 0 if the day is -before the first Sunday of the year. + +Returns the week of the year during which this date falls, if weeks +are understood to being on Sunday. The date must be valid. Can return 0 if +the day is before the first Sunday of the year. -@date: Date -@Returns: Week number +@date: a #GDate. +@Returns: week number. - -Return the number of weeks in the year, where weeks are taken to start -on Sunday. Will be 52 or 53. Date must be valid. (Years always have 52 -7-day periods, plus 1 or 2 extra days depending on whether it's a leap -year. This function is basically telling you how many Sundays are in -the year, i.e. there are 53 Sundays if one of the extra days happens -to be a Sunday.) + +Returns the number of weeks in the year, where weeks are taken to start +on Sunday. Will be 52 or 53. The date must be valid. (Years always have 52 +7-day periods, plus 1 or 2 extra days depending on whether it's a leap +year. This function is basically telling you how many Sundays are in +the year, i.e. there are 53 Sundays if one of the extra days happens +to be a Sunday.) -@year: Year to count weeks in -@Returns: Number of weeks +@year: year to count weeks in. +@Returns: number of weeks. - -Generate a printed representation of the date, in a locale-specific -way. Works just like the standard C strftime() -function, but only accepts date-related formats; time-related formats -give undefined results. Date must be valid. + +Generates a printed representation of the date, in a locale-specific +way. Works just like the standard C strftime() +function, but only accepts date-related formats; time-related formats +give undefined results. Date must be valid. -@s: Destination buffer -@slen: Max buffer size -@format: Format string -@date: valid #GDate -@Returns: number of characters written to the buffer, or 0 the buffer was too small +@s: destination buffer. +@slen: buffer size. +@format: format string. +@date: valid #GDate. +@Returns: number of characters written to the buffer, or 0 the buffer was too small. - -Fills in the date-related bits of a struct tm -using the @date value. Initializes the non-date parts with something -sane but meaningless. + +Fills in the date-related bits of a struct tm +using the @date value. Initializes the non-date parts with something +sane but meaningless. -@date: Date to set the struct tm from -@tm: struct tm to fill +@date: a #GDate to set the struct tm from. +@tm: struct tm to fill. - -Returns TRUE if the #GDate represents an existing day. #GDate must not -contain garbage; it should have been initialized with g_date_clear() -if it wasn't allocated by one of the g_date_new() variants. + +Returns %TRUE if the #GDate represents an existing day. The date must not +contain garbage; it should have been initialized with g_date_clear() +if it wasn't allocated by one of the g_date_new() variants. -@date: Date to check +@date: a #GDate to check. @Returns: Whether the date is valid. - -Returns TRUE if the day of the month is valid (a day is valid if it's -between 1 and 31 inclusive). + +Returns %TRUE if the day of the month is valid (a day is valid if it's +between 1 and 31 inclusive). -@day: Day to check. -@Returns: Boolean, whether the day is valid. +@day: day to check. +@Returns: %TRUE if the day is valid. - -Returns TRUE if the month value is valid. The 12 #GDateMonth -enumeration values are the only valid months. + +Returns %TRUE if the month value is valid. The 12 #GDateMonth +enumeration values are the only valid months. -@month: Month -@Returns: Boolean, whether the month is valid +@month: month. +@Returns: %TRUE if the month is valid. - -Returns TRUE if the year is valid. Any year greater than 0 is valid, -though there is a 16-bit limit to what GDate will understand. + +Returns %TRUE if the year is valid. Any year greater than 0 is valid, +though there is a 16-bit limit to what #GDate will understand. -@year: Year -@Returns: Boolean, whether the year is valid. +@year: year. +@Returns: %TRUE if the year is valid. - -Returns TRUE if the day/month/year triplet forms a valid, existing day -in the range of days GDate understands (Year 1 or later, no more than -a few thousand years in the future). + +Returns %TRUE if the day/month/year triplet forms a valid, existing day +in the range of days #GDate understands (Year 1 or later, no more than +a few thousand years in the future). -@day: Day -@month: Month -@year: Year -@Returns: Boolean, whether the date is a valid one +@day: day. +@month: month. +@year: year. +@Returns: %TRUE if the date is a valid one. - -Returns TRUE if the Julian day is valid. Anything greater than zero is basically a -valid Julian, though there is a 32-bit limit. + +Returns %TRUE if the Julian day is valid. Anything greater than zero is basically a +valid Julian, though there is a 32-bit limit. -@julian_date: Julian day to check -@Returns: Boolean, whether the Julian day is valid. +@julian_date: Julian day to check. +@Returns: %TRUE if the Julian day is valid. - -Returns TRUE if the weekday is valid. The 7 #GDateWeekday enumeration -values are the only valid weekdays. + +Returns %TRUE if the weekday is valid. The 7 #GDateWeekday enumeration +values are the only valid weekdays. -@weekday: Weekday -@Returns: Boolean, whether the weekday is valid. +@weekday: weekday. +@Returns: %TRUE if the weekday is valid. diff --git a/docs/reference/glib/tmpl/hash_tables.sgml b/docs/reference/glib/tmpl/hash_tables.sgml index c93fb17..3668ce1 100644 --- a/docs/reference/glib/tmpl/hash_tables.sgml +++ b/docs/reference/glib/tmpl/hash_tables.sgml @@ -87,7 +87,7 @@ Specifies the type of the hash function which is passed to g_hash_table_new() when a #GHashTable is created. -The function is passed a key and should return a guint hash value. +The function is passed a key and should return a #guint hash value. The functions g_direct_hash(), g_int_hash() and g_str_hash() provide hash functions which can be used when the key is a #gpointer, #gint, and #gchar* respectively. @@ -108,13 +108,13 @@ lookup. Specifies the type of a function used to test two values for -equality. The function should return TRUE if both values are equal and -FALSE otherwise. +equality. The function should return %TRUE if both values are equal and +%FALSE otherwise. @a: a value. @b: a value to compare with. -@Returns: TRUE if @a = @b; FALSE otherwise. +@Returns: %TRUE if @a = @b; %FALSE otherwise. @@ -237,14 +237,14 @@ which is passed to g_hash_table_foreach(). Specifies the type of the function passed to g_hash_table_foreach_remove(). It is called with each key/value pair, together with the @user_data parameter passed to g_hash_table_foreach_remove(). -It should return TRUE if the key/value pair should be removed from the +It should return %TRUE if the key/value pair should be removed from the #GHashTable. @key: a key. @value: the value associated with the key. @user_data: user data passed to g_hash_table_remove(). -@Returns: TRUE if the key/value pair should be removed from the #GHashTable. +@Returns: %TRUE if the key/value pair should be removed from the #GHashTable. @@ -275,14 +275,14 @@ This function is deprecated and will be removed in the next major -Compares two #gpointer arguments and returns TRUE if they are equal. +Compares two #gpointer arguments and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using pointers as keys in a #GHashTable. @v: a key. @v2: a key to compare with @v. -@Returns: TRUE if the two keys match. +@Returns: %TRUE if the two keys match. @@ -298,7 +298,7 @@ using gpointer values as keys in a #GHashTable. -Compares the two #gint values being pointed to and returns TRUE if they are +Compares the two #gint values being pointed to and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using pointers to integers as keys in a #GHashTable. @@ -306,14 +306,14 @@ parameter, when using pointers to integers as keys in a #GHashTable. @v: a pointer to a #gint key. @v2: a pointer to a #gint key to compare with @v. -@Returns: TRUE if the two keys match. +@Returns: %TRUE if the two keys match. Converts a pointer to a #gint to a hash value. It can be passed to g_hash_table_new() as the @hash_func parameter, when -using pointers to gint values as keys in a #GHashTable. +using pointers to #gint values as keys in a #GHashTable. @v: a pointer to a #gint key. @@ -322,14 +322,14 @@ using pointers to gint values as keys in a #GHashTable. -Compares two strings and returns TRUE if they are equal. +Compares two strings and returns %TRUE if they are equal. It can be passed to g_hash_table_new() as the @key_equal_func parameter, when using strings as keys in a #GHashTable. @v: a key. @v2: a key to compare with @v. -@Returns: TRUE if the two keys match. +@Returns: %TRUE if the two keys match. diff --git a/docs/reference/glib/tmpl/memory.sgml b/docs/reference/glib/tmpl/memory.sgml index 22feb94..3942db7 100644 --- a/docs/reference/glib/tmpl/memory.sgml +++ b/docs/reference/glib/tmpl/memory.sgml @@ -22,87 +22,72 @@ This also means that there is no need to check if the call succeeded. -Allocates @count elements of type @type. +Allocates @n_structs elements of type @struct_type. The returned pointer is cast to a pointer to the given type. -If @count is 0 it returns NULL. +If @count is 0 it returns %NULL. -@struct_type: -@n_structs: -@Returns: a pointer to the allocated memory, cast to a pointer to @type. - -@type: the type of the elements to allocate. -@count: the number of elements to allocate. +@struct_type: the type of the elements to allocate. +@n_structs: the number of elements to allocate. +@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. -Allocates @count elements of type @type, initialized to 0's. +Allocates @n_structs elements of type @struct_type, initialized to 0's. The returned pointer is cast to a pointer to the given type. -If @count is 0 it returns NULL. +If @count is 0 it returns %NULL. -@struct_type: -@n_structs: -@Returns: a pointer to the allocated memory, cast to a pointer to @type. - -@type: the type of the elements to allocate. -@count: the number of elements to allocate. +@struct_type: the type of the elements to allocate. +@n_structs: the number of elements to allocate. +@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. Reallocates the memory pointed to by @mem, so that it now has space for -@count elements of type @type. It returns the new address of the memory, -which may have been moved. +@n_struct elements of type @struct_type. It returns the new address of +the memory, which may have been moved. -@struct_type: +@struct_type: the type of the elements to allocate. @mem: the currently allocated memory. -@n_structs: -@Returns: a pointer to the new allocated memory, cast to a pointer to @type. - -@type: the type of the elements to allocate. -@count: the number of elements to allocate. +@n_structs: the number of elements to allocate. +@Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type. -Allocates @size bytes of memory. -If @size is 0 it returns NULL. +Allocates @n_bytes bytes of memory. +If @n_bytes is 0 it returns %NULL. -@n_bytes: +@n_bytes: the number of bytes to allocate. @Returns: a pointer to the allocated memory. - -@size: the number of bytes to allocate. -Allocates @size bytes of memory, initialized to 0's. -If @size is 0 it returns NULL. +Allocates @n_bytes bytes of memory, initialized to 0's. +If @n_bytes is 0 it returns %NULL. -@n_bytes: +@n_bytes: the number of bytes to allocate. @Returns: a pointer to the allocated memory. - -@size: the number of bytes to allocate. Reallocates the memory pointed to by @mem, so that it now has space for -@size bytes of memory. It returns the new address of the memory, which may +@n_bytes bytes of memory. It returns the new address of the memory, which may have been moved. @mem may be %NULL, in which case it's considered to have zero-length. @n_bytes may be 0, in which case %NULL will be returned. @mem: the memory to reallocate. -@n_bytes: new size of the memory in bytes +@n_bytes: new size of the memory in bytes. @Returns: the new address of the allocated memory. - -@size: the new size of the allocated memory, in bytes. @@ -111,8 +96,8 @@ Attempts to allocate @n_bytes, and returns %NULL on failure. Contrast with g_malloc(), which aborts the program on failure. -@n_bytes: number of bytes to allocate -@Returns: the allocated memory, or %NULL +@n_bytes: number of bytes to allocate. +@Returns: the allocated memory, or %NULL. @@ -122,15 +107,15 @@ on failure. Contrast with g_realloc(), which aborts the program on failure. If @mem is %NULL, behaves the same as g_try_malloc(). -@mem: previously-allocated memory, or %NULL -@n_bytes: number of bytes to allocate -@Returns: the allocated memory, or %NULL +@mem: previously-allocated memory, or %NULL. +@n_bytes: number of bytes to allocate. +@Returns: the allocated memory, or %NULL. Frees the memory pointed to by @mem. -If @mem is NULL it simply returns. +If @mem is %NULL it simply returns. @mem: the memory to free. @@ -142,7 +127,7 @@ Allocates @size bytes on the stack; these bytes will be freed when the current stack frame is cleaned up. -@size: number of bytes to allocate +@size: number of bytes to allocate. @@ -151,9 +136,9 @@ Copies a block of memory @n bytes long, from @s to @d. The source and destination areas may overlap. -In order to use this function, you must include string.h +In order to use this function, you must include string.h yourself, because this macro will typically simply resolve -to memmove() and GLib does not include string.h for you. +to memmove() and GLib does not include string.h for you. @d: the destination address to copy the bytes to. @@ -164,36 +149,36 @@ to memmove() and GLib does not include string.h for you. Allocates @byte_size bytes of memory, and copies @byte_size bytes into it -from @mem. If @mem is NULL it returns NULL. +from @mem. If @mem is %NULL it returns %NULL. @mem: the memory to copy. @byte_size: the number of bytes to copy. -@Returns: a pointer to the newly allocated copy of the memory, or NULL if @mem -is NULL. +@Returns: a pointer to the newly allocated copy of the memory, or %NULL if @mem +is %NULL. -A set of functions used to perform memory allocation. The same GMemVTable must +A set of functions used to perform memory allocation. The same #GMemVTable must be used for all allocations in the same program; a call to g_mem_set_vtable(), if it exists, should be prior to any use of GLib. -@malloc: function to use for allocating memory -@realloc: function to use for reallocating memory -@free: function to use to free memory -@calloc: function to use for allocating zero-filled memory -@try_malloc: function to use for allocating memory without a default error handler -@try_realloc: function to use for reallocating memory without a default error handler +@malloc: function to use for allocating memory. +@realloc: function to use for reallocating memory. +@free: function to use to free memory. +@calloc: function to use for allocating zero-filled memory. +@try_malloc: function to use for allocating memory without a default error handler. +@try_realloc: function to use for reallocating memory without a default error handler. Sets the #GMemVTable to use for memory allocation. You can use this to provide custom memory allocation routines. THIS FUNCTION MUST BE CALLED BEFORE USING ANY -OTHER GLIB FUNCTIONS. The vtable only needs to provide malloc, realloc, and free -functions; GLib can provide default implementations of the others. The malloc -and realloc implementations should return %NULL on failure, GLib will handle +OTHER GLIB FUNCTIONS. The @vtable only needs to provide malloc(), realloc(), and free() +functions; GLib can provide default implementations of the others. The malloc() +and realloc() implementations should return %NULL on failure, GLib will handle error-checking for you. @vtable is copied, so need not persist after this function has been called. @@ -211,15 +196,16 @@ function has been called. - +A #GMemVTable containing profiling variants of the memory +allocation functions. Use them together with g_mem_profile() +in order to get information about the memory allocation pattern +of your program. Outputs a summary of memory usage. -To use this function you must configure glib with the flag -'--enable-mem-profile=yes' before compiling. It outputs the frequency of allocations of different sizes, @@ -228,6 +214,9 @@ the total number of bytes which have been freed, and the difference between the previous two values, i.e. the number of bytes still in use. - + +Note that this function will not output anything unless you have +previously installed the #glib_mem_profiler_table with g_mem_set_vtable(). + diff --git a/docs/reference/glib/tmpl/type_conversion.sgml b/docs/reference/glib/tmpl/type_conversion.sgml index e2fc8b7..fb94e5d 100644 --- a/docs/reference/glib/tmpl/type_conversion.sgml +++ b/docs/reference/glib/tmpl/type_conversion.sgml @@ -28,8 +28,8 @@ in a pointer value. Naively, you might try this, but it's incorrect: p = (void*) 42; i = (int) p; -Again, that example was NOT correct, don't copy it. The problem is -that on some systems you need to do this: +Again, that example was not correct, don't copy it. +The problem is that on some systems you need to do this: gpointer p; int i; @@ -66,7 +66,7 @@ storing integers in pointers, and only preserve 32 bits of the integer; values outside the range of a 32-bit integer will be mangled. -@i: integer to stuff into a pointer +@i: integer to stuff into a pointer. @@ -86,33 +86,35 @@ integer; values outside the range of a 32-bit integer will be mangled. -Same as GINT_TO_POINTER(), but for unsigned integers. +Stuffs an unsigned integer into a pointer type. -@u: integer to stuff into the pointer +@u: unsigned integer to stuff into the pointer. -Same as GPOINTER_TO_INT(), but for unsigned integers. +Extracts an unsigned integer from a pointer. The integer must have +been stored in the pointer with GUINT_TO_POINTER(). -@p: pointer to extract an integer from +@p: pointer to extract an unsigned integer from. - +Stuffs a #gsize into a pointer type. -@s: +@s: #gsize to stuff into the pointer. - +Extracts a #gsize from a pointer. The #gsize must have +been stored in the pointer with GSIZE_TO_POINTER(). -@p: +@p: pointer to extract a #gsize from. -- 2.7.4