2 * Copyright © 2009, 2010 Codethink Limited
3 * Copyright © 2011 Collabora Ltd.
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 of the licence, or (at your option) any later version.
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.
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Author: Ryan Lortie <desrt@desrt.ca>
21 * Stef Walter <stefw@collabora.co.uk>
28 #include <glib/garray.h>
29 #include <glib/gstrfuncs.h>
30 #include <glib/gatomic.h>
31 #include <glib/gslice.h>
32 #include <glib/gtestutils.h>
33 #include <glib/gmem.h>
34 #include <glib/gmessages.h>
41 * A simple refcounted data type representing an immutable byte sequence
42 * from an unspecified origin.
44 * The purpose of a #GBytes is to keep the memory region that it holds
45 * alive for as long as anyone holds a reference to the bytes. When
46 * the last reference count is dropped, the memory is released. Multiple
47 * unrelated callers can use byte data in the #GBytes without coordinating
48 * their activities, resting assured that the byte data will not change or
49 * move while they hold a reference.
51 * A #GBytes can come from many different origins that may have
52 * different procedures for freeing the memory region. Examples are
53 * memory from g_malloc(), from memory slices, from a #GMappedFile or
54 * memory from other allocators.
56 * #GBytes work well as keys in #GHashTable. Use g_bytes_equal() and
57 * g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full().
58 * #GBytes can also be used as keys in a #GTree by passing the g_bytes_compare()
59 * function to g_tree_new().
61 * The data pointed to by this bytes must not be modified. For a mutable
62 * array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a
63 * mutable array for a #GBytes sequence. To create an immutable #GBytes from
64 * a mutable #GByteArray, use the g_byte_array_free_to_bytes() function.
74 GDestroyNotify free_func;
80 * @data: (array length=size): the data to be used for the bytes
81 * @size: the size of @data
83 * Creates a new #GBytes from @data.
87 * Returns: (transfer full): a new #GBytes
92 g_bytes_new (gconstpointer data,
95 return g_bytes_new_take (g_memdup (data, size), size);
100 * @data: (transfer full) (array length=size): the data to be used for the bytes
101 * @size: the size of @data
103 * Creates a new #GBytes from @data.
105 * After this call, @data belongs to the bytes and may no longer be
106 * modified by the caller. g_free() will be called on @data when the
107 * bytes is no longer in use. Because of this @data must have been created by
108 * a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many
109 * functions that wrap these calls (such as g_new(), g_strdup(), etc).
111 * For creating #GBytes with memory from other allocators, see
112 * g_bytes_new_with_free_func().
114 * Returns: (transfer full): a new #GBytes
119 g_bytes_new_take (gpointer data,
122 return g_bytes_new_with_free_func (data, size, g_free, data);
127 * g_bytes_new_static:
128 * @data: (array length=size): the data to be used for the bytes
129 * @size: the size of @data
131 * Creates a new #GBytes from static data.
133 * @data must be static (ie: never modified or freed).
135 * Returns: (transfer full): a new #GBytes
140 g_bytes_new_static (gconstpointer data,
143 return g_bytes_new_with_free_func (data, size, NULL, NULL);
147 * g_bytes_new_with_free_func:
148 * @data: (array length=size): the data to be used for the bytes
149 * @size: the size of @data
150 * @free_func: the function to call to release the data
151 * @user_data: data to pass to @free_func
153 * Creates a #GBytes from @data.
155 * When the last reference is dropped, @free_func will be called with the
156 * @user_data argument.
158 * @data must not be modified after this call is made until @free_func has
159 * been called to indicate that the bytes is no longer in use.
161 * Returns: (transfer full): a new #GBytes
166 g_bytes_new_with_free_func (gconstpointer data,
168 GDestroyNotify free_func,
173 bytes = g_slice_new (GBytes);
176 bytes->free_func = free_func;
177 bytes->user_data = user_data;
178 bytes->ref_count = 1;
180 return (GBytes *)bytes;
184 * g_bytes_new_from_bytes:
186 * @offset: offset which subsection starts at
187 * @length: length of subsection
189 * Creates a #GBytes which is a subsection of another #GBytes. The @offset +
190 * @length may not be longer than the size of @bytes.
192 * A reference to @bytes will be held by the newly created #GBytes until
193 * the byte data is no longer needed.
195 * Returns: (transfer full): a new #GBytes
200 g_bytes_new_from_bytes (GBytes *bytes,
204 g_return_val_if_fail (bytes != NULL, NULL);
205 g_return_val_if_fail (offset <= bytes->size, NULL);
206 g_return_val_if_fail (offset + length <= bytes->size, NULL);
208 return g_bytes_new_with_free_func ((gchar *)bytes->data + offset, length,
209 (GDestroyNotify)g_bytes_unref, g_bytes_ref (bytes));
215 * @size: (out) (allow-none): location to return size of byte data
217 * Get the byte data in the #GBytes. This data should not be modified.
219 * This function will always return the same pointer for a given #GBytes.
221 * Returns: (array length=size) (type guint8): a pointer to the byte data
226 g_bytes_get_data (GBytes *bytes,
229 g_return_val_if_fail (bytes != NULL, NULL);
239 * Get the size of the byte data in the #GBytes.
241 * This function will always return the same value for a given #GBytes.
248 g_bytes_get_size (GBytes *bytes)
250 g_return_val_if_fail (bytes != NULL, 0);
259 * Increase the reference count on @bytes.
261 * Returns: the #GBytes
266 g_bytes_ref (GBytes *bytes)
268 g_return_val_if_fail (bytes != NULL, NULL);
270 g_atomic_int_inc (&bytes->ref_count);
277 * @bytes: (allow-none): a #GBytes
279 * Releases a reference on @bytes. This may result in the bytes being
285 g_bytes_unref (GBytes *bytes)
290 if (g_atomic_int_dec_and_test (&bytes->ref_count))
292 if (bytes->free_func != NULL)
293 bytes->free_func (bytes->user_data);
294 g_slice_free (GBytes, bytes);
300 * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
301 * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
303 * Compares the two #GBytes values being pointed to and returns
304 * %TRUE if they are equal.
306 * This function can be passed to g_hash_table_new() as the @key_equal_func
307 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
309 * Returns: %TRUE if the two keys match.
314 g_bytes_equal (gconstpointer bytes1,
315 gconstpointer bytes2)
317 const GBytes *b1 = bytes1;
318 const GBytes *b2 = bytes2;
320 g_return_val_if_fail (bytes1 != NULL, FALSE);
321 g_return_val_if_fail (bytes2 != NULL, FALSE);
323 return b1->size == b2->size &&
324 memcmp (b1->data, b2->data, b1->size) == 0;
329 * @bytes: (type GLib.Bytes): a pointer to a #GBytes key
331 * Creates an integer hash code for the byte data in the #GBytes.
333 * This function can be passed to g_hash_table_new() as the @key_equal_func
334 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
336 * Returns: a hash value corresponding to the key.
341 g_bytes_hash (gconstpointer bytes)
343 const GBytes *a = bytes;
344 const signed char *p, *e;
347 g_return_val_if_fail (bytes != NULL, 0);
349 for (p = (signed char *)a->data, e = (signed char *)a->data + a->size; p != e; p++)
350 h = (h << 5) + h + *p;
357 * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
358 * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
360 * Compares the two #GBytes values.
362 * This function can be used to sort GBytes instances in lexographical order.
364 * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is
365 * greater, and zero if bytes2 is equal to bytes1
370 g_bytes_compare (gconstpointer bytes1,
371 gconstpointer bytes2)
373 const GBytes *b1 = bytes1;
374 const GBytes *b2 = bytes2;
377 g_return_val_if_fail (bytes1 != NULL, 0);
378 g_return_val_if_fail (bytes2 != NULL, 0);
380 ret = memcmp (b1->data, b2->data, MIN (b1->size, b2->size));
381 if (ret == 0 && b1->size != b2->size)
382 ret = b1->size < b2->size ? -1 : 1;
387 try_steal_and_unref (GBytes *bytes,
388 GDestroyNotify free_func,
393 if (bytes->free_func != free_func)
396 /* Are we the only reference? */
397 if (g_atomic_int_get (&bytes->ref_count) == 1)
400 result = (gpointer)bytes->data;
401 g_slice_free (GBytes, bytes);
410 * g_bytes_unref_to_data:
411 * @bytes: (transfer full): a #GBytes
412 * @size: location to place the length of the returned data
414 * Unreferences the bytes, and returns a pointer the same byte data
417 * As an optimization, the byte data is returned without copying if this was
418 * the last reference to bytes and bytes was created with g_bytes_new(),
419 * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
422 * Returns: (transfer full): a pointer to the same byte data, which should
423 * be freed with g_free()
428 g_bytes_unref_to_data (GBytes *bytes,
433 g_return_val_if_fail (bytes != NULL, NULL);
434 g_return_val_if_fail (size != NULL, NULL);
437 * Optimal path: if this is was the last reference, then we can return
438 * the data from this GBytes without copying.
441 result = try_steal_and_unref (bytes, g_free, size);
445 * Copy: Non g_malloc (or compatible) allocator, or static memory,
446 * so we have to copy, and then unref.
448 result = g_memdup (bytes->data, bytes->size);
450 g_bytes_unref (bytes);
457 * g_bytes_unref_to_array:
458 * @bytes: (transfer full): a #GBytes
460 * Unreferences the bytes, and returns a new mutable #GByteArray containing
461 * the same byte data.
463 * As an optimization, the byte data is transferred to the array without copying
464 * if this was the last reference to bytes and bytes was created with
465 * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all
466 * other cases the data is copied.
468 * Returns: (transfer full): a new mutable #GByteArray containing the same byte data
473 g_bytes_unref_to_array (GBytes *bytes)
478 g_return_val_if_fail (bytes != NULL, NULL);
480 data = g_bytes_unref_to_data (bytes, &size);
481 return g_byte_array_new_take (data, size);