The following sections describe various data types and functions that are used internally to implement the other features. These are not usually of interest to users of the MuPDF library, but are provided anyway because why not?
All text strings in MuPDF use the UTF-8 encoding.
The following functions encode and decode UTF-8
characters, and return the number of bytes used by the
UTF-8 character (at most FZ_UTFMAX).
int fz_chartorune(int *rune, const char *str);
int fz_runetochar(char *str, int rune);
Since many of the C string functions are locale dependent, we also
provide our own locale independent versions of these functions. We also
have a couple of semi-standard functions like strsep and
strlcpy that we can’t rely on the system providing. These
should be pretty self explanatory:
char *fz_strdup(fz_context *ctx, const char *s);
float fz_strtof(const char *s, char **es);
char *fz_strsep(char **stringp, const char *delim);
size_t fz_strlcpy(char *dst, const char *src, size_t n);
size_t fz_strlcat(char *dst, const char *src, size_t n);
void *fz_memmem(const void *haystack, size_t haystacklen, const void *needle, size_t needlelen);
int fz_strcasecmp(const char *a, const char *b);
There are also a couple of functions to process filenames and URLs:
char *fz_cleanname(char *path);void fz_dirname(char *dir, const char *path, size_t dir_size);char *fz_urldecode(char *url);Our printf family handles the common printf
formatting characters, with a few minor differences. We also support
several non-standard formatting characters. The same printf
syntax is used in the printf functions in the I/O module as
well.
size_t fz_vsnprintf(char *buffer, size_t space, const char *fmt, va_list args);
size_t fz_snprintf(char *buffer, size_t space, const char *fmt, ...);
char *fz_asprintf(fz_context *ctx, const char *fmt, ...);
char *fz_pool_asprintf(fz_context *ctx, fz_pool *pool, const char *fmt, ...);
%%, %c, %e, %f,
%p, %x, %d, %u,
%s%g floatfloat in the shortest possible format that won’t
lose precision, except NaN to 0,
+Inf to FLT_MAX, -Inf to
-FLT_MAX.
%M fz_matrix*%g separated by
spaces.
%R fz_rect*x0, y0, x1,
y1 in the rectangle as %g separated by spaces.
%P fz_point*x, y in the point as %g
separated by spaces.
%C intUTF-8. Useful to print unicode text.
%q char*%( char*%n char*/ and PDF name hex-escapes.
We have a generic hash table structure with fixed length keys.
The keys and values are not reference counted by the hash table. Callers are responsible for manually taking care of reference counting when inserting and removing values from the table, should that be desired.
fz_hash_table *fz_new_hash_table(fz_context *ctx, int initial_size, int key_length, int lock, void (*drop_value)(fz_context *ctx, void *value));drop_value callback function to
the constructor is only used to release values when the hash table is
destroyed.
void fz_drop_hash_table(fz_context *ctx, fz_hash_table *table);drop_value function on all
the values in the table.
void *fz_hash_find(fz_context *ctx, fz_hash_table *table, const void *key);NULL if not
found.
void *fz_hash_insert(fz_context *ctx, fz_hash_table *table, const void *key, void *value);NULL if the value was inserted for
the first time. Does not reference count the value!
void fz_hash_remove(fz_context *ctx, fz_hash_table *table, const void *key);void fz_hash_for_each(fz_context *ctx, fz_hash_table *table, void *state, void (*callback)(fz_context *ctx, void *state, void *key, int key_length, void *value);The fz_tree structure is a self-balancing binary tree
that maps text strings to values.
void *fz_tree_lookup(fz_context *ctx, fz_tree *node, const char *key);NULL if not found.
fz_tree *fz_tree_insert(fz_context *ctx, fz_tree *root, const char *key, void *value);void fz_drop_tree(fz_context *ctx, fz_tree *node, void (*dropfunc)(fz_context *ctx, void *value));There is no constructor for this structure, since there is no
containing root structure. Instead, the insert function returns the new
root node. Use NULL for the initial empty tree.
fz_tree *tree = NULL;
tree = fz_tree_insert(ctx, tree, "A", my_a_obj);
tree = fz_tree_insert(ctx, tree, "B", my_b_obj);
tree = fz_tree_insert(ctx, tree, "C", my_c_obj);
assert(fz_tree_lookup(ctx, tree, "B") == my_b_obj);
We have a rudimentary XML parser that handles well formed XML. It does not do any namespace processing, and it does not validate the XML syntax.
The parser supports UTF-8, UTF-16,
iso-8859-1, iso-8859-7, koi8,
windows-1250, windows-1251, and
windows-1252 encoded input.
If preserve_white is false, we will discard all
whitespace-only text elements. This is useful for parsing
non-text documents such as XPS and SVG. Preserving whitespace is useful
for parsing XHTML.
typedef struct { opaque } fz_xml_doc;
typedef struct { opaque } fz_xml;
fz_xml_doc *fz_parse_xml(fz_context *ctx, fz_buffer *buf, int preserve_white);
void fz_drop_xml(fz_context *ctx, fz_xml_doc *xml);
fz_xml *fz_xml_root(fz_xml_doc *xml);
fz_xml *fz_xml_prev(fz_xml *item);
fz_xml *fz_xml_next(fz_xml *item);
fz_xml *fz_xml_up(fz_xml *item);
fz_xml *fz_xml_down(fz_xml *item);
int fz_xml_is_tag(fz_xml *item, const char *name);char *fz_xml_tag(fz_xml *item);NULL.
char *fz_xml_att(fz_xml *item, const char *att);NULL
if not a tag or missing.
char *fz_xml_text(fz_xml *item);UTF-8 text of the text element, or
NULL if not a text element.
fz_xml *fz_xml_find(fz_xml *item, const char *tag);NULL if there is no sibling with that tag name.
fz_xml *fz_xml_find_next(fz_xml *item, const char *tag);NULL if none.
fz_xml *fz_xml_find_down(fz_xml *item, const char *tag);NULL if none.