Mercurial > pidgin3 / file comparison

comparison: core/stringref.h

core/stringref.h

changeset 14253
b63ebf84c42b
parent 9713
bb37562302a1
equal deleted inserted replaced
14252:d10dda2777a9 14253:b63ebf84c42b
1 /**
2 * @file stringref.h Reference-counted immutable strings
3 * @ingroup core
4 *
5 * gaim
6 *
7 * Gaim is the legal property of its developers, whose names are too numerous
8 * to list here. Please refer to the COPYRIGHT file distributed with this
9 * source distribution.
10 *
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, write to the Free Software
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 *
25 */
26 #ifndef _GAIM_STRINGREF_H_
27 #define _GAIM_STRINGREF_H_
28
29 /**
30 * The internal representation of a stringref.
31 *
32 * @note For this structure to be useful, the string contained within
33 * it must be immutable -- for this reason, do _not_ access it
34 * directly!
35 */
36 typedef struct _GaimStringref {
37 guint32 ref; /**< The reference count of this string.
38 * Note that reference counts are only
39 * 31 bits, and the high-order bit
40 * indicates whether this string is up
41 * for GC at the next idle handler...
42 * But you aren't going to touch this
43 * anyway, right? */
44 char value[1]; /**< The string contained in this ref.
45 * Notice that it is simply "hanging
46 * off the end" of the ref ... this
47 * is to save an allocation. */
48 } GaimStringref;
49
50 /**
51 * Creates an immutable reference-counted string object. The newly
52 * created object will have a reference count of 1.
53 *
54 * @param value This will be the value of the string; it will be
55 * duplicated.
56 *
57 * @return A newly allocated string reference object with a refcount
58 * of 1.
59 */
60 GaimStringref *gaim_stringref_new(const char *value);
61
62 /**
63 * Creates an immutable reference-counted string object. The newly
64 * created object will have a reference count of zero, and if it is
65 * not referenced before the next iteration of the mainloop it will
66 * be freed at that time.
67 *
68 * @param value This will be the value of the string; it will be
69 * duplicated.
70 *
71 * @return A newly allocated string reference object with a refcount
72 * of zero.
73 */
74 GaimStringref *gaim_stringref_new_noref(const char *value);
75
76 /**
77 * Creates an immutable reference-counted string object from a printf
78 * format specification and arguments. The created object will have a
79 * reference count of 1.
80 *
81 * @param format A printf-style format specification.
82 *
83 * @return A newly allocated string reference object with a refcount
84 * of 1.
85 */
86 GaimStringref *gaim_stringref_printf(const char *format, ...);
87
88 /**
89 * Increase the reference count of the given stringref.
90 *
91 * @param stringref String to be referenced.
92 *
93 * @return A pointer to the referenced string.
94 */
95 GaimStringref *gaim_stringref_ref(GaimStringref *stringref);
96
97 /**
98 * Decrease the reference count of the given stringref. If this
99 * reference count reaches zero, the stringref will be freed; thus
100 * you MUST NOT use this string after dereferencing it.
101 *
102 * @param stringref String to be dereferenced.
103 */
104 void gaim_stringref_unref(GaimStringref *stringref);
105
106 /**
107 * Retrieve the value of a stringref.
108 *
109 * @note This value should not be cached or stored in a local variable.
110 * While there is nothing inherently incorrect about doing so, it
111 * is easy to forget that the cached value is in fact a
112 * reference-counted object and accidentally use it after
113 * dereferencing. This is more problematic for a reference-
114 * counted object than a heap-allocated object, as it may seem to
115 * be valid or invalid nondeterministically based on how many
116 * other references to it exist.
117 *
118 * @param stringref String reference from which to retrieve the value.
119 *
120 * @return The contents of the string reference.
121 */
122 const char *gaim_stringref_value(const GaimStringref *stringref);
123
124 /**
125 * Compare two stringrefs for string equality. This returns the same
126 * value as strcmp would, where <0 indicates that s1 is "less than" s2
127 * in the ASCII lexicography, 0 indicates equality, etc.
128 *
129 * @param s1 The reference string.
130 *
131 * @param s2 The string to compare against the reference.
132 *
133 * @return An ordering indication on s1 and s2.
134 */
135 int gaim_stringref_cmp(const GaimStringref *s1, const GaimStringref *s2);
136
137 /**
138 * Find the length of the string inside a stringref.
139 *
140 * @param stringref The string in whose length we are interested.
141 *
142 * @return The length of the string in stringref
143 */
144 size_t gaim_stringref_len(const GaimStringref *stringref);
145
146 #endif /* _GAIM_STRINGREF_H_ */

Mercurial Repository: pidgin3

mercurial