Mercurial > pidgin3 / file comparison

comparison: libpurple/stringref.h

libpurple/stringref.h

changeset 40306
012857bbfc69
parent 40305
d0aa478e8e8a
child 40309
913a68cbf8b9
equal deleted inserted replaced
40305:d0aa478e8e8a 40306:012857bbfc69
1 /* TODO: Can we just replace this whole thing with a GCache */
2
3 /* purple
4 *
5 * Purple is the legal property of its developers, whose names are too numerous
6 * to list here. Please refer to the COPYRIGHT file distributed with this
7 * source distribution.
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., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
22 *
23 */
24
25 #ifndef PURPLE_STRINGREF_H
26 #define PURPLE_STRINGREF_H
27 /**
28 * SECTION:stringref
29 * @section_id: libpurple-stringref
30 * @short_description: <filename>stringref.h</filename>
31 * @title: Reference-counted Immutable Strings
32 */
33
34 typedef struct _PurpleStringref PurpleStringref;
35
36 G_BEGIN_DECLS
37
38 /**
39 * purple_stringref_new:
40 * @value: This will be the value of the string; it will be
41 * duplicated.
42 *
43 * Creates an immutable reference-counted string object. The newly
44 * created object will have a reference count of 1.
45 *
46 * Returns: (transfer full): A newly allocated string reference object with a refcount
47 * of 1.
48 */
49 PurpleStringref *purple_stringref_new(const char *value);
50
51 /**
52 * purple_stringref_new_noref:
53 * @value: This will be the value of the string; it will be
54 * duplicated.
55 *
56 * Creates an immutable reference-counted string object. The newly
57 * created object will have a reference count of zero, and if it is
58 * not referenced before the next iteration of the mainloop it will
59 * be freed at that time.
60 *
61 * Returns: (transfer full): A newly allocated string reference object with a refcount
62 * of zero.
63 */
64 PurpleStringref *purple_stringref_new_noref(const char *value);
65
66 /**
67 * purple_stringref_printf:
68 * @format: A printf-style format specification.
69 * @...: The arguments for the format specification.
70 *
71 * Creates an immutable reference-counted string object from a printf
72 * format specification and arguments. The created object will have a
73 * reference count of 1.
74 *
75 * Returns: A newly allocated string reference object with a refcount
76 * of 1.
77 */
78 PurpleStringref *purple_stringref_printf(const char *format, ...);
79
80 /**
81 * purple_stringref_ref:
82 * @stringref: String to be referenced.
83 *
84 * Increase the reference count of the given stringref.
85 *
86 * Returns: (transfer full): A pointer to the referenced string.
87 */
88 PurpleStringref *purple_stringref_ref(PurpleStringref *stringref);
89
90 /**
91 * purple_stringref_unref:
92 * @stringref: String to be dereferenced.
93 *
94 * Decrease the reference count of the given stringref. If this
95 * reference count reaches zero, the stringref will be freed; thus
96 * you MUST NOT use this string after dereferencing it.
97 */
98 void purple_stringref_unref(PurpleStringref *stringref);
99
100 /**
101 * purple_stringref_value:
102 * @stringref: String reference from which to retrieve the value.
103 *
104 * Retrieve the value of a stringref.
105 *
106 * Note: This value should not be cached or stored in a local variable.
107 * While there is nothing inherently incorrect about doing so, it
108 * is easy to forget that the cached value is in fact a
109 * reference-counted object and accidentally use it after
110 * dereferencing. This is more problematic for a reference-
111 * counted object than a heap-allocated object, as it may seem to
112 * be valid or invalid nondeterministically based on how many
113 * other references to it exist.
114 *
115 * Returns: The contents of the string reference.
116 */
117 const char *purple_stringref_value(const PurpleStringref *stringref);
118
119 /**
120 * purple_stringref_cmp:
121 * @s1: The reference string.
122 * @s2: The string to compare against the reference.
123 *
124 * Compare two stringrefs for string equality. This returns the same
125 * value as strcmp would, where <0 indicates that s1 is "less than" s2
126 * in the ASCII lexicography, 0 indicates equality, etc.
127 *
128 * Returns: An ordering indication on s1 and s2.
129 */
130 int purple_stringref_cmp(const PurpleStringref *s1, const PurpleStringref *s2);
131
132 /**
133 * purple_stringref_len:
134 * @stringref: The string in whose length we are interested.
135 *
136 * Find the length of the string inside a stringref.
137 *
138 * Returns: The length of the string in stringref
139 */
140 size_t purple_stringref_len(const PurpleStringref *stringref);
141
142 G_END_DECLS
143
144 #endif /* PURPLE_STRINGREF_H */

Mercurial Repository: pidgin3

mercurial