浏览 | 提交新的代码片段 | 创建代码包

多字节函数库系列：cyfget.h
类型: Function	类别: Other
许可证: GNU Library Public License	语言: C++
描述: 多字节函数库头文件之一，主要为有关文本文件“按字符数”读取的函数声明，支持不同locale（语言/编码）的临时变换，和不需变换locale情况下不同编码文本的按字符读取〔即将出来〕。

该代码片段的版本系列:

片段ID	下载版本	提交时间	提交人	删除
4562	0.1	2002-06-26 19:57	renxiao

点击"下载版本"来下载该代码片段.

最新版本的代码片段: 0.1

/*: cyfget.h --Own_lib函数库系列-----------------------------------------------
libcyfunc.a
说明: 此头文件声明了有关文件(包括标准输入)的读取函数, 输入计数多以字符计.
作者: 任逍 |2002.04.30.~
版权: GNU GPL/LGPL

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

#ifndef __CY_CYFGET_H__
# define __CY_CYFGET_H__


//&: safegets.cc ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//标准输入: 安全读入函数

char *  cy_safegets(char * dest_str,
                    int max_chars,
                    const char * locale_ctype = NULL);

char *  cy_safegets(char * dest_str,
                    int max_chars,
                    int & length,	//!
                    int & chars,	//!
                    const char * locale_ctype = NULL);

/*
描述: 代替有"缓冲溢出"安全隐患的"gets()"标准读入函数.
      本函数实际使用的是"fgets()"标准文件读入函数, 但"FILE*"直接设成了'stdin'.
      返回的字符串中已去掉了末尾的换行符(如果有)或超过max_chars字符数的输入.
      用户调用cy_safegets()时, 传递有足够大(MB_CUR_MAX * max_chars + 1)内存空间
      的目的字符串指针 | 需要读入的最多字符数(非字节数) | 和"LC_CTYPE"区域设置
      字符串(如: "zh_CN.GBK", 默认值为NULL, 表示不改变系统设置). 传入区域字符串
      后函数将临时改变系统"LC_CTYPE"的设置.
      第二个函数为重载函数, 增加了第三个整数引用参数用于返回实际字串的单字节数,
      和第四个整数引用参数用于返回实际字串的字符数.
dest_str:
      保存读入字符串的内存空间的指针/或NULL值.
max_chars:
      需要从标准输入设备读入的字符个数(按: 对于中文应是输入法服务器传来的字串).
locale_ctype:
      读入字串所属的LC_CTYPE区域(语系/编码). 一般程序开头已经设定, 故此可不管它.
[length]:
      返回实际读取字符串的字节数.
[chars]:
      返回实际读取字符串的字符数.
locale_ctype = NULL:
      读入字串所属的LC_CTYPE区域(语系/编码). 一般程序开头已经设定, 故此可不管它.
返回值:
      返回指向dest_str内存空间/堆中的字符串指针(末尾已加'\0'). 若有错误返回NULL.

注意! 1. 函数从标准输入读入字符串直到出现换行, 或是已读了max_chars个字符为止.
      2. 当传递LC_CTYPE区域设置时, 参数dest_str必须为NULL, 函数返回指向自由存储
         区/堆中的字符串指针, 故用完后应立即delete[]掉, 并赋值为NULL.
      3. 传入区域字符串后函数将临时改变系统"LC_CTYPE"的设置. 在退出时会恢复其原
         来的设置.

TimeFrom: 2002.04.30.
*/
//&!



//&: mbsfgets.cc ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//文件输入: 多字节字符串行读入函数

char *  cy_mbsfgets(char * dest_str,
                    int max_chars,
                    FILE * stream,
                    const char * locale_ctype = NULL);

char *  cy_mbsfgets(char * dest_str,
                    int max_chars,
                    FILE * stream,
                    int & length,	//!
                    int & chars,	//!
                    const char * locale_ctype = NULL);

/*
描述: 当处理多字节文本文件(如中文)时, 标准fgets()函数只能按字节读入, 这样很容易
      读入半个字符而使读入的字符串不完整, 为此, 程序中需增加一些额外的处理代码,
      但这样又让代码看起来不够简洁.
      本函数试图封装这一过程, 使对东亚文本的读取操作直接一些, 代码也简洁一些. 函
      数使用了"mbstowcs()/wcstombs()"标准库函数, 所以在您的程序开头应setlocale().
      与"fgets()"标准库函数类似, 文件中行尾的换行符被与其它字符同样对待的读入.
      同样, 字符串的末尾附上了'\0'(空字符)结束符.
      用户调用函数时: 传递有足够大(MB_CUR_MAX * max_chars +1)内存空间的目的字符
      串地址(指针) |  最多字符(非字节)数 | 文件流指针 | 和"LC_CTYPE"区域设置字符
      串(如: "zh_CN.GBK", 默认值为NULL, 表示不改变系统设置. 另当传递了一个无效的
      区域设置时, 函数不改变当前的该设置, 但该"设置"已为真!).
      下一个函数为重载函数, 增加了返回实际读取字串字节数的引用变量和返回实际读取
      字串字符数的引用变量.
dest_str:
      保存读入字符串的内存空间的指针/或NULL值.
max_chars:
      需要从文件流stream中读入的最多字符个数.
stream:
      FILE结构的文件流指针.
[length]:
      返回实际读取字符串的字节数.
[chars]:
      返回实际读取字符串的字符数.
locale_ctype = NULL:
      读入字串所属的LC_CTYPE区域(语系/编码). 一般程序开头已经设定, 故此可不管它.
返回值:
      返回指向dest_str内存空间的字符串指针(末尾已加'\0'). 若有错误返回NULL.

注意! 1. 函数从stream读入字符串直到出现换行或到文件尾或已读了max_chars个字符为止.
      2. 当传递LC_CTYPE区域设置时, 参数dest_str应为NULL, 函数返回指向自由存储区
         的字符串指针(用完后应delete[]掉, 并赋值为NULL), 若参数dest_str不为NULL,
         函数移动文件流指针一行/或指定字符数(不足一行时), 返回NULL.
         当不传递LC_CTYPE设置, 并且设定参数dest_str为NULL时, 其行为与LC_CTYPE为真
         && dest_str为真(可传递空字符串"")时一样(只有文件流指针移动 && 返回NULL).
      3. 传入区域字符串后函数将临时改变系统"LC_CTYPE"的设置. 在退出时会恢复其原
         来的设置.

TimeFrom: 2002.05.08.
*/
//&!


