﻿/*
	© 2012-2015 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 r454
\author FrankHB <frankhb1989@gmail.com>
\since build 305
\par 创建时间:
	2012-04-29 17:11:42 +0800
\par 修改时间:
	2015-05-24 14:49 +0800
\par 文本编码:
	UTF-8
\par 模块名称:
	Documentation::YBase
*/


/*

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

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

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

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

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

@1.3.1 目标代码兼容性：
基本内容参见 [Documentation::Designation @@2.3.6] 。
现阶段 YBase 提供以下二进制兼容性保证：
除非在变更日志中使用 $src 标识([Documentation::ProjectRules @@2.2.7.1]) ，满足二进制库向后兼容保证([Documentation::CommonRules @@2.2.4.2]) 。

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

@2.1 LibDefect 以外的设计和实现原则：

@2.1.1 调用安全性：
基本内容参见 [Documentation::CommonRules @@3.11] 。
除非另行约定， YBase 中 LibDefect 以外的接口仅保证非成员或静态成员函数的可重入性和线程安全性。
除非有显著性能问题，否则非成员或静态成员接口应保证线程安全性。
不依赖异步安全性，不在任何实现中直接调用终止程序或对应注册回调的函数([Documenation::LanguageConvention @@5.15.3.4]) 。
不降低性能时尽量保证可重入性。

@2.1.2 语言规范：
尽量严格遵守 ISO C++ ，涉及未指定行为和实现定义的行为时应由文档说明。
默认使用 ISO C++11 的一个严格子集，基本内容参见 [Documentation::ProjectRules @@1.2.1] ，不符合此规则的例外由本节指定或文档另行约定。
允许在预处理指令中使用特定实现的宏检查支持的特性，作为进行非正式的变通。
允许使用去除后不影响语义正确性和可观察行为的扩展。
除以上或另行约定（参见 @2.3 、 @2.4 和 @2.5），不使用不向后兼容 ISO C++11 或更新版本的语言特性，或依赖特定平台实现的接口。

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

@2.3 YDefinition ：
模块 YBase::YDefinition ，文件名 ydef.h ，是其它 YBase 头文件的公共依赖项。
若其它文件不依赖此文件，则也不依赖其它 YBase 文件。
YDefinition 实现及判断语言特性的接口可能依赖具体语言实现的特性限制，允许在预处理指令中使用特定实现的宏检查支持的特性。
YDefinition 在 @2.1.2 的基础上支持更多实现，且提供特定 ISO C++11 关键字的替代。
YDefinition 中的特性应保证在被替代的关键字不被支持时仍可以被实现接受。
文件內容为系统环境和公用类型和宏的基础定义，包括对实现环境的检测、实现特性的封装、部分未被实现关键字替代以及一些语言层次上的公共基础设施。
以下名称以 y 起始的宏是表达式宏([Documentation::CommonRules @@5.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 库选项宏：
辅助静态库和动态库编译。
宏名仅使用大写字母和下划线。
公开 API 以宏 YB_API 标识。
在 Win32 平台上支持动态库。构建动态库时需定义 YB_BUILD_DLL ；此外，使用动态库时需定义 YB_DLL 。

@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 @@5.4.3.3] 。
调用宏 yunseq 对代码格式化目的视为特别约定([Documentation::CommonRules @@5.4.3.3]) ，按以下规则处理：
参数不包含块结构（如 lambda 表达式）且不超过 3 行时，视为函数调用格式化，或表示此处代码未完成（需要继续扩展）时使用以下规则；
其它情况下宏名、每个参数和调用的 ) 单独占据独立的行，每个参数视为语句，但不需要添加额外的 { 和 } 组成块的边界。

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

@2.4.1 头文件直接依赖性：
"cast.hpp" 、 "utility.hpp" 和 "tuple.hpp" 依赖 "type_op.hpp" ；
"integer_sequence.hpp" 依赖 "variadic.hpp" ；
"tuple.hpp" 依赖 "integer_sequence.hpp" ；
"iterator_op.hpp" 依赖 "deref_op.hpp" ；
"iterator.hpp" 依赖 "iterator_op.hpp" ；
"functional.hpp" 、 "hash.hpp" 和 "mixin.hpp" 依赖 "tuple.hpp" ；
"any.h" 依赖 "utility.hpp" ；
"any_iterator.hpp" 依赖 "any.h" 。
另见 @2.4.3 、 @2.4.4 和 @2.4.5 。

@2.4.2 命名空间和模板特化：
命名空间 ystdex 内 details 命名空间和声明以宏 yimpl (@2.3.3)修饰的命名空间保留为非公开实现。
除块作用域和非公开的实现命名空间和此处列明的例外，禁止其它的别名声明引入 std 成员命名空间：
ystdex 中对标准库的元编程和类型特征名称使用别名声明；
文档指定的以实现为 ADL([Documentation::LanguageConvention @@5.3.3.1]) 提供并行重载为目的的别名声明。
ystdex 的类型在声明所在的同一头文件中，可能存在 std 命名空间中的类模板的对应特化。
std 的成员对 ystdex 命名空间中的类模板可能存在对应特化。注意完整包含所需的头文件，而不仅是 std 成员声明的标准库头。当前包括以下类型：
std::tuple （使用 "tuple.hpp" 代替 <tuple> ）。

@2.4.2.1 YBase 引入的公开命名空间：
ystdex ： YStandardEx 使用的默认命名空间。
ystdex::any_ops ： ystdex::any 相关的底层操作接口。
inline ystdex::cpp2011_traits 包含 ISO C++ 2011 <type_traits> 引入的名称的命名空间。
inline ystdex::cpp2014_traits 包含 ISO C++ 2014 <type_traits> 引入的名称的命名空间。
ystdex::dependent_operators ： YBase::YStandardEx::Operators 使用的隔离 ADL 的命名空间。
ystdex::dependent_swap ： 引入 std::swap 实现为 ADL 提供重载的命名空间。
ystdex::threading ：线程相关操作。
ystdex::vseq ：变长序列操作。

@2.4.3 不依赖其它 YStandardEx 文件的基本头文件：
这些头文件直接依赖 YDefinition 。

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

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

@2.4.3.3 引用包装 Ref ：
提供替代 std::reference_wrapper 的类模板 ystdex::lref 和相关接口。
注意 std::reference_wrapper 要求完整类型，而 boost::reference_wrapper 和 ystdex::lref 不需要。

@2.4.3.4 解引用操作 DereferenceOperation ：
提供解引用操作检查的模板，作为迭代器操作的基础。

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

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

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

@2.4.4.1 ISO C 断言/调试跟踪扩展 CAssert ：
头文件扩展了标准库头 <cassert> ，提供若干断言函数。这些函数提供无异常抛出保证的异常规范以便于在隐式指定异常规范的无异常抛出的析构函数([Documentation::LanguageConvention @@5.10.5.5]) 中使用。
在库使用约定([Documentation::CommonRules @@3.13.2]) 和语言使用规约([Documentation::LanguageConvention @@5.15.3.3]) 的基础上使用方式同 <cassert> 和 <assert.h> （允许定义宏控制重复包含的内容）。

@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.4.5 ISO C 宽字符分类操作扩展 CWideCharacterType ：
头文件扩展了标准库头 <cwctype> ，提供一些替代实现。

@2.4.4.6 ISO C 字符分类操作扩展 CCtype ：
头文件扩展了标准库头 <cctype> ，提供一些扩展实现。

@2.4.5 ISO C++ 基本扩展：
扩展标准库文件，不依赖以上文件外的 YStandardEx 头文件。
扩展的标准库头被直接或间接地包含。

@2.4.5.1 标准库异常扩展接口 Exception ：
扩展了标准库头 <exception> 和 <stdexcept> ，提供便利接口和若干异常基类。

@2.4.5.2 标准库 Utilities 元编程扩展接口 IntegerSequence ：
扩展了 ISO C++14 标准库头 <utility> 的 std::integer_sequence 等的元编程相关接口，并在 ISO C++14 前提供这些接口和实现。

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

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

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

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

@2.4.5.7 数组操作 Array ：
扩展了标准库头 <array> ，提供内建数组和 std::array 相关类型的操作。

@2.4.5.8 迭代器操作 IteratorOperation ：
扩展了标准库头 <iterator> 。

@2.4.5.9 通用指针 Pointer ：
间接扩展了标准库头 <iterator> ，提供指针的迭代器适配器包装和其它模板。

@2.4.5.10 通用迭代器 Iterator ：
间接扩展了标准库头 <iterator> ，提供若干迭代器适配器和相关操作。

@2.4.5.11 泛型算法 Algorithm ：
扩展了标准库头 <algorithm> ，提供一些泛型算法。
除非另行约定，使用 first 和 last 为名称的参数指定同一个范围，否则不保证结果正确，可能引起未定义行为。

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

@2.4.6 标准库替代：

@2.4.6.1 伪互斥量 PseudoMutex ：
提供单线程环境下的互斥量和锁接口。

@2.4.7 其它扩展接口：

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

@2.4.7.2 通用容器操作 Containers ：
实现通用容器适配器模板和对容器类型及构建数组容器的操作。
参数限制同 Algorithm (@2.4.5.11) 。

@2.4.7.3 基类实用设施 Base ：
提供适合被作为基类的通用接口。

@2.4.7.4 可选值包装类型 Optional ：
提供 Boost.Optional 和提议的 ISO C++ std::experiment::optional 的类似的可选值包装。

@2.4.7.5 动态泛型类型 Any ：
主要提供 Boost.Any 和提议的 ISO C++ std::experiment::any 的类似的基于类型擦除实现的用于保存运行时确定类型的值的对象，默认使用和 libstdc++ 5 类似的小对象优化实现。
命名空间 any_ops 提供更多可供用户调整的内部接口。
提供了一些其它不和 any 类直接相关的类型擦除接口。

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

@2.4.7.7 基于类继承的混入接口 Mixin ：
提供基本的混入接口类型。

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

@2.4.7.9 位段数据结构和访问 BitSegment ：
提供访问位集合的类型和操作。

@2.4.7.10 并发操作 Concurrency ：
提供线程池等实用并发特性。

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

@2.4.7.12 高速缓冲容器模板 Cache ：
提供抽象的缓冲容器模板及操作。

@2.5 LibDefect ：
用于修正依赖的标准库实现因不完善或配置问题等与标准规定的接口的偏差。
和 YStandardEx 支持相同的语言标准。
除非另行说明，支持基本实现环境最低版本，参见 [Documentation::Dependencies @@1] 。
可能会因为更新而缺少兼容性，当前仅对最新环境进行测试。
可支持 libstdc++ 以外的 C++ 实现，但未测试。

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

@2.6.1 Timing ：
计时相关的基础设施。可用于性能测试。

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

@3.1 语言特性使用限制：
YBase 不重载 operator, ，也不对其它代码是否重载 operator, 做出假设。

@3.2 异常使用规则：
基本内容参见 [Documentation::LanguageConvention @@5.10.5] 。
所有内部的异常类型继承 std::exception ，使用 catch(std::exception&) 满足无异常抛出保证([Documentation::LanguageConvention @@5.10.5.1.3]) 。

*/
////

