Audacious  $Id:Doxyfile42802007-03-2104:39:00Znenolod$
core.h
Go to the documentation of this file.
1 /*
2  * core.h
3  * Copyright 2011 John Lindgren
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions are met:
7  *
8  * 1. Redistributions of source code must retain the above copyright notice,
9  * this list of conditions, and the following disclaimer.
10  *
11  * 2. Redistributions in binary form must reproduce the above copyright notice,
12  * this list of conditions, and the following disclaimer in the documentation
13  * provided with the distribution.
14  *
15  * This software is provided "as is" and without any warranty, express or
16  * implied. In no event shall the authors be liable for any damages arising from
17  * the use of this software.
18  */
19 
20 #ifndef LIBAUDCORE_CORE_H
21 #define LIBAUDCORE_CORE_H
22 
23 /* #define STRPOOL_DEBUG */
24 
25 #undef NULL
26 #ifdef __cplusplus /* *sigh* */
27 #define NULL 0
28 #else
29 #define NULL ((void *) 0)
30 #endif
31 
32 /* "bool_t" means "int" for compatibility with GLib */
33 #undef bool_t
34 #define bool_t int
35 
36 #undef FALSE
37 #define FALSE ((bool_t) 0)
38 #undef TRUE
39 #define TRUE ((bool_t) 1)
40 
41 /* Simple sanity check to catch (1) strings that are still in use after their
42  * reference count has dropped to zero and (2) strings that should have been
43  * pooled but never were. If the check fails, the program is aborted. */
44 #define STR_CHECK(str) do {if ((str) && (str)[-1] != '@') strpool_abort (str);} while (0)
45 
46 /* If the pool contains a copy of <str>, increments its reference count.
47  * Otherwise, adds a copy of <str> to the pool with a reference count of one.
48  * In either case, returns the copy. Because this copy may be shared by other
49  * parts of the code, it should not be modified. If <str> is NULL, simply
50  * returns NULL with no side effects. */
51 #ifdef STRPOOL_DEBUG
52 char * str_get_debug (const char * str, const char * file, int line);
53 #define str_get(str) str_get_debug (str, __FILE__, __LINE__)
54 #else
55 char * str_get (const char * str);
56 #endif
57 
58 /* Increments the reference count of <str>, where <str> is the address of a
59  * string already in the pool. Faster than calling str_get() a second time.
60  * Returns <str> for convenience. If <str> is NULL, simply returns NULL with no
61  * side effects. */
62 #ifdef STRPOOL_DEBUG
63 char * str_ref_debug (char * str, const char * file, int line);
64 #define str_ref(str) str_ref_debug (str, __FILE__, __LINE__)
65 #else
66 char * str_ref (char * str);
67 #endif
68 
69 /* Decrements the reference count of <str>, where <str> is the address of a
70  * string in the pool. If the reference count drops to zero, releases the
71  * memory used by <str>. If <str> is NULL, simply returns NULL with no side
72  * effects. */
73 #ifdef STRPOOL_DEBUG
74 void str_unref_debug (char * str, const char * file, int line);
75 #define str_unref(str) str_unref_debug (str, __FILE__, __LINE__)
76 #else
77 void str_unref (char * str);
78 #endif
79 
80 /* Calls str_get() on the first <len> characters of <str>. If <str> has less
81  * than or equal to <len> characters, equivalent to str_get(). */
82 char * str_nget (const char * str, int len);
83 
84 /* Calls sprintf() internally, then pools the produced string with str_get(). */
85 char * str_printf (const char * format, ...);
86 
87 /* Used by STR_CHECK; should not be called directly. */
88 void strpool_abort (char * str);
89 
90 /* Releases all memory used by the string pool. If strings remain in the pool,
91  * a warning may be printed to stderr in order to reveal memory leaks. */
92 void strpool_shutdown (void);
93 
94 #endif /* LIBAUDCORE_CORE_H */