//&: mbsrfgets.cc ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//cy_mbsfgets()函数的处理有 "状态改变" 编码系统的另一个版本

char *  cy_mbsrfgets(char * dest_str,
                     int max_chars,
                     FILE * stream,
                     bool state_is = false,
                     const char * locale_ctype = NULL);

char *  cy_mbsrfgets(char * dest_str,
                     int max_chars,
                     FILE * stream,
                     int & length,	//!
                     int & chars,	//!
                     bool state_is = false,
                     const char * locale_ctype = NULL);

/*
描述: 函数提供的功能和使用方法与前两个函数基本相同, 唯一不同的是此处的两个函数能
      处理有"状态改变"的编码系统(如日文的"SJIS/Shift JIS"编码). 参数表中增加了一
      个"mbstate_t"的设置开关, 当第一次读入某种语言编码的文本文件时, 请置为true.
state_is = false:
      一个处理有"状态改变"的编码文本的开关. 只需初次读取文本时置其为true(真).

注意! 函数内部处理采用"mbsrtowcs()/wcsrtombs()", 故其应当也适用于无状态改变的编
      码系统(如中文).
*/
//&!


//&: mbfgetc.cc ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//文件输入: 多字节字符字读入函数

char *  cy_mbfgetc(char * dest_str,
                   FILE * stream,
                   const char * locale_ctype = NULL);

char *  cy_mbfgetc(char * dest_str,
                   FILE * stream,
                   int & length,	//!
                   const char * locale_ctype = NULL);

/*
描述: 对于多字节文本文件(如中文)的读取, libcylib.a库已提供了cy_mbsfgets()函数.
      按字符逐字读入多字节文本效率并不高, 但为保持"完整", 在此亦提供多字节文本
      的逐字读入函数cy_mbfgetc().
      为了提高磁盘读写效率, 建议先用cy_mbsfgets()读入一行(或许只是行的一部分),
      然后再对已读入内存中的字符串进行处理.
      顾名思意, 此函数以单个字(可能有多个字节)的方式从文件流中读入文本. 同样,
      因采用了"mbtowc()/wctomb()"标准库函数, 所以在您的程序开头应setlocale().
      与标准函数"fgetc()"类似, 函数返回一个字(一个多字节序列, 末尾已附'\0'). 
      调用函数时: 传递保存读取字的目的地址 | 文件流指针 | "LC_CTYPE"区域设置字符
      串(如: "zh_CN.GBK", 默认值为NULL, 表示不改变系统设置).
      下一个函数为重载函数. 增加了返回实际读取字的字节长度的整数引用参数.
dest_str:
      保存读入字符串的内存空间的指针(大小: "MB_LEN_MAX + 1").
stream:
      FILE结构的文件流指针.
[length]:
      返回实际读取字符串的字节数.
locale_ctype = NULL:
      读入字串所属的LC_CTYPE区域(语系/编码). 一般程序开头已经设定, 故此可不管它.
返回值:
      函数返回读入的多字节字符(单字节字符串). 当有错误时, 返回NULL.

注意! 传入区域字符串后函数将临时改变系统"LC_CTYPE"的设置. 在函数退出时才恢复其
      原有的设置.

TimeFrom: 2002.05.09.
*/
//&!

//&: mbrfgetc.cc ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//cy_mbfgetc()函数的处理有 "状态改变" 编码系统的另一个版本

char *  cy_mbrfgetc(char * dest_str,
                    FILE * stream,
                    bool state_is = false,
                    const char * locale_ctype = NULL);

char *  cy_mbrfgetc(char * dest_str,
                    FILE * stream,
                    int & length,	//!
                    bool state_is = false,
                    const char * locale_ctype = NULL);

/*
描述: 函数提供的功能和使用方法与前两个函数基本相同, 唯一不同的是此处的两个函数能
      处理有"状态改变"的编码系统(如日文的"SJIS/Shift JIS"编码). 参数表中增加了一
      个"mbstate_t"的设置开关, 当第一次读入某种语言编码的文本文件时, 请置为true.
state_is = false:
      一个处理有"状态改变"的编码文本的开关. 只需初次读取文本时置其为true(真).

注意! 函数内部处理采用"mbrtowc()/wcrtomb()", 故其应当也适用于无状态改变的编码系
      统(如中文).
*/
//&!


//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#endif	// define __CY_CYFGET_H__ end.



		

提交新版本

如果您修改了一个代码片段并且觉得很应该让别人共享,您可以把这作为这个代码片段的最新版本提交上来.