Difference between revisions of "cpp/language/attributes/deprecated"

Latest revision as of 11:41, 12 August 2024

Indicates that the name or entity declared with this attribute is deprecated, that is, the use is allowed, but discouraged for some reason.

(non-member) variable, e.g., [[deprecated]] int x;,
static data member, e.g., struct S { [[deprecated]] static constexpr char CR{13}; };,
non-static data member, e.g., union U { [[deprecated]] int n; };,
function, e.g., [[deprecated]] void f();,
namespace, e.g., namespace [[deprecated]] NS { int x; },
enumeration, e.g., enum [[deprecated]] E {};,

enumerator, e.g., enum { A [[deprecated]], B [[deprecated]] = 42 };,

(since C++17)

template specialization, e.g., template<> struct [[deprecated]] X<int> {};.

A name declared non-deprecated may be redeclared deprecated. A name declared deprecated cannot be un-deprecated by redeclaring it without this attribute.

[edit] Example

Run this code

#include <iostream>
 
[[deprecated]]
void TriassicPeriod()
{
    std::clog << "Triassic Period: [251.9 - 208.5] million years ago.\n";
}
 
[[deprecated("Use NeogenePeriod() instead.")]]
void JurassicPeriod()
{
    std::clog << "Jurassic Period: [201.3 - 152.1] million years ago.\n";
}
 
[[deprecated("Use calcSomethingDifferently(int).")]]
int calcSomething(int x)
{
    return x * 2;
}
 
int main()
{
    TriassicPeriod();
    JurassicPeriod();
}

Possible output:

Triassic Period: [251.9 - 208.5] million years ago.
Jurassic Period: [201.3 - 152.1] million years ago.
 
main.cpp:20:5: warning: 'TriassicPeriod' is deprecated [-Wdeprecated-declarations]
    TriassicPeriod();
    ^
main.cpp:3:3: note: 'TriassicPeriod' has been explicitly marked deprecated here
[[deprecated]]
  ^
main.cpp:21:5: warning: 'JurassicPeriod' is deprecated: Use NeogenePeriod() instead ⮠
 [-Wdeprecated-declarations]
    JurassicPeriod();
    ^
main.cpp:8:3: note: 'JurassicPeriod' has been explicitly marked deprecated here
[[deprecated("Use NeogenePeriod() instead")]]
  ^
2 warnings generated.

[edit] References

C++23 standard (ISO/IEC 14882:2024):

9.12.5 Deprecated attribute [dcl.attr.deprecated]

C++20 standard (ISO/IEC 14882:2020):

9.12.4 Deprecated attribute [dcl.attr.deprecated]

C++17 standard (ISO/IEC 14882:2017):

10.6.4 Deprecated attribute [dcl.attr.deprecated]

C++14 standard (ISO/IEC 14882:2014):

7.6.5 Deprecated attribute [dcl.attr.deprecated]

[edit] See also

C documentation for deprecated

