libwapcaplet.h File Reference

#include <sys/types.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <assert.h>

Include dependency graph for libwapcaplet.h:

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

Go to the source code of this file.

Classes
struct	lwc_string_s

Macros
#define	lwc_string_unref(str)
#define	lwc_string_isequal(str1, str2, ret)    ((*(ret) = ((str1) == (str2))), lwc_error_ok)
#define	lwc__assert_and_expr(str, expr)   (expr)
#define	lwc_string_data(str)   lwc__assert_and_expr(str, (const char *)((str)+1))
#define	lwc_string_length(str)   lwc__assert_and_expr(str, (str)->len)
#define	lwc_string_hash_value(str)   lwc__assert_and_expr(str, (str)->hash)

Typedefs
typedef uint32_t	lwc_refcounter
typedef uint32_t	lwc_hash
typedef struct lwc_string_s	lwc_string
typedef void(*	lwc_iteration_callback_fn) (lwc_string *str, void *pw)
typedef enum lwc_error_e	lwc_error

Enumerations
enum	lwc_error_e { lwc_error_ok = 0 , lwc_error_oom = 1 , lwc_error_range = 2 }

Functions
lwc_error	lwc_intern_string (const char *s, size_t slen, lwc_string **ret)
lwc_error	lwc_intern_substring (lwc_string *str, size_t ssoffset, size_t sslen, lwc_string **ret)
lwc_error	lwc_string_tolower (lwc_string *str, lwc_string **ret)
void	lwc_string_destroy (lwc_string *str)
lwc_error	lwc__intern_caseless_string (lwc_string *str)
void	lwc_iterate_strings (lwc_iteration_callback_fn cb, void *pw)

Macro Definition Documentation

lwc__assert_and_expr

#define lwc__assert_and_expr	(		str,
			expr
	)		(expr)

lwc_string_data

#define lwc_string_data

(

str

)

lwc__assert_and_expr(str, (const char *)((str)+1))

Retrieve the data pointer for an interned string.

Parameters

str	The string to retrieve the data pointer for.

Returns

The C string data pointer for str.

Note

The data we point at belongs to the string and will die with the string. Keep a ref if you need it.

You may not rely on the NULL termination of the strings in future. Any code relying on it currently should be modified to use lwc_string_length if possible.

lwc_string_hash_value

#define lwc_string_hash_value

(

str

)

lwc__assert_and_expr(str, (str)->hash)

Retrieve (or compute if unavailable) a hash value for the content of the string.

Parameters

str	The string to get the hash for.

Returns

The 32 bit hash of str.

Note

This API should only be used as a convenient way to retrieve a hash value for the string. This hash value should not be relied on to be unique within an invocation of the program, nor should it be relied upon to be stable between invocations of the program. Never use the hash value as a way to directly identify the value of the string.

lwc_string_isequal

#define lwc_string_isequal	(		str1,
			str2,
			ret
	)		((*(ret) = ((str1) == (str2))), lwc_error_ok)

Check if two interned strings are equal.

Parameters

str1	The first string in the comparison.
str2	The second string in the comparison.
ret	A pointer to a boolean to be filled out with the result.

Returns

Result of operation, if not ok then value pointed to by ret will not be valid.

lwc_string_length

#define lwc_string_length

(

str

)

lwc__assert_and_expr(str, (str)->len)

Retrieve the data length for an interned string.

Parameters

str	The string to retrieve the length of.

Returns

The length of str.

lwc_string_unref

#define lwc_string_unref

(

str

)

Value:

        {                       \
        lwc_string *__lwc_s = (str);                \
        assert(__lwc_s != NULL);                \
        __lwc_s->refcnt--;                      \
        if ((__lwc_s->refcnt == 0) ||                   \
            ((__lwc_s->refcnt == 1) && (__lwc_s->insensitive == __lwc_s)))  \
            lwc_string_destroy(__lwc_s);                \
    }

