# [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