libpurple/stringref.h

   1 /* TODO: Can we just replace this whole thing with a GCache */
   2
   3 /**
   4  * @file stringref.h Reference-counted immutable strings
   5  * @ingroup core
   6  */
   7
   8 /* purple
   9  *
  10  * Purple is the legal property of its developers, whose names are too numerous
  11  * to list here.  Please refer to the COPYRIGHT file distributed with this
  12  * source distribution.
  13  *
  14  * This program is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 2 of the License, or
  17  * (at your option) any later version.
  18  *
  19  * This program is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License
  25  * along with this program; if not, write to the Free Software
  26  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  27  *
  28  */
  29 #ifndef _PURPLE_STRINGREF_H_
  30 #define _PURPLE_STRINGREF_H_
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 typedef struct _PurpleStringref PurpleStringref;
  37
  38 /**
  39  * Creates an immutable reference-counted string object.  The newly
  40  * created object will have a reference count of 1.
  41  *
  42  * @param value This will be the value of the string; it will be
  43  *              duplicated.
  44  *
  45  * @return A newly allocated string reference object with a refcount
  46  *         of 1.
  47  */
  48 PurpleStringref *purple_stringref_new(const char *value);
  49
  50 /**
  51  * Creates an immutable reference-counted string object.  The newly
  52  * created object will have a reference count of zero, and if it is
  53  * not referenced before the next iteration of the mainloop it will
  54  * be freed at that time.
  55  *
  56  * @param value This will be the value of the string; it will be
  57  *              duplicated.
  58  *
  59  * @return A newly allocated string reference object with a refcount
  60  *         of zero.
  61  */
  62 PurpleStringref *purple_stringref_new_noref(const char *value);
  63
  64 /**
  65  * Creates an immutable reference-counted string object from a printf
  66  * format specification and arguments.  The created object will have a
  67  * reference count of 1.
  68  *
  69  * @param format A printf-style format specification.
  70  *
  71  * @return A newly allocated string reference object with a refcount
  72  *         of 1.
  73  */
  74 PurpleStringref *purple_stringref_printf(const char *format, ...);
  75
  76 /**
  77  * Increase the reference count of the given stringref.
  78  *
  79  * @param stringref String to be referenced.
  80  *
  81  * @return A pointer to the referenced string.
  82  */
  83 PurpleStringref *purple_stringref_ref(PurpleStringref *stringref);
  84
  85 /**
  86  * Decrease the reference count of the given stringref.  If this
  87  * reference count reaches zero, the stringref will be freed; thus
  88  * you MUST NOT use this string after dereferencing it.
  89  *
  90  * @param stringref String to be dereferenced.
  91  */
  92 void purple_stringref_unref(PurpleStringref *stringref);
  93
  94 /**
  95  * Retrieve the value of a stringref.
  96  *
  97  * @note This value should not be cached or stored in a local variable.
  98  *       While there is nothing inherently incorrect about doing so, it
  99  *       is easy to forget that the cached value is in fact a
 100  *       reference-counted object and accidentally use it after
 101  *       dereferencing.  This is more problematic for a reference-
 102  *       counted object than a heap-allocated object, as it may seem to
 103  *       be valid or invalid nondeterministically based on how many
 104  *       other references to it exist.
 105  *
 106  * @param stringref String reference from which to retrieve the value.
 107  *
 108  * @return The contents of the string reference.
 109  */
 110 const char *purple_stringref_value(const PurpleStringref *stringref);
 111
 112 /**
 113  * Compare two stringrefs for string equality.  This returns the same
 114  * value as strcmp would, where <0 indicates that s1 is "less than" s2
 115  * in the ASCII lexicography, 0 indicates equality, etc.
 116  *
 117  * @param s1 The reference string.
 118  *
 119  * @param s2 The string to compare against the reference.
 120  *
 121  * @return An ordering indication on s1 and s2.
 122  */
 123 int purple_stringref_cmp(const PurpleStringref *s1, const PurpleStringref *s2);
 124
 125 /**
 126  * Find the length of the string inside a stringref.
 127  *
 128  * @param stringref The string in whose length we are interested.
 129  *
 130  * @return The length of the string in stringref
 131  */
 132 size_t purple_stringref_len(const PurpleStringref *stringref);
 133
 134 #ifdef __cplusplus
 135 }
 136 #endif
 137
 138 #endif /* _PURPLE_STRINGREF_H_ */