cutext/sink.h: Text Sink
[cutext: Unicode and Text Handling]

Data Structures

struct  cutext_sink_descriptor
struct  cutext_sink
struct  cutext_countsink
struct  cutext_buffersink

Sink API

typedef char const * cutext_sink_info_encoding_t
typedef cu_str_t cutext_sink_info_debug_state_t
typedef struct
cu_bool_t cutext_sink_info_key_inherits (cutext_sink_info_key_t key)
cutext_sink_descriptor_t cutext_sink_descriptor (cutext_sink_t sink)
void cutext_sink_init (cutext_sink_t sink, cutext_sink_descriptor_t descriptor)
size_t cutext_sink_write (cutext_sink_t sink, void const *buf, size_t max_size)
unsigned int cutext_sink_flags (cutext_sink_t sink)
cu_bool_t cutext_sink_is_clogfree (cutext_sink_t sink)
void cutext_sink_assert_clogfree (cutext_sink_t sink)
cu_box_t cutext_sink_info (cutext_sink_t sink, cutext_sink_info_key_t key)
cu_box_t cutext_sink_info_inherit (cutext_sink_t sink, cutext_sink_info_key_t key, cutext_sink_t subsink)
char const * cutext_sink_encoding (cutext_sink_t sink)
cu_bool_t cutext_sink_flush (cutext_sink_t sink)
cu_box_t cutext_sink_finish (cutext_sink_t sink)
void cutext_sink_discard (cutext_sink_t sink)
cu_bool_t cutext_sink_iterA_subsinks (cutext_sink_t sink, cu_clop(f, cu_bool_t, cutext_sink_t))
void cutext_sink_debug_dump (cutext_sink_t sink)
#define CU_DSINK_WRITE_ERROR   ((size_t)-1)

Generic callbacks

size_t cutext_sink_noop_write (cutext_sink_t, void const *, size_t)
cu_bool_t cutext_sink_noop_flush (cutext_sink_t)
cu_box_t cutext_sink_noop_finish (cutext_sink_t)
void cutext_sink_noop_discard (cutext_sink_t)
size_t cutext_sink_subsinks_write (cutext_sink_t, void const *, size_t)
cu_bool_t cutext_sink_subsinks_flush (cutext_sink_t)
cu_bool_t cutext_sink_empty_iterA_subsinks (cutext_sink_t, cu_clop(f, cu_bool_t, cutext_sink_t))
cu_box_t cutext_sink_default_info (cutext_sink_t, cutext_sink_info_key_t)
cu_bool_t cutext_sink_noop_enter (cutext_sink_t, struct cufo_tag *, struct cufo_attrbind *)
void cutext_sink_noop_leave (cutext_sink_t, struct cufo_tag *)

Sink Implementations

cutext_sink_t cutext_sink_new_str (void)
cutext_sink_t cutext_sink_new_wstring (void)
cutext_sink_t cutext_sink_fdopen (char const *encoding, int fd, cu_bool_t close_fd)
cutext_sink_t cutext_sink_fopen (char const *encoding, char const *path)
cutext_sink_t cutext_sink_stack_buffer (cutext_sink_t subsink)
cutext_sink_t cutext_sink_stack_iconv (char const *new_encoding, cutext_sink_t subsink)
cutext_sink_t cutext_countsink_to_sink (cutext_countsink_t sink)
void cutext_countsink_init (cutext_countsink_t sink)
size_t cutext_countsink_count (cutext_countsink_t sink)
cutext_sink_t cutext_buffersink_to_sink (cutext_buffersink_t sink)
void cutext_buffersink_init (cutext_buffersink_t sink)
cu_buffer_t cutext_buffersink_buffer (cutext_buffersink_t sink)

Detailed Description

This header provides a data structure with callbacks for defining data sinks which are consumers of arbitrary byte streams.

A data sink is said to be clog-free if it's write-callback is guaranteed to always cosume all data provided to it. Data sinks derived form cutext_sink may or may not be clog-free. This property may be essential to some callers, and since this is not checked at compile time, it's recommendable that