Release a reference on an lwc_string.

This decreases the reference count on the given lwc_string.

Parameters

str	The string to unref.

Note

If the reference count reaches zero then the string will be freed. (Ref count of 1 where string is its own insensitve match will also result in the string being freed.)

Typedef Documentation

lwc_error

typedef enum lwc_error_e lwc_error

Result codes which libwapcaplet might return.

lwc_hash

typedef uint32_t lwc_hash

The type of a hash value used in libwapcaplet.

lwc_iteration_callback_fn

typedef void(* lwc_iteration_callback_fn) (lwc_string *str, void *pw)

String iteration function

Parameters

str	A string which has been interned.
pw	The private pointer for the allocator.

lwc_refcounter

typedef uint32_t lwc_refcounter

The type of a reference counter used in libwapcaplet.

lwc_string

typedef struct lwc_string_s lwc_string

An interned string.

NOTE: The contents of this struct are considered PRIVATE and may change in future revisions. Do not rely on them whatsoever. They're only here at all so that the ref, unref and matches etc can use them.

Enumeration Type Documentation

lwc_error_e

enum lwc_error_e

Result codes which libwapcaplet might return.

Enumerator
lwc_error_ok	No error.
lwc_error_oom	Out of memory.
lwc_error_range	Substring internment out of range.

Function Documentation

lwc__intern_caseless_string()

lwc_error lwc__intern_caseless_string ( lwc_string *  str )

extern

Intern a caseless copy of the passed string.

Parameters

str	The string to intern the caseless copy of.

Returns

lwc_error_ok if successful, otherwise the error code describing the issue.,

Note

This is for "internal" use by the caseless comparison macro and not for users.

lwc_intern_string()

lwc_error lwc_intern_string ( const char *  s, size_t  slen, lwc_string **  ret  )

extern

Intern a string.

Take a copy of the string data referred to by s and slen and intern it. The resulting lwc_string can be used for simple and caseless comparisons by lwc_string_isequal and lwc_string_caseless_isequal respectively.

Parameters

s	Pointer to the start of the string to intern.
slen	Length of the string in characters. (Not including any terminators)
ret	Pointer to lwc_string pointer to fill out.

Returns

Result of operation, if not OK then the value pointed to by ret will not be valid.

Note

The memory pointed to by s is not referenced by the result.

If the string was already present, its reference count is incremented rather than allocating more memory.

The returned string is currently NULL-terminated but this will not necessarily be the case in future. Try not to rely on it.

lwc_intern_substring()

lwc_error lwc_intern_substring ( lwc_string *  str, size_t  ssoffset, size_t  sslen, lwc_string **  ret  )

extern

Intern a substring.

Intern a subsequence of the provided lwc_string.

Parameters

str	String to acquire substring from.
ssoffset	Substring offset into str.
sslen	Substring length.
ret	Pointer to pointer to lwc_string to fill out.

Returns

Result of operation, if not OK then the value pointed to by ret will not be valid.

lwc_iterate_strings()

void lwc_iterate_strings ( lwc_iteration_callback_fn  cb, void *  pw  )

extern

Iterate the context and return every string in it.

If there are no strings found in the context, then this has the side effect of removing the global context which will reduce the chances of false-positives on leak checkers.

Parameters

cb	The callback to give the string to.
pw	The private word for the callback.

lwc_string_destroy()

void lwc_string_destroy ( lwc_string *  str )

extern

Destroy an unreffed lwc_string.

This destroys an lwc_string whose reference count indicates that it should be.

Parameters

str	The string to unref.

lwc_string_tolower()

lwc_error lwc_string_tolower ( lwc_string *  str, lwc_string **  ret  )

extern

Optain a lowercased lwc_string from given lwc_string.

Parameters

str	String to create lowercase string from.
ret	Pointer to lwc_string pointer to fill out.

Returns

Result of operation, if not OK then the value pointed to by ret will not be valid.