stringref.h File Reference

Reference-counted immutable strings. More...

This graph shows which files directly or indirectly include this file:

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.

Typedef Documentation

PurpleStringref

typedef struct _PurpleStringref PurpleStringref

Definition at line 36 of file stringref.h.

Function Documentation

purple_stringref_cmp()

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.

purple_stringref_len()

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

purple_stringref_new()

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.

purple_stringref_new_noref()

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.

purple_stringref_printf()

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.

purple_stringref_ref()

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.

purple_stringref_unref()

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.

purple_stringref_value()

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.