From c553535fb8dda2839d13ab5f807ffbc66b63d67b Mon Sep 17 00:00:00 2001 From: Bjarne Stroustrup Date: Mon, 18 Jul 2016 21:10:52 -0400 Subject: [PATCH] fixing typos adding "concept" markers, hopefully to minimize confusion --- CppCoreGuidelines.md | 58 ++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/CppCoreGuidelines.md b/CppCoreGuidelines.md index 9a9b9ce..7e31ee3 100644 --- a/CppCoreGuidelines.md +++ b/CppCoreGuidelines.md @@ -10694,7 +10694,7 @@ Application concepts are easier to reason about. ??? -###### Note +##### Note With the exception of `async()`, the standard-library facilities are low-level, machine-oriented, threads-and-lock level. This is a necessary foundation, but we have to try to raise the level of abstrcation: for productivity, for reliability, and for performance. @@ -11117,7 +11117,7 @@ A `thread` that has not been `detach()`ed when it is destroyed terminates the pr ### CP.30: Do not pass pointers to local variables to non-`raii_thread's -###### Reason +##### Reason In general, you cannot know whether a non-`raii_thread` will outlife your thread (so that those pointers will become invalid. @@ -11264,7 +11264,7 @@ Instead, we could have a set of pre-created worker threads processing the messag raii_thread w4 {worker}; } -###### Note +##### Note If you system has a good thread pool, use it. If your system has a good message queue, use it. @@ -11662,11 +11662,11 @@ For example, reading `clock` twice will often yield two different values, so the `clock` is `const` because the program should not try to write to `clock`. -###### Note +##### Note Unless you are writing the lowest level code manipulating hardware directly, consider `volatile` an esoteric feature that is best avoided. -###### Example +##### Example Usually C++ code receives `volatile` memory that is owned Elsewhere (hardware or another language): @@ -12462,7 +12462,7 @@ For example: One reason to prefer a specific return type is to have names for its members, rather than the somewhat cryptic `first` and `second` and to avoid confusion with other uses of `std::pair`. -###### Example +##### Example In general, you must clean up before an error exit. This can be messy: @@ -13081,18 +13081,18 @@ Flag template type arguments without concepts ##### Reason - "Standard" concepts (as provided by the [GSL]#S-GSL), the ISO concepts TS, [Ranges TS](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/n4569.pdf), and hopefully soon the ISO standard itself) + "Standard" concepts (as provided by the [GSL](#S-GSL) and the [Ranges TS](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/n4569.pdf), and hopefully soon the ISO standard itself) saves us the work of thinking up our own concepts, are better thought out than we can manage to do in a hurry, and improves interoperability. ##### Note Unless you are creating a new generic library, most of the concepts you need will already be defined by the standard library. -##### Example, bad +##### Example (using TS concepts) - concept - // don't define this: Sortable is in the GSL - Ordered_container = Sequence && Random_access> && Ordered>; + template + // don't define this: Sortable is in the GSL + concept Ordered_container = Sequence && Random_access> && Ordered>; void sort(Ordered_container& s); @@ -13104,7 +13104,7 @@ It is better and simpler just to use `Sortable`: ##### Note -The set of "standard" concepts is evolving as we approach real (ISO) standardization. +The set of "standard" concepts is evolving as we approach an ISO standard including concepts. ##### Note @@ -13123,11 +13123,11 @@ Hard. `auto` is the weakest concept. Concept names convey more meaning than just `auto`. -##### Example +##### Example (using TS concepts) vector v; auto& x = v.front(); // bad - String& s = v.begin(); // good + String& s = v.begin(); // good (String is a GSL concept) ##### Enforcement @@ -13139,7 +13139,7 @@ Hard. Readability. Direct expression of an idea. -##### Example +##### Example (using TS concepts) To say "`T` is `Sortable`": @@ -13185,7 +13185,7 @@ Concepts are meant to express semantic notions, such as "a number", "a range" of Simple constraints, such as "has a `+` operator" and "has a `>` operator" cannot be meaningfully specified in isolation and should be used only as building blocks for meaningful concepts, rather than in user code. -##### Example, bad +##### Example, bad (using TS concepts) template concept Addable = has_plus; // bad; insufficient @@ -13256,9 +13256,9 @@ Helps implementers and maintainers. This is a specific variant of the gerenral rule that [a concept mist make semantic sense](#Rt-low). -##### Example, bad +##### Example, bad (using TS concepts) - template Subtractable = requires(T a, T, b) { a-b; }; + template concept Subtractable = requires(T a, T, b) { a-b; }; This makes no semantic sense. You need at least `+` to make `-` meaningful and useful. @@ -13342,7 +13342,7 @@ A meaningful/useful concept has a semantic meaning. Expressing these semantics in an informal, semi-formal, or formal way makes the concept comprehensible to readers and the effort to express it can catch conceptual errors. Specifying semantics is a powerful design tool. -##### Example +##### Example (using TS concepts) template // The operators +, -, *, and / for a number are assumed to follow the usual mathematical rules @@ -13371,7 +13371,7 @@ Once language support is available, the `//` in front of the axiom can be remove The GSL concepts have well defined semantics; see the Palo Alto TR and the Ranges TS. -##### Exception +##### Exception (using TS concepts) Early versions of a new "concept" still under development will often just define simple sets of constraints without a well-specified semantics. Finding good semantics can take effort and time. @@ -13403,7 +13403,7 @@ Each new use case may require such an incomplete concepts to be improved. Otherwise they cannot be distinguished automatically by the compiler. -##### Example +##### Example (using TS concepts) template concept bool Input_iter = requires (I iter) { ++iter; }; @@ -13426,7 +13426,7 @@ If two concepts have exactly the same requirements, they are logically equivalen Two concepts requiring the same syntax but having different semantics leads to ambiguity unless the programmer differentiates them. -##### Example +##### Example (using TS concepts) template // iterator providing random access concept bool RA_iter = ...; @@ -13439,7 +13439,7 @@ The programmer (in a library) must define `is_contiguous` (a trait) appropriatel Wrapping a tag class into a concept leads to a simpler expression of this idea: - concept Contiguous = is_contiguous::value; + template concept Contiguous = is_contiguous::value; template concept bool Contiguous_iter = RA_iter && Contiguous; @@ -13464,7 +13464,7 @@ Prefer the standard-library ones. Clarity. Maintainability. Functions with complementary requirements expressed using negation are brittle. -##### Example +##### Example (using TS concepts) Initially, people will try to define functions with complementary requirements: @@ -13506,7 +13506,7 @@ The compiler will select the overload and emit an appropriate error. The definition is more readable and corresponds directly to what a user has to write. Conversions are taken into account. You don't have to remember the names of all the type traits. -##### Example, bad +##### Example (using TS concepts) You might be tempted to define a concept `Equality` like this: @@ -13539,7 +13539,7 @@ However, the interface to a template is a critical concept - a contract between Function objects can carry more information through an interface than a "plain" pointer to function. In general, passing function objects gives better performance than passing pointers to functions. -##### Example +##### Example (using TS concepts) bool greater(double x, double y) { return x > y; } sort(v, greater); // pointer to function: potentially slow @@ -13576,7 +13576,7 @@ The performance argument depends on compiler and optimizer technology. Keep interfaces simple and stable. -##### Example +##### Example (using TS concepts) Consider, a `sort` instrumented with (oversimplified) simple debug support: @@ -13601,7 +13601,7 @@ Should this be rewritten to: After all, there is nothing in `Sortable` that requires `iostream` support. On the other hand, there is nothing in the fundamental idea of sorting that says anything about debugging. -###### Note +##### Note If we require every operation used to be listed among the requirements, the interface becomes unstable: every time we change the debug facilities, the usage data gathering, testing support, error reporting, etc. @@ -16387,7 +16387,7 @@ It's verbose and only needed where C compatibility matters. void g(); // better -###### Note +##### Note Even Dennis Ritchie deemed `void f(void)` an abomination. You can make an argument for that abomination in C when function prototypes were rare so that banning: