Add Generics

xcatliu · xcatliu · commit 97df13b19d1c · 2017-01-15T23:58:09.000+08:00
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -0,0 +1,25 @@
+{
+  // Use IntelliSense to learn about possible Node.js debug attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "启动程序",
+      "program": "${workspaceRoot}/app.ts",
+      "cwd": "${workspaceRoot}",
+      "outFiles": [],
+      "sourceMaps": true
+    },
+    {
+      "type": "node",
+      "request": "attach",
+      "name": "附加到进程",
+      "port": 5858,
+      "outFiles": [],
+      "sourceMaps": true
+    }
+  ]
+}
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -7,18 +7,18 @@
   - [Hello TypeScript](introduction/hello-typescript.md)
 - [基础](basics/README.md)
   - [原始数据类型](basics/primitive-data-types.md)
-  - [任意值（Any）](basics/any.md)
+  - [任意值](basics/any.md)
   - [类型推论](basics/type-inference.md)
   - [联合类型](basics/union-types.md)
   - [对象的类型——接口](basics/type-of-object-interfaces.md)
   - [数组的类型](basics/type-of-array.md)
   - [函数的类型](basics/type-of-function.md)
-  - [声明文件（.d.ts）](basics/declaration-files.md)
+  - [声明文件](basics/declaration-files.md)
   - [内置对象](basics/built-in-objects.md)
 - 进阶（未完成）
   - [类的用法](advanced/use-of-class.md)
   - [类的类型](advanced/type-of-class.md)
-  - [元组（Tuple）](advanced/tuple.md)
-  - [枚举（Enum）](advanced/enum.md)
+  - [元组](advanced/tuple.md)
+  - [枚举](advanced/enum.md)
 - 实践（未完成）
 - 学习资料（未完成）
diff --git a/advanced/README.md b/advanced/README.md
@@ -0,0 +1,3 @@
+## 进阶
+
+---
diff --git a/advanced/enum.md b/advanced/enum.md
@@ -1,4 +1,4 @@
-# 枚举（Enum）
+# 枚举
 
 枚举（Enum）类型用于取值被限定在一定范围内的场景，比如一周只能有七天，颜色限定为红绿蓝等。
 
