From 889a49f79ccc3e188da74ef2138e9b46f9933af1 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Thu, 18 Oct 2018 18:22:46 -0700
Subject: [PATCH] doc: document use of buffer.swap16() for utf16be

Fixes: https://github.com/nodejs/node/issues/12813

PR-URL: https://github.com/nodejs/node/pull/23747
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
---
 doc/api/buffer.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/api/buffer.md b/doc/api/buffer.md
index 11f3795741b3d3..c62e3380e9bc66 100644
--- a/doc/api/buffer.md
+++ b/doc/api/buffer.md
@@ -1936,6 +1936,14 @@ buf2.swap16();
 // Throws ERR_INVALID_BUFFER_SIZE
 ```
 
+One convenient use of `buf.swap16()` is to perform a fast in-place conversion
+between UTF-16 little-endian and UTF-16 big-endian:
+
+```js
+const buf = Buffer.from('This is little-endian UTF-16', 'utf16le');
+buf.swap16(); // Convert to big-endian UTF-16 text.
+```
+
 ### buf.swap32()
 <!-- YAML
 added: v5.10.0