1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/stringref.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,138 @@
1.4 +/* TODO: Can we just replace this whole thing with a GCache */
1.5 +
1.6 +/**
1.7 + * @file stringref.h Reference-counted immutable strings
1.8 + * @ingroup core
1.9 + */
1.10 +
1.11 +/* purple
1.12 + *
1.13 + * Purple is the legal property of its developers, whose names are too numerous
1.14 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.15 + * source distribution.
1.16 + *
1.17 + * This program is free software; you can redistribute it and/or modify
1.18 + * it under the terms of the GNU General Public License as published by
1.19 + * the Free Software Foundation; either version 2 of the License, or
1.20 + * (at your option) any later version.
1.21 + *
1.22 + * This program is distributed in the hope that it will be useful,
1.23 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.24 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.25 + * GNU General Public License for more details.
1.26 + *
1.27 + * You should have received a copy of the GNU General Public License
1.28 + * along with this program; if not, write to the Free Software
1.29 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.30 + *
1.31 + */
1.32 +#ifndef _PURPLE_STRINGREF_H_
1.33 +#define _PURPLE_STRINGREF_H_
1.34 +
1.35 +#ifdef __cplusplus
1.36 +extern "C" {
1.37 +#endif
1.38 +
1.39 +typedef struct _PurpleStringref PurpleStringref;
1.40 +
1.41 +/**
1.42 + * Creates an immutable reference-counted string object. The newly
1.43 + * created object will have a reference count of 1.
1.44 + *
1.45 + * @param value This will be the value of the string; it will be
1.46 + * duplicated.
1.47 + *
1.48 + * @return A newly allocated string reference object with a refcount
1.49 + * of 1.
1.50 + */
1.51 +PurpleStringref *purple_stringref_new(const char *value);
1.52 +
1.53 +/**
1.54 + * Creates an immutable reference-counted string object. The newly
1.55 + * created object will have a reference count of zero, and if it is
1.56 + * not referenced before the next iteration of the mainloop it will
1.57 + * be freed at that time.
1.58 + *
1.59 + * @param value This will be the value of the string; it will be
1.60 + * duplicated.
1.61 + *
1.62 + * @return A newly allocated string reference object with a refcount
1.63 + * of zero.
1.64 + */
1.65 +PurpleStringref *purple_stringref_new_noref(const char *value);
1.66 +
1.67 +/**
1.68 + * Creates an immutable reference-counted string object from a printf
1.69 + * format specification and arguments. The created object will have a
1.70 + * reference count of 1.
1.71 + *
1.72 + * @param format A printf-style format specification.
1.73 + *
1.74 + * @return A newly allocated string reference object with a refcount
1.75 + * of 1.
1.76 + */
1.77 +PurpleStringref *purple_stringref_printf(const char *format, ...);
1.78 +
1.79 +/**
1.80 + * Increase the reference count of the given stringref.
1.81 + *
1.82 + * @param stringref String to be referenced.
1.83 + *
1.84 + * @return A pointer to the referenced string.
1.85 + */
1.86 +PurpleStringref *purple_stringref_ref(PurpleStringref *stringref);
1.87 +
1.88 +/**
1.89 + * Decrease the reference count of the given stringref. If this
1.90 + * reference count reaches zero, the stringref will be freed; thus
1.91 + * you MUST NOT use this string after dereferencing it.
1.92 + *
1.93 + * @param stringref String to be dereferenced.
1.94 + */
1.95 +void purple_stringref_unref(PurpleStringref *stringref);
1.96 +
1.97 +/**
1.98 + * Retrieve the value of a stringref.
1.99 + *
1.100 + * @note This value should not be cached or stored in a local variable.
1.101 + * While there is nothing inherently incorrect about doing so, it
1.102 + * is easy to forget that the cached value is in fact a
1.103 + * reference-counted object and accidentally use it after
1.104 + * dereferencing. This is more problematic for a reference-
1.105 + * counted object than a heap-allocated object, as it may seem to
1.106 + * be valid or invalid nondeterministically based on how many
1.107 + * other references to it exist.
1.108 + *
1.109 + * @param stringref String reference from which to retrieve the value.
1.110 + *
1.111 + * @return The contents of the string reference.
1.112 + */
1.113 +const char *purple_stringref_value(const PurpleStringref *stringref);
1.114 +
1.115 +/**
1.116 + * Compare two stringrefs for string equality. This returns the same
1.117 + * value as strcmp would, where <0 indicates that s1 is "less than" s2
1.118 + * in the ASCII lexicography, 0 indicates equality, etc.
1.119 + *
1.120 + * @param s1 The reference string.
1.121 + *
1.122 + * @param s2 The string to compare against the reference.
1.123 + *
1.124 + * @return An ordering indication on s1 and s2.
1.125 + */
1.126 +int purple_stringref_cmp(const PurpleStringref *s1, const PurpleStringref *s2);
1.127 +
1.128 +/**
1.129 + * Find the length of the string inside a stringref.
1.130 + *
1.131 + * @param stringref The string in whose length we are interested.
1.132 + *
1.133 + * @return The length of the string in stringref
1.134 + */
1.135 +size_t purple_stringref_len(const PurpleStringref *stringref);
1.136 +
1.137 +#ifdef __cplusplus
1.138 +}
1.139 +#endif
1.140 +
1.141 +#endif /* _PURPLE_STRINGREF_H_ */