stringref.h File Reference

Reference-counted immutable strings. More...

Go to the source code of this file.

Typedefs

typedef struct _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.

Definition in file stringref.h.


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.