Unicode Data

The pdfout_data type holds a complex data structure. This is the data format used to interface with the parsers and emitters described below.

It is organized into 3 different types:

• Scalar:

  A scalar holds an UTF-8 string, which may contain embedded null bytes and does not have to be null-terminated.

• Array:

  An array holds an array of pointers to pdfout_data types.

• Hash:

  A hash is a set of key-value pairs. Both key and value are pointers to pdfout_data types. The keys must be unique scalars.

Functions

Calling one of the pdfout_data_scalar_* functions on an ARRAY or HASH will throw an exception. Likewise for the pdfout_data_array_* and pdfout_data_hash_* functions.

Type queries

These never throw.

 bool pdfout_data_is_scalar (fz_context *ctx, pdfout_data *data);
 bool pdfout_data_is_array (fz_context *ctx, pdfout_data *data);
 bool pdfout_data_is_hash (fz_context *ctx, pdfout_data *data);

Scalars

Create a new scalar with

 pdfout_data *pdfout_data_scalar_new (fz_context *ctx, const char *value, int len);

Return the value of a scalar with

 char *pdfout_data_scalar_get (fz_context *ctx, pdfout_data *scalar, int *len);

where the length of the string is stored in *len.

Comparison with a string is done with

 bool pdfout_data_scalar_eq (fz_context *ctx, pdfout_data *scalar, const char *s);

Arrays

Create a new array with

 pdfout_data *pdfout_data_array_new (fz_context *ctx);

The length of an array is obtained with

 int pdfout_data_array_len (fz_context *ctx, pdfout_data *array);

Elements of an array are accessed with

 pdfout_data *pdfout_data_array_get (fz_context *ctx, pdfout_data *array,
                                     int pos);

New elements are appended with

 void pdfout_data_array_push (fz_context *ctx, pdfout_data *array,
                              pdfout_data *entry);

Hashes

Create a new hash with

 pdfout_data *pdfout_data_hash_new (fz_context *ctx);

The number of key-value pairs in a hash is obtained with

 int pdfout_data_hash_len (fz_context *ctx, pdfout_data *hash);

New key-value pairs are appended with

 void pdfout_data_hash_push (fz_context *ctx, pdfout_data *hash,
                             pdfout_data *key, pdfout_data *value);

key has to be a scalar. The keys in a hash must be unique. Trying to add a key which is already present in the hash will throw an exception.

There are multiple functions to access a hashes key-value pairs.

 pdfout_data *pdfout_data_hash_get_key (fz_context *ctx, pdfout_data *hash,
                                        int i);
 pdfout_data *pdfout_data_hash_get_value (fz_context *ctx, pdfout_data *hash,
                                          int i);

These extract key and value of the i-th key-value pair.

Hash Convenience Functions

 pdfout_data *pdfout_data_hash_gets (fz_context *ctx, pdfout_data *hash,
                                     char *key);

Searches the hash for the key key and returns the key's value. If no key is found, NULL is returned.

If it is known that the key is a null-terminated string, and the value is a scalar, use this convenience function:

 void pdfout_data_hash_get_key_value (fz_context *ctx, pdfout_data *hash,
                                      char **key, char **value, int *value_len,
                                      int i);

Throw if the value is not a scalar.

To add a null-terminated key with a scalar value, use this function:

 void pdfout_data_hash_push_key_value (fz_context *ctx, pdfout_data *hash,
                                       const char *key, const char *value,
                                       int value_len)

Destructor

 void pdfout_data_drop (fz_context *ctx, pdfout_data *data);

Recursively free.

Comparison

A deep comparison of two pdfout_data types is performed with the following function:

 int pdfout_data_cmp (fz_context *ctx, pdfout_data *x, pdfout_data *y);

Copying

A deep copy of a pdfout_data type is created by

 pdfout_data *pdfout_data_copy (fz_context *ctx, pdfout_data *data);
 

Parsing and Emitting

A pdfout_parser reades a pdfout_data object from a fz_stream. Conversely, a pdfout_emitter writes a pdfout_data object to a fz_output.

This is done with these functions:

 pdfout_data *pdfout_parser_parse (fz_context *ctx, pdfout_parser *parser);
 
 void pdfout_emitter_emit (fz_context *ctx, pdfout_emitter *emitter,
                          pdfout_data *data);
 

JSON

A JSON parser/emitter is created with these functions:

 pdfout_parser *pdfout_parser_json_new (fz_context *ctx, fz_stream *stm);

 pdfout_emitter *pdfout_emitter_json_new (fz_context *ctx, fz_output *out);
 

Destructors

 void pdfout_parser_drop (fz_context *ctx, pdfout_parser *parser);

 void pdfout_emitter_drop (fz_context *ctx, pdfout_emitter *emitter);