[Tarantool-patches] [PATCH v3 14/16] module api: expose box_key_def_extract_key()

[Alexander Turenko <alexander.turenko@tarantool.org>]

Unlike box_tuple_extract_key() it accepts a key_def structure, not
space_id, index_id pair.

Another difference from box_tuple_extract_key() is that this function
allows to pass so called multikey index. See commit 2.2.0-259-gf1d9f2575
('box: introduce multikey indexes in memtx') for details.

Note: The <multikey_idx> parameter is ignored on the backported version
of the patch on 1.10.

Part of #5273
---
 src/box/key_def.c                |   7 ++
 src/box/key_def.h                |  20 +++++
 src/exports.h                    |   1 +
 test/app-tap/module_api.c        | 126 +++++++++++++++++++++++++++++++
 test/app-tap/module_api.test.lua |   2 +-
 5 files changed, 155 insertions(+), 1 deletion(-)

diff --git a/src/box/key_def.c b/src/box/key_def.c
index 7226f2482..da1c23135 100644
--- a/src/box/key_def.c
+++ b/src/box/key_def.c
@@ -620,6 +620,13 @@ box_key_def_merge(const box_key_def_t *first, const box_key_def_t *second)
 	return key_def_merge(first, second);
 }
 
+char *
+box_key_def_extract_key(box_key_def_t *key_def, box_tuple_t *tuple,
+			int multikey_idx, uint32_t *key_size_ptr)
+{
+	return tuple_extract_key(tuple, key_def, multikey_idx, key_size_ptr);
+}
+
 /* }}} Module API functions */
 
 int
