hicc 0.1.1

Safe, efficient, full-featured FFI between Rust and C++
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

# hicc

A `Rust FFI` SDK that easily and efficiently enables the calling of any `c++ api` function, while significantly increasing the memory safety of `c++ api` interfaces.

        --------                ---------------------------        ------------------              --------
        | rust | ---rust api---| c++ abi declare with rust |       | c++ abi declare |---c++ api---| c++  |
        -------                 ---------------------------        ------------------              --------
                                              |                             |
                                     -----------------               ---------------
                                     | hicc rust sdk |-----c abi-----| hicc c++ sdk |
                                     -----------------        |      ---------------
                                                              |                     
                                     -----------------        |
                                     | hicc js sdk   | --------
                                     -----------------

## 版本变更说明

### v0.1.1

1. `EXPORT_METHOD`支持变长参数的函数，无需使用`EXPORT_VARIADIC`.
2. 消除包含`va_list`和`...`函数的参数数量约束.

## 支持的功能介绍

### 支持的数据类型.

|数据类型|是否支持|备注|
|---|---|---|
|`T`|support||
|`const T&`|support||
|`T&`|support||
|`T&&`|support|`rust`侧同`T`|
|`const T*`|support|程序员管理资源生命周期|
|`T*`|support|程序员管理资源生命周期|
|`const T**`多重指针|support|程序员管理资源生命周期|
|`T**`多重指针|support|程序员管理资源生命周期|
|`std::function<R(ArgTypes...)>`|support||

**说明**:
1. `rust`侧忽略`volatile`.

### 支持的函数类型.

|函数分类|是否支持|
|---|---|
|funtion`(external linkage/internal linkage/no linkage)`|support|
|function overloading|support|
|default parameters|support|
|template function|support|
|class member function|support|
|`noexcept(false)`|support|
|**template class**|support|
|`dynamic_cast`|support|
|realizing virtual function with rust|support|
|`va_list`|support|
|variadic(`...`)|partial support(仅全局函数，参数和返回值无类类型)|

### 安全性保证和增强

基于`rust`生命周期机制，可增强`c++`接口的安全性. 

`c++`容器的迭代器是一个典型的例子.

```
template<class T, class Allocator> class vector {
    //...
    iterator begin();
};
```
可映射为如下`rust`接口:
```
hicc::import_class! {
    pub class vector<T> {
        // ...
        fn begin(&mut self) -> &mut VecIter<T>;
    }
    pub class VecIter<T> {
        //...
    }
}
```

迭代器和容器的生命周期关联起来，基于`rust`的借用规则，增强了接口的安全性.

## 开发指南.

详细内容参见`cargo doc`生成的文档.

可参考`examples`目录下的样例，模板类可参考`hicc-std`的实现.

**约束**: 依赖`c++11`及更高版本的特性.