Buffers and streams

Buffers

A fz_buffer holds a dynamically allocated block of memory.

A new fz_buffer is created with

 fz_buffer *fz_new_buffer(fz_context *ctx, size_t capacity);

Increase the refcount with

 fz_buffer *fz_keep_buffer(fz_context *ctx, fz_buffer *buf);

Drop the buffer with

 void fz_drop_buffer(fz_context *ctx, fz_buffer *buf);

The fz_buffer struct has the following fields:

 struct fz_buffer_s
 {
        int refs;
        unsigned char *data;
        size_t cap, len;
        int unused_bits;
        int shared;
 };

Writing to buffers

 void fz_write_buffer(fz_context *ctx, fz_buffer *buf, const void *data, size_t len);
 void fz_write_buffer_byte(fz_context *ctx, fz_buffer *buf, int val);
 size_t fz_buffer_printf(fz_context *ctx, fz_buffer *buffer, const char *fmt, ...);
 size_t fz_buffer_vprintf(fz_context *ctx, fz_buffer *buffer, const char *fmt, va_list args);

See Writing to output streams for details on the printf-like functions.

Output streams

The fz_output stream is a abstract output handle. It can output to files and fz_buffers.

The following functions create a fz_output.

 fz_output *fz_new_output_with_file_ptr(fz_context *ctx, FILE *output, int close);
 fz_output *fz_new_output_with_path(fz_context *ctx, const char *filename, int
 append);


 fz_output *fz_new_output_with_buffer(fz_context *ctx, fz_buffer *buffer);

Increase the refcount of buffer.

 void fz_drop_output(fz_context *ctx, fz_output *out);

Deallocate an output and drop/close the underlying object.

Writing to output streams.

These all throw on write error.

•  void fz_write(fz_context *ctx, fz_output *out, const void *data, size_t size);

•  fz_putc(fz_context *ctx, fz_output *out, unsigned_char *x);

•  fz_puts(fz_context *ctx, fz_output *out, const void *string);

  Output string. Does not append a newline.

•  void fz_printf(fz_context *ctx, fz_output *out, const char *fmt, ...);
   void fz_vprintf(fz_context *ctx, fz_output *out, const char *fmt, va_list ap);
   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, ...);

  For those, the allowed printf conversion specifiers are %c, %d, %o, %s, %u, %x. The only allowed modifier is zero padding, e.g. %02d.

  Custom conversion specifiers:

  %f, %g

  Return shortest possible decimal representation of a float.

  %C

  UTF-8 encoded int.

  %M, %R, %P

  output fz_matrix*, fz_rect*, fz_point* respectively.

  %q, %(

  output escaped strings in C/PDF syntax.

  %ll{d,u,x}

  indicate 64-bit values.

  %z{d,u,x}

  indicate size_t value.

  %Z{d,u,x}

  indicate fz_off_t value.

Other operations

•  void fz_seek_output(fz_context *ctx, fz_output *out, fz_off_t off, int whence);

•  fz_off_t fz_tell_output(fz_context *ctx, fz_output *out);

Input streams

 fz_stream *fz_open_buffer(fz_context *ctx, fz_buffer *buf);

Increase the refcount of buf.

 fz_stream *fz_open_file_ptr(fz_context *ctx, FILE *file);

Will close file if the stream is dropped.

 void fz_drop_stream(fz_context *ctx, fz_stream *stm);

Deallocate a stream and drop/close the underlying object.

Operations on input streams

•  size_t fz_read(fz_context *ctx, fz_stream *stm, unsigned char *data, size_t len);

  Read up to len bytes from the stream stm. Will throw on read error. Return the number of read bytes. If the return value is smaller than len, end-of-file was reached.

•  fz_off_t fz_tell(fz_context *ctx, fz_stream *stm);

  Return the current reading position.

•  void fz_seek(fz_context *ctx, fz_stream *stm, fz_off_t offset, int whence);

  Seek a stream. Like fseek.