C/C++文件头例子

 

/*! @file

********************************************************************************

<PRE>

模块名         : 白杨string扩展库

文件名         : stringEx.h

相关文件       : stringEx.cpp

文件实现功能   : C++ string 类功能扩展

作者           : 白杨

版本           : 1.14

--------------------------------------------------------------------------------
多线程安全性   : 否,多线程共享时需要显式同步和互斥
异常时安全性   : 是,满足资源申请即初始化
准则
--------------------------------------------------------------------------------

备注           : string的基础上构建,未添加任何数据成员

--------------------------------------------------------------------------------

修改记录 :

         版本     修改人     修改内容

2003/08/27   1.0      白杨       创建

2003/12/29   1.1      白杨       新增正则表达式、

                                 operator<<操作符等功能

2004/01/28   1.2      白杨       新增部分函数

2004/02/02   1.3      白杨       新增部分函数

2004/03/11   1.6      白杨       新增部分函数

2004/03/29   1.7      白杨       新增ref(), set_size()等函数

2004/06/28   1.8      白杨       移植到namespace BaiY

2004/07/15   1.9      白杨       新增换码/还原函数;为所有正则函

                                 数增加perl风格的字符类

2004/07/19   1.10     白杨       新增vformat()函数;重写、改进

                                 format()函数

2004/08/28   1.11     白杨       ·调整到新编码规范(ver1.5)
                                 ·增加get_all_fields和get_all_delimited_fields
                                   系列函数
2005/03/30   1.12     白杨       添加了针对指针值的 operator<< 操作
                                 和 to_tstr / from_tstr
2005/05/11   1.13     白杨       修改 regex_comp 接口,使用句柄和资源申请即初始
                                 化语义,增加通配符匹配 wildcard_match 和
                                 wildcard_esc_match
2005/05/22   1.14     白杨       新增与已编译正则一起使用的正则替换方法
</PRE>

********************************************************************************


* 版权所有(c) 2003 - 2005, 白杨, 保留所有权利
 

================================================================================

* to_strfrom_strto_wstrfrom_wstr等函数只能做标准^ASCII^字符集的宽/窄字符转

 

 
 

================================================================================

* formatvformat函数所能处理的最大字符串长度限制为MAX_STRING,如需临时改变,可

  以使用:format(maxLength, fmt, ...)函数和vformat(maxLength, fmt, arglist)函数

 

 

================================================================================

* 支持如下ostream风格的流式输入操作,可以方便地用于将个类数据追加到串:

    operator<<(char)        

    operator<<(BYTE) 

    operator<<(int)         

    operator<<(unsigned)    

    opeartor<<(long)

    operator<<(unsigned long)

    operator<<(float)

    operator<<(double)         

    operator<<(const stringEx&)

    operator<<(const char*) 

    operator<<(const BYTE*) 

 

    operator<<(wchar_t)

    operator<<(wstringEx)

 

 

================================================================================

* 支持兼容IEEE 1003.2-1992 (POSIX.2)标准,并且能够正确处理包含0值之字符串的

  正则表达式功能。

 

  同时也支持perl风格的字符类。

 

  为此提供了以下函数:

    regex_find();

    regex_find_replace();

    regex_find_replace_all();

 

    regex_comp();

    regex_find_with_comp();

    regex_free();

 

  - 也可以通过定义宏“#define BaiY_USE_REGEX 0”禁用此功能。

 

  - 为了提高搜索效率,避免大量重复的表达式编译:regex_find()会自动缓存最近一次使

    用的正则表达式(缓存的内容可以通过用空表达式调用regex_find()函数释放)。如果

    需要高效率的交替搜索多个表达式,请使用regex_comp()regex_find_with_comp()

    regex_free()函数。

 

  - 对于wstringEx,还保证能够正确识别UNICODE字符类(如空白符,大小写等)。所以在

    构建一个正则表达式的时候,应该尽量使用如[:blank:][:upper:]这样的字符类,而

    不是如[A-Z]这样的自定义集合。

 

  - 以下是所有POSIX字符类描述,及其对应perl字符类

 

    POSIX         perl     描述

    [:alnum:]                  字母和数字

    [:alpha:]       \a         字母

    [:lower:]       \l         小写字母

    [:upper:]       \u         大写字母

    [:blank:]                  空白字符(空格和制表符)

    [:space:]       \s         所有空格符(比[:blank:]包含的范围广)

    [:cntrl:]                  不可打印的控制字符(退格、删除、警铃...

    [:digit:]       \d         十进制数字

    [:xdigit:]      \x         十六进制数字

    [:graph:]                  可打印的非空白字符

    [:print:]       \p         可打印字符

    [:punct:]                  标点符号

 

  - 此外,perl还有以下特殊字符类:

 

    perl    等效POSIX表达式   描述

    \o        [0-7]             八进制数字

    \O        [^0-7]            非八进制数字

    \w        [[:alnum:]_]      单词构成字符

    \W        [^[:alnum:]_]     非单词构成字符

    \A        [^[:alpha:]]      非字母

    \L        [^[:lower:]]      非小写字母

    \U        [^[:upper:]]      非大写字母

    \S        [^[:space:]]      非空格符

    \D        [^[:digit:]]      非数字

    \X        [^[:xdigit:]]     非十六进制数字

    \P        [^[:print:]]      非可打印字符

 

  - POSIX字符类必须在方括号中工作,相反,perl字符类则必须在方括号外工作。

 

  - 在允许perl风格的正则搜索和替换中,还可以使用以下特殊字符换码序列:

 

    \r  -  回车

    \n  -  换行

    \b  -  退格

    \t  -  制表符

    \v  -  垂直制表符

    \"  -  双引号

    \'  -  单引号

   

   

================================================================================

* 支持以给定的换码符和换码表进行换码和还原操作,为此提供了2个函数:

 

    stringEx& escape_translate(IN const char cEscape,

                               IN const stringEx vstTransTable[][2]);

 

    stringEx& escape_restore(IN const char cEscape,

                             IN const stringEx vstTransTable[][2],

                             IN bool bEraseUnknownEscapeSequence = true,

                             IN bool bUntouchEscEsc = false);

 

  - 使用范例:

 

      // 定义换码表

      const stringEx tbl[][2] = {

          { "<", "LS" },

          { ">", "GT" },

          { "=", "EQ" },

          { "",  "" }   // 换码表结束符

      };

      // 定义换码符

      const char ESC = '%';

 

      stringEx test = "<TEST>aaaa%==%bbbb</TEST>";

      cout << test.escape_translate( ESC, tbl ) << endl;

      cout << test.escape_restore( ESC, tbl ) << endl;

 

      程序输出:

          %LSTEST%GTaaaa%%%EQ%EQ%%bbbb%LS/TEST%GT

          <TEST>aaaa%==%bbbb</TEST>

 

 

================================================================================

* 为了增加与C函数一起使用的效率,提供了以下方法:

    char_type* ref( void )

    void set_size( IN size_t len )

    void set_length( IN size_t len )

 

  - 可以这样使用:

      stingEx a;

      const char* pcStr = "test";

      len = strlen(pcStr);

 

      a.reserve(len);

      strcpy(a.ref(), pcStr);

      a.set_size(len);

 

  - 但是如果有另一个stringEx类对象与“a”引用同一块存储的话,则会导致两个对象的

    内容同时被改变,为防止这种情况发生,应该这样使用它们:

      stringEx a,b;

      a = "something";

      b = a;                  // ba引用同一块内存

      const char* pcStr = "test";

      len = strlen(pcStr);

 

      a.resize(len);          // 对象a发生写时拷贝

      strcpy(a.ref(), pcStr);

    不过很显然,前一种方法效率较高。

 

  - set_length() 方法是set_size方法的一个别名

 

  - 使用以上函数时需要在basic_string模板类中添加两个保护成员函数,具体请参看“安

    装事项”文档。

 

*******************************************************************************/