Swift 3 SE-0006 在标准库中应用API设计指南 Swift 3 教程

admin

Swift 3 SE-0006 在标准库中应用API设计指南  Swift 3 教程

第一部分 提交review前必读

做为下面三份文档的一部分，它们的内容是彼此关联的：

• SE-0023 API设计指南
• SE-0006 在标准库中应用设计指南
• SE-0005 更好的把Objective-C APIs转换成Swift版本
  

这三份文档的内容是相互关联的（例如：标准库中一个API的调整和某个API guideline是对应的，或根据某条设计指南制定的Clang importer规则，等等）。正因为存在这些内容交叉，为了保证讨论是可维护的，我们希望你：

• 在提交review之前，对以上三份文档中的全部内容，有一个基本的了解；
• 在提交以上三个文档的review时，请参照每个文档的review声明。在你提交review时，如果文档间交叉引用有助于帮你阐述观点，你应该包含它们（这也是被提倡的做法）。
  

第二部分 简介

API设计指南作为Swift 3开发工作的一部分，让标准库做为这份指南的实现典范是很重要的。在各种类型的App中，标准库中的API都是最常使用的Swift API，并且，标准库也为其它的程序库提供了实现基础。

在这份提议中，我们回顾了整个标准库，并且让它的设计遵循API设计指南中的要求。

第三部分 提议的解决方案

实际的代码修改在Swift repository的swift-3-api-guidelines分支。总体来说，这些变化可以归结于以下几个方面：

• 在protocol名称中，去掉了Type后缀。在一些特殊情况下，为了避免和一些基本类型名称混淆，我们需要添加Protocol后缀（尽管这些类型我们期望在Swift 3中被废除）；
• 在所有的API中，和generator相关的概念，都被重命名成了iterator；
• 删除了仅用于CollectionOfOne的索引类型Bit。我们推荐使用Int；
• 在“不安全的指针类型（unsafe pointer types）”中，泛型参数名从Memory改为了Pointee；
• 删除了“不安全的指针类型”的默认初始化方法，我们推荐使用nil；
• 删除了struct PermutationGenerator；
• 删除了MutableSliceable protocol，你可以使用Collection where SubSequence : MutableCollection；
• sort()重命名成了sorted()，sortInPlace()重命名成了sort()；
• reverse()重命名成了reversed()；
• enumerate()重命名成了enumerated()；
• 简化了partition() API；
• SequenceType.minElement()重命名为了.min()，.maxElement()重命名为了.max()；
• 删除了一些序列和集合配接器（Collection adapters）的初始化方法。我们建议你调用对应算法函数或方法；
• 把一些函数变成了类方法或反之；
• 把以null结尾的UTF-8数据变成String对象的工厂函数变成了String的一个初始化方法；
  

第四部分 API差异对比
原文地址：

https://github.com/Boxue/swift-api-design-guidelines/blob/master/SE-0006%20apply-api-guidelines-to-the-standard-library.md