GLib: implement GMutex natively on Linux

[platform/upstream/glib.git] / glib / gbytes.c

diff --git a/glib/gbytes.c b/glib/gbytes.c
index 4d1f6c6..a22500b 100644 (file)
--- a/glib/gbytes.c
+++ b/glib/gbytes.c
@@ -13,9 +13,7 @@
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  *
  * Author: Ryan Lortie <desrt@desrt.ca>
  *         Stef Walter <stefw@collabora.co.uk>
@@ -38,8 +36,8 @@
 /**
  * GBytes:
  *
- * A simple refcounted data type representing an immutable byte sequence
- * from an unspecified origin.
+ * A simple refcounted data type representing an immutable sequence of zero or
+ * more bytes from an unspecified origin.
  *
  * The purpose of a #GBytes is to keep the memory region that it holds
  * alive for as long as anyone holds a reference to the bytes.  When
@@ -68,8 +66,8 @@
 
 struct _GBytes
 {
-  gconstpointer data;
-  gsize size;
+  gconstpointer data;  /* may be NULL iff (size == 0) */
+  gsize size;  /* may be 0 */
   gint ref_count;
   GDestroyNotify free_func;
   gpointer user_data;
@@ -77,13 +75,13 @@ struct _GBytes
 
 /**
  * g_bytes_new:
- * @data: (transfer none) (array length=size) (element-type guint8):
+ * @data: (transfer none) (array length=size) (element-type guint8) (allow-none):
  *        the data to be used for the bytes
  * @size: the size of @data
  *
  * Creates a new #GBytes from @data.
  *
- * @data is copied.
+ * @data is copied. If @size is 0, @data may be %NULL.
  *
  * Returns: (transfer full): a new #GBytes
  *
@@ -93,12 +91,14 @@ GBytes *
 g_bytes_new (gconstpointer data,
              gsize         size)
 {
+  g_return_val_if_fail (data != NULL || size == 0, NULL);
+
   return g_bytes_new_take (g_memdup (data, size), size);
 }
 
 /**
  * g_bytes_new_take:
- * @data: (transfer full) (array length=size) (element-type guint8):
+ * @data: (transfer full) (array length=size) (element-type guint8) (allow-none):
           the data to be used for the bytes
  * @size: the size of @data
  *
@@ -113,6 +113,8 @@ g_bytes_new (gconstpointer data,
  * For creating #GBytes with memory from other allocators, see
  * g_bytes_new_with_free_func().
  *
+ * @data may be %NULL if @size is 0.
+ *
  * Returns: (transfer full): a new #GBytes
  *
  * Since: 2.32
@@ -127,13 +129,14 @@ g_bytes_new_take (gpointer data,
 
 /**
  * g_bytes_new_static: (skip)
- * @data: (transfer full) (array length=size) (element-type guint8):
+ * @data: (transfer full) (array length=size) (element-type guint8) (allow-none):
           the data to be used for the bytes
  * @size: the size of @data
  *
  * Creates a new #GBytes from static data.
  *
- * @data must be static (ie: never modified or freed).
+ * @data must be static (ie: never modified or freed). It may be %NULL if @size
+ * is 0.
  *
  * Returns: (transfer full): a new #GBytes
  *
@@ -148,7 +151,7 @@ g_bytes_new_static (gconstpointer data,
 
 /**
  * g_bytes_new_with_free_func:
- * @data: (array length=size): the data to be used for the bytes
+ * @data: (array length=size) (allow-none): the data to be used for the bytes
  * @size: the size of @data
  * @free_func: the function to call to release the data
  * @user_data: data to pass to @free_func
@@ -161,6 +164,8 @@ g_bytes_new_static (gconstpointer data,
  * @data must not be modified after this call is made until @free_func has
  * been called to indicate that the bytes is no longer in use.
  *
+ * @data may be %NULL if @size is 0.
+ *
  * Returns: (transfer full): a new #GBytes
  *
  * Since: 2.32
@@ -173,6 +178,8 @@ g_bytes_new_with_free_func (gconstpointer  data,
 {
   GBytes *bytes;
 
+  g_return_val_if_fail (data != NULL || size == 0, NULL);
+
   bytes = g_slice_new (GBytes);
   bytes->data = data;
   bytes->size = size;
@@ -204,6 +211,7 @@ g_bytes_new_from_bytes (GBytes  *bytes,
                         gsize    offset,
                         gsize    length)
 {
+  /* Note that length may be 0. */
   g_return_val_if_fail (bytes != NULL, NULL);
   g_return_val_if_fail (offset <= bytes->size, NULL);
   g_return_val_if_fail (offset + length <= bytes->size, NULL);
@@ -221,8 +229,12 @@ g_bytes_new_from_bytes (GBytes  *bytes,
  *
  * This function will always return the same pointer for a given #GBytes.
  *
- * Returns: (transfer none) (array length=size) (type guint8): a pointer to the
- *          byte data
+ * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes
+ * may represent an empty string with @data non-%NULL and @size as 0. %NULL will
+ * not be returned if @size is non-zero.
+ *
+ * Returns: (transfer none) (array length=size) (type guint8) (allow-none): a pointer to the
+ *          byte data, or %NULL
  *
  * Since: 2.32
  */