Any buffer can be turned into a clog-free buffer by stacking a buffer on top of it, as done by cutext_sink_stack_buffer.

Define Documentation

#define CU_DSINK_WRITE_ERROR   ((size_t)-1)

Special return value for cutext_sink_write to indicate failure.

.flags = 0, \
    .write = cutext_sink_noop_write, \
    .flush = cutext_sink_noop_flush, \
    .finish = cutext_sink_noop_finish, \
    .discard = cutext_sink_noop_discard, \
    .iterA_subsinks = cutext_sink_empty_iterA_subsinks, \
    .info = cutext_sink_default_info, \
    .enter = cutext_sink_noop_enter, \
    .leave = cutext_sink_noop_leave

Function Documentation

cu_buffer_t cutext_buffersink_buffer ( cutext_buffersink_t  sink  ) 

The underlying buffer of sink.

void cutext_buffersink_init ( cutext_buffersink_t  sink  ) 

Initialise the buffer sink sink.

size_t cutext_countsink_count ( cutext_countsink_t  sink  ) 

Returns the number of bytes written to sink.

void cutext_countsink_init ( cutext_countsink_t  sink  ) 

Initialise sink.

void cutext_sink_assert_clogfree ( cutext_sink_t  sink  ) 

Control function to check that sink is clog-free. It is recommended to call this once before starting to write to a sink where a clog-free sink is required for correct operation.

void cutext_sink_discard ( cutext_sink_t  sink  ) 

Inform sink that no more data will be written, and that the operation is considered failed. This means any buffered data may be discarded and resources closed. Operations on external resources such as file creation or database updates, may or may not be reverted.

cu_box_t cutext_sink_finish ( cutext_sink_t  sink  ) 

Inform sink that no more data will be written. This implies flushing any buffered data and closing resources. Some sinks may return constructed data.

cu_bool_t cutext_sink_flush ( cutext_sink_t  sink  ) 

Attempt to write any buffered data and pass down the flush request to sub-sinks.

cu_box_t cutext_sink_info_inherit ( cutext_sink_t  sink,
cutext_sink_info_key_t  key,
cutext_sink_t  subsink 

Returns a suitable value for the default case of the info implementation of sink if it passes its input to subsink.

void cutext_sink_init ( cutext_sink_t  sink,
cutext_sink_descriptor_t  descriptor 

Initialise sink with callbacks from descriptor.

cu_bool_t cutext_sink_is_clogfree ( cutext_sink_t  sink  ) 

True if sink is clog-free, as reported by the CU_DSINK_FN_IS_CLOGFREE response.

cu_bool_t cutext_sink_iterA_subsinks ( cutext_sink_t  sink,
cu_clop(f, cu_bool_t, cutext_sink_t)   

Iterates over the immediate subsinks in case sink is a filter.

cutext_sink_t cutext_sink_new_str ( void   ) 

Returns a sink on which the call to cutext_sink_finish returns a cu_str_t of the written data. No conversion is done. Writing UTF-8 encoded data gives a text string.

cutext_sink_t cutext_sink_new_wstring ( void   ) 

Returns a sink on which the call to cutext_sink_finish returns a cu_wstring_t of the written data. No conversion is done. Writing cu_wchar_encoding encoded characters gives a text string.

cutext_sink_t cutext_sink_stack_buffer ( cutext_sink_t  subsink  ) 

Creates a clog-free sink of subsink by buffering data.

cutext_sink_t cutext_sink_stack_iconv ( char const *  new_encoding,
cutext_sink_t  subsink 

Modifies the character encoding of subsink to new_encoding by passing the data through iconv.

size_t cutext_sink_write ( cutext_sink_t  sink,
void const *  buf,
size_t  max_size 

Tries to write up to max_size bytes starting at buf to the sink, and returns the number of bytes actually consumed. If the sink is clog-free, max_size is returned. A special return value CU_DSINK_WRITE_ERROR indicates failure.

Generated 2009-11-23 for culibs-0.25 using Doxygen. Maintained by Petter Urkedal.