init commit

include/mupdf/fitz/buffer.h

@@ -1,31 +1,69 @@
+// Copyright (C) 2004-2023 Artifex Software, Inc.
+//
+// This file is part of MuPDF.
+//
+// MuPDF is free software: you can redistribute it and/or modify it under the
+// terms of the GNU Affero General Public License as published by the Free
+// Software Foundation, either version 3 of the License, or (at your option)
+// any later version.
+//
+// MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+// FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+// details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
+//
+// Alternative licensing terms are available from the licensor.
+// For commercial licensing, see <https://www.artifex.com/> or contact
+// Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
+// CA 94129, USA, for further information.
+
 #ifndef MUPDF_FITZ_BUFFER_H
 #define MUPDF_FITZ_BUFFER_H
 
 #include "mupdf/fitz/system.h"
 #include "mupdf/fitz/context.h"
 
-/*
-	fz_buffer is a wrapper around a dynamically allocated array of bytes.
+/**
+	fz_buffer is a wrapper around a dynamically allocated array of
+	bytes.
 
 	Buffers have a capacity (the number of bytes storage immediately
 	available) and a current size.
+
+	The contents of the structure are considered implementation
+	details and are subject to change. Users should use the accessor
+	functions in preference.
 */
-typedef struct fz_buffer_s fz_buffer;
+typedef struct
+{
+	int refs;
+	unsigned char *data;
+	size_t cap, len;
+	int unused_bits;
+	int shared;
+} fz_buffer;
 
-/*
-	fz_keep_buffer: Increment the reference count for a buffer.
+/**
+	Take an additional reference to the buffer. The same pointer
+	is returned.
 
-	Returns a pointer to the buffer.
+	Never throws exceptions.
 */
 fz_buffer *fz_keep_buffer(fz_context *ctx, fz_buffer *buf);
 
-/*
-	fz_drop_buffer: Decrement the reference count for a buffer.
+/**
+	Drop a reference to the buffer. When the reference count reaches
+	zero, the buffer is destroyed.
+
+	Never throws exceptions.
 */
 void fz_drop_buffer(fz_context *ctx, fz_buffer *buf);
 
-/*
-	fz_buffer_storage: Retrieve internal memory of buffer.
+/**
+	Retrieve internal memory of buffer.
 
 	datap: Output parameter that will be pointed to the data.
 
@@ -33,81 +71,110 @@ void fz_drop_buffer(fz_context *ctx, fz_buffer *buf);
 */
 size_t fz_buffer_storage(fz_context *ctx, fz_buffer *buf, unsigned char **datap);
 
-/*
-	fz_string_from_buffer: Ensure that a buffer's data ends in a
+/**
+	Ensure that a buffer's data ends in a
 	0 byte, and return a pointer to it.
 */
 const char *fz_string_from_buffer(fz_context *ctx, fz_buffer *buf);
 
-/*
-	fz_new_buffer: Create a new buffer.
-
-	capacity: Initial capacity.
-
-	Returns pointer to new buffer.
-*/
 fz_buffer *fz_new_buffer(fz_context *ctx, size_t capacity);
 
-/*
-	fz_new_buffer_from_data: Create a new buffer with existing data.
+/**
+	Create a new buffer with existing data.
 
 	data: Pointer to existing data.
 	size: Size of existing data.
 
-	Takes ownership of data. Does not make a copy. Calls fz_free on the
-	data when the buffer is deallocated. Do not use 'data' after passing
-	to this function.
+	Takes ownership of data. Does not make a copy. Calls fz_free on
+	the data when the buffer is deallocated. Do not use 'data' after
+	passing to this function.
 
 	Returns pointer to new buffer. Throws exception on allocation
 	failure.
 */
 fz_buffer *fz_new_buffer_from_data(fz_context *ctx, unsigned char *data, size_t size);
 
-/*
-	fz_new_buffer_from_shared_data: Like fz_new_buffer, but does not take ownership.
+/**
+	Like fz_new_buffer, but does not take ownership.
 */
 fz_buffer *fz_new_buffer_from_shared_data(fz_context *ctx, const unsigned char *data, size_t size);
 
-/*
-	fz_new_buffer_from_copied_data: Create a new buffer containing a copy of the passed data.
+/**
+	Create a new buffer containing a copy of the passed data.
 */
-fz_buffer *
-fz_new_buffer_from_copied_data(fz_context *ctx, const unsigned char *data, size_t size);
+fz_buffer *fz_new_buffer_from_copied_data(fz_context *ctx, const unsigned char *data, size_t size);
 
-/*
-	fz_new_buffer_from_base64: Create a new buffer with data decoded from a base64 input string.
+/**
+	Make a new buffer, containing a copy of the data used in
+	the original.
+*/
+fz_buffer *fz_clone_buffer(fz_context *ctx, fz_buffer *buf);
+
+/**
+	Create a new buffer with data decoded from a base64 input string.
 */
 fz_buffer *fz_new_buffer_from_base64(fz_context *ctx, const char *data, size_t size);
 
-/*
-	fz_resize_buffer: Ensure that a buffer has a given capacity,
+/**
+	Ensure that a buffer has a given capacity,
 	truncating data if required.
 
-	capacity: The desired capacity for the buffer. If the current size
-	of the buffer contents is smaller than capacity, it is truncated.
+	capacity: The desired capacity for the buffer. If the current
+	size of the buffer contents is smaller than capacity, it is
+	truncated.
 */
 void fz_resize_buffer(fz_context *ctx, fz_buffer *buf, size_t capacity);
 
