You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
All notable changes to this project will be documented in this file.
3
4
4
-
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
5
-
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
5
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
7
7
## Unreleased
8
8
@@ -17,8 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
17
17
18
18
### Changed
19
19
20
-
- better handling of mutable borrows and lifetime relationships for functions
21
-
with contracts
20
+
- better handling of mutable borrows and lifetime relationships for functions with contracts
22
21
23
22
## [0.6.1] - 2021-07-13
24
23
@@ -27,65 +26,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
27
26
- support for `impl Trait` return types
28
27
29
28
## [0.6.0] - 2020-09-05
29
+
30
30
### Changed
31
+
31
32
-`pre` is now `requires`
32
33
-`post` is now `ensures`
33
34
34
35
## [0.5.2] - 2020-09-05
36
+
35
37
### Fixed
38
+
36
39
- Unused braces in function body generated code are removed
37
40
38
41
## [0.5.1] - 2020-08-06
42
+
39
43
### Changed
44
+
40
45
- Trait methods now handle attributes better.
41
46
42
47
## [0.5.0] - 2020-08-06
48
+
43
49
### Changed
50
+
44
51
- Implication operator is now `->`.
45
52
46
53
## [0.4.0] - 2020-05-01
54
+
47
55
### Added
56
+
48
57
- Added support for MIRAI assertions
49
58
- Added implication operator
50
59
51
60
## [0.3.0] - 2019-07-20
61
+
52
62
### Added
63
+
53
64
- Pseudo-function `old(expr)` which in a post-condition evaluates the expression before function execution.
54
65
- Automatic generation of documentation containing all contracts.
55
66
56
67
## [0.2.2] - 2019-07-17
68
+
57
69
### Fixed
70
+
58
71
- Errors inside functions/methods are now properly reported with the correct source location.
72
+
59
73
### Changed
74
+
60
75
- internal handling of contracts is now done in a single proc-macro pass instead of one for each contract.
61
76
62
77
## [0.2.1] - 2019-06-07
78
+
63
79
### Fixed
80
+
64
81
- Functions/methods with explicit return statements no longer skip `post` conditions
65
82
66
83
## [0.2.0] - 2014-04-12
84
+
67
85
### Added
86
+
68
87
-`contract_trait` attribute to make all implementors of a trait respect contracts.
69
88
70
89
## [0.1.1] - 2019-04-08
90
+
71
91
### Added
92
+
72
93
- Feature flags to override contract behavior.
73
94
-`disable_contracts` ignores all checks
74
95
-`override_debug` only checks contracts in debug configurations.
75
96
-`override_log` only prints using the `log`-crate interface.
76
97
77
98
## [0.1.0] - 2019-04-06
78
-
### Added
79
-
- attributes `pre`/`post`/`invariant` and `debug_` versions of each.
80
-
81
-
82
-
83
-
84
-
85
-
86
-
87
-
88
-
89
-
90
99
100
+
### Added
91
101
102
+
- attributes `pre`/`post`/`invariant` and `debug_` versions of each.
Annotate functions and methods with "contracts", using *invariants*,
12
-
*pre-conditions* and *post-conditions*.
9
+
Annotate functions and methods with "contracts", using _invariants_, _pre-conditions_ and _post-conditions_.
13
10
14
-
[Design by contract][dbc] is a popular method to augment code with formal
15
-
interface specifications.
16
-
These specifications are used to increase the correctness of the code by
17
-
checking them as assertions at runtime.
11
+
[Design by contract][dbc] is a popular method to augment code with formal interface specifications. These specifications are used to increase the correctness of the code by checking them as assertions at runtime.
@@ -71,10 +65,9 @@ This crate exposes the `requires`, `ensures` and `invariant` attributes.
71
65
72
66
-`requires` are checked before a function/method is executed.
73
67
-`ensures` are checked after a function/method ran to completion
74
-
-`invariant`s are checked both before *and* after a function/method ran.
68
+
-`invariant`s are checked both before _and_ after a function/method ran.
75
69
76
-
Additionally, all those attributes have versions with different "modes". See
77
-
[the Modes section](#Modes) below.
70
+
Additionally, all those attributes have versions with different "modes". See [the Modes section](#Modes) below.
78
71
79
72
For `trait`s and trait `impl`s the `contract_trait` attribute can be used.
80
73
@@ -84,9 +77,7 @@ More specific information can be found in the crate documentation.
84
77
85
78
### `old()` function
86
79
87
-
One unique feature that this crate provides is an `old()` pseudo-function which
88
-
allows to perform checks using a value of a parameter before the function call
89
-
happened. This is only available in `ensures` attributes.
80
+
One unique feature that this crate provides is an `old()` pseudo-function which allows to perform checks using a value of a parameter before the function call happened. This is only available in `ensures` attributes.
90
81
91
82
```rust
92
83
#[ensures(*x == old(*x) + 1, "after the call `x` was incremented")]
@@ -97,9 +88,7 @@ fn incr(x: &mut usize) {
97
88
98
89
### `->` operator
99
90
100
-
For more complex functions it can be useful to express behaviour using logical
101
-
implication. Because Rust does not feature an operator for implication, this
102
-
crate adds this operator for use in attributes.
91
+
For more complex functions it can be useful to express behaviour using logical implication. Because Rust does not feature an operator for implication, this crate adds this operator for use in attributes.
**Note**: Because of the design of `syn`, it is tricky to add custom operators
120
-
to be parsed, so this crate performs a rewrite of the `TokenStream` instead.
121
-
The rewrite works by separating the expression into a part that's left of the
122
-
`->` operator and the rest on the right side. This means that
123
-
`if a -> b { c } else { d }` will not generate the expected code.
124
-
Explicit grouping using parenthesis or curly-brackets can be used to avoid this.
125
-
108
+
**Note**: Because of the design of `syn`, it is tricky to add custom operators to be parsed, so this crate performs a rewrite of the `TokenStream` instead. The rewrite works by separating the expression into a part that's left of the `->` operator and the rest on the right side. This means that `if a -> b { c } else { d }` will not generate the expected code. Explicit grouping using parenthesis or curly-brackets can be used to avoid this.
126
109
127
110
## Modes
128
111
129
112
All the attributes (requires, ensures, invariant) have `debug_*` and `test_*` versions.
130
113
131
-
-`debug_requires`/`debug_ensures`/`debug_invariant` use `debug_assert!`
132
-
internally rather than `assert!`
133
-
-`test_requires`/`test_ensures`/`test_invariant` guard the `assert!` with an
134
-
`if cfg!(test)`.
135
-
This should mostly be used for stating equivalence to "slow but obviously
136
-
correct" alternative implementations or checks.
137
-
114
+
-`debug_requires`/`debug_ensures`/`debug_invariant` use `debug_assert!` internally rather than `assert!`
115
+
-`test_requires`/`test_ensures`/`test_invariant` guard the `assert!` with an `if cfg!(test)`. This should mostly be used for stating equivalence to "slow but obviously correct" alternative implementations or checks.
116
+
138
117
For example, a merge-sort implementation might look like this
118
+
139
119
```rust
140
120
#[test_ensures(is_sorted(input))]
141
121
fnmerge_sort<T:Ord+Copy>(input:&mut [T]) {
@@ -145,19 +125,16 @@ All the attributes (requires, ensures, invariant) have `debug_*` and `test_*` ve
145
125
146
126
## Set-up
147
127
148
-
To install the latest version, add `contracts` to the dependency section of the
149
-
`Cargo.toml` file.
128
+
To install the latest version, add `contracts` to the dependency section of the `Cargo.toml` file.
150
129
151
130
```
152
131
[dependencies]
153
132
contracts = "0.6.3"
154
133
```
155
134
156
-
To then bring all procedural macros into scope, you can add `use contracts::*;`
157
-
in all files you plan to use the contract attributes.
135
+
To then bring all procedural macros into scope, you can add `use contracts::*;` in all files you plan to use the contract attributes.
158
136
159
-
Alternatively use the "old-style" of importing macros to have them available
160
-
project-wide.
137
+
Alternatively use the "old-style" of importing macros to have them available project-wide.
161
138
162
139
```rust
163
140
#[macro_use]
@@ -168,20 +145,14 @@ extern crate contracts;
168
145
169
146
This crate exposes a number of feature flags to configure the assertion behavior.
170
147
171
-
-`disable_contracts` - disables all checks and assertions.
172
-
-`override_debug` - changes all contracts (except `test_` ones) into `debug_*`
173
-
versions
174
-
-`override_log` - changes all contracts (except `test_` ones) into a
175
-
`log::error!()` call if the condition is violated.
176
-
No abortion happens.
177
-
-`mirai_assertions` - instead of regular assert! style macros, emit macros
178
-
used by the [MIRAI] static analyzer. For more documentation of this usage,
179
-
head to the [MIRAI] repo.
148
+
-`disable_contracts` - disables all checks and assertions.
149
+
-`override_debug` - changes all contracts (except `test_` ones) into `debug_*` versions
150
+
-`override_log` - changes all contracts (except `test_` ones) into a `log::error!()` call if the condition is violated. No abortion happens.
151
+
-`mirai_assertions` - instead of regular assert! style macros, emit macros used by the [MIRAI] static analyzer. For more documentation of this usage, head to the [MIRAI] repo.
0 commit comments