﻿/*
	© 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 YBase.txt
\ingroup Documentation
\brief YBase 说明。
\version r192
\author FrankHB <frankhb1989@gmail.com>
\since build 305
\par 创建时间:
	2012-04-29 17:11:42 +0800
\par 修改时间:
	2014-03-01 13:05 +0800
\par 文本编码:
	UTF-8
\par 模块名称:
	Documentation::YBase
*/


/*

@0 体例和适用范围：
引用标记参见 [Documentation::CommonRules @@0.1] 。
项目范围参见 [Documentation::ProjectRules @@1.1] 。
本文档适用于 YBase 。
部分编码细节和其它规范和 YFramework 共享，参见 [Documentation::Designation] 。

@1 设计：
 YBase 是 YSLib(the YSLib project) 的顶级子项目([ProjectRules @@1.1]) ，且不被其它顶级子项目依赖。

@1.1 设计的基本原理和表达形式：
以扩展标准库为基础构建 YSLib 项目的基础实现。

@1.2 理论背景、工具和依据：
基本内容参见 [Documentation::CommonRules @@2.1] 。
标准库扩展部分和 Boost 接口兼容，参见 http://www.boost.org/ 。

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

@2 实现约束、组成和架构：

@2.1 LibDefect 以外的设计和实现原则：
除了去除后不影响语义正确性和可观察行为的扩展，遵守 ISO C++ ，不使用不兼容于 ISO C++11 的特性或依赖于特定平台实现的接口。
注意 YDefinition 实现及判断语言特性的接口可能依赖于具体语言实现的特性限制。
关于当前允许使用的非 ISO C++03 扩展参见 [Documentation::Designation @1.3.2.1] 。
尽量严格遵守 ISO C++11 ，涉及未确定行为和实现定义的行为时应附文档说明。
除非另有说明， YBase 中 LibDefect 以外的接口仅保证非成员或静态成员函数的可重入性和线程安全性。
除非有显著性能问题，否则非成员或静态成员接口应保证线程安全性。
不降低性能时尽量保证可重入性。

@2.2 文件依赖性：
以下为基本代码依赖性规则按（以优先级顺序排列，即后者不满足前者的部分以前者为准）：
 ydef.h(@2.3) 仅依赖标准库头文件。
 LibDefect 不包含头文件或仅包含标准库头文件。
 YBase 依赖且仅依赖 YBase 文件和标准库头文件。
 YStandardEx 相关的头文件依赖性参见 @2.4.1 。

@2.3 YDefinition ：
模块 YBase::YDefinition ，文件名 ydef.h ，是其它 YBase 头文件的公共依赖项。
若其它文件不依赖此文件，则也不依赖其它 YBase 文件。
文件內容为系统环境和公用类型和宏的基础定义，包括对实现环境的检测、实现特性的封装、部分未被实现关键字替代以及一些语言层次上的公共基础设施。
以下名称以 y 起始的宏是表达式宏([Documentation::CommonRules @@6.10]) 或替代关键字(@2.3.7) 。

@2.3.1 实现标记宏：
 YB_IMPL_CPP 指示支持的 ISO C++ 版本。
其它 YB_IMPL_* 宏指示实现的版本。

@2.3.2 预处理器通用助手宏 ：
用于预处理记号处理。

@2.3.3 宏 yimpl ：
接口代码中标注不作为公开接口实现而不应被用户依赖具体内容的部分的宏。
保证记号被原样替换。

@2.3.4 语言实现特性宏：
指示受到支持的若干 C++ 语言和方言特性。
宏名仅使用大写字母和下划线。

@2.3.5 库选项宏：
辅助静态库和动态库编译。
宏名仅使用大写字母和下划线。

@2.3.6 特性选项宏：
指示是否启用若干特性。

@2.3.7 替代关键字：
模拟语言实现的关键字。
宏名仅使用小写字母。

@2.3.7.1 宏 yunused ：
用于标记未使用的表达式。
显式转换为 void 类型以标记表达式未被作为子表达式使用，可避免某些实现的警告。

@2.3.7.2 宏 yoffsetof ：
同标准库宏 offsetof ，但额外提供了对于可能导致未定义行为的检查。
某些实现（如 GNU C++ ）可能已经自行提供了内建检查，所以此宏并非必要。但为了一致性在库的代码使用此宏。

@2.3.7.3 宏 yunseq ：
用于标记无序列依赖表达式组，以支持非序列优化。
参见 [Documentation::CommonRules @@6.4.3.3] 。

@2.4 YStandardEx ：
 YStandardEx 直接扩充标准库，包含仅依赖于标准库而非标准库的接口。
实现的内容限制为以下两个部分：
适用范围最广的基础设施（比标准库更严格），如序列/非序列调用、通用类型转换、元类型、函数对象、迭代器；
直接基于标准库接口的抽象和封装，如输入/输出抽象。
所有更具体应用问题领域相关的或特定于运行时表达形式相关的操作，如形式语言处理等，都不由 YStandardEx 直接提供接口。

@2.4.1 头文件直接依赖性：
 "type_op.hpp" 和 "variadic.hpp" 依赖于 YDefinition ；
 "cast.hpp" 和 "functional.hpp" 依赖于 "type_op.hpp" ；
 "functional.hpp" 依赖于 "variadic.hpp" 。
另见 @2.4.3 、 @2.4.4 和 @2.4.5 。

@2.4.2 模板特化：
 ystdex 的类型在声明所在的同一头文件中，可能存在 std 命名空间中的类模板的对应特化。
 std 的成员对 ystdex 命名空间中的类模板可能存在对应特化。注意完整包含所需的头文件，而不仅是 std 成员声明的标准库头文件。当前包括以下类型：
  std::tuple （使用 "tuple.hpp" 代替 <tuple> ）。

@2.4.3 不依赖其它 YStandardEx 文件的基本头文件：

@2.4.3.1 C++ 类型操作 TypeOperation ：
扩展了标准库头文件 <type_traits> ，包括元编程设施等。

@2.4.3.2 C++ 变长参数相关操作 Variadic ：
使用 ISO C++11 起提供的变长参数包(pack) 的特性提供序列等基本接口的模板库。

@2.4.3.3 C++ 类型操作检测 Examiner ：
使用元编程和模板匹配检查特定类型是否存在特定操作。

@2.4.3.4 重载操作符 Operators ：
 Boost.Operators 的重新实现。迭代器相关部分参数有所删减。

@2.4.4 ISO C 扩展：
扩展标准库文件，不依赖以上文件外的 YStandardEx 头文件。

@2.4.4.1 ISO C 断言/调试跟踪扩展 CAssert ：
头文件扩展了标准库头文件 <cassert> ，提供若干断言函数。

@2.4.4.2 ISO C 标准整数类型操作 CStandardInteger。
头文件间接扩展了标准库头文件 <cstdint> ，提供一些类型操作和一些整数类型的模板特化以及模算术的基本支持。

@2.4.4.3 ISO C 标准字符串扩展 CString ：
头文件扩展了标准库头文件 <cstring> ，提供可在翻译时求值的 C 风格字符串操作等。

@2.4.4.4 ISO C 标准输入/输出扩展 CStandardIO ：
头文件扩展了标准库头文件 <cstdio> ，提供 C/C++ 流操作模式参数的转换和 C 标准库输入的迭代器包装。

@2.4.5 ISO C++ 基本扩展：
扩展标准库文件，不依赖以上文件外的 YStandardEx 头文件。

@2.4.5.1 元组类型和操作 Tuple ：
扩展了标准库头文件 <tuple> ，提供类型特征和序列相关的特化操作等。

@2.4.5.2 函数和可调用对象 Functional ：
扩展了标准库头文件 <functional> ，提供函数类型操作和各种一般调用的实现。

@2.4.5.3 实用设施 Utilities ：
扩展了标准库头文件 <utility> ，提供一些常用杂项功能。

@2.4.5.4 泛型算法 Algorithms ：
扩展了标准库头文件 <algorithm> ，提供一些泛型算法。

@2.4.5.5 存储和智能指针特性 Memory ：
扩展了标准库头文件 <memory> ，提供对智能指针类型的操作及判断迭代器不可解引用的模板。

@2.4.5.6 通用迭代器 Iterator ：
扩展了标准库头文件 <iterator> ，提供对迭代器的指针和若干迭代器适配器。

@2.4.6 其它扩展接口：

@2.4.6.1 C++ 转换模板 Cast ：
实现各种带类型限制的转换模板。

@2.4.6.2 通用容器操作 Containers ：
实现通用容器适配器模板和对容器类型及构建数组容器的操作。

@2.4.6.3 ISO C++ 标准字符串扩展 String ：
间接扩展了标准库头文件 <string> ，提供 std::char_traits 的扩展功能和对 std::basic_string 及类似类型的操作。

@2.4.6.4 动态泛型类型 Any ：
 Boost.Any 和提议的 ISO C++ tr2::any 的类似的基于类型擦除实现的用于保存运行时确定类型的值的对象。提供了更多可供用户调整的内部接口和默认的小对象优化实现。

@2.4.6.5 动态泛型迭代器 AnyIterator ：
基于 ystdex::any(@2.4.6.4) 实现的用于保存运行时确定类型迭代器的对象。

@2.4.6.6 有理数运算 Rational ：
提供定点数模板等有理数算术类型接口。

@2.4.6.7 抽象路径模板 Path ：
提供抽象的路径模板及操作。

@2.5 LibDefect ：
用于修正依赖的标准库实现因不完善或配置问题等与标准规定的接口的偏差。

@2.6 YTest ：
提供软件测试需要的一些功能的辅助库。

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

@3.1 异常规则：
尽量保持异常中立。
禁止 catch(...) 以避免错误地捕获非 C++ 异常，参见 [Documentation::CommonRules @@5.10.5.6] 。
所有内部的异常类型继承 std::exception ，使用 catch(std::exception&) 满足无异常抛出保证([Documentation::CommonRules @@5.10.5.1.3]) 。

*/
////

