/*: cyutf.h --Own_lib函数库系列------------------------------------------------
libcyfunc.a
说明: 此头文件声明了有关国际编码UTF系列的函数.
作者: 任逍 |2002.05.26.~
版权: GNU GPL/LGPL

! 编辑器: vim-6.0 |操作系统: TurboLinux7.0简体中文版
------------------------------------------------------------------------------*/

#ifndef __CY_CYUTF_H__
# define __CY_CYUTF_H__

#define __need_size_t
#define __need_NULL
#include <stddef.h>


//&: utf8chars.cc ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//字符统计: UFT-8编码字符串

size_t  cy_utf8chars(const unsigned char * src_str,
                     size_t max_chars,
                     size_t * num_chars = NULL);

/*
描述: 对于国际通行的UTF-8编码字符串, 函数迭代处理以获得字符串的实际字符数(字符数
      通过引用参数num_chars获得).
src_str:
      接受检测字符数的字符串指针.
max_chars:
      需要检测的最多字符个数限制, 若置之为0, 则检测直到字符串结束符'\0'.
num_chars:
      返回实际字串字符个数的指针参数.
返回值:
      返回实际检测的字节数. 若检测到非法字符序列, 则返回-1.

注意! 传递的字符串必须是合法的UTF-8编码序列.

TimeFrom: 2002.05.26.
*/
//&!


//&: toutf8.cc ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//编码转换: (Any)->UFT-8编码字符串

size_t  cy_toutf8(char * out_buf, 
                  size_t buf_len,
                  const char * in_str, 
                  const char * in_code, 
                  bool conv_begin = false);

size_t  cy_toutf8(char * out_buf, 
                  size_t buf_len,
                  const char * in_str, 
                  const char * in_code,
                  size_t & in_len,	//!
                  bool conv_begin = false);

/*
描述: 将任何编码(系统支持的)字符串通过iconv()函数转换为UTF-8编码字节序列.
      下一函数为重载函数, 增加了用于返回源字符串实际转换字节数的参数引用.
out_buf:
      转换的目标字符串空间指针.
buf_len:
      保存目标字符串的内存空间的大小(包括末尾的'\0'字符空间), 按字节计算.
in_str:
      被转换的源字符串指针.
in_code:
      被转换的源字符串编码.
[in_len]:
      用于返回已经被转换的源字符串的字节数(不包括结尾符'\0').
conv_begin = false:
      对于有"状态改变"的编码系统, 在处理连续分段字符串时, 第一次请置其为true.
返回值:
      返回转换后的UTF-8编码字符串的字节数. 若遇到错误返回-1, 若遇到非法字节序列
      或buf_len不足(in_str中还有非空字符待转换), 返回0.

注意! 1. 用iconv()函数转换不同编码字符串时, 与系统LC_CTYPE/locale无关.
      2. 当遇到非法字节序列或buf_len小于转换字符串需要的长度而返回0时, dest_str
         中保存有已经正常转换的字符串(在串的正确位置已有'\0'结束符).

TimeFrom: 2002.05.26.
*/
//&!


//&: utf8to.cc ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//编码转换: UFT-8编码字符串->(Any)

size_t  cy_utf8to(char * out_buf, 
                  size_t buf_len,
                  const char * out_code, 
                  const char * in_str, 
                  bool conv_begin = false);

size_t  cy_utf8to(char * out_buf, 
                  size_t buf_len,
                  const char * out_code, 
                  const char * in_str, 
                  size_t & in_len,	//!
                  bool conv_begin = false);

/*
描述: 通过iconv()函数将UTF-8编码字节序列转换为系统支持的任何编码字符串.
      下一函数为重载函数, 增加了用于返回实际转换字节数的两个参数引用.
out_buf:
      转换的目标字符串空间指针.
buf_len:
      保存目标字符串的内存空间的大小(包括末尾的'\0'字符空间), 按字节计算.
out_code:
      转换的目的字符串的编码.
in_str:
      被转换的源字符串指针(应为末尾有正常结束符'\0'的字符串).
[in_len]:
      用于返回已经被转换的源字符串(UTF-8编码)的字节数(不包括结尾符'\0').
conv_begin = false:
      对于有"状态改变"的编码系统, 在处理连续分段字符串时, 第一次请置其为true.
返回值:
      返回转换后的目标编码字符串的字节数. 若遇到错误返回-1, 若遇到非法字节序列
      或buf_len不足(in_str中还有非空字符待转换), 返回0.

注意! 1. 用iconv()函数转换不同编码字符串时, 与系统LC_CTYPE/locale无关.
      2. 当遇到非法字节序列或buf_len小于转换字符串需要的长度而返回0时, dest_str
         中保存有已经正常转换的字符串(在串的正确位置已有'\0'结束符).

TimeFrom: 2002.05.26.
*/
//&!


//&: utf8towcs.cc ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//编码转换: UTF-8 ->宽字节编码字符串

size_t  cy_utf8towcs(wchar_t * dest_wstr,
                     const unsigned char * src_str,
                     size_t max_chars);

/*
描述: 将国际通行用于磁盘存储的8bits字节序列---UTF-8编码的字符串转换为wchar_t宽
      字节字符串不需要查找码表, 它通过简单的码位截取与合成即可完成.
      本函数提供这一实现.
dest_wstr:
      字符串转换到的宽字节序列目标地址.
src_str:
      被转换的源字符串的指针.
max_chars:
      将被转换的最多字符个数限制, 若置之为0, 则转换直到字符串结束符'\0'.
返回值:
      返回实际转换的字符数. 若遇到错误或检测到非法字节序列, 则返回-1.

注意! 1. 传递的字符串必须是合法的UTF-8编码序列.
      2. 除0外, 如果返回值等于max_chars, 则转换后的款字符串不是以L'\0'结尾的.
*/
//&!


//&: wcstoutf8.cc ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//编码转换: 宽字节编码字符串->UTF-8

size_t  cy_wcstoutf8(char * dest_str,
                     const wchar_t * src_wstr,
                     size_t max_length);

/*
描述: 对于国际通行用于磁盘存储的8bits字节序列---UTF-8编码字符串, 由一般为内存中
      使用的wchar_t宽字节序列转换过来时不需查找码表, 它通过简单的码位析取与分配
      即可完成. 本函数提供这一实现.
dest_str:
      宽字节字符串转换为UTF-8编码字符串的目标地址.
src_wstr:
      被转换的源字符串.
max_length:
      转换的目的字符串最多字节数限制, 若置之为0, 则认为目的字符串空间已经足够大!
      转换将直到字符串结束符'\0'才结束.
返回值:
      返回实际转换后的字符串的字节数. 若遇到错误或检测到非法字节序列, 则返回-1.

注意! 1. 传递的字符串应是能被合法转换为UTF-8编码的宽字节序列.
      2. 除0外, 如果返回值等于max_length, 则转换后的字符串不是以'\0'结尾的.

TimeFrom: 2002.06.05.
*/
//&!

#endif	// end of __CY_CYUTF_H__