pkarr: PK_ARR_MOVE_IN_PLACE

1 files changed, 27 insertions, 4 deletions

diff --git a/pk.h.in b/pk.h.in
index 6ae6b89..0ca132b 100644
--- a/pk.h.in
+++ b/pk.h.in
@@ -128,17 +128,40 @@
 * The following definitions (shown with defaults) can be overridden:
 * PK_ARR_INITIAL_COUNT        16
 * PK_ARR_GROW_RATIO           1.5
-*
-* Initialize `stride`, `alignment` (optional), and `bkt` (optional) members
+* PK_ARR_MOVE_IN_PLACE       (not defined)
+*
+* The macro `PK_ARR_MOVE_IN_PLACE` ensures that when possible, the pointer value
+*  of `arr->data` is preserved.
+* It is used in the following methods:
+*  `pk_arr_move_to_back`
+*  `pk_arr_remove_at`
+* This has two additinal benefits:
+*  1. Minimizing the number and `sz` of calls to `pk_new`
+*  2. Ensuring `data[0]` to `data[(N - 1) * stride]` is not copied extraneously
+*   to a new buffer.
+* The speed of this will vary depending on usage, platform, and compiler.
+*
+* Initialize `stride`, `alignment`, and `bkt` (optional) members
 *  *before* calling any `pk_arr_*` methods.
+*
+* Examples:
 * ``` c
 * struct pk_arr arr = {0};
-* arr.stride = sizeof(obj);
-* arr.alignment = alignof(obj); // optional
+* arr.stride = sizeof(obj);     // required
+* arr.alignment = alignof(obj); // required
 * arr.bkt = bkt;                // optional
 * pk_arr_reserve(&arr, 10);     // optional
 * pk_arr_append(&arr, &obj);
 * ```
+* ``` c
+* struct pk_arr arr = {0};
+* arr.stride = sizeof(obj);     // required
+* arr.alignment = alignof(obj); // required
+* arr.bkt = bkt;                // optional
+* pk_arr_resize(&arr, 10);
+* obj* d = (obj*)arr->data;
+* d[0] = ...;
+* ```
 *
 *******************************************************************************/