@@ Line 1: / Line 1: @@
-{{cpp/attribute/title|deprecated}}
+{{cpp/language/attributes/title|deprecated|notes={{mark since c++14}}}}
-{{cpp/attribute/navbar}}
+{{cpp/language/attributes/navbar}}
-Indicates that the use of the name or entity declared with this attribute is allowed, but discouraged for some reason.
+Indicates that the name or entity declared with this attribute is [[enwiki:Deprecation|deprecated]], that is, the use is allowed, but discouraged for some reason.
 ===Syntax===
 {{sdsc begin}}
 {{sdsc|num=1|1=
-{{spar|class-key}} {{ttb|<nowiki>[[</nowiki>deprecated}}{{spar|reason}}{{mark optional}}{{ttb|<nowiki>]]</nowiki>}} {{spar|class-name}} {{ttb|;}}
+{{ttb|{{c/core|[[deprecated]]}}}}
 }}
 {{sdsc|num=2|1=
-{{spar|class-key}} {{ttb|<nowiki>[[</nowiki>deprecated}}{{spar|reason}}{{mark optional}}{{ttb|<nowiki>]]</nowiki>}} {{spar|class-name}} {{spar|final}}{{mark optional}} {{spar|base-clause}}{{mark optional}} {{ttb|{}} {{spar|member-specification}} {{ttb|} }}
+{{ttb|<nowiki>[[</nowiki>deprecated(}} {{spar|string-literal}} {{ttb|)<nowiki>]]</nowiki>}}
-}}
-{{sdsc|num=3|1=
-{{ttb|using}} {{spar|identifier}} {{ttb|<nowiki>[[</nowiki>deprecated}}{{spar|reason}}{{mark optional}}{{ttb|<nowiki>]]</nowiki>}} {{ttb|{{=}}}} {{spar|defining-type-id}} {{ttb|;}}
-}}
-{{sdsc|num=4|1=
-{{ttb|<nowiki>[[</nowiki>deprecated}}{{spar|reason}}{{mark optional}}{{ttb|<nowiki>]]</nowiki>}} {{spar|declaration}}
-}}
-{{sdsc|num=5|1=
-{{spar|declarator-id}} {{ttb|<nowiki>[[</nowiki>deprecated}}{{spar|reason}}{{mark optional}}{{ttb|<nowiki>]]</nowiki>}}
-}}
-{{sdsc|num=6|1=
-{{ttb|inline}}{{mark optional}} {{ttb|namespace}} {{ttb|<nowiki>[[</nowiki>deprecated}}{{spar|reason}}{{mark optional}}{{ttb|<nowiki>]]</nowiki>}} {{spar|name}} {{ttb|{}} {{spar|namespace-body}} {{ttb|} }}
-}}
-{{sdsc|num=7|1=
-{{spar|enum-key}} {{ttb|<nowiki>[[</nowiki>deprecated}}{{spar|reason}}{{mark optional}}{{ttb|<nowiki>]]</nowiki>}} {{spar|enumeration-name}} {{spar|enum-base}}{{mark optional}} {{ttb|;}}
-}}
-{{sdsc|num=8|1=
-{{spar|enum-key}} {{ttb|<nowiki>[[</nowiki>deprecated}}{{spar|reason}}{{mark optional}}{{ttb|<nowiki>]]</nowiki>}} {{spar|enumeration-name}} {{spar|enum-base}}{{mark optional}} {{ttb|{}} {{spar|enumerator-list}} {{ttb|} }}
-}}
-{{sdsc|num=9|1=
-{{spar|enumerator}} {{ttb|<nowiki>[[</nowiki>deprecated}}{{spar|reason}}{{mark optional}}{{ttb|<nowiki>]]</nowiki>}}
 }}
 {{sdsc end}}
-{{spar|reason}}, if present, has the form {{ttb|(}} {{spar|string-literal}} {{ttb|)}}.
+{{par begin}}
+{{par|{{spar|string-literal}}|an [[cpp/language/string literal#Unevaluated strings|unevaluated string literal]] that could be used to explain the rationale for deprecation and/or to suggest a replacing entity}}
+{{par end}}
 ===Explanation===
-Indicates that the use of the name or entity declared with this attribute is allowed, but discouraged for some reason.
+Indicates that the use of the name or entity declared with this attribute is allowed, but discouraged for some reason. Compilers typically issue warnings on such uses. The {{spar|string-literal}}, if specified, is usually included in the warnings.
-This attribute is allowed in declarations of classes, typedef-names, variables, non-static data members, functions, namespaces, enumerations, enumerators, and template specializations.
+This attribute is allowed in declarations of the following names or entities:
+* [[cpp/language/classes|class/struct/union]], e.g., {{c|struct [[deprecated]] S;}},
+* [[cpp/language/typedef|typedef-name]], including those declared by [[cpp/language/type_alias|alias declaration]], e.g.,
+:* {{c|[[deprecated]] typedef S* PS;}},
+:* {{c|1=using PS [[deprecated]] = S*;}},
+* (non-member) variable, e.g., {{c|[[deprecated]] int x;}},
+* [[cpp/language/static|static data member]], e.g., {{c|struct S { [[deprecated]] static constexpr char CR{13}; };}},
+* [[cpp/language/data members|non-static data member]], e.g., {{c|union U { [[deprecated]] int n; };}},
+* {{lt|cpp/language/function}}, e.g., {{c|[[deprecated]] void f();}},
+* {{lt|cpp/language/namespace}}, e.g., {{c|namespace [[deprecated]] NS { int x; }<!---->}},
+* [[cpp/language/enum|enumeration]], e.g., {{c|enum [[deprecated]] E {};}},
+{{rrev|since=c++17|1=
+* enumerator, e.g., {{c|1=enum { A [[deprecated]], B [[deprecated]] = 42 };}},
+}}
+* {{lt|cpp/language/template specialization}}, e.g., {{c|template<> struct [[deprecated]] X<int> {};}}.
 A name declared non-deprecated may be redeclared deprecated. A name declared deprecated cannot be un-deprecated by redeclaring it without this attribute.
@@ Line 47: / Line 43: @@
 {{example
 |code=
+#include <iostream>
+[[deprecated]]
+void TriassicPeriod()
+{
+    std::clog << "Triassic Period: [251.9 - 208.5] million years ago.\n";
+}
+[[deprecated("Use NeogenePeriod() instead.")]]
+void JurassicPeriod()
+{
+    std::clog << "Jurassic Period: [201.3 - 152.1] million years ago.\n";
+}
+[[deprecated("Use calcSomethingDifferently(int).")]]
+int calcSomething(int x)
+{
+    return x * 2;
+}
+int main()
+{
+    TriassicPeriod();
+    JurassicPeriod();
+}
+|p=true
+|output=
+Triassic Period: [251.9 - 208.5] million years ago.
+Jurassic Period: [201.3 - 152.1] million years ago.
+main.cpp:20:5: warning: 'TriassicPeriod' is deprecated [-Wdeprecated-declarations]
+    TriassicPeriod();
+    ^
+main.cpp:3:3: note: 'TriassicPeriod' has been explicitly marked deprecated here
+[[deprecated]]
+  ^
+main.cpp:21:5: warning: 'JurassicPeriod' is deprecated: Use NeogenePeriod() instead ⮠
+ [-Wdeprecated-declarations]
+    JurassicPeriod();
+    ^
+main.cpp:8:3: note: 'JurassicPeriod' has been explicitly marked deprecated here
+[[deprecated("Use NeogenePeriod() instead")]]
+  ^
+warnings generated.
 }}
-{{langlinks|ja|zh}}
+===References===
+{{ref std c++23}}
+{{ref std|section=9.12.5|title=Deprecated attribute|id=dcl.attr.deprecated}}
+{{ref std end}}
+{{ref std c++20}}
+{{ref std|section=9.12.4|title=Deprecated attribute|id=dcl.attr.deprecated}}
+{{ref std end}}
+{{ref std c++17}}
+{{ref std|section=10.6.4|title=Deprecated attribute|id=dcl.attr.deprecated}}
+{{ref std end}}
+{{ref std c++14}}
+{{ref std|section=7.6.5|title=Deprecated attribute|id=dcl.attr.deprecated}}
+{{ref std end}}
+===See also===
+{{dsc begin}}
+{{dsc see c|c/language/attributes/deprecated}}
+{{dsc end}}
+{{langlinks|es|ja|ru|zh}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

assume (C++23)
carries_dependency (C++11)
deprecated (C++14)
fallthrough (C++17)
indeterminate (C++26)
likely (C++20)
maybe_unused (C++17)
nodiscard (C++17)
noreturn (C++11)
no_unique_address (C++20)
optimize_for_synchronized (TM TS)
unlikely (C++20)


`[[deprecated]]`	(1)

`[[deprecated(` string-literal `)]]`	(2)

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/language/attributes/deprecated"

Latest revision as of 11:41, 12 August 2024

Contents

[edit] Syntax

[edit] Explanation

[edit] Example

[edit] References

[edit] See also

Navigation

Toolbox