From 4f71fa1907858e6baa47cd89b508bdafa14021cc Mon Sep 17 00:00:00 2001 From: Gireesh Punathil Date: Thu, 29 Nov 2018 19:53:28 +0530 Subject: [PATCH] doc: add a note on usage scope of AliasedBuffer Explain usage context and scope of AliasedBuffer API and its function in the C++ style guide. Provide an example code. Fixes: https://github.com/nodejs/node/issues/22977 PR-URL: https://github.com/nodejs/node/pull/24724 Reviewed-By: Anna Henningsen Reviewed-By: Joyee Cheung Reviewed-By: Vse Mozhet Byt --- CPP_STYLE_GUIDE.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/CPP_STYLE_GUIDE.md b/CPP_STYLE_GUIDE.md index 5099f34ea866c9..b82ed7cc190ec8 100644 --- a/CPP_STYLE_GUIDE.md +++ b/CPP_STYLE_GUIDE.md @@ -21,6 +21,7 @@ * [Use explicit pointer comparisons](#use-explicit-pointer-comparisons) * [Ownership and Smart Pointers](#ownership-and-smart-pointers) * [Avoid non-const references](#avoid-non-const-references) + * [Use AliasedBuffers to manipulate TypedArrays](#use-aliasedbuffers-to-manipulate-typedarrays) * [Others](#others) * [Type casting](#type-casting) * [Using `auto`](#using-auto) @@ -257,6 +258,21 @@ class ExampleClass { }; ``` +### Use AliasedBuffers to manipulate TypedArrays + +When working with typed arrays that involve direct data modification +from C++, use an `AliasedBuffer` when possible. The API abstraction and +the usage scope of `AliasedBuffer` are documented in [aliased_buffer.h][]. + +```c++ +// Create an AliasedBuffer. +AliasedBuffer data; +... + +// Modify the data through natural operator semantics. +data[0] = 12345; +``` + ## Others ### Type casting @@ -382,3 +398,4 @@ even `try` and `catch` **will** break. [Run Time Type Information]: https://en.wikipedia.org/wiki/Run-time_type_information [cppref_auto_ptr]: https://en.cppreference.com/w/cpp/memory/auto_ptr [without C++ exception handling]: https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_exceptions.html#intro.using.exception.no +[aliased_buffer.h]: https://github.com/nodejs/node/blob/master/src/aliased_buffer.h#L12