1/*
2 * Copyright © 2009, 2010 Codethink Limited
3 * Copyright © 2011 Collabora Ltd.
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
17 *
18 * Author: Ryan Lortie <desrt@desrt.ca>
19 * Stef Walter <stefw@collabora.co.uk>
20 */
21
22#include "config.h"
23
24#include "gbytes.h"
25
26#include <glib/garray.h>
27#include <glib/gstrfuncs.h>
28#include <glib/gatomic.h>
29#include <glib/gslice.h>
30#include <glib/gtestutils.h>
31#include <glib/gmem.h>
32#include <glib/gmessages.h>
33#include <glib/grefcount.h>
34
35#include <string.h>
36
37/**
38 * GBytes:
39 *
40 * A simple refcounted data type representing an immutable sequence of zero or
41 * more bytes from an unspecified origin.
42 *
43 * The purpose of a #GBytes is to keep the memory region that it holds
44 * alive for as long as anyone holds a reference to the bytes. When
45 * the last reference count is dropped, the memory is released. Multiple
46 * unrelated callers can use byte data in the #GBytes without coordinating
47 * their activities, resting assured that the byte data will not change or
48 * move while they hold a reference.
49 *
50 * A #GBytes can come from many different origins that may have
51 * different procedures for freeing the memory region. Examples are
52 * memory from g_malloc(), from memory slices, from a #GMappedFile or
53 * memory from other allocators.
54 *
55 * #GBytes work well as keys in #GHashTable. Use g_bytes_equal() and
56 * g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full().
57 * #GBytes can also be used as keys in a #GTree by passing the g_bytes_compare()
58 * function to g_tree_new().
59 *
60 * The data pointed to by this bytes must not be modified. For a mutable
61 * array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a
62 * mutable array for a #GBytes sequence. To create an immutable #GBytes from
63 * a mutable #GByteArray, use the g_byte_array_free_to_bytes() function.
64 *
65 * Since: 2.32
66 **/
67
68/* Keep in sync with glib/tests/bytes.c */
69struct _GBytes
70{
71 gconstpointer data; /* may be NULL iff (size == 0) */
72 gsize size; /* may be 0 */
73 gatomicrefcount ref_count;
74 GDestroyNotify free_func;
75 gpointer user_data;
76};
77
78/**
79 * g_bytes_new:
80 * @data: (transfer none) (array length=size) (element-type guint8) (nullable):
81 * the data to be used for the bytes
82 * @size: the size of @data
83 *
84 * Creates a new #GBytes from @data.
85 *
86 * @data is copied. If @size is 0, @data may be %NULL.
87 *
88 * Returns: (transfer full): a new #GBytes
89 *
90 * Since: 2.32
91 */
92GBytes *
93g_bytes_new (gconstpointer data,
94 gsize size)
95{
96 g_return_val_if_fail (data != NULL || size == 0, NULL);
97
98 return g_bytes_new_take (data: g_memdup2 (mem: data, byte_size: size), size);
99}
100
101/**
102 * g_bytes_new_take:
103 * @data: (transfer full) (array length=size) (element-type guint8) (nullable):
104 * the data to be used for the bytes
105 * @size: the size of @data
106 *
107 * Creates a new #GBytes from @data.
108 *
109 * After this call, @data belongs to the bytes and may no longer be
110 * modified by the caller. g_free() will be called on @data when the
111 * bytes is no longer in use. Because of this @data must have been created by
112 * a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many
113 * functions that wrap these calls (such as g_new(), g_strdup(), etc).
114 *
115 * For creating #GBytes with memory from other allocators, see
116 * g_bytes_new_with_free_func().
117 *
118 * @data may be %NULL if @size is 0.
119 *
120 * Returns: (transfer full): a new #GBytes
121 *
122 * Since: 2.32
123 */
124GBytes *
125g_bytes_new_take (gpointer data,
126 gsize size)
127{
128 return g_bytes_new_with_free_func (data, size, free_func: g_free, user_data: data);
129}
130
131
132/**
133 * g_bytes_new_static: (skip)
134 * @data: (transfer full) (array length=size) (element-type guint8) (nullable):
135 * the data to be used for the bytes
136 * @size: the size of @data
137 *
138 * Creates a new #GBytes from static data.
139 *
140 * @data must be static (ie: never modified or freed). It may be %NULL if @size
141 * is 0.
142 *
143 * Returns: (transfer full): a new #GBytes
144 *
145 * Since: 2.32
146 */
147GBytes *
148g_bytes_new_static (gconstpointer data,
149 gsize size)
150{
151 return g_bytes_new_with_free_func (data, size, NULL, NULL);
152}
153
154/**
155 * g_bytes_new_with_free_func: (skip)
156 * @data: (array length=size) (element-type guint8) (nullable):
157 * the data to be used for the bytes
158 * @size: the size of @data
159 * @free_func: the function to call to release the data
160 * @user_data: data to pass to @free_func
161 *
162 * Creates a #GBytes from @data.
163 *
164 * When the last reference is dropped, @free_func will be called with the
165 * @user_data argument.
166 *
167 * @data must not be modified after this call is made until @free_func has
168 * been called to indicate that the bytes is no longer in use.
169 *
170 * @data may be %NULL if @size is 0.
171 *
172 * Returns: (transfer full): a new #GBytes
173 *
174 * Since: 2.32
175 */
176GBytes *
177g_bytes_new_with_free_func (gconstpointer data,
178 gsize size,
179 GDestroyNotify free_func,
180 gpointer user_data)
181{
182 GBytes *bytes;
183
184 g_return_val_if_fail (data != NULL || size == 0, NULL);
185
186 bytes = g_slice_new (GBytes);
187 bytes->data = data;
188 bytes->size = size;
189 bytes->free_func = free_func;
190 bytes->user_data = user_data;
191 g_atomic_ref_count_init (arc: &bytes->ref_count);
192
193 return (GBytes *)bytes;
194}
195
196/**
197 * g_bytes_new_from_bytes:
198 * @bytes: a #GBytes
199 * @offset: offset which subsection starts at
200 * @length: length of subsection
201 *
202 * Creates a #GBytes which is a subsection of another #GBytes. The @offset +
203 * @length may not be longer than the size of @bytes.
204 *
205 * A reference to @bytes will be held by the newly created #GBytes until
206 * the byte data is no longer needed.
207 *
208 * Since 2.56, if @offset is 0 and @length matches the size of @bytes, then
209 * @bytes will be returned with the reference count incremented by 1. If @bytes
210 * is a slice of another #GBytes, then the resulting #GBytes will reference
211 * the same #GBytes instead of @bytes. This allows consumers to simplify the
212 * usage of #GBytes when asynchronously writing to streams.
213 *
214 * Returns: (transfer full): a new #GBytes
215 *
216 * Since: 2.32
217 */
218GBytes *
219g_bytes_new_from_bytes (GBytes *bytes,
220 gsize offset,
221 gsize length)
222{
223 gchar *base;
224
225 /* Note that length may be 0. */
226 g_return_val_if_fail (bytes != NULL, NULL);
227 g_return_val_if_fail (offset <= bytes->size, NULL);
228 g_return_val_if_fail (offset + length <= bytes->size, NULL);
229
230 /* Avoid an extra GBytes if all bytes were requested */
231 if (offset == 0 && length == bytes->size)
232 return g_bytes_ref (bytes);
233
234 base = (gchar *)bytes->data + offset;
235
236 /* Avoid referencing intermediate GBytes. In practice, this should
237 * only loop once.
238 */
239 while (bytes->free_func == (gpointer)g_bytes_unref)
240 bytes = bytes->user_data;
241
242 g_return_val_if_fail (bytes != NULL, NULL);
243 g_return_val_if_fail (base >= (gchar *)bytes->data, NULL);
244 g_return_val_if_fail (base <= (gchar *)bytes->data + bytes->size, NULL);
245 g_return_val_if_fail (base + length <= (gchar *)bytes->data + bytes->size, NULL);
246
247 return g_bytes_new_with_free_func (data: base, size: length,
248 free_func: (GDestroyNotify)g_bytes_unref, user_data: g_bytes_ref (bytes));
249}
250
251/**
252 * g_bytes_get_data:
253 * @bytes: a #GBytes
254 * @size: (out) (optional): location to return size of byte data
255 *
256 * Get the byte data in the #GBytes. This data should not be modified.
257 *
258 * This function will always return the same pointer for a given #GBytes.
259 *
260 * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes
261 * may represent an empty string with @data non-%NULL and @size as 0. %NULL will
262 * not be returned if @size is non-zero.
263 *
264 * Returns: (transfer none) (array length=size) (element-type guint8) (nullable):
265 * a pointer to the byte data, or %NULL
266 *
267 * Since: 2.32
268 */
269gconstpointer
270g_bytes_get_data (GBytes *bytes,
271 gsize *size)
272{
273 g_return_val_if_fail (bytes != NULL, NULL);
274 if (size)
275 *size = bytes->size;
276 return bytes->data;
277}
278
279/**
280 * g_bytes_get_size:
281 * @bytes: a #GBytes
282 *
283 * Get the size of the byte data in the #GBytes.
284 *
285 * This function will always return the same value for a given #GBytes.
286 *
287 * Returns: the size
288 *
289 * Since: 2.32
290 */
291gsize
292g_bytes_get_size (GBytes *bytes)
293{
294 g_return_val_if_fail (bytes != NULL, 0);
295 return bytes->size;
296}
297
298
299/**
300 * g_bytes_ref:
301 * @bytes: a #GBytes
302 *
303 * Increase the reference count on @bytes.
304 *
305 * Returns: the #GBytes
306 *
307 * Since: 2.32
308 */
309GBytes *
310g_bytes_ref (GBytes *bytes)
311{
312 g_return_val_if_fail (bytes != NULL, NULL);
313
314 g_atomic_ref_count_inc (arc: &bytes->ref_count);
315
316 return bytes;
317}
318
319/**
320 * g_bytes_unref:
321 * @bytes: (nullable): a #GBytes
322 *
323 * Releases a reference on @bytes. This may result in the bytes being
324 * freed. If @bytes is %NULL, it will return immediately.
325 *
326 * Since: 2.32
327 */
328void
329g_bytes_unref (GBytes *bytes)
330{
331 if (bytes == NULL)
332 return;
333
334 if (g_atomic_ref_count_dec (arc: &bytes->ref_count))
335 {
336 if (bytes->free_func != NULL)
337 bytes->free_func (bytes->user_data);
338 g_slice_free (GBytes, bytes);
339 }
340}
341
342/**
343 * g_bytes_equal:
344 * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
345 * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
346 *
347 * Compares the two #GBytes values being pointed to and returns
348 * %TRUE if they are equal.
349 *
350 * This function can be passed to g_hash_table_new() as the @key_equal_func
351 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
352 *
353 * Returns: %TRUE if the two keys match.
354 *
355 * Since: 2.32
356 */
357gboolean
358g_bytes_equal (gconstpointer bytes1,
359 gconstpointer bytes2)
360{
361 const GBytes *b1 = bytes1;
362 const GBytes *b2 = bytes2;
363
364 g_return_val_if_fail (bytes1 != NULL, FALSE);
365 g_return_val_if_fail (bytes2 != NULL, FALSE);
366
367 return b1->size == b2->size &&
368 (b1->size == 0 || memcmp (s1: b1->data, s2: b2->data, n: b1->size) == 0);
369}
370
371/**
372 * g_bytes_hash:
373 * @bytes: (type GLib.Bytes): a pointer to a #GBytes key
374 *
375 * Creates an integer hash code for the byte data in the #GBytes.
376 *
377 * This function can be passed to g_hash_table_new() as the @key_hash_func
378 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
379 *
380 * Returns: a hash value corresponding to the key.
381 *
382 * Since: 2.32
383 */
384guint
385g_bytes_hash (gconstpointer bytes)
386{
387 const GBytes *a = bytes;
388 const signed char *p, *e;
389 guint32 h = 5381;
390
391 g_return_val_if_fail (bytes != NULL, 0);
392
393 for (p = (signed char *)a->data, e = (signed char *)a->data + a->size; p != e; p++)
394 h = (h << 5) + h + *p;
395
396 return h;
397}
398
399/**
400 * g_bytes_compare:
401 * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
402 * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
403 *
404 * Compares the two #GBytes values.
405 *
406 * This function can be used to sort GBytes instances in lexicographical order.
407 *
408 * If @bytes1 and @bytes2 have different length but the shorter one is a
409 * prefix of the longer one then the shorter one is considered to be less than
410 * the longer one. Otherwise the first byte where both differ is used for
411 * comparison. If @bytes1 has a smaller value at that position it is
412 * considered less, otherwise greater than @bytes2.
413 *
414 * Returns: a negative value if @bytes1 is less than @bytes2, a positive value
415 * if @bytes1 is greater than @bytes2, and zero if @bytes1 is equal to
416 * @bytes2
417 *
418 *
419 * Since: 2.32
420 */
421gint
422g_bytes_compare (gconstpointer bytes1,
423 gconstpointer bytes2)
424{
425 const GBytes *b1 = bytes1;
426 const GBytes *b2 = bytes2;
427 gint ret;
428
429 g_return_val_if_fail (bytes1 != NULL, 0);
430 g_return_val_if_fail (bytes2 != NULL, 0);
431
432 ret = memcmp (s1: b1->data, s2: b2->data, MIN (b1->size, b2->size));
433 if (ret == 0 && b1->size != b2->size)
434 ret = b1->size < b2->size ? -1 : 1;
435 return ret;
436}
437
438static gpointer
439try_steal_and_unref (GBytes *bytes,
440 GDestroyNotify free_func,
441 gsize *size)
442{
443 gpointer result;
444
445 if (bytes->free_func != free_func || bytes->data == NULL ||
446 bytes->user_data != bytes->data)
447 return NULL;
448
449 /* Are we the only reference? */
450 if (g_atomic_ref_count_compare (arc: &bytes->ref_count, val: 1))
451 {
452 *size = bytes->size;
453 result = (gpointer)bytes->data;
454 g_slice_free (GBytes, bytes);
455 return result;
456 }
457
458 return NULL;
459}
460
461
462/**
463 * g_bytes_unref_to_data:
464 * @bytes: (transfer full): a #GBytes
465 * @size: (out): location to place the length of the returned data
466 *
467 * Unreferences the bytes, and returns a pointer the same byte data
468 * contents.
469 *
470 * As an optimization, the byte data is returned without copying if this was
471 * the last reference to bytes and bytes was created with g_bytes_new(),
472 * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
473 * data is copied.
474 *
475 * Returns: (transfer full) (array length=size) (element-type guint8)
476 * (not nullable): a pointer to the same byte data, which should be
477 * freed with g_free()
478 *
479 * Since: 2.32
480 */
481gpointer
482g_bytes_unref_to_data (GBytes *bytes,
483 gsize *size)
484{
485 gpointer result;
486
487 g_return_val_if_fail (bytes != NULL, NULL);
488 g_return_val_if_fail (size != NULL, NULL);
489
490 /*
491 * Optimal path: if this is was the last reference, then we can return
492 * the data from this GBytes without copying.
493 */
494
495 result = try_steal_and_unref (bytes, free_func: g_free, size);
496 if (result == NULL)
497 {
498 /*
499 * Copy: Non g_malloc (or compatible) allocator, or static memory,
500 * so we have to copy, and then unref.
501 */
502 result = g_memdup2 (mem: bytes->data, byte_size: bytes->size);
503 *size = bytes->size;
504 g_bytes_unref (bytes);
505 }
506
507 return result;
508}
509
510/**
511 * g_bytes_unref_to_array:
512 * @bytes: (transfer full): a #GBytes
513 *
514 * Unreferences the bytes, and returns a new mutable #GByteArray containing
515 * the same byte data.
516 *
517 * As an optimization, the byte data is transferred to the array without copying
518 * if this was the last reference to bytes and bytes was created with
519 * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all
520 * other cases the data is copied.
521 *
522 * Do not use it if @bytes contains more than %G_MAXUINT
523 * bytes. #GByteArray stores the length of its data in #guint, which
524 * may be shorter than #gsize, that @bytes is using.
525 *
526 * Returns: (transfer full): a new mutable #GByteArray containing the same byte data
527 *
528 * Since: 2.32
529 */
530GByteArray *
531g_bytes_unref_to_array (GBytes *bytes)
532{
533 gpointer data;
534 gsize size;
535
536 g_return_val_if_fail (bytes != NULL, NULL);
537
538 data = g_bytes_unref_to_data (bytes, size: &size);
539 return g_byte_array_new_take (data, len: size);
540}
541

source code of gtk/subprojects/glib/glib/gbytes.c