7763
|
1 /**
|
|
2 * @file stringref.h Reference-counted immutable strings
|
|
3 * @ingroup core
|
|
4 *
|
|
5 * gaim
|
|
6 *
|
|
7 * Copyright (C) 2003 Ethan Blanton <elb@elitists.net>
|
|
8 *
|
|
9 * This program is free software; you can redistribute it and/or modify
|
|
10 * it under the terms of the GNU General Public License as published by
|
|
11 * the Free Software Foundation; either version 2 of the License, or
|
|
12 * (at your option) any later version.
|
|
13 *
|
|
14 * This program is distributed in the hope that it will be useful,
|
|
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
17 * GNU General Public License for more details.
|
|
18 *
|
|
19 * You should have received a copy of the GNU General Public License
|
|
20 * along with this program; if not, write to the Free Software
|
|
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
22 *
|
|
23 */
|
|
24
|
|
25 #ifndef _GAIM_STRINGREF_H_
|
|
26 #define _GAIM_STRINGREF_H_
|
|
27
|
|
28 /**
|
|
29 * @note For this structure to be useful, the string contained within
|
|
30 * it must be immutable -- for this reason, do _not_ access it
|
|
31 * directly!
|
|
32 */
|
|
33 typedef struct _GaimStringref {
|
|
34 int ref;
|
|
35 char value[0];
|
|
36 } GaimStringref;
|
|
37
|
|
38 /**
|
|
39 * Creates an immutable reference-counted string object. The newly
|
|
40 * created object will have a reference count of 1.
|
|
41 *
|
|
42 * @param value This will be the value of the string; it will be
|
|
43 * duplicated.
|
|
44 *
|
7767
|
45 * @return A newly allocated string reference object with a refcount
|
|
46 * of 1.
|
7763
|
47 */
|
|
48 GaimStringref *gaim_stringref_new(const char *value);
|
|
49
|
|
50 /**
|
7767
|
51 * Creates an immutable reference-counted string object from a printf
|
|
52 * format specification and arguments. The created object will have a
|
|
53 * reference count of 1.
|
|
54 *
|
|
55 * @param format A printf-style format specification.
|
|
56 *
|
|
57 * @return A newly allocated string reference object with a refcount
|
|
58 * of 1.
|
|
59 */
|
|
60 GaimStringref *gaim_stringref_printf(const char *format, ...);
|
|
61
|
|
62 /**
|
7763
|
63 * Increase the reference count of the given stringref.
|
|
64 *
|
|
65 * @param stringref String to be referenced.
|
|
66 *
|
|
67 * @return A pointer to the referenced string.
|
|
68 */
|
|
69 GaimStringref *gaim_stringref_ref(GaimStringref *stringref);
|
|
70
|
|
71 /**
|
|
72 * Decrease the reference count of the given stringref. If this
|
|
73 * reference count reaches zero, the stringref will be freed; thus
|
|
74 * you MUST NOT use this string after dereferencing it.
|
|
75 *
|
|
76 * @param stringref String to be dereferenced.
|
|
77 */
|
|
78 void gaim_stringref_unref(GaimStringref *stringref);
|
|
79
|
|
80 /**
|
|
81 * Retrieve the value of a stringref.
|
|
82 *
|
|
83 * @note This value should not be cached or stored in a local variable.
|
|
84 * While there is nothing inherently incorrect about doing so, it
|
|
85 * is easy to forget that the cached value is in fact a
|
|
86 * reference-counted object and accidentally use it after
|
|
87 * dereferencing. This is more problematic for a reference-
|
|
88 * counted object than a heap-allocated object, as it may seem to
|
|
89 * be valid or invalid nondeterministically based on how many
|
|
90 * other references to it exist.
|
|
91 *
|
|
92 * @param stringref String reference from which to retrieve the value.
|
|
93 *
|
|
94 * @return The contents of the string reference.
|
|
95 */
|
7768
|
96 const char *gaim_stringref_value(const GaimStringref *stringref);
|
7763
|
97
|
|
98 #endif /* _GAIM_STRINGREF_H_ */
|