-/*
-	fz_grow_buffer: Make some space within a buffer (i.e. ensure that
+/**
+	Make some space within a buffer (i.e. ensure that
 	capacity > size).
 */
 void fz_grow_buffer(fz_context *ctx, fz_buffer *buf);
 
-/*
-	fz_trim_buffer: Trim wasted capacity from a buffer by resizing internal memory.
+/**
+	Trim wasted capacity from a buffer by resizing internal memory.
 */
 void fz_trim_buffer(fz_context *ctx, fz_buffer *buf);
 
-/*
-	fz_append_buffer: Append the contents of source buffer to destination buffer.
+/**
+	Empties the buffer. Storage is not freed, but is held ready
+	to be reused as the buffer is refilled.
+
+	Never throws exceptions.
+*/
+void fz_clear_buffer(fz_context *ctx, fz_buffer *buf);
+
+/**
+	Create a new buffer with a (subset of) the data from the buffer.
+
+	start: if >= 0, offset from start of buffer, if < 0 offset from end of buffer.
+
+	end: if >= 0, offset from start of buffer, if < 0 offset from end of buffer.
+
+*/
+fz_buffer *fz_slice_buffer(fz_context *ctx, fz_buffer *buf, int64_t start, int64_t end);
+
+/**
+	Append the contents of the source buffer onto the end of the
+	destination buffer, extending automatically as required.
+
+	Ownership of buffers does not change.
 */
 void fz_append_buffer(fz_context *ctx, fz_buffer *destination, fz_buffer *source);
 
-/*
+/**
+	Write a base64 encoded data block, optionally with periodic newlines.
+*/
+void fz_append_base64(fz_context *ctx, fz_buffer *out, const unsigned char *data, size_t size, int newline);
+
+/**
+	Append a base64 encoded fz_buffer, optionally with periodic newlines.
+*/
+void fz_append_base64_buffer(fz_context *ctx, fz_buffer *out, fz_buffer *data, int newline);
+
+/**
 	fz_append_*: Append data to a buffer.
-	fz_append_printf: Format and append data to buffer using printf-like formatting (see fz_vsnprintf).
-	fz_append_pdf_string: Append a string with PDF syntax quotes and escapes.
+
 	The buffer will automatically grow as required.
 */
 void fz_append_data(fz_context *ctx, fz_buffer *buf, const void *data, size_t len);
@@ -120,25 +187,53 @@ void fz_append_int32_be(fz_context *ctx, fz_buffer *buf, int x);
 void fz_append_int16_be(fz_context *ctx, fz_buffer *buf, int x);
 void fz_append_bits(fz_context *ctx, fz_buffer *buf, int value, int count);
 void fz_append_bits_pad(fz_context *ctx, fz_buffer *buf);
-void fz_append_printf(fz_context *ctx, fz_buffer *buffer, const char *fmt, ...);
-void fz_append_vprintf(fz_context *ctx, fz_buffer *buffer, const char *fmt, va_list args);
+
+/**
+	fz_append_pdf_string: Append a string with PDF syntax quotes and
+	escapes.
+
+	The buffer will automatically grow as required.
+*/
 void fz_append_pdf_string(fz_context *ctx, fz_buffer *buffer, const char *text);
 
-/*
-	fz_terminate_buffer: Zero-terminate buffer in order to use as a C string.
+/**
+	fz_append_printf: Format and append data to buffer using
+	printf-like formatting (see fz_vsnprintf).
 
-	This byte is invisible and does not affect the length of the buffer as returned by fz_buffer_storage.
-	The zero byte is written *after* the data, and subsequent writes will overwrite the terminating byte.
+	The buffer will automatically grow as required.
+*/
+void fz_append_printf(fz_context *ctx, fz_buffer *buffer, const char *fmt, ...);
+
+/**
+	fz_append_vprintf: Format and append data to buffer using
+	printf-like formatting with varargs (see fz_vsnprintf).
+*/
+void fz_append_vprintf(fz_context *ctx, fz_buffer *buffer, const char *fmt, va_list args);
+
+/**
+	Zero-terminate buffer in order to use as a C string.
+
+	This byte is invisible and does not affect the length of the
+	buffer as returned by fz_buffer_storage. The zero byte is
+	written *after* the data, and subsequent writes will overwrite
+	the terminating byte.
+
+	Subsequent changes to the size of the buffer (such as by
+	fz_buffer_trim, fz_buffer_grow, fz_resize_buffer, etc) may
+	invalidate this.
 */
 void fz_terminate_buffer(fz_context *ctx, fz_buffer *buf);
 
-/*
-	fz_md5_buffer: Create MD5 digest of buffer contents.
+/**
+	Create an MD5 digest from buffer contents.
+
+	Never throws exceptions.
 */
 void fz_md5_buffer(fz_context *ctx, fz_buffer *buffer, unsigned char digest[16]);
 
-/*
-	fz_buffer_extract: Take ownership of buffer contents.
+/**
+	Take ownership of buffer contents.
+
 	Performs the same task as fz_buffer_storage, but ownership of
 	the data buffer returns with this call. The buffer is left
 	empty.