luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-09 20:35:49 +01:00
Code Issues Packages Projects Releases Wiki Activity

Move gutils docs inline

Browse Source
This commit is contained in:
Matthias Clasen 2011-06-08 23:44:39 -04:00
parent e89f183cf6
commit 7648415a50
6 changed files with 102 additions and 472 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/tmpl/.gitignore vendored
View File

@ -24,6 +24,7 @@ linked_lists_single.sgml
markup.sgml markup.sgml
memory_chunks.sgml memory_chunks.sgml
memory.sgml memory.sgml
misc_utils.sgml
option.sgml option.sgml
patterns.sgml patterns.sgml
quarks.sgml quarks.sgml

458
docs/reference/glib/tmpl/misc_utils.sgml
View File

@ -1,458 +0,0 @@
<!-- ##### SECTION Title ##### -->
Miscellaneous Utility Functions
<!-- ##### SECTION Short_Description ##### -->
a selection of portable utility functions
<!-- ##### SECTION Long_Description ##### -->
<para>
These are portable utility functions.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### FUNCTION g_get_application_name ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_set_application_name ##### -->
<para>
</para>
@application_name:
<!-- ##### FUNCTION g_get_prgname ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_set_prgname ##### -->
<para>
</para>
@prgname:
<!-- ##### FUNCTION g_getenv ##### -->
<para>
</para>
@variable:
@Returns:
<!-- ##### FUNCTION g_setenv ##### -->
<para>
</para>
@variable:
@value:
@overwrite:
@Returns:
<!-- ##### FUNCTION g_unsetenv ##### -->
<para>
</para>
@variable:
<!-- ##### FUNCTION g_listenv ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_get_user_name ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_get_real_name ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_get_user_cache_dir ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_get_user_data_dir ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_get_user_config_dir ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### ENUM GUserDirectory ##### -->
<para>
</para>
@G_USER_DIRECTORY_DESKTOP:
@G_USER_DIRECTORY_DOCUMENTS:
@G_USER_DIRECTORY_DOWNLOAD:
@G_USER_DIRECTORY_MUSIC:
@G_USER_DIRECTORY_PICTURES:
@G_USER_DIRECTORY_PUBLIC_SHARE:
@G_USER_DIRECTORY_TEMPLATES:
@G_USER_DIRECTORY_VIDEOS:
@G_USER_N_DIRECTORIES:
<!-- ##### FUNCTION g_get_user_special_dir ##### -->
<para>
</para>
@directory:
@Returns:
<!-- ##### FUNCTION g_get_system_data_dirs ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_get_system_config_dirs ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_reload_user_special_dirs_cache ##### -->
<para>
</para>
@void:
<!-- ##### FUNCTION g_get_host_name ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_get_home_dir ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_get_tmp_dir ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_get_current_dir ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION g_basename ##### -->
@file_name:
@Returns:
<!-- ##### MACRO g_dirname ##### -->
<para>
This function is deprecated and will be removed in the next major
release of GLib. Use g_path_get_dirname() instead.
</para>
<para>
Gets the directory components of a file name.
If the file name has no directory components "." is returned.
The returned string should be freed when no longer needed.
</para>
@Returns: the directory components of the file.
<!-- ##### FUNCTION g_path_is_absolute ##### -->
<para>
</para>
@file_name:
@Returns:
<!-- ##### FUNCTION g_path_skip_root ##### -->
<para>
</para>
@file_name:
@Returns:
<!-- ##### FUNCTION g_path_get_basename ##### -->
<para>
</para>
@file_name:
@Returns:
<!-- ##### FUNCTION g_path_get_dirname ##### -->
<para>
</para>
@file_name:
@Returns:
<!-- ##### FUNCTION g_build_filename ##### -->
<para>
</para>
@first_element:
@Varargs:
@Returns:
<!-- ##### FUNCTION g_build_filenamev ##### -->
<para>
</para>
@args:
@Returns:
<!-- ##### FUNCTION g_build_path ##### -->
<para>
</para>
@separator:
@first_element:
@Varargs:
@Returns:
<!-- ##### FUNCTION g_build_pathv ##### -->
<para>
</para>
@separator:
@args:
@Returns:
<!-- ##### FUNCTION g_format_size_for_display ##### -->
<para>
</para>
@size:
@Returns:
<!-- ##### FUNCTION g_find_program_in_path ##### -->
<para>
</para>
@program:
@Returns:
<!-- ##### FUNCTION g_bit_nth_lsf ##### -->
<para>
Find the position of the first bit set in @mask, searching from (but not
including) @nth_bit upwards. Bits are numbered from 0 (least significant)
to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the
0th bit, set @nth_bit to -1.
</para>
@mask: a #gulong containing flags.
@nth_bit: the index of the bit to start the search from.
@Returns: the index of the first bit set which is higher than @nth_bit.
<!-- ##### FUNCTION g_bit_nth_msf ##### -->
<para>
Find the position of the first bit set in @mask, searching from (but not
including) @nth_bit downwards. Bits are numbered from 0 (least significant)
to sizeof(#gulong) * 8 - 1 (31 or 63, usually). To start searching from the
last bit, set @nth_bit to -1 or GLIB_SIZEOF_LONG * 8.
</para>
@mask: a #gulong containing flags.
@nth_bit: the index of the bit to start the search from.
@Returns: the index of the first bit set which is lower than @nth_bit.
<!-- ##### FUNCTION g_bit_storage ##### -->
<para>
Gets the number of bits used to hold @number,
e.g. if @number is 4, 3 bits are needed.
</para>
@number: a guint.
@Returns: the number of bits used to hold @number.
<!-- ##### FUNCTION g_spaced_primes_closest ##### -->
<para>
Gets the smallest prime number from a built-in array of primes which
is larger than @num. This is used within GLib to calculate the optimum
size of a #GHashTable.
</para>
<para>
The built-in array of primes ranges from 11 to 13845163 such that
each prime is approximately 1.5-2 times the previous prime.
</para>
@num: a #guint.
@Returns: the smallest prime number from a built-in array of primes which is
larger than @num.
<!-- ##### FUNCTION g_atexit ##### -->
<para>
</para>
@func:
<!-- ##### FUNCTION g_parse_debug_string ##### -->
<para>
</para>
@string:
@keys:
@nkeys:
@Returns:
<!-- ##### STRUCT GDebugKey ##### -->
<para>
Associates a string with a bit flag.
Used in g_parse_debug_string().
</para>
@key: the string
@value: the flag
<!-- ##### USER_FUNCTION GVoidFunc ##### -->
<para>
Declares a type of function which takes no arguments and has no return value.
It is used to specify the type function passed to g_atexit().
</para>
@void:
<!-- ##### USER_FUNCTION GFreeFunc ##### -->
<para>
Declares a type of function which takes an arbitrary data pointer argument
and has no return value. It is not currently used in GLib or GTK+.
</para>
@data: a data pointer.
<!-- ##### FUNCTION g_qsort_with_data ##### -->
<para>
</para>
@pbase:
@total_elems:
@size:
@compare_func:
@user_data:
<!-- ##### FUNCTION g_nullify_pointer ##### -->
<para>
</para>
@nullify_location:

20
glib/gprimes.c
View File

@ -71,16 +71,28 @@ static const guint g_primes[] =
13845163, 13845163,
}; };
static const guint g_nprimes = sizeof (g_primes) / sizeof (g_primes[0]); /**
* g_spaced_primes_closest:
* @num: a #guint
*
* Gets the smallest prime number from a built-in array of primes which
* is larger than @num. This is used within GLib to calculate the optimum
* size of a #GHashTable.
*
* The built-in array of primes ranges from 11 to 13845163 such that
* each prime is approximately 1.5-2 times the previous prime.
*
* Returns: the smallest prime number from a built-in array of primes
* which is larger than @num
*/
guint guint
g_spaced_primes_closest (guint num) g_spaced_primes_closest (guint num)
{ {
gint i; gint i;
for (i = 0; i < g_nprimes; i++) for (i = 0; i < G_N_ELEMENTS (g_primes); i++)
if (g_primes[i] > num) if (g_primes[i] > num)
return g_primes[i]; return g_primes[i];
return g_primes[g_nprimes - 1]; return g_primes[G_N_ELEMENTS (g_primes) - 1];
} }

