Fixed-Width Character Sequences

A sequence declared as sequence<char<N>> contains fixed-width byte arrays, not single C char values and not necessarily zero-terminated strings. Its iterator carries N as elem_size. Each application buffer must provide exactly that many bytes per logical element.

Functions for these sequences use the _char suffix rather than a generated TYPE suffix. Typed logical traversal still hides plain versus RLE storage.

Logical I/O

    MCO_RET mco_seq_next_char(
            mco_seq_iterator_h iterator,
            void* value);

    MCO_RET mco_seq_get_char(
            mco_seq_iterator_h input,
            void* buf,
            mco_size_t* size);

    MCO_RET mco_seq_get_nullable_char(
            mco_seq_iterator_h input,
            void* buf,
            mco_size_t* size,
            mco_bitmap_word_t* null_bitmap);

On entry, size is the buffer capacity in elements; on return, it is the number of elements written. Use mco_seq_get_char() for non-nullable input. Use mco_seq_get_nullable_char() for nullable input; it preserves positions and sets one bit per NULL element.

Application Buffers

    MCO_RET mco_seq_unget_char(
            mco_seq_iterator_h result,
            void const* buf,
            mco_size_t buf_size,
            mco_size_t elem_size);

    MCO_RET mco_seq_unget_nullable_char(
            mco_seq_iterator_h result,
            void const* buf,
            mco_size_t buf_size,
            mco_size_t elem_size,
            mco_bitmap_word_t const* null_bitmap);

buf_size is the number of elements and elem_size is the width of one element in bytes. The functions do not copy buf or null_bitmap. Keep both alive and unchanged until every dependent pipeline has finished. Do not call mco_seq_free_buffer() for these source iterators.

Construction and Transformation

The following functions follow the contracts of their typed counterparts, while retaining the fixed element width in the iterator:

• mco_seq_const_char() constructs an unbounded constant sequence from one value and its byte size.
• mco_seq_parse_char() parses a sequence literal using the specified element width.
• mco_seq_if_char(), mco_seq_iif_char(), and mco_seq_filter_char() perform conditional selection.
• mco_seq_unique_char(), mco_seq_thin_char(), mco_seq_repeat_char(), mco_seq_map_char(), and mco_seq_reverse_char() transform logical elements.
• mco_seq_add_char() concatenates each pair of corresponding elements. It copies bytes from each operand up to that operand's first NUL or declared width, then pads the remaining result width with NUL bytes. The result width is the sum of the operand widths and must not exceed MCO_SEQ_MAX_CHAR_SIZE.
• mco_seq_eq_char(), mco_seq_ne_char(), mco_seq_gt_char(), mco_seq_ge_char(), mco_seq_lt_char(), and mco_seq_le_char() compare corresponding elements and return Boolean sequences.
• mco_seq_join_char() joins the iterators supplied by a meta-iterator and takes the result element width explicitly.
• mco_seq_order_by_char() applies a permutation; its optional data buffer follows the ownership rules described for mco_seq_order_by_TYPE().
• mco_seq_print_char() formats another scalar sequence into fixed-width character elements.
• mco_seq_match() evaluates a pattern against character elements and returns Boolean values.

Character Callbacks

Character callbacks receive the element width because values are byte arrays. A value-producing callback writes exactly elem_size bytes to result.

    typedef void (*mco_seq_func_char_ptr_t)(
            char* result, char const* arg, mco_size_t elem_size);
    typedef void (*mco_seq_func2_char_ptr_t)(
            char* result, char const* arg1, char const* arg2,
            mco_size_t elem_size);
    typedef mco_seq_bool (*mco_seq_cond_char_ptr_t)(
            char const* arg, mco_size_t elem_size);

    MCO_RET mco_seq_func_char(
            mco_seq_iterator_h result,
            mco_seq_iterator_h input,
            mco_seq_func_char_ptr_t func);
    MCO_RET mco_seq_func2_char(
            mco_seq_iterator_h result,
            mco_seq_iterator_h left,
            mco_seq_iterator_h right,
            mco_seq_func2_char_ptr_t func);
    MCO_RET mco_seq_cond_char(
            mco_seq_iterator_h result,
            mco_seq_iterator_h input,
            mco_seq_cond_char_ptr_t func);

The context forms are mco_seq_func_ctx_char(), mco_seq_func2_ctx_char(), and mco_seq_cond_ctx_char(). Their callback types are mco_seq_func_ctx_char_ptr_t, mco_seq_func2_ctx_char_ptr_t, and mco_seq_cond_ctx_char_ptr_t; each adds void* ctx as the final callback argument.

Safety Rules

• Do not use C string functions unless the schema width and stored data guarantee a terminator.
• All inputs to an element-wise character operation must have compatible element widths.
• The payload bytes for a NULL element are unspecified; inspect the NULL result before reading them.
• Use memcpy() or byte-wise access for application structures unless their alignment and representation are explicitly guaranteed.