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

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)

Definition at line 261 of file libwapcaplet.h.

◆ 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.

Definition at line 276 of file libwapcaplet.h.

◆ 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.

Definition at line 298 of file libwapcaplet.h.

◆ 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.

Definition at line 188 of file libwapcaplet.h.

◆ 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.

Definition at line 284 of file libwapcaplet.h.

◆ lwc_string_unref

#define lwc_string_unref ( str )

Value:

                {                                  \
                lwc_string *__lwc_s = (str);                     \
                if (__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.)

Definition at line 159 of file libwapcaplet.h.

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.

Definition at line 31 of file libwapcaplet.h.

◆ 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.

Definition at line 56 of file libwapcaplet.h.

◆ lwc_refcounter

typedef uint32_t lwc_refcounter

The type of a reference counter used in libwapcaplet.

Definition at line 26 of file libwapcaplet.h.

◆ 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.

Definition at line 61 of file libwapcaplet.h.

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.

Definition at line 255 of file libwapcaplet.c.

◆ 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.

Definition at line 143 of file libwapcaplet.c.

◆ 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.

Definition at line 152 of file libwapcaplet.c.

◆ 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.

Definition at line 270 of file libwapcaplet.c.

◆ 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.

Definition at line 187 of file libwapcaplet.c.

◆ 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.

Definition at line 168 of file libwapcaplet.c.

Classes

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ lwc__assert_and_expr

◆ lwc_string_data

◆ lwc_string_hash_value

◆ lwc_string_isequal

◆ lwc_string_length

◆ lwc_string_unref

Typedef Documentation

◆ lwc_error

◆ lwc_hash

◆ lwc_iteration_callback_fn

◆ lwc_refcounter

◆ lwc_string

Enumeration Type Documentation

◆ lwc_error_e

Function Documentation

◆ lwc__intern_caseless_string()

◆ lwc_intern_string()

◆ lwc_intern_substring()

◆ lwc_iterate_strings()

◆ lwc_string_destroy()

◆ lwc_string_tolower()