QRust (2) Data Type

This article is machine translated

The data types supported by QRust can be divided into two categories: primitive types and collection types. These data types are passed between Qt and Rust and can be used as function arguments, return values, and fields of struct.

Primitive Types

Collection Types

Note that in the table above, the type starting with the q character is an alias for some C++ type, such as qint32, which is int. It makes no difference whether a variable is defined as qint32 or int when programming with QRust. The corresponding aliases are listed below.

Packet Structure

The above types of data are encapsulated in a binary package structure when passed between Qt and Rust, the package structure is as follows:

The primitive types package structure starts with 1 byte tag, the value of the tag indicates which type it is, and the following values are differentiated according to the length of bytes occupied by different types, such as i8 and u8 occupy 1 byte, and u16 and i16 occupy 2 bytes. More special is the string type, which describes the length of the string after the tag followed by 4 bytes, and the value of the string after the length (utf-8 vector, no ‘\0’ ending).

The collection types package structure is slightly more complex, but not hard to understand.

list package structure:

The tag ranges from 50 to 99. After the tag there is a 4-byte length unit that describes the length of the list package body. The body part contains all the elements, and the structure of the elements is the same as the primitive type structure.

Hash package structure with int as key:

The hash packet tag ranges from 100 to 149, followed by a 4-byte length unit. Each element in the package consists of two parts, because key is of type int, so the structure is the same as i32 in the primitive package structure, and the value part can also refer to the description of the primitive package structure.

Hash package structure with str as key:

The value of tag ranges from 150 to 199. It’s basically the same structure as the previous one, except that the element key has changed.

struct type:

QRust supports custom struct types, structs can be equated to objects in application scenarios, and support for automated (or possibly semi-automated) transformation of structs is one of the highlights of QRust.

When using Qrust for struct data types to pass between Qt and Rust, there are the following points to note:

1) The field name and quantity must be the same on both sides, and the struct name can be different.

2) The Rust side needs to add serialization and deserialization macros to the struct, such as:

[derive(Serialize, Deserialize, Clone, Debug)]
pub struct A {
    a: bool,
    v: Vec,
}

3) Qt side needs to carry out QMetaObject transformation of struct, for example:

struct A{
  Q_GADGET
  Q_PROPERTY(bool a MEMBER a);
  Q_PROPERTY(QList v MEMBER v);
public:
  bool a;
  QList v;
};

In Rust, Serialize and Deserialize macros must be added to struct. In Qt, struct needs to be extended as follows:

• First, you need to add the Q_GADGET macro flag to support Qt meta-object programming.
• The second is to add a Q_PROPERTY macro for each field, format: Q_PROPERTY(type field name MEMBER field name), Q_PROPERTY macro supports struct field traversal, read and write, and type derivation.
• Third, add the public: flag before the field, because the Q_PROPERTY macro execution ends with private:, causing all fields to become private, adding public: will force the change back.

The package structure of struct is the most complex of all types, but it’s also not hard to understand:

The tag of the struct is 24 (base 10). A byte after the tag describes the length of the struct name, followed by the struct name string vector. One byte after the name describes the number of fields (this limits the number of fields to 255), followed by four bytes describing the length of the body, which is all the fields. The field structure is divided into two parts, the field name and the field value. The field name conforms to the definition of the String type, and the field value can refer to the definition of the primitive type or the collection type.

Note: The struct field does not all support primitive types and collection types, which need to be removed:

• struct
• Vec<struct>
• HashMap<i32, struct>
• HashMap<String, struct>

Complex types cannot be nested

A struct field cannot be defined as another struct type. Structs cannot be nested. For example, you cannot use the following struct definition in QRust:

struct A{
struct B b;
}

You can’t nest other collections in a collection type, you can’t define variables like:

QList<QHash<int, bool>> a;

Collection and struct are both complex types. The reason why QRust does not support complex type nesting is related to serialization and deserialization technology. Serialization technology uses the canonical framework library serde in Rust, and QMetaObject is used in the processing of struct on Qt, both of which do not support nesting or are not fully supported.

For static languages such as Rust and Qt, templates and macros are necessary in the serialization process. For example, type derivation is carried out in the serialization process of struct. Compilation preprocessing may generate a lot of code and increase the length of the source code. If complex types are allowed to be nested, the code length may increase exponentially, leading to problems. The compilation preprocessing of C++ templates and Rust macros is more complicated, and it is not discussed here. If you are interested, you can browse the relevant books.

But struct nesting is often encountered, such as the following struct:

struct User{
  qint32  id;
  QString name;
  struct Address address; 
};

It is natural to include address objects in user objects, but how do you solve this problem if you don’t support nesting? QRust’s solution is flattening, pass User and Address as two arguments, and the function definition can be modified:

add_user(user);  //The user contains the address

Changed to:

add_user(user, address);  //flattening

Function input is relatively easy to flatten, if the query from the database, i.e. function return value what to do, can return both user and address? The answer is yes, and QRust has been specifically extended to return multiple return values at the same time.

A function definition in Rust that returns a tuple structure that can contain multiple return values:

pub fn get_user(user_id: i32) -> (User, Address)

Multiple return values can also be processed when serializing:

let (user, address) = get_user(user_id); 
let mut pack = Vec::new();
pack.extend(ser::to_pack(&user)?);  //Serialize the first return value
pack.extend(ser::to_pack(&address)?);   //Serialize the second return value
let pack_multi = ser::to_pack_multi(pack);  //The two return values are assembled together
Ok(Some(pack_multi))

In OnTheSSH software, this multi-return value method is often used, for example, the system monitoring needs to obtain CPU, memory, disk, network, port and other structural information at the same time.

This problem can be extended a bit further, for example, when getting all users, it can be handled like this:

pub fn get_all_users() -> (Vec<User>, Vec<Address>)
pub fn get_all_users() -> (Vec<User>, HashMap<i32, Address>)

The first method needs to define a user_id field in the Address to associate which user the address belongs to, and the second method directly uses the key to associate. This is also why there are both int and string keys in QRust’s Hash type, because int and string are the most commonly used primary keys in the database and are used very frequently.

QRust limits the maximum number of function arguments and multiple return values to 255.

Null and Exception

Null and exceptions are special results that are often encountered in a business system, such as the user has been deleted when call get_user(id) function, or when a command is sent but the network is unreachable. In OnTheSSH software, multiple return values are used to handle null and exception, the first return value is a special structure:

struct RetState
{
    bool    state;          
    qint32  err_code;       
};

The state field indicates the state of the function execution. If it is true, it means that the function was successfully executed and you get the result of the function from the second return value. If it is false, you do not need to get the subsequent return value. At this point, you should look at the err_code field to see what kind of error encoding is involved.

Serialize and deserialize functions

Using the serde framework gives Rust good type inference, so there is a unified from_pack and to_pack function for serialization and deserialization. The Qt side is currently unable to do this, each type needs to correspond to an independent function, the following table lists all serialization and deserialization correspondence: