[Tip] How to Reference the C++ Standard or a Proposal
Table of Contents
You’re writing a document about C++, one feature or some cool programming technique. At one point you think that you have to prove that something works and that’s why you need to quote text from the Standard. How to do it?
Referencing the C++ Standard, or maybe a proposal might be quite confusing. Where can you find the latest documents and papers and how to link to them efficiently?
In this blog post, I’d share with you some useful tips, links and tools that will help you with this task.
Firstly, let’s start with a set of useful links.
- https://isocpp.org/ - set it to your home page! This is the main page of all C++ relevant information, news, standardization, tools, conferences, training, books and more.
- https://isocpp.org/std/the-standard - this page describes the current official and published ISO standard. It mentions the drafts of the upcoming standard.
- https://isocpp.org/std/status - current status of the language and the library, merging of TS (technical specifications), larger features.
- https://isocpp.org/std/the-life-of-an-iso-proposal - how to submit a proposal to the committee and how each paper evolves, is merged into the Standard or is rejected.
- https://github.com/cplusplus/draft - current official draft of the Standard
- https://github.com/timsong-cpp/cppwp - several Standards, also the current working draft but compiled from the official ISO repository into a nice-looking HTML or PDF!
- http://eel.is/c++draft/ - another handy site, with HTML of the current draft
- https://en.cppreference.com/w/cpp/compiler_support - C++ compiler support
- Where can you get the ISO C++ standard, and what does “open standard” mean? – Sutter’s Mill
Referencing to the Standard
Let’s say you want to describe closure type of a lambda. You know that in C++17 the closure type has no default constructor. You need to find the page from the Standard where such lambda behaviour is specified.
You can find the paragraph in the official ISO Specification. That’s the correct way (if your document is also official, then it might be best to buy the ISO Spec). But if you don’t want to pay for the official paper, you can use drafts. While they might contain some differences vs the final Specification (especially some minor changes and editorials), it might be good enough for most of the purposes.
One way to reference the spec is from the latest draft. You might use services like using timsong-cpp.github.io or eel.is, and you see that in section 18.104.22.168 Closure types #13 there’s:
The closure type associated with a lambda-expression has no default constructor if the lambda-expression has a lambda-capture and a defaulted default constructor otherwise.
So there’s a default constructor in some cases!
What’s wrong here?
The ongoing changes for C++20! (and you wanted C++17 state)
How to fix this?
You need to reference “frozen” C++ standard. The official github repo doesn’t have revisions, but you can do it with timsong-cpp. It lists several important revisions:
You can also use wg21.link service (returns PDFs):
- https://wg21.link/std11 - C++11
- https://wg21.link/std14 - C++14
- https://wg21.link/std17 - C++17
- https://wg21.link/std - current working draft
For our example with lambdas, we can go to C++17’s latest draft - N4659 and then reference the following section:
The closure type associated with a lambda-expression has no default constructor and a deleted copy assignment operator.
Now you’re fine
Additionally it might be handy to reference the name of the section (like
[expr.prim.lambda.capture]), rather than its number (
22.214.171.124 Captures). Names don’t change that often, but numbers might.
[tip]: Don’t reference to draft as it might change, it’s best to select a published C++ version (or a final draft before publication).
Referencing to a Proposal
Proposals are documents that describe some feature that might potentially be merged into the final Standard. It evolves according to the support from the Committee.
Many papers can be rejected, of course.
Where can you find them?
At isocpp.org there are mailings that are published before each (and after) ISO Meetings.
You can reference papers that “live” and are actively discussed at meetings.
For example, here’s a mailing from the last meeting (Kona 2019):
- Papers 2019
- post-Kona mailing available
Changes && Compiler Support
Another way to find a paper with a feature is through a list of C++ supported features. That way you can find a paper for an already merged feature.
You can use C++ compiler support - cppreference.com that contains long list of various C++ features. Similar lists can be found for GCC, Clang, and MSVC respectively.
Recently, for C++17, we also have a paper that describes all the changes, with the papers that were merged:
To sum up:
I showed you at least two sources where you can find a proposal.
Should you use that long URL starting with http://www.open-std.org/jtc1 ? Is there a better way?
As you see, linking to papers might be confusing.
But there’s a handy tool that might help.
Have a look:
Just use https://wg21.link/ (there’s a description of that linking service there)
Basically, you need to select a paper number, for example, P0636 (C++17 changes) and then put that after https://wg21.link/
you might notice that it pointed to r3 - so the latest version.
I’ve noticed that usually, the first version of the paper shows the motivation and longer descriptions. So if you want to explain a proposal better then you might refer to some earlier version. For a paper that eventually went into the Standard, the latest revisions are mostly smaller changes and wording.
If you want to refer to a selected version of the paper, then provide the full name like P0636r1
[tip]: you can find a paper through ISO mailings (published at isocpp.org) or through C++ compiler support or other lists with C++ changes.
[tip]: use wg21.link system to refer to a paper.
In this post I showed you my ways of linking to the selected C++ Standard that I use for my blog posts. Do you use some other ways? Do you have other resources? Let me know in comments.
- Converting from Boost to std::filesystem
- Dark Corner of C++ Corner Cases
- Lambdas: From C++11 to C++20, Part 2
- C++17 In Detail is 100% Ready!
- Lambdas: From C++11 to C++20, Part 1