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: (transfer none) (array length=size) (element-type guint8):
81 * the data to be used for the bytes
82 * @size: the size of @data
84 * Creates a new #GBytes from @data.
88 * Returns: (transfer full): a new #GBytes
93 g_bytes_new (gconstpointer data
,
96 return g_bytes_new_take (g_memdup (data
, size
), size
);
101 * @data: (transfer full) (array length=size) (element-type guint8):
102 the data to be used for the bytes
103 * @size: the size of @data
105 * Creates a new #GBytes from @data.
107 * After this call, @data belongs to the bytes and may no longer be
108 * modified by the caller. g_free() will be called on @data when the
109 * bytes is no longer in use. Because of this @data must have been created by
110 * a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many
111 * functions that wrap these calls (such as g_new(), g_strdup(), etc).
113 * For creating #GBytes with memory from other allocators, see
114 * g_bytes_new_with_free_func().
116 * Returns: (transfer full): a new #GBytes
121 g_bytes_new_take (gpointer data
,
124 return g_bytes_new_with_free_func (data
, size
, g_free
, data
);
129 * g_bytes_new_static: (skip)
130 * @data: (transfer full) (array length=size) (element-type guint8):
131 the data to be used for the bytes
132 * @size: the size of @data
134 * Creates a new #GBytes from static data.
136 * @data must be static (ie: never modified or freed).
138 * Returns: (transfer full): a new #GBytes
143 g_bytes_new_static (gconstpointer data
,
146 return g_bytes_new_with_free_func (data
, size
, NULL
, NULL
);
150 * g_bytes_new_with_free_func:
151 * @data: (array length=size): the data to be used for the bytes
152 * @size: the size of @data
153 * @free_func: the function to call to release the data
154 * @user_data: data to pass to @free_func
156 * Creates a #GBytes from @data.
158 * When the last reference is dropped, @free_func will be called with the
159 * @user_data argument.
161 * @data must not be modified after this call is made until @free_func has
162 * been called to indicate that the bytes is no longer in use.
164 * Returns: (transfer full): a new #GBytes
169 g_bytes_new_with_free_func (gconstpointer data
,
171 GDestroyNotify free_func
,
176 bytes
= g_slice_new (GBytes
);
179 bytes
->free_func
= free_func
;
180 bytes
->user_data
= user_data
;
181 bytes
->ref_count
= 1;
183 return (GBytes
*)bytes
;
187 * g_bytes_new_from_bytes:
189 * @offset: offset which subsection starts at
190 * @length: length of subsection
192 * Creates a #GBytes which is a subsection of another #GBytes. The @offset +
193 * @length may not be longer than the size of @bytes.
195 * A reference to @bytes will be held by the newly created #GBytes until
196 * the byte data is no longer needed.
198 * Returns: (transfer full): a new #GBytes
203 g_bytes_new_from_bytes (GBytes
*bytes
,
207 g_return_val_if_fail (bytes
!= NULL
, NULL
);
208 g_return_val_if_fail (offset
<= bytes
->size
, NULL
);
209 g_return_val_if_fail (offset
+ length
<= bytes
->size
, NULL
);
211 return g_bytes_new_with_free_func ((gchar
*)bytes
->data
+ offset
, length
,
212 (GDestroyNotify
)g_bytes_unref
, g_bytes_ref (bytes
));
218 * @size: (out) (allow-none): location to return size of byte data
220 * Get the byte data in the #GBytes. This data should not be modified.
222 * This function will always return the same pointer for a given #GBytes.
224 * Returns: (transfer none) (array length=size) (type guint8): a pointer to the
230 g_bytes_get_data (GBytes
*bytes
,
233 g_return_val_if_fail (bytes
!= NULL
, NULL
);
243 * Get the size of the byte data in the #GBytes.
245 * This function will always return the same value for a given #GBytes.
252 g_bytes_get_size (GBytes
*bytes
)
254 g_return_val_if_fail (bytes
!= NULL
, 0);
263 * Increase the reference count on @bytes.
265 * Returns: the #GBytes
270 g_bytes_ref (GBytes
*bytes
)
272 g_return_val_if_fail (bytes
!= NULL
, NULL
);
274 g_atomic_int_inc (&bytes
->ref_count
);
281 * @bytes: (allow-none): a #GBytes
283 * Releases a reference on @bytes. This may result in the bytes being
289 g_bytes_unref (GBytes
*bytes
)
294 if (g_atomic_int_dec_and_test (&bytes
->ref_count
))
296 if (bytes
->free_func
!= NULL
)
297 bytes
->free_func (bytes
->user_data
);
298 g_slice_free (GBytes
, bytes
);
304 * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
305 * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
307 * Compares the two #GBytes values being pointed to and returns
308 * %TRUE if they are equal.
310 * This function can be passed to g_hash_table_new() as the @key_equal_func
311 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
313 * Returns: %TRUE if the two keys match.
318 g_bytes_equal (gconstpointer bytes1
,
319 gconstpointer bytes2
)
321 const GBytes
*b1
= bytes1
;
322 const GBytes
*b2
= bytes2
;
324 g_return_val_if_fail (bytes1
!= NULL
, FALSE
);
325 g_return_val_if_fail (bytes2
!= NULL
, FALSE
);
327 return b1
->size
== b2
->size
&&
328 memcmp (b1
->data
, b2
->data
, b1
->size
) == 0;
333 * @bytes: (type GLib.Bytes): a pointer to a #GBytes key
335 * Creates an integer hash code for the byte data in the #GBytes.
337 * This function can be passed to g_hash_table_new() as the @key_equal_func
338 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
340 * Returns: a hash value corresponding to the key.
345 g_bytes_hash (gconstpointer bytes
)
347 const GBytes
*a
= bytes
;
348 const signed char *p
, *e
;
351 g_return_val_if_fail (bytes
!= NULL
, 0);
353 for (p
= (signed char *)a
->data
, e
= (signed char *)a
->data
+ a
->size
; p
!= e
; p
++)
354 h
= (h
<< 5) + h
+ *p
;
361 * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
362 * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
364 * Compares the two #GBytes values.
366 * This function can be used to sort GBytes instances in lexographical order.
368 * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is
369 * greater, and zero if bytes2 is equal to bytes1
374 g_bytes_compare (gconstpointer bytes1
,
375 gconstpointer bytes2
)
377 const GBytes
*b1
= bytes1
;
378 const GBytes
*b2
= bytes2
;
381 g_return_val_if_fail (bytes1
!= NULL
, 0);
382 g_return_val_if_fail (bytes2
!= NULL
, 0);
384 ret
= memcmp (b1
->data
, b2
->data
, MIN (b1
->size
, b2
->size
));
385 if (ret
== 0 && b1
->size
!= b2
->size
)
386 ret
= b1
->size
< b2
->size
? -1 : 1;
391 try_steal_and_unref (GBytes
*bytes
,
392 GDestroyNotify free_func
,
397 if (bytes
->free_func
!= free_func
|| bytes
->data
== NULL
)
400 /* Are we the only reference? */
401 if (g_atomic_int_get (&bytes
->ref_count
) == 1)
404 result
= (gpointer
)bytes
->data
;
405 g_slice_free (GBytes
, bytes
);
414 * g_bytes_unref_to_data:
415 * @bytes: (transfer full): a #GBytes
416 * @size: location to place the length of the returned data
418 * Unreferences the bytes, and returns a pointer the same byte data
421 * As an optimization, the byte data is returned without copying if this was
422 * the last reference to bytes and bytes was created with g_bytes_new(),
423 * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
426 * Returns: (transfer full): a pointer to the same byte data, which should
427 * be freed with g_free()
432 g_bytes_unref_to_data (GBytes
*bytes
,
437 g_return_val_if_fail (bytes
!= NULL
, NULL
);
438 g_return_val_if_fail (size
!= NULL
, NULL
);
441 * Optimal path: if this is was the last reference, then we can return
442 * the data from this GBytes without copying.
445 result
= try_steal_and_unref (bytes
, g_free
, size
);
449 * Copy: Non g_malloc (or compatible) allocator, or static memory,
450 * so we have to copy, and then unref.
452 result
= g_memdup (bytes
->data
, bytes
->size
);
454 g_bytes_unref (bytes
);
461 * g_bytes_unref_to_array:
462 * @bytes: (transfer full): a #GBytes
464 * Unreferences the bytes, and returns a new mutable #GByteArray containing
465 * the same byte data.
467 * As an optimization, the byte data is transferred to the array without copying
468 * if this was the last reference to bytes and bytes was created with
469 * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all
470 * other cases the data is copied.
472 * Returns: (transfer full): a new mutable #GByteArray containing the same byte data
477 g_bytes_unref_to_array (GBytes
*bytes
)
482 g_return_val_if_fail (bytes
!= NULL
, NULL
);
484 data
= g_bytes_unref_to_data (bytes
, &size
);
485 return g_byte_array_new_take (data
, size
);