More release tidyups.

Add some function documentation to fitz.h.

Add fz_ prefix to runetochar, chartorune, runelen etc. Change
fz_runetochar to avoid passing unnecessary pointer.

4 files changed, 225 insertions, 23 deletions

diff --git a/fitz/base_string.c b/fitz/base_string.c
index 8ab09438..7587f96b 100644
--- a/fitz/base_string.c
+++ b/fitz/base_string.c
@@ -29,8 +29,8 @@ fz_strlcpy(char *dst, const char *src, int siz)
 	if (n == 0) {
 		if (siz != 0)
 			*d = '\0';		/* NUL-terminate dst */
-			while (*s++)
-				;
+		while (*s++)
+			;
 	}
 
 	return(s - src - 1);	/* count does not include NUL */
@@ -101,7 +101,7 @@ enum
 };
 
 int
-chartorune(int *rune, char *str)
+fz_chartorune(int *rune, char *str)
 {
 	int c, c1, c2, c3;
 	long l;
@@ -176,16 +176,15 @@ bad:
 }
 
 int
-runetochar(char *str, int *rune)
+fz_runetochar(char *str, int rune)
 {
 	/* Runes are signed, so convert to unsigned for range check. */
-	unsigned long c;
+	unsigned long c = (unsigned long)rune;
 
 	/*
 	 * one character sequence
 	 *	00000-0007F => 00-7F
 	 */
-	c = *rune;
 	if(c <= Rune1) {
 		str[0] = c;
 		return 1;
@@ -233,10 +232,10 @@ runetochar(char *str, int *rune)
 }
 
 int
-runelen(int c)
+fz_runelen(int c)
 {
 	char str[10];
-	return runetochar(str, &c);
+	return fz_runetochar(str, c);
 }
 
 float fz_atof(const char *s)
diff --git a/fitz/dev_text.c b/fitz/dev_text.c
index 618a2e6e..79d8c137 100644
--- a/fitz/dev_text.c
+++ b/fitz/dev_text.c
@@ -172,7 +172,7 @@ fz_debug_text_span_xml(fz_text_span *span)
 				putchar(c);
 			else
 			{
-				n = runetochar(buf, &c);
+				n = fz_runetochar(buf, c);
 				for (k = 0; k < n; k++)
 					putchar(buf[k]);
 			}
@@ -204,7 +204,7 @@ fz_debug_text_span(fz_text_span *span)
 				putchar(c);
 			else
 			{
-				n = runetochar(buf, &c);
+				n = fz_runetochar(buf, c);
 				for (k = 0; k < n; k++)
 					putchar(buf[k]);
 			}
diff --git a/fitz/fitz-internal.h b/fitz/fitz-internal.h
index efc08a41..04ce19e5 100644
--- a/fitz/fitz-internal.h
+++ b/fitz/fitz-internal.h
@@ -15,6 +15,9 @@ fz_context *fz_clone_context_internal(fz_context *ctx);
 void fz_new_aa_context(fz_context *ctx);
 void fz_free_aa_context(fz_context *ctx);
 
+/* Default locks */
+extern fz_locks_context fz_locks_default;
+
 #if defined(MEMENTO) || defined(DEBUG)
 #define FITZ_DEBUG_LOCKING
 #endif
@@ -54,6 +57,22 @@ fz_unlock(fz_context *ctx, int lock)
  * Basic runtime and utility functions
  */
 
+/*
+	fz_malloc_struct: Allocate storage for a structure (with scavenging),
+	clear it, and (in Memento builds) tag the pointer as belonging to a
+	struct of this type.
+
+	CTX: The context.
+
+	STRUCT: The structure type.
+
+	Returns a pointer to allocated (and cleared) structure. Throws
+	exception on failure to allocate.
+*/
+/* alloc and zero a struct, and tag it for memento */
+#define fz_malloc_struct(CTX, STRUCT) \
+	Memento_label(fz_calloc(CTX,1,sizeof(STRUCT)), #STRUCT)
+
 /* Range checking atof */
 float fz_atof(const char *s);
 
diff --git a/fitz/fitz.h b/fitz/fitz.h
index a6a197ca..f9d5c567 100644
--- a/fitz/fitz.h
+++ b/fitz/fitz.h
@@ -318,14 +318,80 @@ enum {
 	FZ_LOCK_MAX
 };
 
-/* Default locks */
-extern fz_locks_context fz_locks_default;
+/*
+	Memory Allocation and Scavenging:
+
+	All calls to MuPDFs allocator functions pass through to the
+	underlying allocators passed in when the initial context is
+	created, after locks are taken (using the supplied locking function)
+	to ensure that only one thread at a time calls through.
+
+	If the underlying allocator fails, MuPDF attempts to make room for
+	the allocation by evicting elements from the store, then retrying.
+
+	Any call to allocate may then result in several calls to the underlying
+	allocator, and result in elements that are only referred to by the
+	store being freed.
+*/
+
+/*
+	fz_malloc: Allocate a block of memory (with scavenging)
 
-/* The following throw exceptions on failure to allocate */
+	size: The number of bytes to allocate.
+
+	Returns a pointer to the allocated block. May return NULL if size is
+	0. Throws exception on failure to allocate.
+*/
 void *fz_malloc(fz_context *ctx, unsigned int size);
+
+/*
+	fz_calloc: Allocate a zeroed block of memory (with scavenging)
+
+	count: The number of objects to allocate space for.
+
+	size: The size (in bytes) of each object.
+
+	Returns a pointer to the allocated block. May return NULL if size
+	and/or count are 0. Throws exception on failure to allocate.
+*/
 void *fz_calloc(fz_context *ctx, unsigned int count, unsigned int size);
+
+/*
+	fz_malloc_array: Allocate a block of (non zeroed) memory (with
+	scavenging). Equivalent to fz_calloc without the memory clearing.
+
+	count: The number of objects to allocate space for.
+
+	size: The size (in bytes) of each object.
+
+	Returns a pointer to the allocated block. May return NULL if size
+	and/or count are 0. Throws exception on failure to allocate.
+*/
 void *fz_malloc_array(fz_context *ctx, unsigned int count, unsigned int size);
+
+/*
+	fz_resize_array: Resize a block of memory (with scavenging).
+
+	p: The existing block to resize
+
+	count: The number of objects to resize to.
+
+	size: The size (in bytes) of each object.
+
+	Returns a pointer to the resized block. May return NULL if size
+	and/or count are 0. Throws exception on failure to resize (original
+	block is left unchanged).
+*/
 void *fz_resize_array(fz_context *ctx, void *p, unsigned int count, unsigned int size);
+
+/*
+	fz_strdup: Duplicate a C string (with scavenging)
+
+	s: The string to duplicate.
+
+	Returns a pointer to a duplicated string. Throws exception on failure
+	to allocate.
+*/
 char *fz_strdup(fz_context *ctx, char *s);
 
 /*
@@ -335,26 +401,144 @@ char *fz_strdup(fz_context *ctx, char *s);
 */
 void fz_free(fz_context *ctx, void *p);
 
-/* The following return NULL on failure to allocate */
+/*
+	fz_malloc_no_throw: Allocate a block of memory (with scavenging)
+
+	size: The number of bytes to allocate.
+
+	Returns a pointer to the allocated block. May return NULL if size is
+	0. Returns NULL on failure to allocate.
+*/
 void *fz_malloc_no_throw(fz_context *ctx, unsigned int size);
-void *fz_malloc_array_no_throw(fz_context *ctx, unsigned int count, unsigned int size);
+
+/*
+	fz_calloc_no_throw: Allocate a zeroed block of memory (with scavenging)
+
+	count: The number of objects to allocate space for.
+
+	size: The size (in bytes) of each object.
+
+	Returns a pointer to the allocated block. May return NULL if size
+	and/or count are 0. Returns NULL on failure to allocate.
+*/
 void *fz_calloc_no_throw(fz_context *ctx, unsigned int count, unsigned int size);
+
+/*
+	fz_malloc_array_no_throw: Allocate a block of (non zeroed) memory
+	(with scavenging). Equivalent to fz_calloc_no_throw without the
+	memory clearing.
+
+	count: The number of objects to allocate space for.
+
+	size: The size (in bytes) of each object.
+
+	Returns a pointer to the allocated block. May return NULL if size
+	and/or count are 0. Returns NULL on failure to allocate.
+*/
+void *fz_malloc_array_no_throw(fz_context *ctx, unsigned int count, unsigned int size);
+
+/*
+	fz_resize_array_no_throw: Resize a block of memory (with scavenging).
+
+	p: The existing block to resize
+
+	count: The number of objects to resize to.
+
+	size: The size (in bytes) of each object.
+
+	Returns a pointer to the resized block. May return NULL if size
+	and/or count are 0. Returns NULL on failure to resize (original
+	block is left unchanged).
+*/
 void *fz_resize_array_no_throw(fz_context *ctx, void *p, unsigned int count, unsigned int size);
-char *fz_strdup_no_throw(fz_context *ctx, char *s);
 
-/* alloc and zero a struct, and tag it for memento */
-#define fz_malloc_struct(CTX, STRUCT) \
-	Memento_label(fz_calloc(CTX,1,sizeof(STRUCT)), #STRUCT)
+/*
+	fz_strdup_no_throw: Duplicate a C string (with scavenging)
+
+	s: The string to duplicate.
+
+	Returns a pointer to a duplicated string. Returns NULL on failure
+	to allocate.
+*/
+char *fz_strdup_no_throw(fz_context *ctx, char *s);
 
 /* safe string functions */
+/*
+	fz_strsep: Given a pointer to a C string (or a pointer to NULL) break
+	it at the first occurence of a delimiter char (from a given set).
+
+	stringp: Pointer to a C string pointer (or NULL). Updated on exit to
+	point to the first char of the string after the delimiter that was
+	found. The string pointed to by stringp will be corrupted by this
+	call (as the found delimiter will be overwritten by 0).
+
+	delim: A C string of acceptable delimiter characters.
+
+	Returns a pointer to a C string containing the chars of stringp up
+	to the first delimiter char (or the end of the string), or NULL.
+*/
 char *fz_strsep(char **stringp, const char *delim);
+
+/*
+	fz_strlcpy: Copy at most n-1 chars of a string into a destination
+	buffer with null termination, returning the real length of the
+	initial string (excluding terminator).
+
+	dst: Destination buffer, at least n bytes long.
+
+	src: C string (non-NULL).
+
+	n: Size of dst buffer in bytes.
+
+	Returns the length (excluding terminator) of src.
+*/
 int fz_strlcpy(char *dst, const char *src, int n);
+
+/*
+	fz_strlcat: Concatenate 2 strings, with a maximum length.
+
+	dst: pointer to first string in a buffer of n bytes.
+
+	src: pointer to string to concatenate.
+
+	n: Size (in bytes) of buffer that dst is in.
+
+	Returns the real length that a concatenated dst + src would have been
+	(not including terminator).
+*/
 int fz_strlcat(char *dst, const char *src, int n);
 
-/* utf-8 encoding and decoding */
-int chartorune(int *rune, char *str);
-int runetochar(char *str, int *rune);
-int runelen(int c);
+/*
+	fz_chartorune: UTF8 decode a string of chars to a rune.
+
+	rune: Pointer to an int to assign the decoded 'rune' to.
+
+	str: Pointer to a UTF8 encoded string
+
+	Returns the number of bytes consumed. Does not throw exceptions.
+*/
+int fz_chartorune(int *rune, char *str);
+
+/*
+	runetochar: UTF8 encode a run to a string of chars.
+
+	str: Pointer to a place to put the UTF8 encoded string.
+
+	rune: Pointer to a 'rune'.
+
+	Returns the number of bytes the rune took to output. Does not throw
+	exceptions.
+*/
+int fz_runetochar(char *str, int rune);
+
+/*
+	fz_runelen: Count many chars are required to represent a rune.
+
+	rune: The rune to encode.
+
+	Returns the number of bytes required to represent this run in UTF8.
+*/
+int fz_runelen(int rune);
 
 /* getopt */
 extern int fz_getopt(int nargc, char * const *nargv, const char *ostr);