From b9349b144d8246b111d322724a66c685db5c72d5 Mon Sep 17 00:00:00 2001
From: waiting <1661926154@qq.com>
Date: Wed, 22 May 2019 20:53:54 +0800
Subject: [PATCH] =?UTF-8?q?docs(arrayBuffer):=20=E6=9B=B4=E6=96=B0=20Array?=
 =?UTF-8?q?Buffer/=E5=AD=97=E7=AC=A6=E4=B8=B2=20=E7=9B=B8=E4=BA=92?=
 =?UTF-8?q?=E8=BD=AC=E6=8D=A2=E5=87=BD=E6=95=B0=EF=BC=8C=E6=94=AF=E6=8C=81?=
 =?UTF-8?q?=E5=A4=9A=E8=AF=AD=E8=A8=80=E5=8F=8A=E5=A4=9A=E7=BC=96=E7=A0=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. 原方法对于非 Unicode BMP 基本平面字符支持不理想。改为使用实验性 TextEncoder/TextDecoder 接口实现。
2. 浏览器支持列表见函数备注
3. Node.js v8.3 开始在 util 对象下实现接口，v11 开始提供全局接口
4. 函数名使用 ab （而非 buf）代表 ArrayBuffer ，避免与 Node.js 的 Buffer （Uint8Array的一个扩展）混淆
5. 虽然是 ECMA js 文档，考虑到 TypeScript 日益壮大，并且函数签名更利于文档规范化，故以带有类型的 TypeScript 代码展示
---
 docs/arraybuffer.md | 56 +++++++++++++++++++++++++--------------------
 1 file changed, 31 insertions(+), 25 deletions(-)

diff --git a/docs/arraybuffer.md b/docs/arraybuffer.md
index cf883c3..fbf8bb4 100644
--- a/docs/arraybuffer.md
+++ b/docs/arraybuffer.md
@@ -448,34 +448,40 @@ Float64Array.BYTES_PER_ELEMENT // 8
 
 ### ArrayBuffer 与字符串的互相转换
 
-`ArrayBuffer`转为字符串，或者字符串转为`ArrayBuffer`，有一个前提，即字符串的编码方法是确定的。假定字符串采用 UTF-16 编码（JavaScript 的内部编码方式），可以自己编写转换函数。
+`ArrayBuffer` 和字符串相互转换， 使用原生 `TextEncoder` `TextDecoder` 类方法转换任何字符集字符串  
+outputEncoding 输出编码一般保持默认值（utf-8），可选值见文档：
+- https://encoding.spec.whatwg.org
+- https://nodejs.org/api/util.html#util_whatwg_supported_encodings
 
-```javascript
-// ArrayBuffer 转为字符串，参数为 ArrayBuffer 对象
-function ab2str(buf) {
-  // 注意，如果是大型二进制数组，为了避免溢出，
-  // 必须一个一个字符地转
-  if (buf && buf.byteLength < 1024) {
-    return String.fromCharCode.apply(null, new Uint16Array(buf));
-  }
-
-  const bufView = new Uint16Array(buf);
-  const len =  bufView.length;
-  const bstr = new Array(len);
-  for (let i = 0; i < len; i++) {
-    bstr[i] = String.fromCharCode.call(null, bufView[i]);
-  }
-  return bstr.join('');
+```ts
+/**
+ * Convert ArrayBuffer/TypedArray to String via TextDecoder
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder
+ */
+function ab2str(
+  input: ArrayBuffer | Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array,
+  outputEncoding: string = 'utf8',
+): string {
+  const decoder = new TextDecoder(outputEncoding)
+  return decoder.decode(input)
 }
 
-// 字符串转为 ArrayBuffer 对象，参数为字符串
-function str2ab(str) {
-  const buf = new ArrayBuffer(str.length * 2); // 每个字符占用2个字节
-  const bufView = new Uint16Array(buf);
-  for (let i = 0, strLen = str.length; i < strLen; i++) {
-    bufView[i] = str.charCodeAt(i);
-  }
-  return buf;
+/**
+ * Convert String to ArrayBuffer via TextEncoder
+ *
+ * @see https://developer.mozilla.org/zh-CN/docs/Web/API/TextEncoder
+ */
+function str2ab(input: string): ArrayBuffer {
+  const view = str2Uint8Array(input)
+  return view.buffer
+}
+
+/** Convert String to Uint8Array */
+function str2Uint8Array(input: string): Uint8Array {
+  const encoder = new TextEncoder()
+  const view = encoder.encode(input)
+  return view
 }
 ```