diff --git a/config/spellcheck/ignored_words.txt b/config/spellcheck/ignored_words.txt index 40d6c40..94eacd0 100644 --- a/config/spellcheck/ignored_words.txt +++ b/config/spellcheck/ignored_words.txt @@ -1,12 +1,19 @@ args +asm +baz Bjarne +bool checkmark +coe constexpr cppreference Engelhart +enum EPUB errno expr +explorative +extern Florian func Furst @@ -16,8 +23,11 @@ Hyland JC Krathwohl ness +nothrow NRVO +RAII req +Rethrowing RVO Sattler SG diff --git a/config/spellcheck/wordlist b/config/spellcheck/wordlist index 4bcf96a..2a083db 100644 --- a/config/spellcheck/wordlist +++ b/config/spellcheck/wordlist @@ -1,5 +1,6 @@ -personal_ws-1.1 en 18 ABI +API +APIs boolean computable destructors @@ -10,6 +11,7 @@ metaprogramming namespace namespaces ODR +personal_ws-1.1 en 18 preprocessor redeclarations SFINAE diff --git a/sources/knowledge_areas.dat b/sources/knowledge_areas.dat index f3566a8..c1b5677 100644 --- a/sources/knowledge_areas.dat +++ b/sources/knowledge_areas.dat @@ -12,7 +12,8 @@ P Preprocessor ? ? ? ? Macros B Basics Types, Objects, Values, Expressions, Statements, and Control-Flow Constructs ? ? ? ? Constant Objects - ? ? ? ? Declarations and Definitions + ? ? ? ? Declarations + def y y y Definitions ? ? ? ? Selection Constructs (e.g., if, ternary) ? ? ? ? Looping Constructs (e.g., for, while, etc.) F Functions @@ -50,10 +51,10 @@ T Generic Programming (Templates) ? ? ? ? Requires Clauses req-expr y y n Requires Expressions EH Error Handling - ? ? ? ? Classes of Errors + coe y y n Categories of Errors ? ? ? ? errno ? ? ? ? Error Codes - ? ? ? ? Exception Handling + eh y y y Exception Handling SL Standard Library ? ? ? ? Input/Output (I/O) ? ? ? ? Containers, Iterators, and Algorithms diff --git a/sources/modules/compilation-model/linkage.md b/sources/modules/compilation-model/linkage.md new file mode 100644 index 0000000..9c2e96b --- /dev/null +++ b/sources/modules/compilation-model/linkage.md @@ -0,0 +1,6 @@ +## C++ compilation model: Linkage {#linkage} + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/compilation-model/translation-units.md b/sources/modules/compilation-model/translation-units.md new file mode 100644 index 0000000..94141b3 --- /dev/null +++ b/sources/modules/compilation-model/translation-units.md @@ -0,0 +1,6 @@ +## C++ compilation model: Translation units {#translunits} + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/error-handling/c-style-error-codes.md b/sources/modules/error-handling/c-style-error-codes.md new file mode 100644 index 0000000..62dcfe9 --- /dev/null +++ b/sources/modules/error-handling/c-style-error-codes.md @@ -0,0 +1,6 @@ +## Error handling: C-style error codes {#cerrcodes} + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/error-handling/categories-of-errors.md b/sources/modules/error-handling/categories-of-errors.md new file mode 100644 index 0000000..7c66474 --- /dev/null +++ b/sources/modules/error-handling/categories-of-errors.md @@ -0,0 +1,114 @@ +## Error handling: Categories of errors + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +### Overview + +_Provides a short natural language abstract of the module’s contents._ +_Specifies the different levels of teaching._ + +------------------------------------------------------------------------ +Level Objective +----------------- ------------------------------------------------------ +Foundational Categories of errors + +Main Handling different categories of errors + +Advanced --- + +------------------------------------------------------------------------ + +### Motivation + +_Why is this important?_ +_Why do we want to learn/teach this topic?_ + +Programs can run in a normal state or erroneous state. Students should be able +to identify different types of erroneous state and how to best handle them. + +### Topic introduction + +_Very brief introduction to the topic._ + +This topic is an umbrella topic that refers to the different topics for types of errors and error handling. + +### Foundational: Categories of errors {#coe-found} + +#### Background/Required Knowledge + +A student: + +* should know the basics about linkage [[C++ compilation model: Linkage - Foundational]][1] + +#### Student outcomes + +_A list of things "a student should be able to" after the curriculum._ +_The next word should be an action word and testable in an exam._ +_Max 5 items._ + +A student should be able to: + +1. Describe different kinds of errors and exceptional situations that require different approaches of error handling. +2. Provide some examples of the different error categories. +3. Identify potential erroneous code sections and attribute them to different error categories. + + +#### Caveats + +_This section mentions subtle points to understand, like anything resulting in +implementation-defined, unspecified, or undefined behavior._ + +No caveats at present. + +#### Points to cover + +_This section lists important details for each point._ + +Errors can happen at different times during software lifetime. + +* Compile-time errors +* Link-time errors +* Execution-time errors + +There are different types of errors + +* Logic errors (violations of logical preconditions) +* Run-time errors (errors during code execution due to causes that are external to the program) + + +### Main: Handling different categories of errors {#coe-main} + +#### Background/Required Knowledge + +#### Student outcomes + +A student should be able to: + +1. pick the right error handling approach for a given problem. +2. enumerate different error handling strategies. +3. make a clear distinction between error-handling code and normal-case handling code + + +#### Caveats + +* The different error handling strategies have different trade-offs (runtime performance, readability, ...) +* The trade-off space depends on the run-time context (embedded, ...) +* There also exist unhandleable errors (e.g., ODR violations, undefined behavior) + +#### Points to cover + +* Exception handling [[Error handling: Exception handling - Foundational]][2] +* Returning a value indication failure [[Error handling: C-style error-codes - Foundational]][3] +* Terminating the program +* Improving error handling by having the error occur at an earlier stage in the software development cycle [[Error handling: Static assert - Foundational]][4] + +### Advanced {#coe-advanced} + +_These are important topics that are not expected to be covered but provide +guidance where one can continue to investigate this topic in more depth._ + +[1]: ../compilation-model/linkage.md +[2]: ../error-handling/exception-handling.md +[3]: ../error-handling/c-style-error-codes.md +[4]: ../error-handling/static-assert.md diff --git a/sources/modules/error-handling/error-codes.md b/sources/modules/error-handling/error-codes.md new file mode 100644 index 0000000..488f155 --- /dev/null +++ b/sources/modules/error-handling/error-codes.md @@ -0,0 +1,99 @@ +## Error handling: Error codes {#ecodes} + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +### Overview + +_Provides a short natural language abstract of the module’s contents._ +_Specifies the different levels of teaching._ + +------------------------------------------------------------------------ +Level Objective +----------------- ------------------------------------------------------ +Foundational Handling error codes with `std::error_code` + +Main Designing APIs around `std::error_code` + +Advanced --- + +------------------------------------------------------------------------ + +### Motivation + +_Why is this important?_ +_Why do we want to learn/teach this topic?_ + +C++ offers a type safe way of passing around errors, contrary to the C-style of error handling, by this, we prevent bugs when passing error codes. +Furthermore, error handling with error codes is more commonly used than exception handling, which only should be used in exceptional situations and in some environments is not feasible at all, e.g., in embedded or performance critical software. + +### Topic introduction + +_Very brief introduction to the topic._ + +C++ offers `std::error_code`, which encapsulates error codes in a type safe way. +This topic describes how to use these error codes. + +### Foundational: Handling error codes with `std::error_code` {#eh-found} + +#### Background/Required Knowledge + +A student: + +* should know that there are different ways of error handling [[Error handling: Categories of errors]][1] +* should know function return values + +#### Student outcomes + +_A list of things "a student should be able to" after the curriculum._ +_The next word should be an action word and testable in an exam._ +_Max 5 items._ + +A student should be able to: + +1. write code to handle errors with `std::error_code`, e.g., obtain the message of the error code or check if an error occurred. +2. distinguish between the different categories and make justified decisions when to use which + +#### Caveats + +_This section mentions subtle points to understand, like anything resulting in +implementation-defined, unspecified, or undefined behavior._ + +#### Points to cover + +_This section lists important details for each point._ + +* a brief overview of `std::error_code` and how to use it + +### Main: Designing APIs around `std::error_code` {#eh-main} + +#### Background/Required Knowledge + +* should know how to use reference parameters as an output parameter + +#### Student outcomes + +A student should be able to: + +1. create an `error_code` and design API that work with `std:error_code` +2. write code that utilizes `std::error_category` +3. explain the difference between C-style error handling with errno and `std::error_code` +4. make effective use of the interface of `std::error_code` + +#### Caveats + +* reset errno before calling a function that might set errno (better pass an input parameter `std::error_code`) + +#### Points to cover + +* provide a full picture of `std::error_code` and it’s APIs +* `std::error_category` (explorative) + +### Advanced + +_These are important topics that are not expected to be covered but provide +guidance where one can continue to investigate this topic in more depth._ + +* implementing your own `error_category` + +[1]: error-handling/categories-of-errors.md diff --git a/sources/modules/error-handling/exception-handling.md b/sources/modules/error-handling/exception-handling.md new file mode 100644 index 0000000..9f073a4 --- /dev/null +++ b/sources/modules/error-handling/exception-handling.md @@ -0,0 +1,111 @@ +### Overview + +_Provides a short natural language abstract of the module’s contents._ +_Specifies the different levels of teaching._ + +------------------------------------------------------------------------ +Level Objective +----------------- ------------------------------------------------------ +Foundational Standards exception hierarchy + +Main Exception guarantees + +Advanced --- + +------------------------------------------------------------------------ + +### Motivation + +_Why is this important?_ +_Why do we want to learn/teach this topic?_ + +Exception handling is used to be able to continue the program in case of +exceptional situations (like requesting a ridiculous amount of memory: +`bad_alloc`). + +### Topic introduction + +_Very brief introduction to the topic._ + +There are other forms of handling difficult situations, but here we concentrate +on exception handling and the peculiarities/characteristics of it. Because +there are different forms, we should know when to use which type of handling +special situations. + +### Foundational: Standards exception hierarchy {#eh-found} + +#### Background/Required Knowledge + +A student: + +* should know about basic and user-defined types [[Type system: fundamental types]][1] [[Type system: user-defined types]][2] +* should know about flow of control [???] +* should know about blocks and statements [???] + +#### Student outcomes + +_A list of things "a student should be able to" after the curriculum._ +_The next word should be an action word and testable in an exam._ +_Max 5 items._ + +A student should be able to: + +1. Explain how some `std::` calls may cause an exception +2. Discern the different standard exception types +3. Write simple try … except code (e.g., out of memory, vector at indexing) +4. Explain on a “simplified” conceptual level what happens when an exception is thrown and is bubbled up through the callers until it is caught + + +#### Caveats + +_This section mentions subtle points to understand, like anything resulting in +implementation-defined, unspecified, or undefined behavior._ + +* Exceptions should be used for exceptional situations and should not be used to manage normal control flow. + +#### Points to cover + +_This section lists important details for each point._ + +* Exception hierarchy from the standard library +* Common library functions that may throw exceptions +* Basic handling exceptions: try/catch/throw +* How exceptions bubble up until caught + + +### Main: Exception guarantees {#eh-main} + +#### Background/Required Knowledge + +* RAII +* Order of construction/destruction of class members + +#### Student outcomes + +A student should be able to: + +1. Explain the four different exception guarantees +2. Explain the exception guarantees that the standard library containers offer. +3. Explain what happens when a exception is thrown in constructor + + +#### Caveats + +* Make sure code is designed with RAII in mind to prevent resources leaking during exception handling, when the stack is unwound. +* Care should be taken in constructor design to make all fully constructed members deleted when the stack unwinding mechanism is activated. + +#### Points to cover + +* Exception guarantees: Nothrow/Strong/Basic/No +* Rethrowing an exception + +### Advanced: Exception-safe containers and edge cases {#eh-advanced} + +_These are important topics that are not expected to be covered but provide +guidance where one can continue to investigate this topic in more depth._ + +* Rethrowing a modified exception +* Writing exception safe containers + +[1]: ../type-system/fundamental-types.md +[2]: ../type-system/user-defined-types.md \ No newline at end of file diff --git a/sources/modules/error-handling/static-assert.md b/sources/modules/error-handling/static-assert.md new file mode 100644 index 0000000..0bb472f --- /dev/null +++ b/sources/modules/error-handling/static-assert.md @@ -0,0 +1,6 @@ +## Error handling: Static assert {#staticassert} + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/object-model/declarations.md b/sources/modules/object-model/declarations.md index feee753..1a966ab 100644 --- a/sources/modules/object-model/declarations.md +++ b/sources/modules/object-model/declarations.md @@ -1,6 +1,117 @@ -## C++ object model: declarations +## C++ object model: Declarations _Skeleton descriptions are typeset in italic text,_ _so please don't remove these descriptions when editing the topic._ -This topic is currently under construction and will soon be filled with information :) +### Overview + +_Provides a short natural language abstract of the module’s contents._ +_Specifies the different levels of teaching._ + +------------------------------------------------------------------------ +Level Objective +----------------- ------------------------------------------------------ +Foundational Declaring variables + +Main Declaring for programs + +Advanced Special cases and peculiarities + +------------------------------------------------------------------------ + +### Motivation + +_Why is this important?_ +_Why do we want to learn/teach this topic?_ + +* Introduces a name and it’s type +* `int baz;` +* `void bar();` +* `class Foo;` + +### Topic introduction + +_Very brief introduction to the topic._ + +Introduce names and their associated type in a scope. + +### Foundational: Declaring variables + + +#### Background/Required Knowledge + + +A student: + +* is familiar with the basic C++ types: + * bool (Boolean type) + * int (Integer type) + * double (Floating-point type) + +#### Student outcomes + +_A list of things "a student should be able to" after the curriculum._ +_The next word should be an action word and testable in an exam._ +_Max 5 items._ + +A student should be able to: + +1. declare a variable with a specific type ‘int baz;’ +2. declare a function ‘void bar();’ +3. declare a class ‘class Foo;’ +4. forward declare a user-defined type or a function +5. explain the difference between a definition and a declaration + +#### Caveats + +_This section mentions subtle points to understand, like anything resulting in +implementation-defined, unspecified, or undefined behavior._ + +No caveats at present. + +#### Points to cover + +_This section lists important details for each point._ + +### Main: Declarations for programs + + +#### Background/Required Knowledge + + +* All of the above. +* Basic template syntax + +#### Student outcomes + +_A list of things "a student should be able to" after the curriculum._ +_The next word should be an action word and testable in an exam._ +_Max 5 items._ + +A student should be able to: + +1. create header and source files with a declaration in the former and definition of a variable/function in the latter +2. declare type aliases to introduce a type with an alternative name ‘using std::string;’ +3. write a forward template declaration + +#### Caveats + +_This section mentions subtle points to understand, like anything resulting in +implementation-defined, unspecified, or undefined behavior._ + +* Declaring aliases can introduce name clashes +* Prefer using declaration’s over using directives in header files [link] +* The order of declarations dictates the order of initialization + +#### Points to cover + +_This section lists important details for each point._ + +### Advanced + +_These are important topics that are not expected to be covered but provide +guidance where one can continue to investigate this topic in more depth._ + +* asm declaration +* using-enum-declaration +* extern "C" declarations diff --git a/sources/modules/object-model/definitions.md b/sources/modules/object-model/definitions.md new file mode 100644 index 0000000..e0447fa --- /dev/null +++ b/sources/modules/object-model/definitions.md @@ -0,0 +1,115 @@ +## C++ object model: Definitions {#def} + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +### Overview + +_Provides a short natural language abstract of the module’s contents._ +_Specifies the different levels of teaching._ + +------------------------------------------------------------------------ +Level Objective +----------------- ------------------------------------------------------ +Foundational Defining variables and ODR + +Main Defining for programs + +Advanced Special cases and peculiarities + +------------------------------------------------------------------------ + +### Motivation + +_Why is this important?_ +_Why do we want to learn/teach this topic?_ + +* A definition is a declaration that supplies all that is needed for a complete entity +* `int baz = 42;` +* `void bar() { /* implementation */ }` +* `class Foo { /* class body */ };` + +### Topic introduction + +_Very brief introduction to the topic._ + +A definition extends a declaration, providing all that is needed for a complete +entity, e.g., allocate memory for variables, provide the implementation for +functions, complete definitions of data and function members of a class. + +### Foundational: Defining variables and ODR {#def-found} + + +#### Background/Required Knowledge + + +A student: + +* is familiar with declarations [[C++ object model: declarations]][1] + +#### Student outcomes + +_A list of things "a student should be able to" after the curriculum._ +_The next word should be an action word and testable in an exam._ +_Max 5 items._ + +A student should be able to: + +1. define a variable with a specific type `int baz = 42;` +2. define a function `void bar() {}` +3. define a class `class Foo {};` +4. explain the one definition rule + + +#### Caveats + +_This section mentions subtle points to understand, like anything resulting in +implementation-defined, unspecified, or undefined behavior._ + +No caveats at present. + +#### Points to cover + +_This section lists important details for each point._ + +* One definition rule (ODR) + +### Main: Defining for programs {#def-main} + + +#### Background/Required Knowledge + + +* All of the above. +* is familiar with declarations [[C++ object model: declarations]][1] + +#### Student outcomes + +_A list of things "a student should be able to" after the curriculum._ +_The next word should be an action word and testable in an exam._ +_Max 5 items._ + +A student should be able to: + +1. organize variables, functions, classes into multiple translation units, describing interface with declarations and providing the implementations with definitions without violating ODR. +2. distinguish between template declaration and definition + +#### Caveats + +_This section mentions subtle points to understand, like anything resulting in +implementation-defined, unspecified, or undefined behavior._ + +* Putting a definition into a header file that is included more than once leads to ODR violations, possibly resulting in linker errors. + +#### Points to cover + +_This section lists important details for each point._ + +### Advanced: Special cases and peculiarities {#def-advanced} + +_These are important topics that are not expected to be covered but provide +guidance where one can continue to investigate this topic in more depth._ + +* ABI Incompatibilities: Different definitions of the same type in multiple object files can lead to subtle program errors. + +[1]: ../object-model/declarations.md diff --git a/sources/modules/type-system/fundamental-types.md b/sources/modules/type-system/fundamental-types.md new file mode 100644 index 0000000..4dfae7e --- /dev/null +++ b/sources/modules/type-system/fundamental-types.md @@ -0,0 +1,6 @@ +## Type system: Fundamental types + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :) diff --git a/sources/modules/type-system/user-defined-types.md b/sources/modules/type-system/user-defined-types.md new file mode 100644 index 0000000..fa4d490 --- /dev/null +++ b/sources/modules/type-system/user-defined-types.md @@ -0,0 +1,6 @@ +## Types system: User-defined types + +_Skeleton descriptions are typeset in italic text,_ +_so please don't remove these descriptions when editing the topic._ + +This topic is currently under construction and will soon be filled with information :)