﻿/*
	© 2012-2014 FrankHB.

	This file is part of the YSLib project, and may only be used,
	modified, and distributed under the terms of the YSLib project
	license, LICENSE.TXT.  By continuing to use, modify, or distribute
	this file you indicate that you have read the license and
	understand and accept it fully.
*/

/*!	\file CHRLib.txt
\ingroup Documentation
\brief CHRLib 说明。
\version r149
\author FrankHB <frankhb1989@gmail.com>
\since build 305
\par 创建时间:
	2012-04-29 17:11:42 +0800
\par 修改时间:
	2014-02-05 02:47 +0800
\par 文本编码:
	UTF-8
\par 模块名称:
	Documentation::CHRLib
*/


/*

@0 体例和适用范围：
引用标记参见 [Documentation::CommonRules @@0.1] 。
本文档适用于 CHRLib 。

@1 设计：
 CHRLib 是 Character Homomorphism Representation Library 的缩写，是一个字符或类似数据结构的表示支持库。

@1.1 设计的基本原理和表达形式：
支持基于字符的相关构造（编码和字符集等）的抽象。
实现相关的同态(@1.4.1) 操作，包括特定编码字符串的转换。

@1.2 理论背景、工具和依据：
基本内容参见 [Documentation::CommonRules @@2.1] 。

@1.2.1 字符同态(homomorphism) ：
关于同态(homomorphism) ，参见基础数学。
设非空有限集合 X 、 Y 和 E 满足：
 E ⊂ X ，
 X ∩ Y = Ø ；
设 x1 ∈ E ， x2 ∈ E ；
设存在二元高阶函数 f : E × E → X 和 g : Y × Y → Y 。
则可存在同态 h : X → Y 满足不变式 h(f(x1, x2)) = g(h(x1), h(x2)) 。
这里编译时确定的 X 和 Y 中的元素可以表示编码、字符集或区域(locale) 等字符相关的实体。
生成函数 f 和过滤函数 g 是在这些集合上的高阶转换函数，用于取得这些映射。
 CHRLib 的实现抽象 f 、 g 和 h ，表达它们的一些典型具体实例（如接受迭代器的字符序列转换），并提供便于用户引入新的实例的接口。

@1.2.1.1 典型抽象实例 [草案，未实现] ：
设存在非空的编码集 E 、转换规则集 C 和特征集 Y ， X = C ∪ E ， x1 ∈ E ， x2 ∈ E ；
高阶函数 f 是编码转换选择器， c = f(x1, x2) 是转换 x1 编码到 x2 编码的转换函数（接受字符序列作为参数），即 c ∈ C ；
高阶函数 g 是一个特征选择器，接受转换函数实现中对于指定的 x1 和 x2 所需的特征 h(x1) 和 h(x2) 分别作为参数，结果 y = g(h(x1), h(x2)) 是一个能表达适用于 x1 至 x2 转换特征的公共实现 y ∈ Y ；
则高阶函数 h 分别用于提取 x1 和 x2 中转换函数所需的特征，
此时不变式两端都为 y ，表示编码转换操作和特征选择操作的实现之间共有的特征。
用户指定 E 和 Y ，可通过库提供的原型设施适当构造 g 、 h 、f 和 C 并通过库设施得到对应的 c 。在 f 上应用 x1 和 x2 得到所需要的转换函数。

@1.2.1.2 关于字符编码转换相关的一个具体实例 [草案，未实现] ：
设编码集 E = {GBK, UTF-8} ，
原型集 P1 = {UTF-16LE, UTF-32} ，原型集 P2 = {zh-CN, zh-TW, zh-HK, zh-hans, en-US} ，
特征集 Y1 ⊂ {y | y : E × E → P1} 表示 E 中的编码转换过程中可使用 P1 作为中间代码，特征集 Y2 ⊂ {y | y : E → P2} 表示 E 中的编码可适用于 PC1 中的区域，
库原型设施 ph 、 pg 、 pf 和用户提供的编码解释器 e 、规则解释器 r ；
则可有 h = ph(e(E), r((Y1, PC1), (Y2, PC2))) ， g = pg(h) ， F = pf(g) ，
其中 f ∈ F 表示任意满足 Y1 和 Y2 约束的 E 中任意元素 x1 到 x2 的编码转换选择器， c = f(x1, x2) 是具体转换函数。

@1.3 构建原则：
基本内容参见 [Documentation::CommonRules @@2.2] 。
其它见 [Documentation::Designation @@1.3] 。

@1.4 通用语义：
基本内容参见 [Documentation::CommonRules @@2.3] 。

@1.5 领域模型：

@1.5.1 字符类型：
基于 C++11 基本类型的 UCS-2/UCS-4 字符类型，以及 UCS 整数类型，参见 chrdef.h 。

@1.5.2 编码：
基于 MIBEnum 的字符编码定义，参见 encoding.h 。

@1.5.3 字符映射：
转换序列、转换结果和编码宽度等，参见 chrmap.h 。

@1.5.4 静态编码映射：
提供特定编码的转换 API ，参见 smap.hpp 。

@1.5.5 字符编码处理：
编码判断和编码转换 API ，参见 chrproc.h 。

@1.6 存在问题：
完备性。

@2 实现概览：
除非另有说明， CHRLib 仅保证非成员或静态成员函数的线程安全性。

@2.1 领域模型实现：
略。

@2.2 字节序：
不保证所有情形下字节序都一致。
除非另有说明，字符类型 ucs2_t 和 ucs2_t 存储的字节序同实现使用的基本整数类型。
接口说明中若未指定字节序，表示同时适合于大端序和小端序（如 UCS-2 指 UCS-2BE 和 UCS-2LE） 。

@2.3 限制：
目前 Unicode 编码中仅支持基本多文种平面(BMP) 编码点。对 UTF-16 编码支持仅实现兼容 UCS-2 的部分。

@3 API 设计和风格概述：
参见 [Documentation::Designation @@3] 。

@4 标识符命名规约(naming convention) ：
参见 [Documentation::Designation @@4] 。

@5 程序部署和配置：
当前包含于 YFramework 中，作为专用支持库，参见 [Documentation::Designation @@5] 。

@5.1 依赖项：
仅依赖于标准库、 YBase 和 YFramework 的 YCLib::Platform 。

@6 编码风格导引：
参见 [Documentation::Designation @@6] 。

@7 一般实现导引：
暂略。
接口使用方法参见注释和 YFramework 源代码。

*/
////

