tarantool / tarantool/doc

tntcxx: properly document template arguments

Open
#3,967 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

tntcxx
Dominant language
CSS
Stars
15
Forks
49
Avg merge
1d 13h
Merged PRs (30d)
3

Description

Some methods accept tuples and keys, which have template types. For example:

std::tuple data = std::make_tuple(key_value, "112", 2.22);
rid_t insert = conn.space[space_id].insert(data);

Documentation describes the argument as "a tuple to insert" and always passes std::tuple. Probably, we should write somewhere, that any array-like object can be passed as tuple - for example, std::vector<int> or std:array<int, N> can be passed as a tuple of integers and std::vector<std::variant<int, std::string, ...>> can be passed as a tuple containing different types.

Generally, here are supported objects:

  • std::nullptr_t for MP_NIL.
  • fundamental types (int, float, bool, ...)
  • integral constants
  • const char *, std::string for MP_STR. Also, we have tnt::string_constant type, which is an equivalent of std::integral_constant for strings.
  • Any iterable or tuple-like object is considered as MP_ARR.
  • Any iterable or tuple-like object, containing pairs (including std::map), is considered as MP_MAP.
  • Any optional-like object is considered to be MP_NIL if it is empty, otherwise it is processed in the same way as its underlying value.
  • Any variant-like object is processed in the same way as its underlying value.

Also, one can populate its own class with encoding rule using static constexpr mpp_enc or mpp member, containing pointers to the class member. Used members must be public. Example:

struct MyTuple {
    int id;
    std::string name;
    std::map<std::string, std::string> attributes;

    static constexpr mpp = std::make_tuple(&MyTuple::id, &MyTuple::name, &MyTuple::attributes);
}
/* ... */
MyTuple data = MyTuple{...};
rid_t insert = conn.space[space_id].insert(data);

This object will be encoded as an array of 3 elements - int, string and map.

Also, one can use mpp::as_* tag to specify what type to encode into. Example:

auto data = std::make_tuple(1, "value1", 2, "value2");
auto map = mpp::as_map(data);

Here, data is a tuple, so it will be encoded as array. If one needs to encode it as map {1: "value1", 2: "value2"}, he should use mpp::as_map tag (or make tuple of pairs instead of plain tuple).

P.S.
I'm not sure that we should use MessagePack types in connector terminology, probably it's better to use more abstract ones (map or dict instead of MP_MAP, for example).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No documentation files are named; start by locating the connector documentation for insert arguments and the existing MessagePack encoding guidance. Document the supported scalar, iterable, map, optional-like, variant-like, and custom mpp forms, including mpp::as_map, and clarify the terminology used for encoded values.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.