Skip to content

Commit 46d03b7

Browse files
lczllxlczllx
committed
feat(cpp14): add 07-deprecated-attribute
Book chapter (zh + en): - section 一/I: Basic usage — marking functions and variables - section 二/II: Real-world case — _CXX17_DEPRECATE_C_HEADER macro from msvc-stl/stl/inc/yvals_core.h#L1057-L1061 - section 三/III: Notes — applicable targets, optional messages - section 四/IV: Exercise topics and d2x checker command - section 五/V: External resources Exercise: 0. Mark a deprecated function and verify it still works. 2 D2X_YOUR_ANSWER. Build wiring: - register 07 target in dslings/cpp14, dslings/en/cpp14, solutions/cpp14 - add 07 entry to zh/en SUMMARY.md
1 parent 1c37ddd commit 46d03b7

10 files changed

Lines changed: 264 additions & 0 deletions

File tree

‎book/en/src/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
# C++14 Core Language Features
3232

3333
- [Generic Lambdas](./cpp14/00-generic-lambdas.md)
34+
- [deprecated Attribute](./cpp14/07-deprecated-attribute.md)
3435

3536
# Additional Resources
3637

‎book/en/src/cpp14/07-deprecated-attribute.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
<div align=right>
2+
3+
🌎 [中文] | [English]
4+
</div>
5+
6+
[中文]: ../../cpp14/07-deprecated-attribute.html
7+
[English]: ./07-deprecated-attribute.html
8+
9+
# deprecated Attribute
10+
11+
C++14 introduces the `[[deprecated]]` attribute to mark deprecated functions, classes, or variables, producing compile-time warnings
12+
13+
| Book | Video | Code | X |
14+
| --- | --- | --- | --- |
15+
| [cppreference-attribute](https://en.cppreference.com/w/cpp/language/attributes) / [markdown](https://github.com/mcpp-community/d2mcpp/blob/main/book/en/src/cpp14/07-deprecated-attribute.md) | [Video Explanation]() | [Exercise Code](https://github.com/mcpp-community/d2mcpp/blob/main/dslings/en/cpp14/07-deprecated-attribute-0.cpp) | |
16+
17+
18+
**Why introduced?**
19+
20+
- Before C++11, there was no standard way to mark deprecated APIs — only documentation or non-standard `#warning`
21+
- `[[deprecated]]` produces warnings at compile time that callers cannot ignore
22+
23+
## I. Basic Usage and Scenarios
24+
25+
```cpp
26+
[[deprecated("Use new_api() instead")]]
27+
void old_api() { }
28+
29+
[[deprecated]]
30+
int legacy_value = 42;
31+
32+
void modern_code() {
33+
old_api(); // warning: old_api is deprecated
34+
int x = legacy_value; // warning: legacy_value is deprecated
35+
}
36+
```
37+
38+
## II. Real-World Case — [[deprecated]] in the STL
39+
40+
> The MSVC STL wraps `[[deprecated]]` in macros for deprecation warnings on obsolete headers. The example below cites the vendored [MSVC STL](https://github.com/mcpp-community/d2mcpp/tree/main/msvc-stl) (source: [`msvc-stl/stl/inc/yvals_core.h`](https://github.com/mcpp-community/d2mcpp/blob/main/msvc-stl/stl/inc/yvals_core.h#L1057-L1061))
41+
42+
```cpp
43+
// MSVC STL · msvc-stl/stl/inc/yvals_core.h (abridged)
44+
#define _CXX17_DEPRECATE_C_HEADER \
45+
[[deprecated("warning STL4004: " \
46+
"<ccomplex>, <cstdalign>, <cstdbool>, and <ctgmath> " \
47+
"are deprecated in C++17.")]]
48+
```
49+
50+
## III. Notes
51+
52+
- Can mark: functions, classes, variables, enums, using aliases
53+
- Message string is optional but recommended
54+
- Deprecated does not mean removed — the compiler still generates code
55+
56+
## IV. Exercise Code
57+
58+
### Exercise Topics
59+
60+
- 0 - [[[deprecated]] Attribute — Marking Deprecated Functions](https://github.com/mcpp-community/d2mcpp/blob/main/dslings/en/cpp14/07-deprecated-attribute-0.cpp)
61+
62+
### Auto-Checker Command
63+
64+
```
65+
d2x checker deprecated-attribute
66+
```
67+
68+
## V. Other
69+
70+
- [Discussion Forum](https://forum.d2learn.org/category/20)
71+
- [d2mcpp Tutorial Repository](https://github.com/mcpp-community/d2mcpp)
72+
- [Tutorial Video List](https://space.bilibili.com/65858958/lists/5208246)
73+
- [Tutorial Support Tool - xlings](https://github.com/openxlings/xlings)

‎book/src/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
# C++14核心语言特性
3232

3333
- [泛型 lambda - generic lambdas](./cpp14/00-generic-lambdas.md)
34+
- [deprecated 属性 - deprecated attribute](./cpp14/07-deprecated-attribute.md)
3435

3536
# 其他
3637

‎book/src/cpp14/07-deprecated-attribute.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
<div align=right>
2+
3+
🌎 [中文] | [English]
4+
</div>
5+
6+
[中文]: ./07-deprecated-attribute.html
7+
[English]: ../en/cpp14/07-deprecated-attribute.html
8+
9+
# deprecated 属性
10+
11+
C++14 引入 `[[deprecated]]` 属性, 允许标记废弃的函数、类或变量, 编译时产生警告
12+
13+
| Book | Video | Code | X |
14+
| --- | --- | --- | --- |
15+
| [cppreference-attribute](https://en.cppreference.com/w/cpp/language/attributes) / [markdown](https://github.com/mcpp-community/d2mcpp/blob/main/book/src/cpp14/07-deprecated-attribute.md) | [视频解读]() | [练习代码](https://github.com/mcpp-community/d2mcpp/blob/main/dslings/cpp14/07-deprecated-attribute-0.cpp) | |
16+
17+
18+
**为什么引入?**
19+
20+
- C++11 之前没有标准方式标记废弃 API, 只能靠文档或 `#warning` 等非标准手段
21+
- `[[deprecated]]` 在编译期产生警告, 调用方无法忽略, 比注释或文档更有效
22+
23+
## 一、基础用法和场景
24+
25+
```cpp
26+
[[deprecated("Use new_api() instead")]]
27+
void old_api() { }
28+
29+
[[deprecated]]
30+
int legacy_value = 42;
31+
32+
void modern_code() {
33+
old_api(); // 编译器警告: old_api is deprecated
34+
int x = legacy_value; // 编译器警告: legacy_value is deprecated
35+
}
36+
```
37+
38+
## 二、真实案例 - STL 中的 [[deprecated]]
39+
40+
> MSVC STL 使用 `[[deprecated]]` 包装废弃头文件和 API 的警告宏。下面以仓库内置的 [MSVC STL](https://github.com/mcpp-community/d2mcpp/tree/main/msvc-stl) 为例 (源码: [`msvc-stl/stl/inc/yvals_core.h`](https://github.com/mcpp-community/d2mcpp/blob/main/msvc-stl/stl/inc/yvals_core.h#L1057-L1061))
41+
42+
```cpp
43+
// MSVC STL · msvc-stl/stl/inc/yvals_core.h (有删节)
44+
#define _CXX17_DEPRECATE_C_HEADER \
45+
[[deprecated("warning STL4004: " \
46+
"<ccomplex>, <cstdalign>, <cstdbool>, and <ctgmath> " \
47+
"are deprecated in C++17.")]]
48+
```
49+
50+
STL 将 `[[deprecated]]` 封装成宏, 在编译期对使用废弃 C 头文件的代码产生标准警告, 用户可借此提前迁移
51+
52+
## 三、注意事项
53+
54+
- 可标记: 函数、类、变量、枚举、using 别名
55+
- 消息字符串可选但推荐
56+
- 废弃不等于删除 — 编译器仍正常生成代码
57+
58+
## 四、练习代码
59+
60+
### 练习代码主题
61+
62+
- 0 - [[[deprecated]] 属性 — 标记废弃函数](https://github.com/mcpp-community/d2mcpp/blob/main/dslings/cpp14/07-deprecated-attribute-0.cpp)
63+
64+
### 练习代码自动检测命令
65+
66+
```
67+
d2x checker deprecated-attribute
68+
```
69+
70+
## 五、其他
71+
72+
- [交流讨论](https://forum.d2learn.org/category/20)
73+
- [d2mcpp教程仓库](https://github.com/mcpp-community/d2mcpp)
74+
- [教程视频列表](https://space.bilibili.com/65858958/lists/5208246)
75+
- [教程支持工具-xlings](https://github.com/openxlings/xlings)

‎dslings/cpp14/07-deprecated-attribute-0.cpp‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// d2mcpp: https://github.com/mcpp-community/d2mcpp
2+
// license: Apache-2.0
3+
// file: dslings/cpp14/07-deprecated-attribute-0.cpp
4+
//
5+
// Exercise/练习: cpp14 | 07 - deprecated attribute | [[deprecated]]
6+
//
7+
// Tips/提示:
8+
// - [[deprecated("message")]] 标记废弃的函数/变量
9+
// - 调用时编译器产生警告
10+
//
11+
// Docs/文档:
12+
// - https://en.cppreference.com/w/cpp/language/attributes
13+
// - https://github.com/mcpp-community/d2mcpp/blob/main/book/src/cpp14/07-deprecated-attribute.md
14+
//
15+
// 练习交流讨论: http://forum.d2learn.org/category/20
16+
//
17+
// Auto-Checker/自动检测命令:
18+
//
19+
// d2x checker deprecated-attribute
20+
//
21+
22+
#include <d2x/cpp/common.hpp>
23+
24+
[[deprecated("Use new_add")]]
25+
D2X_YOUR_ANSWER old_add(int a, int b) { return a + b; }
26+
27+
int new_add(int a, int b) { return a + b; }
28+
29+
int main() {
30+
31+
int r = old_add(10, 20);
32+
d2x_assert_eq(r, D2X_YOUR_ANSWER);
33+
34+
D2X_WAIT
35+
36+
return 0;
37+
}

‎dslings/cpp14/xmake.lua‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,9 @@ target("cpp14-00-generic-lambdas-0")
99
target("cpp14-00-generic-lambdas-1")
1010
set_kind("binary")
1111
add_files("00-generic-lambdas-1.cpp")
12+
13+
-- target: cpp14-07-deprecated-attribute
14+
15+
target("cpp14-07-deprecated-attribute-0")
16+
set_kind("binary")
17+
add_files("07-deprecated-attribute-0.cpp")

‎dslings/en/cpp14/07-deprecated-attribute-0.cpp‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// d2mcpp: https://github.com/mcpp-community/d2mcpp
2+
// license: Apache-2.0
3+
// file: dslings/en/cpp14/07-deprecated-attribute-0.cpp
4+
//
5+
// Exercise: cpp14 | 07 - deprecated attribute | [[deprecated]]
6+
//
7+
// Tips:
8+
// - [[deprecated("message")]] marks deprecated functions/variables
9+
// - The compiler produces a warning on use
10+
//
11+
// Docs:
12+
// - https://en.cppreference.com/w/cpp/language/attributes
13+
// - https://github.com/mcpp-community/d2mcpp/blob/main/book/en/src/cpp14/07-deprecated-attribute.md
14+
//
15+
// Discussion Forum: http://forum.d2learn.org/category/20
16+
//
17+
// Auto-Checker:
18+
//
19+
// d2x checker deprecated-attribute
20+
//
21+
22+
#include <d2x/cpp/common.hpp>
23+
24+
[[deprecated("Use new_add")]]
25+
D2X_YOUR_ANSWER old_add(int a, int b) { return a + b; }
26+
27+
int new_add(int a, int b) { return a + b; }
28+
29+
int main() {
30+
31+
int r = old_add(10, 20);
32+
d2x_assert_eq(r, D2X_YOUR_ANSWER);
33+
34+
D2X_WAIT
35+
36+
return 0;
37+
}

‎dslings/en/cpp14/xmake.lua‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,9 @@ target("cpp14-00-generic-lambdas-0")
99
target("cpp14-00-generic-lambdas-1")
1010
set_kind("binary")
1111
add_files("00-generic-lambdas-1.cpp")
12+
13+
-- target: cpp14-07-deprecated-attribute
14+
15+
target("cpp14-07-deprecated-attribute-0")
16+
set_kind("binary")
17+
add_files("07-deprecated-attribute-0.cpp")

‎solutions/cpp14/07-deprecated-attribute-0.cpp‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// d2mcpp: https://github.com/mcpp-community/d2mcpp
2+
// license: Apache-2.0
3+
// reference solution for: dslings/cpp14/07-deprecated-attribute-0.cpp
4+
//
5+
// 用途: 仅给 CI 与维护者参考使用，不是教程入口。
6+
// 教程练习入口: dslings/cpp14/07-deprecated-attribute-0.cpp
7+
//
8+
9+
#include <d2x/cpp/common.hpp>
10+
11+
[[deprecated("Use new_add")]]
12+
int old_add(int a, int b) { return a + b; }
13+
14+
int new_add(int a, int b) { return a + b; }
15+
16+
int main() {
17+
18+
int r = old_add(10, 20);
19+
d2x_assert_eq(r, 30);
20+
21+
return 0;
22+
}

‎solutions/cpp14/xmake.lua‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,9 @@ target("cpp14-00-generic-lambdas-0-ref")
99
target("cpp14-00-generic-lambdas-1-ref")
1010
set_kind("binary")
1111
add_files("00-generic-lambdas-1.cpp")
12+
13+
-- target: cpp14-07-deprecated-attribute
14+
15+
target("cpp14-07-deprecated-attribute-0-ref")
16+
set_kind("binary")
17+
add_files("07-deprecated-attribute-0.cpp")

0 commit comments

Comments
 (0)