Mercurial > pidgin.yaz
comparison libgaim/stringref.h @ 14192:60b1bc8dbf37
[gaim-migrate @ 16863]
Renamed 'core' to 'libgaim'
committer: Tailor Script <tailor@pidgin.im>
author | Evan Schoenberg <evan.s@dreskin.net> |
---|---|
date | Sat, 19 Aug 2006 01:50:10 +0000 |
parents | |
children | 500a8f54354e |
comparison
equal
deleted
inserted
replaced
14191:009db0b357b5 | 14192:60b1bc8dbf37 |
---|---|
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_ */ |