# [gstream.h] Generic Character ( Set ) & Stream Library

## contents

#include "standard.h"

       [gstream] supports the conversion of strings from one character set to another.
       Beside that it provides a generic stream library which is able to handle different
       character sets.
       Supported platforms are Unix and Windows.

## Types and macros

Default multibyte and wide character sets

    #if defined( _MSDOS ) || defined( _WIN32 )
    #define CS_ID_WCHAR   "1200"
    #else
    #define CS_ID_WCHAR   "UCS-4"
    #endif
    #define CS_ID_MBYTE   "UTF-8"

CSConv_T | Character set conversion type
GStream_T | Generic stream type

Types of generic stream functions

    // read byte vector function (RC>=0 <==> bytes read, RC=-1 <==> error)
    typedef int (*GS_getb_T)(GStream_T gstream, c_byte* b, int cnt);
    // put byte vector function (RC>=0 <==> bytes written, RC=-1 <==> error)
    typedef int (*GS_putb_T)(GStream_T gstream, c_byte* b, int cnt);
    // fseek function
    // (RC = new byte position = origin + offset <==> OK, RC=-1 <==> error)
    typedef LONG_INT (*GS_seek_T)(GStream_T gstream, long offset, int origin);
    // close and free function
    typedef void (*GS_destruct_T)(GStream_T gstream);

## Multibyte and wide character set support

    int GS_csconv_ucs4_utf8
        (
          wc_string in, size_t insize,
          c_string out, size_t outsize
        )
| ucs4 --> utf-8 ( RFC 2279 ) 'insize' contains the number of wide characters in 'in', L'\0' inclusive. 'outsize' contains the number of bytes in 'out', '\0' inclusive. 'out': utf-8 representation of 'in' or NULL RC: >=0 on O.K. ( number of written bytes ) | =-1 on possible incomplete input | =-2 on error
    int GS_csconv_utf8_ucs4
        (
          c_string in, size_t insize,
          wc_string out, size_t outsize
        )
| utf-8 --> ucs4 ( RFC 2279 ) 'insize' contains the number of bytes in 'in', '\0' inclusive. 'outsize' contains the number of wide characters in 'out', L'\0' inclusive. 'out': ucs4 representation of 'in' or NULL RC: >=0 on O.K. ( number of written wide characters ) | =-1 on possible incomplete input | =-2 on error
    c_string GS_ucs4_to_utf8(wc_string in)
| ucs4 --> utf-8 ( RFC 2279 ) RC: utf-8 representation of 'in' or NULL; allocs memory
    wc_string GS_utf8_to_ucs4(c_string in)
| utf-8 --> ucs4 ( RFC 2279 ) RC: ucs4 representation of 'in' or NULL; allocs memory
    void GS_fprint_utf8(FILE* fp, c_string s, c_bool raw)
| print utf-8 string 's' to file 'fp' raw --> printable ascii or hex
    void GS_fprint_ucs4(FILE* fp, wc_string ws, c_bool raw)
| print ucs4 string 'ws' to file 'fp' raw --> printable ascii or hex
    CSConv_T GS_csconv_new(c_string ct, c_string cs)
| create new character set conversion description ( RC=NULL on error )
    void GS_csconv_free(CSConv_T csci)
| free character set conversion description
    int GS_csconv_string
        (
          CSConv_T csci, c_string in, int insize,
          c_string out, int* outsize
        )
| character set conversion of 'in' to 'out' 'outsize' contains the number of bytes in 'out'. 'in' and 'out' must be a valid character buffers with size > 0. RC: >=0 on O.K. ( number of conversions / characters ) | =-1 on possible incomplete input | =-2 on error

## Generic stream support

    void GS_stream_file_free(GStream_T gstream)
| free file stream 'gstream'
    void GS_stream_file_destruct(GStream_T gstream)
| close and free file stream 'gstream'
    GStream_T GS_stream_file_new
              (
                FILE* fp, c_string cs, c_bool close
              )
| create new generic stream on a file opened for binary I/O 'cs' : character set name ( UCS4, UTF-8, MS:CodePage / GNU:iconv-based ) 'close': true <--> close file on stream destruction RC: stream on O.K. | NULL on error
    void GS_stream_string_free(GStream_T gstream)
| free string stream 'gstream'
    GStream_T GS_stream_string_new
              (
                c_string s, unsigned int len, c_string cs
              )
| create new generic stream on a string buffer 'len': string size in bytes, inclusive terminating bytes 'cs' : character set name ( UCS4, UTF-8, MS:CodePage / GNU:iconv-based ) RC: stream on O.K. | NULL on error Note: During write operations when reaching the end of the buffer 's' will be deleted and recreated.
    c_bool GS_stream_string_set
           (
             GStream_T gstream, c_string s, unsigned int len
           )
| reset the string buffer of generic stream 'gstream' 'len': string size in bytes, inclusive terminating bytes RC: True = O.K. Note: The character set of 's' and 'gstream' must be the same.
    c_bool GS_stream_string_insert
           (
             GStream_T gstream, c_string s, unsigned int len
           )
| insert 's' into the string buffer of generic stream 'gstream' 'len': string size in bytes, exclusive terminating bytes RC: True = O.K. Note: The character set of 's' and 'gstream' must be the same.
    int GS_stream_get_wcval(GStream_T gstream, wc_int* wc)
| get wide character 'wc' from 'gstream' RC: =1 on O.K. | =0 on O.K. and EOF | =-1 on error
    int GS_stream_get_wcrc(GStream_T gstream)
| get wide character from 'gstream' RC: >=0 as wide character or =-1 on EOF | =-2 on error
    int GS_stream_put_wcval(GStream_T gstream, wc_int wc)
| put wide character 'wc' to 'gstream' RC: >=0 on O.K. | =-1 on error
    int GS_stream_bytepos(GStream_T gstream, unsigned int* pos)
| get ( relative ) stream position in bytes RC: =0 on O.K. | =-1 on error
    GS_getb_T GS_fun_getb(GStream_T gstream)
| get byte function of 'gstream' or NULL
    GS_putb_T GS_fun_putb(GStream_T gstream)
| put byte function of 'gstream' or NULL
    GS_seek_T GS_fun_seek(GStream_T gstream)
| position function of 'gstream' or NULL
    GS_destruct_T GS_fun_destruct(GStream_T gstream)
| close and free function of 'gstream' or NULL