diff --git a/src/box/key_def.h b/src/box/key_def.h
index fdf65dec6..1b27836a8 100644
--- a/src/box/key_def.h
+++ b/src/box/key_def.h
@@ -525,6 +525,26 @@ box_tuple_compare_with_key(box_tuple_t *tuple_a, const char *key_b,
 API_EXPORT box_key_def_t *
 box_key_def_merge(const box_key_def_t *first, const box_key_def_t *second);
 
+/**
+ * Extract key from tuple by given key definition and return
+ * buffer allocated on the box region with this key.
+ * @sa <box_region_truncate>().
+ *
+ * This function has O(n) complexity, where n is the number of key
+ * parts.
+ *
+ * @param key_def       Definition of key that need to extract.
+ * @param tuple         Tuple from which need to extract key.
+ * @param multikey_idx  Multikey index hint or -1.
+ * @param key_size_ptr  Here will be size of extracted key.
+ *
+ * @retval not NULL  Success.
+ * @retval NULL      Memory allocation error.
+ */
+API_EXPORT char *
+box_key_def_extract_key(box_key_def_t *key_def, box_tuple_t *tuple,
+			int multikey_idx, uint32_t *key_size_ptr);
+
 /** \endcond public */
 
 /*
diff --git a/src/exports.h b/src/exports.h
index 223390d52..a0c7ac84d 100644
--- a/src/exports.h
+++ b/src/exports.h
@@ -31,6 +31,7 @@ EXPORT(box_iterator_free)
 EXPORT(box_iterator_next)
 EXPORT(box_key_def_delete)
 EXPORT(box_key_def_dump_parts)
+EXPORT(box_key_def_extract_key)
 EXPORT(box_key_def_merge)
 EXPORT(box_key_def_new)
 EXPORT(box_key_def_new_v2)
diff --git a/test/app-tap/module_api.c b/test/app-tap/module_api.c
index 175217ef9..25cd8a5e7 100644
--- a/test/app-tap/module_api.c
+++ b/test/app-tap/module_api.c
@@ -1580,6 +1580,131 @@ test_key_def_merge(struct lua_State *L)
 	return 1;
 }
 
+/**
+ * Basic <box_key_def_extract_key>() test.
+ */
+static int
+test_key_def_extract_key(struct lua_State *L)
+{
+	size_t region_svp = box_region_used();
+
+	/*
+	 * Create a key_def.
+	 *
+	 *  |              tuple
+	 *  |            [x, x, x]
+	 *  | key_def     ^     ^
+	 *  |    |        |     |
+	 *  |   (0) <-----+---- string (optional)
+	 *  |    |        |
+	 *  |   (1) <---- unsigned
+	 */
+	box_key_part_def_t parts[2];
+	box_key_part_def_create(&parts[0]);
+	box_key_part_def_create(&parts[1]);
+	parts[0].fieldno = 2;
+	parts[0].field_type = "string";
+	parts[0].flags |= BOX_KEY_PART_DEF_IS_NULLABLE;
+	parts[1].fieldno = 0;
+	parts[1].field_type = "unsigned";
+	box_key_def_t *key_def = box_key_def_new_v2(parts, 2);
+	assert(key_def != NULL);
+
+	/*
+	 * Create tuples to extract keys from them.
+	 *
+	 *  | # | tuple         | key        |
+	 *  | - | ------------- | ---------- |
+	 *  | 0 | [1, 2, "moo"] | ["moo", 1] |
+	 *  | 1 | [1, 2, null]  | [null, 1]  |
+	 *  | 2 | [1, 2]        | [null, 1]  |
+	 *  | 3 | [1]           | [null, 1]  |
+	 */
+	box_tuple_t *tuples[] = {
+		/* [0] = */ new_runtime_tuple("\x93\x01\x02\xa3moo", 7),
+		/* [1] = */ new_runtime_tuple("\x93\x01\x02\xc0", 4),
+		/* [2] = */ new_runtime_tuple("\x92\x01\x02", 3),
+		/* [3] = */ new_runtime_tuple("\x91\x01", 2),
+	};
+	struct {
+		const char *key;
+		uint32_t key_size;
+	} expected_keys_1[] = {
+		/* [0] = */ {"\x92\xa3moo\x01", 6},
+		/* [1] = */ {"\x92\xc0\x01", 3},
+		/* [2] = */ {"\x92\xc0\x01", 3},
+		/* [3] = */ {"\x92\xc0\x01", 3},
+	};
+
+	for (size_t i = 0; i < lengthof(tuples); ++i) {
+		uint32_t key_size = 0;
+		char *key = box_key_def_extract_key(key_def, tuples[i], -1,
+						    &key_size);
+		assert(key != NULL);
+		uint32_t exp_key_size = expected_keys_1[i].key_size;
+		const char *exp_key = expected_keys_1[i].key;
+		assert(key_size == exp_key_size);
+		assert(memcmp(key, exp_key, exp_key_size) == 0);
+	}
+
+	/* Clean up. */
+	for (size_t i = 0; i < lengthof(tuples); ++i)
+		box_tuple_unref(tuples[i]);
+	box_key_def_delete(key_def);
+
+	/*
+	 * Create a key_def with multikey JSON path.
+	 *
+	 *  |             tuple
+	 *  |           [[x, x, x], x, x]
+	 *  | key_def     ^  ^  ^
+	 *  |    |        0  1  2
+	 *  |    |        |  |  |
+	 *  |    |        |--+--+
+	 *  |    |        |
+	 *  |   (0) <---- unsigned
+	 */
+	box_key_part_def_t part;
+	box_key_part_def_create(&part);
+	part.fieldno = 0;
+	part.field_type = "unsigned";
+	part.path = "[*]";
+	key_def = box_key_def_new_v2(&part, 1);
+	assert(key_def != NULL);
+
+	/* [[7, 2, 1], 5, 4] */
+	box_tuple_t *tuple =
+		new_runtime_tuple("\x93\x93\x07\x02\x01\x05\x04", 7);
+
+	struct {
+		const char *key;
+		uint32_t key_size;
+	} expected_keys_2[] = {
+		/* [0] = */ {"\x91\x07", 2},
+		/* [1] = */ {"\x91\x02", 2},
+		/* [2] = */ {"\x91\x01", 2},
+	};
+
+	for (int i = 0; i < (int)lengthof(expected_keys_2); ++i) {
+		uint32_t key_size = 0;
+		char *key = box_key_def_extract_key(key_def, tuple, i,
+						    &key_size);
+		assert(key != NULL);
+		uint32_t exp_key_size = expected_keys_2[i].key_size;
+		const char *exp_key = expected_keys_2[i].key;
+		assert(key_size == exp_key_size);
+		assert(memcmp(key, exp_key, exp_key_size) == 0);
+	}
+
+	/* Clean up. */
+	box_tuple_unref(tuple);
+	box_key_def_delete(key_def);
+	box_region_truncate(region_svp);
+
+	lua_pushboolean(L, 1);
+	return 1;
+}
+
 /* }}} key_def api v2 */
 
 static int
@@ -1961,6 +2086,7 @@ luaopen_module_api(lua_State *L)
 		{"test_key_def_dump_parts", test_key_def_dump_parts},
 		{"test_key_def_validate_tuple", test_key_def_validate_tuple},
 		{"test_key_def_merge", test_key_def_merge},
+		{"test_key_def_extract_key", test_key_def_extract_key},
 		{NULL, NULL}
 	};
 	luaL_register(L, "module_api", lib);
diff --git a/test/app-tap/module_api.test.lua b/test/app-tap/module_api.test.lua
index 6d045f8ce..4de450462 100755
--- a/test/app-tap/module_api.test.lua
+++ b/test/app-tap/module_api.test.lua
@@ -177,7 +177,7 @@ local function test_iscdata(test, module)
 end
 
 local test = require('tap').test("module_api", function(test)
-    test:plan(32)
+    test:plan(33)
     local status, module = pcall(require, 'module_api')
     test:is(status, true, "module")
     test:ok(status, "module is loaded")
-- 
2.25.0