2005-02-10 Havoc Pennington <hp@redhat.com>
[platform/upstream/dbus.git] / dbus / dbus-string.h
1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-string.h String utility class (internal to D-BUS implementation)
3  * 
4  * Copyright (C) 2002, 2003 Red Hat, Inc.
5  *
6  * Licensed under the Academic Free License version 2.1
7  * 
8  * This program is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation; either version 2 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  * 
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, write to the Free Software
20  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
21  *
22  */
23
24 #ifndef DBUS_STRING_H
25 #define DBUS_STRING_H
26
27 #include <config.h>
28
29 #include <dbus/dbus-memory.h>
30 #include <dbus/dbus-types.h>
31 #include <dbus/dbus-sysdeps.h>
32
33 #include <stdarg.h>
34
35 DBUS_BEGIN_DECLS
36
37 /**
38  * DBusString object
39  */
40 struct DBusString
41 {
42   const void *dummy1; /**< placeholder */
43   int   dummy2;       /**< placeholder */
44   int   dummy3;       /**< placeholder */
45   int   dummy4;       /**< placeholder */
46   unsigned int dummy5 : 1; /**< placeholder */
47   unsigned int dummy6 : 1; /**< placeholder */
48   unsigned int dummy7 : 1; /**< placeholder */
49   unsigned int dummy8 : 3; /**< placeholder */
50 };
51
52 #ifdef DBUS_DISABLE_ASSERT
53 /* Some simple inlining hacks; the current linker is not smart enough
54  * to inline non-exported symbols across files in the library.
55  * Note that these break type safety (due to the casts)
56  */
57 #define _dbus_string_get_data(s) ((char*)(((DBusString*)(s))->dummy1))
58 #define _dbus_string_get_length(s) (((DBusString*)(s))->dummy2)
59 #define _dbus_string_set_byte(s, i, b) ((((unsigned char*)(((DBusString*)(s))->dummy1))[(i)]) = (unsigned char) (b))
60 #define _dbus_string_get_byte(s, i) (((const unsigned char*)(((DBusString*)(s))->dummy1))[(i)])
61 #define _dbus_string_get_const_data(s) ((const char*)(((DBusString*)(s))->dummy1))
62 #define _dbus_string_get_const_data_len(s,start,len) (((const char*)(((DBusString*)(s))->dummy1)) + (start))
63 #endif
64
65 dbus_bool_t   _dbus_string_init                  (DBusString        *str);
66 void          _dbus_string_init_const            (DBusString        *str,
67                                                   const char        *value);
68 void          _dbus_string_init_const_len        (DBusString        *str,
69                                                   const char        *value,
70                                                   int                len);
71 dbus_bool_t   _dbus_string_init_preallocated     (DBusString        *str,
72                                                   int                allocate_size);
73 void          _dbus_string_free                  (DBusString        *str);
74 void          _dbus_string_lock                  (DBusString        *str);
75 #ifndef _dbus_string_get_data
76 char*         _dbus_string_get_data              (DBusString        *str);
77 #endif /* _dbus_string_get_data */
78 #ifndef _dbus_string_get_const_data
79 const char*   _dbus_string_get_const_data        (const DBusString  *str);
80 #endif /* _dbus_string_get_const_data */
81 char*         _dbus_string_get_data_len          (DBusString        *str,
82                                                   int                start,
83                                                   int                len);
84 #ifndef _dbus_string_get_const_data_len
85 const char*   _dbus_string_get_const_data_len    (const DBusString  *str,
86                                                   int                start,
87                                                   int                len);
88 #endif
89 #ifndef _dbus_string_set_byte
90 void          _dbus_string_set_byte              (DBusString        *str,
91                                                   int                i,
92                                                   unsigned char      byte);
93 #endif
94 #ifndef _dbus_string_get_byte
95 unsigned char _dbus_string_get_byte              (const DBusString  *str,
96                                                   int                start);
97 #endif /* _dbus_string_get_byte */
98 dbus_bool_t   _dbus_string_insert_bytes          (DBusString        *str,
99                                                   int                i,
100                                                   int                n_bytes,
101                                                   unsigned char      byte);
102 dbus_bool_t   _dbus_string_insert_byte           (DBusString        *str,
103                                                   int                i,
104                                                   unsigned char      byte);
105 dbus_bool_t   _dbus_string_steal_data            (DBusString        *str,
106                                                   char             **data_return);
107 dbus_bool_t   _dbus_string_steal_data_len        (DBusString        *str,
108                                                   char             **data_return,
109                                                   int                start,
110                                                   int                len);
111 dbus_bool_t   _dbus_string_copy_data             (const DBusString  *str,
112                                                   char             **data_return);
113 dbus_bool_t   _dbus_string_copy_data_len         (const DBusString  *str,
114                                                   char             **data_return,
115                                                   int                start,
116                                                   int                len);
117 void          _dbus_string_copy_to_buffer        (const DBusString  *str,
118                                                   char              *buffer,
119                                                   int                len);
120 #ifndef _dbus_string_get_length
121 int           _dbus_string_get_length            (const DBusString  *str);
122 #endif /* !_dbus_string_get_length */
123
124 dbus_bool_t   _dbus_string_lengthen              (DBusString        *str,
125                                                   int                additional_length);
126 void          _dbus_string_shorten               (DBusString        *str,
127                                                   int                length_to_remove);
128 dbus_bool_t   _dbus_string_set_length            (DBusString        *str,
129                                                   int                length);
130 dbus_bool_t   _dbus_string_align_length          (DBusString        *str,
131                                                   int                alignment);
132 dbus_bool_t   _dbus_string_alloc_space           (DBusString        *str,
133                                                   int                extra_bytes);
134 dbus_bool_t   _dbus_string_append                (DBusString        *str,
135                                                   const char        *buffer);
136 dbus_bool_t   _dbus_string_append_len            (DBusString        *str,
137                                                   const char        *buffer,
138                                                   int                len);
139 dbus_bool_t   _dbus_string_append_int            (DBusString        *str,
140                                                   long               value);
141 dbus_bool_t   _dbus_string_append_uint           (DBusString        *str,
142                                                   unsigned long      value);
143 dbus_bool_t   _dbus_string_append_double         (DBusString        *str,
144                                                   double             value);
145 dbus_bool_t   _dbus_string_append_byte           (DBusString        *str,
146                                                   unsigned char      byte);
147 dbus_bool_t   _dbus_string_append_unichar        (DBusString        *str,
148                                                   dbus_unichar_t     ch);
149 dbus_bool_t   _dbus_string_append_4_aligned      (DBusString        *str,
150                                                   const unsigned char octets[4]);
151 dbus_bool_t   _dbus_string_append_8_aligned      (DBusString        *str,
152                                                   const unsigned char octets[8]);
153 dbus_bool_t   _dbus_string_append_printf         (DBusString        *str,
154                                                   const char        *format,
155                                                   ...) _DBUS_GNUC_PRINTF (2, 3);
156 dbus_bool_t   _dbus_string_append_printf_valist  (DBusString        *str,
157                                                   const char        *format,
158                                                   va_list            args);
159 dbus_bool_t   _dbus_string_insert_2_aligned      (DBusString        *str,
160                                                   int                insert_at,
161                                                   const unsigned char octets[2]);
162 dbus_bool_t   _dbus_string_insert_4_aligned      (DBusString        *str,
163                                                   int                insert_at,
164                                                   const unsigned char octets[4]);
165 dbus_bool_t   _dbus_string_insert_8_aligned      (DBusString        *str,
166                                                   int                insert_at,
167                                                   const unsigned char octets[8]);
168 dbus_bool_t   _dbus_string_insert_alignment      (DBusString        *str,
169                                                   int               *insert_at,
170                                                   int                alignment);
171 void          _dbus_string_delete                (DBusString        *str,
172                                                   int                start,
173                                                   int                len);
174 dbus_bool_t   _dbus_string_move                  (DBusString        *source,
175                                                   int                start,
176                                                   DBusString        *dest,
177                                                   int                insert_at);
178 dbus_bool_t   _dbus_string_copy                  (const DBusString  *source,
179                                                   int                start,
180                                                   DBusString        *dest,
181                                                   int                insert_at);
182 dbus_bool_t   _dbus_string_move_len              (DBusString        *source,
183                                                   int                start,
184                                                   int                len,
185                                                   DBusString        *dest,
186                                                   int                insert_at);
187 dbus_bool_t   _dbus_string_copy_len              (const DBusString  *source,
188                                                   int                start,
189                                                   int                len,
190                                                   DBusString        *dest,
191                                                   int                insert_at);
192 dbus_bool_t   _dbus_string_replace_len           (const DBusString  *source,
193                                                   int                start,
194                                                   int                len,
195                                                   DBusString        *dest,
196                                                   int                replace_at,
197                                                   int                replace_len);
198 void          _dbus_string_get_unichar           (const DBusString  *str,
199                                                   int                start,
200                                                   dbus_unichar_t    *ch_return,
201                                                   int               *end_return);
202 dbus_bool_t   _dbus_string_parse_int             (const DBusString  *str,
203                                                   int                start,
204                                                   long              *value_return,
205                                                   int               *end_return);
206 dbus_bool_t   _dbus_string_parse_uint            (const DBusString  *str,
207                                                   int                start,
208                                                   unsigned long     *value_return,
209                                                   int               *end_return);
210 dbus_bool_t   _dbus_string_parse_double          (const DBusString  *str,
211                                                   int                start,
212                                                   double            *value,
213                                                   int               *end_return);
214 dbus_bool_t   _dbus_string_find                  (const DBusString  *str,
215                                                   int                start,
216                                                   const char        *substr,
217                                                   int               *found);
218 dbus_bool_t   _dbus_string_find_to               (const DBusString  *str,
219                                                   int                start,
220                                                   int                end,
221                                                   const char        *substr,
222                                                   int               *found);
223 dbus_bool_t   _dbus_string_find_byte_backward    (const DBusString  *str,
224                                                   int                start,
225                                                   unsigned char      byte,
226                                                   int               *found);
227 dbus_bool_t   _dbus_string_find_blank            (const DBusString  *str,
228                                                   int                start,
229                                                   int               *found);
230 void          _dbus_string_skip_blank            (const DBusString  *str,
231                                                   int                start,
232                                                   int               *end);
233 void          _dbus_string_skip_white            (const DBusString  *str,
234                                                   int                start,
235                                                   int               *end);
236 dbus_bool_t   _dbus_string_equal                 (const DBusString  *a,
237                                                   const DBusString  *b);
238 dbus_bool_t   _dbus_string_equal_c_str           (const DBusString  *a,
239                                                   const char        *c_str);
240 dbus_bool_t   _dbus_string_equal_len             (const DBusString  *a,
241                                                   const DBusString  *b,
242                                                   int                len);
243 dbus_bool_t   _dbus_string_equal_substring       (const DBusString  *a,
244                                                   int                a_start,
245                                                   int                a_len,
246                                                   const DBusString  *b,
247                                                   int                b_start);
248 dbus_bool_t   _dbus_string_starts_with_c_str     (const DBusString  *a,
249                                                   const char        *c_str);
250 dbus_bool_t   _dbus_string_ends_with_c_str       (const DBusString  *a,
251                                                   const char        *c_str);
252 dbus_bool_t   _dbus_string_pop_line              (DBusString        *source,
253                                                   DBusString        *dest);
254 void          _dbus_string_delete_first_word     (DBusString        *str);
255 void          _dbus_string_delete_leading_blanks (DBusString        *str);
256 dbus_bool_t   _dbus_string_append_byte_as_hex    (DBusString        *str,
257                                                   int                byte);
258 dbus_bool_t   _dbus_string_hex_encode            (const DBusString  *source,
259                                                   int                start,
260                                                   DBusString        *dest,
261                                                   int                insert_at);
262 dbus_bool_t   _dbus_string_hex_decode            (const DBusString  *source,
263                                                   int                start,
264                                                   int               *end_return,
265                                                   DBusString        *dest,
266                                                   int                insert_at);
267 dbus_bool_t   _dbus_string_validate_ascii        (const DBusString  *str,
268                                                   int                start,
269                                                   int                len);
270 dbus_bool_t   _dbus_string_validate_utf8         (const DBusString  *str,
271                                                   int                start,
272                                                   int                len);
273 dbus_bool_t   _dbus_string_validate_nul          (const DBusString  *str,
274                                                   int                start,
275                                                   int                len);
276 void          _dbus_string_zero                  (DBusString        *str);
277
278
279 /**
280  * We allocate 1 byte for nul termination, plus 7 bytes for possible
281  * align_offset, so we always need 8 bytes on top of the string's
282  * length to be in the allocated block.
283  */
284 #define _DBUS_STRING_ALLOCATION_PADDING 8
285
286 /**
287  * Defines a static const variable with type #DBusString called "name"
288  * containing the given string literal.
289  *
290  * @param name the name of the variable
291  * @param str the string value
292  */
293 #define _DBUS_STRING_DEFINE_STATIC(name, str)                           \
294   static const char _dbus_static_string_##name[] = str;                 \
295   static const DBusString name = { _dbus_static_string_##name,          \
296                                    sizeof(_dbus_static_string_##name),  \
297                                    sizeof(_dbus_static_string_##name) + \
298                                    _DBUS_STRING_ALLOCATION_PADDING,     \
299                                    sizeof(_dbus_static_string_##name),  \
300                                    TRUE, TRUE, FALSE, 0 }
301
302 DBUS_END_DECLS
303
304 #endif /* DBUS_STRING_H */