9
glib/gtypes.h
View File

@ -92,6 +92,15 @@ typedef guint (*GHashFunc) (gconstpointer key);
typedef void (*GHFunc) (gpointer key, typedef void (*GHFunc) (gpointer key,
gpointer value, gpointer value,
gpointer user_data); gpointer user_data);
/**
* GFreeFunc:
* @data: a data pointer
*
* Declares a type of function which takes an arbitrary
* data pointer argument and has no return value. It is
* not currently used in GLib or GTK+.
*/
typedef void (*GFreeFunc) (gpointer data); typedef void (*GFreeFunc) (gpointer data);
/** /**

59
glib/gutils.c
View File

@ -77,6 +77,15 @@
#include "gwin32.h" #include "gwin32.h"
#endif #endif
/**
* SECTION:misc_utils
* @title: Miscellaneous Utility Functions
* @short_description: a selection of portable utility functions
*
* These are portable utility functions.
*/
#ifdef MAXPATHLEN #ifdef MAXPATHLEN
#define G_PATH_LENGTH MAXPATHLEN #define G_PATH_LENGTH MAXPATHLEN
#elif defined (PATH_MAX) #elif defined (PATH_MAX)
@ -914,6 +923,56 @@ g_path_skip_root (const gchar *file_name)
return NULL; return NULL;
} }
/**
* g_bit_nth_lsf:
* @mask: a #gulong containing flags
* @nth_bit: the index of the bit to start the search from
*
* Find the position of the first bit set in @mask, searching
* from (but not including) @nth_bit upwards. Bits are numbered
* from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
* usually). To start searching from the 0th bit, set @nth_bit to -1.
*
* Returns: the index of the first bit set which is higher than @nth_bit
*/
/**
* g_bit_nth_msf:
* @mask: a #gulong containing flags
* @nth_bit: the index of the bit to start the search from
*
* Find the position of the first bit set in @mask, searching
* from (but not including) @nth_bit downwards. Bits are numbered
* from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
* usually). To start searching from the last bit, set @nth_bit to
* -1 or GLIB_SIZEOF_LONG * 8.
*
* Returns: the index of the first bit set which is lower than @nth_bit
*/
/**
* g_bit_storage:
* @number: a #guint
*
* Gets the number of bits used to hold @number,
* e.g. if @number is 4, 3 bits are needed.
*
* Returns: the number of bits used to hold @number
*/
/**
* g_dirname:
* @file_name: the name of the file
*
* Gets the directory components of a file name.
* If the file name has no directory components "." is returned.
* The returned string should be freed when no longer needed.
*
* Returns: the directory components of the file
*
* Deprecated: use g_path_get_dirname() instead
*/
/** /**
* g_path_get_dirname: * g_path_get_dirname:
* @file_name: the name of the file. * @file_name: the name of the file.

27
glib/gutils.h
View File

@ -196,7 +196,15 @@ typedef enum {
G_CONST_RETURN gchar* g_get_user_special_dir (GUserDirectory directory); G_CONST_RETURN gchar* g_get_user_special_dir (GUserDirectory directory);
typedef struct _GDebugKey GDebugKey; /**
* GDebugKey:
* @key: the string
* @value: the flag
*
* Associates a string with a bit flag.
* Used in g_parse_debug_string().
*/
typedef struct _GDebugKey GDebugKey;
struct _GDebugKey struct _GDebugKey
{ {
const gchar *key; const gchar *key;
@ -226,10 +234,6 @@ G_CONST_RETURN gchar* g_path_skip_root (const gchar *file_name);
#ifndef G_DISABLE_DEPRECATED #ifndef G_DISABLE_DEPRECATED
/* These two functions are deprecated and will be removed in the next
* major release of GLib. Use g_path_get_dirname/g_path_get_basename
* instead. Whatch out! The string returned by g_path_get_basename
* must be g_freed, while the string returned by g_basename must not.*/
G_CONST_RETURN gchar* g_basename (const gchar *file_name); G_CONST_RETURN gchar* g_basename (const gchar *file_name);
#define g_dirname g_path_get_dirname #define g_dirname g_path_get_dirname
@ -272,13 +276,16 @@ gchar** g_get_environ (void);
const gchar* _g_getenv_nomalloc (const gchar *variable, const gchar* _g_getenv_nomalloc (const gchar *variable,
gchar buffer[1024]); gchar buffer[1024]);
/* we try to provide a useful equivalent for ATEXIT if it is /**
* not defined, but use is actually abandoned. people should * GVoidFunc:
* use g_atexit() instead. *
* Declares a type of function which takes no arguments
* and has no return value. It is used to specify the type
* function passed to g_atexit().
*/ */
typedef void (*GVoidFunc) (void); typedef void (*GVoidFunc) (void);
#ifndef ATEXIT #ifndef ATEXIT
# define ATEXIT(proc) g_ATEXIT(proc) # define ATEXIT(proc) g_ATEXIT(proc)
#else #else
# define G_NATIVE_ATEXIT # define G_NATIVE_ATEXIT
#endif /* ATEXIT */ #endif /* ATEXIT */