13.3 Usage
13.3.1 Writing bytes
Single bytes can be written to fz_output streams using fz_write_byte:
/* fz_write_byte: Write a single byte. out: stream to write to. x: value to write */ void fz_write_byte(fz_context *ctx, fz_output *out, unsigned char x);
Blocks of bytes can be written to fz_output streams using fz_write:
/* fz_write: Write data to output. Designed to parallel fwrite. out: Output stream to write to. data: Pointer to data to write. size: Length of data to write. */ void fz_write(fz_context *ctx, fz_output *out, const void *data, size_t size);
13.3.2 Writing objects
We have convenience functions for outputting 16 and 32bit integers in both big and
little endian forms:
/* fz_write_int32_be: Write a big-endian 32-bit binary integer. */ void fz_write_int32_be(fz_context *ctx, fz_output *out, int x); /* fz_write_int32_le: Write a little-endian 32-bit binary integer. */ void fz_write_int32_le(fz_context *ctx, fz_output *out, int x); /* fz_write_int16_be: Write a big-endian 16-bit binary integer. */ void fz_write_int16_be(fz_context *ctx, fz_output *out, int x); /* fz_write_int16_le: Write a little-endian 16-bit binary integer. */ void fz_write_int16_le(fz_context *ctx, fz_output *out, int x);
And a function for outputting utf-8 encoded unicode characters:
/* fz_write_rune: Write a UTF-8 encoded unicode character. */ void fz_write_rune(fz_context *ctx, fz_output *out, int rune);
13.3.3 Writing strings
To output printable strings, we have the simple fputc, fputs and fputrune
equivalents:
/* fz_putc: fputc equivalent for output streams. */ #define fz_putc(C,O,B) fz_write_byte(C, O, B) /* fz_puts: fputs equivalent for output streams. */ #define fz_puts(C,O,S) fz_write(C, O, (S), strlen(S)) /* fz_putrune: fputrune equivalent for output streams. */ #define fz_putrune(C,O,R) fz_write_rune(C, O, R)
We also provide a family of enhanced output functions, patterned after fprintf:
/* fz_vsnprintf: Our customised vsnprintf routine. Takes %c, %d, %o, %s, %u, %x, as usual. Modifiers are not supported except for zero-padding ints (e.g. %02d, %03o, %04x, etc). %f and %g both output in "as short as possible hopefully lossless non-exponent" form, see fz_ftoa for specifics. %C outputs a utf8 encoded int. %M outputs a fz_matrix*. %R outputs a fz_rect*. %P outputs a fz_point*. %q and %( output escaped strings in C/PDF syntax. %ll{d,u,x} indicates that the values are 64bit. %z{d,u,x} indicates that the value is a size_t. */ size_t fz_vsnprintf(char *buffer, size_t space, const char *fmt, va_list args); /* fz_snprintf: The non va_list equivalent of fz_vsnprintf. */ size_t fz_snprintf(char *buffer, size_t space, const char *fmt, ...); /* fz_printf: fprintf equivalent for output streams. See fz_snprintf. */ void fz_printf(fz_context *ctx, fz_output *out, const char *fmt, ...); /* fz_vprintf: vfprintf equivalent for output streams. See fz_vsnprintf. */ void fz_vprintf(fz_context *ctx, fz_output *out, const char *fmt, va_list ap);
13.3.4 Seeking
As with fz_streams, fz_outputs normally move linearly, but in special cases, can be
seekable.
/* fz_seek_output: Seek to the specified file position. See fseek for arguments. Throw an error on unseekable outputs. */ void fz_seek_output(fz_context *ctx, fz_output *out, fz_off_t off, int whence);
Unlike fz_streams, which support fz_tell in all cases, fz_outputs can only
fz_tell_output if they are seekable:
/* fz_tell_output: Return the current file position. Throw an error on unseekable outputs. */ fz_off_t fz_tell_output(fz_context *ctx, fz_output *out);