stringref.h File Reference

Reference-counted immutable strings

purple. More...

Go to the source code of this file.

Typedefs

typedef _PurpleStringref PurpleStringref

Functions

PurpleStringref * purple_stringref_new (const char *value)
 Creates an immutable reference-counted string object.
PurpleStringref * purple_stringref_new_noref (const char *value)
 Creates an immutable reference-counted string object.
PurpleStringref * purple_stringref_printf (const char *format,...)
 Creates an immutable reference-counted string object from a printf format specification and arguments.
PurpleStringref * purple_stringref_ref (PurpleStringref *stringref)
 Increase the reference count of the given stringref.
void purple_stringref_unref (PurpleStringref *stringref)
 Decrease the reference count of the given stringref.
const char * purple_stringref_value (const PurpleStringref *stringref)
 Retrieve the value of a stringref.
int purple_stringref_cmp (const PurpleStringref *s1, const PurpleStringref *s2)
 Compare two stringrefs for string equality.
size_t purple_stringref_len (const PurpleStringref *stringref)
 Find the length of the string inside a stringref.


Detailed Description

Reference-counted immutable strings

purple.

Purple is the legal property of its developers, whose names are too numerous to list here. Please refer to the COPYRIGHT file distributed with this source distribution.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA


Function Documentation

int purple_stringref_cmp const PurpleStringref *  s1,
const PurpleStringref *  s2
 

Compare two stringrefs for string equality.

This returns the same value as strcmp would, where <0 indicates that s1 is "less than" s2 in the ASCII lexicography, 0 indicates equality, etc.

Parameters:
s1 The reference string.
s2 The string to compare against the reference.
Returns:
An ordering indication on s1 and s2.

size_t purple_stringref_len const PurpleStringref *  stringref  ) 
 

Find the length of the string inside a stringref.

Parameters:
stringref The string in whose length we are interested.
Returns:
The length of the string in stringref

PurpleStringref* purple_stringref_new const char *  value  ) 
 

Creates an immutable reference-counted string object.

The newly created object will have a reference count of 1.

Parameters:
value This will be the value of the string; it will be duplicated.
Returns:
A newly allocated string reference object with a refcount of 1.

PurpleStringref* purple_stringref_new_noref const char *  value  ) 
 

Creates an immutable reference-counted string object.

The newly created object will have a reference count of zero, and if it is not referenced before the next iteration of the mainloop it will be freed at that time.

Parameters:
value This will be the value of the string; it will be duplicated.
Returns:
A newly allocated string reference object with a refcount of zero.

PurpleStringref* purple_stringref_printf const char *  format,
  ...
 

Creates an immutable reference-counted string object from a printf format specification and arguments.

The created object will have a reference count of 1.

Parameters:
format A printf-style format specification.
Returns:
A newly allocated string reference object with a refcount of 1.

PurpleStringref* purple_stringref_ref PurpleStringref *  stringref  ) 
 

Increase the reference count of the given stringref.

Parameters:
stringref String to be referenced.
Returns:
A pointer to the referenced string.

void purple_stringref_unref PurpleStringref *  stringref  ) 
 

Decrease the reference count of the given stringref.

If this reference count reaches zero, the stringref will be freed; thus you MUST NOT use this string after dereferencing it.

Parameters:
stringref String to be dereferenced.

const char* purple_stringref_value const PurpleStringref *  stringref  ) 
 

Retrieve the value of a stringref.

Note:
This value should not be cached or stored in a local variable. While there is nothing inherently incorrect about doing so, it is easy to forget that the cached value is in fact a reference-counted object and accidentally use it after dereferencing. This is more problematic for a reference- counted object than a heap-allocated object, as it may seem to be valid or invalid nondeterministically based on how many other references to it exist.
Parameters:
stringref String reference from which to retrieve the value.
Returns:
The contents of the string reference.