X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=src%2Fglsl%2Fralloc.h;h=67eb93833e6a6973499fb8f598199c1d7070fdf4;hb=0d108116bd80b757fb01a84a9f1946ef870b57b8;hp=57e8c7a138a177e0dc2f6234941a035b98842bea;hpb=dc55254f5b23e5ad7a07c974ce772f93b4c11cb0;p=mesa.git

diff --git a/src/glsl/ralloc.h b/src/glsl/ralloc.h
index 57e8c7a138a..67eb93833e6 100644
--- a/src/glsl/ralloc.h
+++ b/src/glsl/ralloc.h
@@ -34,7 +34,14 @@
  * ralloc_free on any particular object to free it and all of its
  * children.
  *
- * This is currently a wrapper around talloc, but that will change.
+ * The conceptual working of ralloc was directly inspired by Andrew
+ * Tridgell's talloc, but ralloc is an independent implementation
+ * released under the MIT license and tuned for Mesa.
+ *
+ * The talloc implementation is available under the GNU Lesser
+ * General Public License (GNU LGPL), version 3 or later. It is
+ * more sophisticated than ralloc in that it includes reference
+ * counting and debugging features. See: http://talloc.samba.org/
  */
 
 #ifndef RALLOC_H
@@ -47,6 +54,7 @@ extern "C" {
 #include <stddef.h>
 #include <stdarg.h>
 #include <stdbool.h>
+#include "main/compiler.h"
 
 /**
  * \def ralloc(ctx, type)
@@ -294,7 +302,7 @@ bool ralloc_strncat(char **dest, const char *str, size_t n);
  *
  * \return The newly allocated string.
  */
-char *ralloc_asprintf (const void *ctx, const char *fmt, ...);
+char *ralloc_asprintf (const void *ctx, const char *fmt, ...) PRINTFLIKE(2, 3);
 
 /**
  * Print to a string, given a va_list.
@@ -306,22 +314,83 @@ char *ralloc_asprintf (const void *ctx, const char *fmt, ...);
  */
 char *ralloc_vasprintf(const void *ctx, const char *fmt, va_list args);
 
+/**
+ * Rewrite the tail of an existing string, starting at a given index.
+ *
+ * Overwrites the contents of *str starting at \p start with newly formatted
+ * text, including a new null-terminator.  Allocates more memory as necessary.
+ *
+ * This can be used to append formatted text when the length of the existing
+ * string is already known, saving a strlen() call.
+ *
+ * \sa ralloc_asprintf_append
+ *
+ * \param str   The string to be updated.
+ * \param start The index to start appending new data at.
+ * \param fmt   A printf-style formatting string
+ *
+ * \p str will be updated to the new pointer unless allocation fails.
+ * \p start will be increased by the length of the newly formatted text.
+ *
+ * \return True unless allocation failed.
+ */
+bool ralloc_asprintf_rewrite_tail(char **str, size_t *start,
+				  const char *fmt, ...)
+				  PRINTFLIKE(3, 4);
+
+/**
+ * Rewrite the tail of an existing string, starting at a given index.
+ *
+ * Overwrites the contents of *str starting at \p start with newly formatted
+ * text, including a new null-terminator.  Allocates more memory as necessary.
+ *
+ * This can be used to append formatted text when the length of the existing
+ * string is already known, saving a strlen() call.
+ *
+ * \sa ralloc_vasprintf_append
+ *
+ * \param str   The string to be updated.
+ * \param start The index to start appending new data at.
+ * \param fmt   A printf-style formatting string
+ * \param args  A va_list containing the data to be formatted
+ *
+ * \p str will be updated to the new pointer unless allocation fails.
+ * \p start will be increased by the length of the newly formatted text.
+ *
+ * \return True unless allocation failed.
+ */
+bool ralloc_vasprintf_rewrite_tail(char **str, size_t *start, const char *fmt,
+				   va_list args);
+
 /**
  * Append formatted text to the supplied string.
  *
+ * This is equivalent to
+ * \code
+ * ralloc_asprintf_rewrite_tail(str, strlen(*str), fmt, ...)
+ * \endcode
+ *
  * \sa ralloc_asprintf
+ * \sa ralloc_asprintf_rewrite_tail
  * \sa ralloc_strcat
  *
  * \p str will be updated to the new pointer unless allocation fails.
  *
  * \return True unless allocation failed.
  */
-bool ralloc_asprintf_append (char **str, const char *fmt, ...);
+bool ralloc_asprintf_append (char **str, const char *fmt, ...)
+			     PRINTFLIKE(2, 3);
 
 /**
  * Append formatted text to the supplied string, given a va_list.
  *
+ * This is equivalent to
+ * \code
+ * ralloc_vasprintf_rewrite_tail(str, strlen(*str), fmt, args)
+ * \endcode
+ *
  * \sa ralloc_vasprintf
+ * \sa ralloc_vasprintf_rewrite_tail
  * \sa ralloc_strcat
  *
  * \p str will be updated to the new pointer unless allocation fails.