summaryrefslogtreecommitdiff
path: root/include/libwapcaplet/libwapcaplet.h
blob: 420f8c3b249cfc404b52ae27f914deb84fe3dee2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
/* libwapcaplet.h
 *
 * String internment and management tools.
 *
 * Copyright 2009 The NetSurf Browser Project.
 *		  Daniel Silverstone <dsilvers@netsurf-browser.org>
 */

#ifndef libwapcaplet_h_
#define libwapcaplet_h_

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

/**
 * Memory allocator type
 */
typedef void *(*lwc_allocator_fn)(void *ptr, size_t size, void *pw);

/**
 * A string internment context.
 */
typedef struct lwc_context_s lwc_context;

/**
 * An interned string.
 */
typedef struct lwc_string_s lwc_string;

/**
 * Error codes which libwapcaplet might return.
 */
typedef enum lwc_error_e {
	lwc_error_ok		= 0,
	lwc_error_oom		= 1,
        lwc_error_range		= 2
} lwc_error;

/**
 * Create an internment context.
 *
 * This creates an internment context with a weak ref of one.
 *
 * You should reference the context with lwc_context_ref to convert
 * that to a strong reference when you decide where to store it.
 */
extern lwc_error lwc_create_context(lwc_allocator_fn alloc, void *pw,
				    lwc_context **ret);

/**
 * Increment the reference count for an internment context.
 */
extern lwc_context *lwc_context_ref(lwc_context *ctx);

/**
 * Decrement the reference count for an internment context.
 *
 * @note If the reference count reaches zero, the context will be freed.
 */
extern void lwc_context_unref(lwc_context *ctx);

/**
 * Intern a string.
 *
 * If the string was already present, its reference count is incremented.
 *
 * The returned string is guaranteed to be NUL-terminated.
 */
extern lwc_error lwc_context_intern(lwc_context *ctx,
				    const char *s, size_t slen,
				    lwc_string **ret);

/**
 * Intern a substring.
 */
extern lwc_error lwc_context_intern_substring(lwc_context *ctx,
					      lwc_string *str,
					      size_t ssoffset, size_t sslen,
					      lwc_string **ret);

/**
 * Increment the reference count on an lwc_string.
 *
 * Use this if copying the string and intending both sides to retain
 * ownership.
 */
extern lwc_string *lwc_context_string_ref(lwc_context *ctx, lwc_string *str);

/**
 * Release a reference on an lwc_string.
 *
 * If the reference count reaches zero then the string will be freed.
 */
extern void lwc_context_string_unref(lwc_context *ctx, lwc_string *str);

/**
 * Check if two interned strings are equal.
 *
 * @note The strings must be from the same intern context and that
 *	 must be the context passed in.
 */
#define lwc_context_string_isequal(ctx, str1, str2, ret) \
	(*ret = (str1 == str2)), lwc_error_ok

/**
 * Check if two interned strings are case-insensitively equal.
 *
 * @note The strings must be from the same intern context and that
 *	 must be the context passed in.
 */
extern lwc_error lwc_context_string_caseless_isequal(lwc_context *ctx,
                                                     lwc_string *str1,
                                                     lwc_string *str2,
                                                     bool *ret);
/**
 * Retrieve the data pointer for an interned string.
 *
 * @note The data we point at belongs to the string and will
 *       die with the string. Keep a ref if you need it.
 */
extern const char *lwc_string_data(lwc_string *str);

/**
 * Retrieve the data length for an interned string.
 *
 * @note The data we point at belongs to the string and will
 *       die with the string. Keep a ref if you need it.
 */
extern size_t lwc_string_length(lwc_string *str);

/**
 * Retrieve (or compute if unavailable) a hash value for the content of the string.
 *
 * @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.
 */
extern uint32_t lwc_string_hash_value(lwc_string *str);

#endif /* libwapcaplet_h_ */