@@ -222,3 +222,5 @@ var directions = [0 /* Up */, 1 /* Down */, 2 /* Left */, 3 /* Right */];
 
 [中文手册 - 枚举]: https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Enums.html
 [C# Enum]: https://msdn.microsoft.com/zh-cn/library/sbbt4032.aspx
+
+---
diff --git a/advanced/generics.md b/advanced/generics.md
@@ -0,0 +1,136 @@
+# 泛型
+
+泛型（Generics）是指在定义函数、接口或类的时候，不预先指定具体的类型，而在使用的时候再指定类型的一种特性。
+
+## 简单的例子
+
+首先，我们来实现一个函数 `createArray`，它可以创建一个指定长度的数组，同时将每一项都填充一个默认值：
+
+```ts
+function createArray(length: number, value: any): Array<any> {
+  let result = [];
+  for (let i = 0; i < length; i++) {
+    result[i] = value;
+  }
+  return result;
+}
+
+createArray(3, 'x'); // ['x', 'x', 'x']
+```
+
+上例中，我们使用了[之前提到过的数组泛型](../basics/type-of-array.md#数组泛型)来定义返回值的类型。
+
+这段代码编译不会报错，但是一个显而易见的缺陷是，它并没有准确的定义返回值的类型：
+
+`Array<any>` 允许数组的每一项都为任意类型。但是我们预期的是，数组中每一项都应该是输入的 `value` 的类型。
+
+这时候，泛型就派上用场了：
+
+```ts
+function createArray<T>(length: number, value: T): Array<T> {
+  let result = [];
+  for (let i = 0; i < length; i++) {
+    result[i] = value;
+  }
+  return result;
+}
+
+createArray<string>(3, 'x'); // ['x', 'x', 'x']
+```
+
+上例中，我们在函数名后添加了 `<T>`，其中 `T` 用来指代任意输入的类型，在后面的输入 `value: T` 和输出 `Array<T>` 中即可使用了。
+
+接着在调用的时候，可以指定它具体的类型为 `string`。当然，也可以不手动指定，而让类型推论自动推算出来：
+
+```ts
+function createArray<T>(length: number, value: T): Array<T> {
+  let result = [];
+  for (let i = 0; i < length; i++) {
+    result[i] = value;
+  }
+  return result;
+}
+
+createArray(3, 'x'); // ['x', 'x', 'x']
+```
+
+## 多个类型参数
+
+定义泛型的时候，可以一次定义多个类型参数：
+
+```ts
+function swap<T, U>(tuple: [T, U]): [U, T] {
+  return [tuple[1], tuple[0]];
+}
+
+swap([7, 'seven']); // ['seven', 7]
+```
+
+上例中，我们定义了一个 `swap` 函数，用来交换输入的元组。
+
+## 泛型约束
+
+在函数内部使用泛型变量的时候，由于事先不知道它是哪种类型，所以不能随意的操作它的属性或方法：
+
+```ts
+function loggingIdentity<T>(arg: T): T {
+  console.log(arg.length);
+  return arg;
+}
+
+// index.ts(2,19): error TS2339: Property 'length' does not exist on type 'T'.
+```
+
+上例中，泛型 `T` 不一定包含属性 `length`，所以编译的时候报错了。
+
+这时，我们可以对泛型进行约束，只允许这个函数传入那些包含 `length` 属性的变量。这就是泛型约束：
+
+```ts
+interface Lengthwise {
+  length: number;
+}
+
+function loggingIdentity<T extends Lengthwise>(arg: T): T {
+  console.log(arg.length);
+  return arg;
+}
+```
+
+上例中，我们使用了 `extends` 约束了泛型 `T` 必须符合接口 `Lengthwise` 的形状，也就是必须包含 `length` 属性。
+
+此时如果调用 `loggingIdentity` 的时候，传入的 `arg` 不包含 `length`，那么在编译阶段就会报错了：
+
+```ts
+interface Lengthwise {
+  length: number;
+}
+
+function loggingIdentity<T extends Lengthwise>(arg: T): T {
+  console.log(arg.length);
+  return arg;
+}
+
+loggingIdentity(7);
+
+// index.ts(10,17): error TS2345: Argument of type '7' is not assignable to parameter of type 'Lengthwise'.
+```
+
+多个类型参数之间也可以互相约束：
+
+```ts
+TBD
+```
+
+## 泛型接口
+
+TBD
+
+## 泛型类
+
+TBD
+
+## 参考
+
+- [Handbook - Generics](http://www.typescriptlang.org/docs/handbook/generics.html) | [中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/generics.html)
+
+---
diff --git a/advanced/tuple.md b/advanced/tuple.md
@@ -1,6 +1,6 @@
-# 元组（Tuple）
+# 元组
 
-元组表示一些特定类型组合成的**数组**类型。
+元组（Tuple）表示一些特定类型组合成的**数组**类型。
 
 ## 简单的例子
 
@@ -92,4 +92,6 @@ console.log(xcatliu[2].slice(1));
 - [Handbook - Basic Types # Tuple](http://www.typescriptlang.org/docs/handbook/basic-types.html#tuple) | [中文版](https://zhongsp.gitbooks.io/typescript-handbook/content/doc/handbook/Basic%20Types.html#元组-tuple)
 - [C# Tuple]
 
+---
+
 [C# Tuple]: https://msdn.microsoft.com/en-us/library/system.tuple(v=vs.110).aspx
diff --git a/basics/README.md b/basics/README.md
@@ -3,13 +3,13 @@
 本部分介绍了 TypeScript 中的常用类型和一些基本概念，旨在让大家对 TypeScript 有个初步的理解。具体内容包括：
 
 - [原始数据类型](primitive-data-types.md)
-- [任意值（Any）](any.md)
+- [任意值](any.md)
 - [类型推论](type-inference.md)
 - [联合类型](union-types.md)
 - [对象的类型——接口](type-of-object-interfaces.md)
 - [数组的类型](type-of-array.md)
 - [函数的类型](type-of-function.md)
-- [声明文件（.d.ts）](declaration-files.md)
+- [声明文件](declaration-files.md)
 - [内置对象](built-in-objects.md)
 
 ---
diff --git a/basics/any.md b/basics/any.md
@@ -1,4 +1,4 @@
-# 任意值（Any）
+# 任意值
 
 任意值（Any）用来表示允许赋值为任意类型。
 
diff --git a/basics/built-in-objects.md b/basics/built-in-objects.md
@@ -108,5 +108,5 @@ npm install @types/node --save-dev
 
 ---
 
-- [上一章：声明文件（.d.ts）](declaration-files.md)
+- [上一章：声明文件](declaration-files.md)
 - [下一章：进阶](../advanced/README.md)
diff --git a/basics/declaration-files.md b/basics/declaration-files.md
@@ -1,4 +1,4 @@
-# 声明文件（.d.ts）
+# 声明文件
 
 当使用第三方库时，我们需要引用它的声明文件。
 
diff --git a/basics/primitive-data-types.md b/basics/primitive-data-types.md
@@ -154,7 +154,7 @@ let num: number = u;
 ---
 
 - [上一章：基础](README.md)
-- [下一章：任意值（Any）](any.md)
+- [下一章：任意值](any.md)
 
 [Primitive data types]: https://developer.mozilla.org/en-US/docs/Glossary/Primitive
 [ES6 中的新类型 `Symbol`]: http://es6.ruanyifeng.com/#docs/symbol
diff --git a/basics/type-inference.md b/basics/type-inference.md
@@ -38,5 +38,5 @@ myFavoriteNumber = 7;
 
 ---
 
-- [上一章：任意值（Any）](any.md)
+- [上一章：任意值](any.md)
 - [下一章：联合类型](union-types.md)
diff --git a/basics/type-of-array.md b/basics/type-of-array.md
@@ -29,15 +29,15 @@ fibonacci.push('8');
 // index.ts(2,16): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
 ```
 
-## 数组泛型（Generic）
+## 数组泛型
 
-也可以使用数组泛型 `Array<elemType>` 来表示数组：
+也可以使用数组泛型（Generic） `Array<elemType>` 来表示数组：
 
 ```ts
 let fibonacci: Array<number> = [1, 1, 2, 3, 5];
 ```
 
-关于泛型，可以参考？？？一章。
+关于泛型，可以参考[《泛型》](../advanced/generics.md)一章。
 
 ## 用接口表示数组
 
diff --git a/basics/type-of-function.md b/basics/type-of-function.md
@@ -187,4 +187,4 @@ push(a, 1, 2, 3);
 ---
 
 - [上一章：数组的类型](type-of-array.md)
-- [下一章：声明文件（.d.ts）](declaration-files.md)
+- [下一章：声明文件](declaration-files.md)
diff --git a/examples/playground/index.js b/examples/playground/index.js
@@ -1,5 +1,5 @@
-function sayHello(person) {
-    return 'Hello, ' + person;
+function loggingIdentity(arg) {
+    console.log(arg.length);
+    return arg;
 }
-var user = [0, 1, 2];
-document.body.innerHTML = sayHello(user);
+loggingIdentity(7);
diff --git a/examples/playground/index.ts b/examples/playground/index.ts
@@ -1,6 +1,10 @@
-function sayHello(person: string) {
-    return 'Hello, ' + person;
+interface Lengthwise {
+  length: number;
 }
 
-let user = [0, 1, 2];
-document.body.innerHTML = sayHello(user);
+function loggingIdentity<T extends Lengthwise>(arg: T): T {
+  console.log(arg.length);
+  return arg;
+}
+
+loggingIdentity(7);

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# 任意值（Any）`
	`1`	`+# 任意值`
`2`	`2`
`3`	`3`	`任意值（Any）用来表示允许赋值为任意类型。`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# 声明文件（.d.ts）`
	`1`	`+# 声明文件`
`2`	`2`
`3`	`3`	`当使用第三方库时，我们需要引用它的声明文件。`
`4`	`4`