annotate libgaim/stringref.h @ 15283:c2f15e2117dc

[gaim-migrate @ 18073] gaim_xfer_new() can return NULL via g_return_if_fail(). It should therefore not be assumed that it returns a GaimXfer; check against its return value before proceeding when creating a GaimXfer. committer: Tailor Script <tailor@pidgin.im>
author Evan Schoenberg <evan.s@dreskin.net>
date Thu, 04 Jan 2007 23:20:12 +0000
parents 500a8f54354e
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
14192
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
1 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
2 * @file stringref.h Reference-counted immutable strings
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
3 * @ingroup core
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
4 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
5 * gaim
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
6 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
7 * Gaim is the legal property of its developers, whose names are too numerous
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
8 * to list here. Please refer to the COPYRIGHT file distributed with this
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
9 * source distribution.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
10 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
11 * This program is free software; you can redistribute it and/or modify
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
12 * it under the terms of the GNU General Public License as published by
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
13 * the Free Software Foundation; either version 2 of the License, or
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
14 * (at your option) any later version.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
15 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
16 * This program is distributed in the hope that it will be useful,
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
19 * GNU General Public License for more details.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
20 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
21 * You should have received a copy of the GNU General Public License
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
22 * along with this program; if not, write to the Free Software
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
24 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
25 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
26 #ifndef _GAIM_STRINGREF_H_
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
27 #define _GAIM_STRINGREF_H_
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
28
14926
500a8f54354e [gaim-migrate @ 17698]
Richard Laager <rlaager@wiktel.com>
parents: 14192
diff changeset
29 #ifdef __cplusplus
500a8f54354e [gaim-migrate @ 17698]
Richard Laager <rlaager@wiktel.com>
parents: 14192
diff changeset
30 extern "C" {
500a8f54354e [gaim-migrate @ 17698]
Richard Laager <rlaager@wiktel.com>
parents: 14192
diff changeset
31 #endif
500a8f54354e [gaim-migrate @ 17698]
Richard Laager <rlaager@wiktel.com>
parents: 14192
diff changeset
32
500a8f54354e [gaim-migrate @ 17698]
Richard Laager <rlaager@wiktel.com>
parents: 14192
diff changeset
33 typedef struct _GaimStringref GaimStringref;
14192
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
34
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
35 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
36 * Creates an immutable reference-counted string object. The newly
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
37 * created object will have a reference count of 1.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
38 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
39 * @param value This will be the value of the string; it will be
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
40 * duplicated.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
41 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
42 * @return A newly allocated string reference object with a refcount
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
43 * of 1.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
44 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
45 GaimStringref *gaim_stringref_new(const char *value);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
46
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
47 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
48 * Creates an immutable reference-counted string object. The newly
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
49 * created object will have a reference count of zero, and if it is
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
50 * not referenced before the next iteration of the mainloop it will
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
51 * be freed at that time.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
52 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
53 * @param value This will be the value of the string; it will be
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
54 * duplicated.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
55 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
56 * @return A newly allocated string reference object with a refcount
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
57 * of zero.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
58 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
59 GaimStringref *gaim_stringref_new_noref(const char *value);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
60
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
61 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
62 * Creates an immutable reference-counted string object from a printf
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
63 * format specification and arguments. The created object will have a
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
64 * reference count of 1.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
65 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
66 * @param format A printf-style format specification.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
67 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
68 * @return A newly allocated string reference object with a refcount
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
69 * of 1.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
70 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
71 GaimStringref *gaim_stringref_printf(const char *format, ...);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
72
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
73 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
74 * Increase the reference count of the given stringref.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
75 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
76 * @param stringref String to be referenced.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
77 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
78 * @return A pointer to the referenced string.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
79 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
80 GaimStringref *gaim_stringref_ref(GaimStringref *stringref);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
81
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
82 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
83 * Decrease the reference count of the given stringref. If this
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
84 * reference count reaches zero, the stringref will be freed; thus
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
85 * you MUST NOT use this string after dereferencing it.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
86 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
87 * @param stringref String to be dereferenced.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
88 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
89 void gaim_stringref_unref(GaimStringref *stringref);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
90
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
91 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
92 * Retrieve the value of a stringref.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
93 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
94 * @note This value should not be cached or stored in a local variable.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
95 * While there is nothing inherently incorrect about doing so, it
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
96 * is easy to forget that the cached value is in fact a
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
97 * reference-counted object and accidentally use it after
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
98 * dereferencing. This is more problematic for a reference-
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
99 * counted object than a heap-allocated object, as it may seem to
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
100 * be valid or invalid nondeterministically based on how many
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
101 * other references to it exist.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
102 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
103 * @param stringref String reference from which to retrieve the value.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
104 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
105 * @return The contents of the string reference.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
106 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
107 const char *gaim_stringref_value(const GaimStringref *stringref);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
108
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
109 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
110 * Compare two stringrefs for string equality. This returns the same
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
111 * value as strcmp would, where <0 indicates that s1 is "less than" s2
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
112 * in the ASCII lexicography, 0 indicates equality, etc.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
113 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
114 * @param s1 The reference string.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
115 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
116 * @param s2 The string to compare against the reference.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
117 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
118 * @return An ordering indication on s1 and s2.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
119 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
120 int gaim_stringref_cmp(const GaimStringref *s1, const GaimStringref *s2);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
121
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
122 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
123 * Find the length of the string inside a stringref.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
124 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
125 * @param stringref The string in whose length we are interested.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
126 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
127 * @return The length of the string in stringref
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
128 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
129 size_t gaim_stringref_len(const GaimStringref *stringref);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
130
14926
500a8f54354e [gaim-migrate @ 17698]
Richard Laager <rlaager@wiktel.com>
parents: 14192
diff changeset
131 #ifdef __cplusplus
500a8f54354e [gaim-migrate @ 17698]
Richard Laager <rlaager@wiktel.com>
parents: 14192
diff changeset
132 }
500a8f54354e [gaim-migrate @ 17698]
Richard Laager <rlaager@wiktel.com>
parents: 14192
diff changeset
133 #endif
500a8f54354e [gaim-migrate @ 17698]
Richard Laager <rlaager@wiktel.com>
parents: 14192
diff changeset
134
14192
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
135 #endif /* _GAIM_STRINGREF_H_ */