├── .github └── workflows │ ├── build.yml │ └── jekyll-gh-pages.yml ├── .gitignore ├── .travis.yml ├── CONTRIBUTING.md ├── CppCoreGuidelines.md ├── LICENSE ├── README.md ├── SECURITY.md ├── _config.yml ├── _includes ├── head.html └── sidebar.html ├── _layouts └── default.html ├── cpp_core_guidelines_16b.png ├── cpp_core_guidelines_logo_text.png ├── docs ├── Introduction to type and resource safety.pdf ├── Lifetime.pdf ├── P0122R4.pdf ├── ctor-dtor-raii-popl12.pdf └── gsl-intro.md ├── index.html ├── param-passing-advanced.png ├── param-passing-normal.png ├── params.json ├── public ├── css │ ├── custom.css │ ├── hyde.css │ └── poole.css └── images │ ├── bg_hr.png │ ├── blacktocat.png │ ├── icon_download.png │ └── sprite_download.png ├── scripts ├── Makefile ├── hunspell │ ├── en_US.aff │ ├── en_US.dic │ └── isocpp.dic ├── nodejs │ ├── package.json │ └── remark │ │ └── .remarkrc └── python │ ├── Makefile.in │ ├── cpplint.py │ ├── cpplint_wrap.py │ └── md-split.py └── talks ├── Contracts-for-Dependable-C++.pdf ├── Large-Scale-C++-With-Modules.pdf ├── MacIntosh - A Few Good Types.pdf ├── MacIntosh - Static Analysis and C++.pdf ├── README.md ├── Stroustrup - CppCon 2015 keynote.pdf └── Sutter - CppCon 2015 day 2 plenary .pdf /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | name: build 2 | on: [push, pull_request] 3 | 4 | jobs: 5 | build: 6 | runs-on: ubuntu-latest 7 | 8 | steps: 9 | - uses: actions/checkout@master 10 | 11 | - name: Install Hunspell 12 | run: | 13 | sudo apt-get update 14 | sudo apt-get install hunspell 15 | 16 | - name: Run cd scripts; make -k 17 | run: cd scripts; make -k 18 | 19 | - name: Run cd .. 20 | run: cd .. 21 | -------------------------------------------------------------------------------- /.github/workflows/jekyll-gh-pages.yml: -------------------------------------------------------------------------------- 1 | # Sample workflow for building and deploying a Jekyll site to GitHub Pages 2 | name: Deploy Jekyll with GitHub Pages dependencies preinstalled 3 | 4 | on: 5 | # Runs on pushes targeting the default branch 6 | push: 7 | branches: ["master"] 8 | 9 | # Allows you to run this workflow manually from the Actions tab 10 | workflow_dispatch: 11 | 12 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 13 | permissions: 14 | contents: read 15 | pages: write 16 | id-token: write 17 | 18 | # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. 19 | # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. 20 | concurrency: 21 | group: "pages" 22 | cancel-in-progress: false 23 | 24 | jobs: 25 | # Build job 26 | build: 27 | runs-on: ubuntu-latest 28 | steps: 29 | - name: Checkout 30 | uses: actions/checkout@v4 31 | - name: Setup Pages 32 | uses: actions/configure-pages@v5 33 | - name: Build with Jekyll 34 | uses: actions/jekyll-build-pages@v1 35 | with: 36 | source: ./ 37 | destination: ./_site 38 | - name: Upload artifact 39 | uses: actions/upload-pages-artifact@v3 40 | 41 | # Deployment job 42 | deploy: 43 | environment: 44 | name: github-pages 45 | url: ${{ steps.deployment.outputs.page_url }} 46 | runs-on: ubuntu-latest 47 | needs: build 48 | steps: 49 | - name: Deploy to GitHub Pages 50 | id: deployment 51 | uses: actions/deploy-pages@v4 52 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | scripts/build 2 | scripts/nodesjs/build 3 | node_modules 4 | _site 5 | scripts/python/__pycache__ 6 | scripts/python/*.pyc 7 | 8 | # VS Code 9 | .vs/ 10 | 11 | # MacOS-specific 12 | .DS_Store -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | # This is the configuration for Travis CI, a free github-integrated service that runs this script for each pull request (if configured) 2 | 3 | # provides gcc, clang, make, scons, cmake 4 | language: c++ 5 | 6 | # alternatives: gcc, clang, or both (as yaml list) 7 | compiler: clang 8 | 9 | addons: 10 | apt: 11 | packages: 12 | - hunspell 13 | 14 | install: 15 | - 16 | 17 | script: 18 | - cd scripts; make -k 19 | - cd .. 20 | 21 | notifications: 22 | email: false 23 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | ## Contributing to the C++ Core Guidelines 2 | 3 | >"Within C++ is a smaller, simpler, safer language struggling to get out." 4 | >-- Bjarne Stroustrup 5 | 6 | The C++ Core Guidelines are a collaborative effort led by Bjarne Stroustrup, much like the C++ language itself. They are the result of many 7 | person-years of discussion and design across a number of organizations. Their design encourages general applicability and broad adoption but 8 | they can be freely copied and modified to meet your organization's needs. 9 | 10 | We encourage contributions to the C++ Core Guidelines in a number of ways: 11 | - **Individual feedback** Are you a developer who is passionate about your code? Join the discussion in 12 | [Issues](https://github.com/isocpp/CppCoreGuidelines/issues). We want to know which rules resonate with you and which don't. Were any rules 13 | inordinately difficult to apply? Does your compiler vendor's Guidelines Support Library (e.g., 14 | [Microsoft's implementation of the GSL](https://github.com/microsoft/gsl)) suit your needs in adopting these guidelines? 15 | - **Organizational adoption** While the guidelines are designed to be broadly adoptable they are also intended to be modified to fit your 16 | organization's particular needs. We encourage your organization to fork this repo and create your own copy of these guidelines with changes 17 | that reflect your needs. We suggest that you make it clear in the title of your guidelines that these are your organization's fork of the 18 | guidelines and that you provide a link back to the original set of [guidelines](https://github.com/isocpp/CppCoreGuidelines). And if any of 19 | your local changes are appropriate to pull back into the original guidelines, please open an 20 | [Issue](https://github.com/isocpp/CppCoreGuidelines/issues) which can lead to a pull request. 21 | - **Maintain the Guidelines** The C++ Core Guidelines were created from a wealth of knowledge spread across a number of organizations 22 | worldwide. If you or your organization is passionate about helping to create the guidelines, consider becoming an editor or maintainer. If 23 | you're a C++ expert who is serious about participating, please 24 | [email coreguidelines@isocpp.org](mailto:coreguidelines@isocpp.org?subject=Maintain%20the%20C++%20Code%20Guidelines). 25 | 26 | ## Contributor License Agreement 27 | By contributing content to the C++ Core Guidelines (i.e., submitting a pull request for inclusion in this repository) you agree with the 28 | [Standard C++ Foundation](https://isocpp.org/about) [Terms of Use](https://isocpp.org/home/terms-of-use), especially all of the terms specified 29 | regarding Copyright and Patents. 30 | - You warrant that your material is original, or you have the right to contribute it. 31 | - With respect to the material that you own, you grant a worldwide, non-exclusive, irrevocable, transferable, and royalty-free license to your contributed 32 | material to Standard C++ Foundation to display, reproduce, perform, distribute, and create derivative works of that material for commercial or 33 | non-commercial use. With respect to any other material you contribute, such material must be under a license sufficient to allow Standard C++ Foundation 34 | to display, reproduce, perform, distribute, and create derivative works of that material for commercial or non-commercial use. 35 | - You agree that, if your contributed material is subsequently reflected in the ISO/IEC C++ standard in any form, it will be subject to all ISO/IEC JTC 36 | 1 policies including [copyrights](http://www.iso.org/iso/home/policies.htm), 37 | [patents](http://www.iso.org/iso/home/standards_development/governance_of_technical_work/patents.htm), and 38 | [procedures](http://www.itscj.ipsj.or.jp/sc29/29w7proc.htm); please direct any questions about these policies to the 39 | [ISO Central Secretariat](http://www.iso.org/iso/home/about.htm). 40 | 41 | 42 | ## Pull requests 43 | 44 | We welcome pull requests for scoped changes to the guidelines--bug fixes in 45 | examples, clarifying ambiguous text, etc. Significant changes should first be 46 | discussed in the [Issues](https://github.com/isocpp/CppCoreGuidelines/issues) 47 | and the Issue number must be included in the pull request. For 48 | guideline-related changes, please specify the rule number in your Issue and/or 49 | Pull Request. 50 | 51 | Changes should be made in a child commit of a recent commit in the master 52 | branch. If you are making many small changes, please create separate PRs to 53 | minimize merge issues. 54 | 55 | ### Document Style Guidelines 56 | 57 | Documents in this repository are written in an unspecific flavor of Markdown, 58 | which leaves some ambiguity for formatting text. We ask that pull requests 59 | maintain the following style guidelines, though we are aware that the document 60 | may not already be consistent. 61 | 62 | #### Indentation 63 | 64 | Code and nested text should use multiples of 4 spaces of indentation, and no 65 | tab characters, like so: 66 | 67 | void func(const int x) 68 | { 69 | std::cout << x << '\n'; 70 | } 71 | 72 | #### Code Blocks 73 | 74 | Please use 4-space indentation to trigger code parsing, rather than [fenced code blocks](https://help.github.com/articles/github-flavored-markdown/#fenced-code-blocks) or any other style, like so: 75 | 76 | This is some document text, with an example below: 77 | 78 | void func() 79 | { 80 | std::cout << "This is code.\n"; 81 | } 82 | 83 | #### Document style decisions 84 | 85 | We've discussed and made decisions on a number of document style. Please do not open PRs that revisit these stylistic points: 86 | 87 | - The CppCoreGuidelines.md file is a single GH-flavored Markdown file. It is not split into separate chapters. 88 | - We do not use syntax highlighting in the Core Guidelines. See PRs #33, #96, #328, and #779. If you want syntax highlighting you 89 | can either view the "pretty" version at http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines or do your own post-processing. 90 | - We're sticking with the ASCII character set. We do not use Unicode em-dashes, Unicode spaces, or pretty quotes. Lots of people edit this file with their various text editors. ASCII is simple and universally understood. 91 | 92 | ### Update dictionary 93 | 94 | Code samples in the guidelines are run through a spelling checker. Be sure to add new class and variable names to [scripts/hunspell/isocpp.dic](https://github.com/isocpp/CppCoreGuidelines/blob/master/scripts/hunspell/isocpp.dic). 95 | 96 | ### Miscellaneous 97 | 98 | To avoid line-ending issues, please set `autocrlf = input` and `whitespace = cr-at-eol` in your git configuration. 99 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) Standard C++ Foundation and its contributors 2 | 3 | Standard C++ Foundation grants you a worldwide, nonexclusive, royalty-free, 4 | perpetual license to copy, use, modify, and create derivative works from this 5 | project for your personal or internal business use only. The above copyright 6 | notice and this permission notice shall be included in all copies or 7 | substantial portions of the project. This license does not grant permission 8 | to use the trade names, trademarks, service marks, or product names of the 9 | licensor, except as required for reasonable and customary use in describing 10 | the origin of the project. 11 | 12 | Standard C++ Foundation reserves the right to accept contributions to the 13 | project at its discretion. 14 | 15 | By contributing material to this project, you grant Standard C++ Foundation, 16 | and those who receive the material directly or indirectly from Standard C++ 17 | Foundation, a perpetual, worldwide, non-exclusive, royalty-free, irrevocable, 18 | transferrable license to reproduce, prepare derivative works of, publicly 19 | display, publicly perform, and distribute your contributed material and such 20 | derivative works, and to sublicense any or all of the foregoing rights to third 21 | parties for commercial or non-commercial use. You also grant Standard C++ 22 | Foundation, and those who receive the material directly or indirectly from 23 | Standard C++ Foundation, a perpetual, worldwide, non-exclusive, royalty-free, 24 | irrevocable license under your patent claims that directly read on your 25 | contributed material to make, have made, use, offer to sell, sell and import 26 | or otherwise dispose of the material. You warrant that your material is your 27 | original work, or that you have the right to grant the above licenses. 28 | 29 | THE PROJECT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 30 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 31 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 32 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 33 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 34 | OUT OF OR IN CONNECTION WITH THE PROJECT OR THE USE OR OTHER DEALINGS IN THE 35 | PROJECT. 36 | 37 | If you believe that anything in the project infringes your copyright, please 38 | contact us at admin@isocpp.org with your contact information and a detailed 39 | description of your intellectual property, including a specific URL where you 40 | believe your intellectual property is being infringed. 41 | 42 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![C++ Core Guidelines](cpp_core_guidelines_logo_text.png)](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) 2 | 3 | >"Within C++ is a smaller, simpler, safer language struggling to get out." 4 | >-- Bjarne Stroustrup 5 | 6 | The [C++ Core Guidelines](CppCoreGuidelines.md) are a collaborative effort led by Bjarne Stroustrup, much like the C++ language itself. They are the result of many 7 | person-years of discussion and design across a number of organizations. Their design encourages general applicability and broad adoption but 8 | they can be freely copied and modified to meet your organization's needs. 9 | 10 | ## Getting started 11 | 12 | The guidelines themselves are found at [CppCoreGuidelines](CppCoreGuidelines.md). The document is in [GH-flavored MarkDown](https://github.github.com/gfm/). It is intentionally kept simple, mostly in ASCII, to allow automatic post-processing such as language translation and reformatting. The editors maintain one 13 | [version formatted for browsing](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines). Note that it is manually integrated and can be slightly older than the version in the master branch. 14 | 15 | The Guidelines are a constantly evolving document without a strict "release" cadence. Bjarne Stroustrup periodically reviews the document and increments the version number in the introduction. [Checkins that increment the version number](https://github.com/isocpp/CppCoreGuidelines/releases) are tagged in git. 16 | 17 | Many of the guidelines make use of the header-only Guidelines Support Library. One implementation is available at [GSL: Guidelines Support Library](https://github.com/Microsoft/GSL). 18 | 19 | ## Background and scope 20 | 21 | The aim of the guidelines is to help people to use modern C++ effectively. By "modern C++" we mean C++11 and newer. In other 22 | words, what would you like your code to look like in 5 years' time, given that you can start now? In 10 years' time? 23 | 24 | The guidelines are focused on relatively higher-level issues, such as interfaces, resource management, memory management, and concurrency. Such 25 | rules affect application architecture and library design. Following the rules will lead to code that is statically type-safe, has no resource 26 | leaks, and catches many more programming logic errors than is common in code today. And it will run fast -- you can afford to do things right. 27 | 28 | We are less concerned with low-level issues, such as naming conventions and indentation style. However, no topic that can help a programmer is 29 | out of bounds. 30 | 31 | Our initial set of rules emphasizes safety (of various forms) and simplicity. They may very well be too strict. We expect to have to introduce 32 | more exceptions to better accommodate real-world needs. We also need more rules. 33 | 34 | You will find some of the rules contrary to your expectations or even contrary to your experience. If we haven't suggested that you change your 35 | coding style in any way, we have failed! Please try to verify or disprove rules! In particular, we'd really like to have some of our rules 36 | backed up with measurements or better examples. 37 | 38 | You will find some of the rules obvious or even trivial. Please remember that one purpose of a guideline is to help someone who is less 39 | experienced or coming from a different background or language to get up to speed. 40 | 41 | The rules are designed to be supported by an analysis tool. Violations of rules will be flagged with references (or links) to the relevant rule. 42 | We do not expect you to memorize all the rules before trying to write code. 43 | 44 | The rules are meant for gradual introduction into a code base. We plan to build tools for that and hope others will too. 45 | 46 | ## Contributions and LICENSE 47 | 48 | Comments and suggestions for improvements are most welcome. We plan to modify and extend this document as our understanding improves and the 49 | language and the set of available libraries improve. More details are found at [CONTRIBUTING](./CONTRIBUTING.md) and [LICENSE](./LICENSE). 50 | 51 | Thanks to [DigitalOcean](https://www.digitalocean.com/?refcode=32f291566cf7&utm_campaign=Referral_Invite&utm_medium=Referral_Program&utm_source=CopyPaste) for hosting the Standard C++ Foundation website. 52 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | ## Reporting a Vulnerability 4 | 5 | Please report vulnerabilities, if any, to cppcg-editors@isocpp.org 6 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | include: [CppCoreGuidelines.md] 2 | exclude: [docs, talks, Gemfile, params.json] 3 | -------------------------------------------------------------------------------- /_includes/head.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | C++ Core Guidelines 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 36 | 37 | 38 | 43 | 44 | 45 | 64 | 65 | 66 | -------------------------------------------------------------------------------- /_includes/sidebar.html: -------------------------------------------------------------------------------- 1 |
2 |
3 |
4 | 5 | 13 |
14 | 67 | 68 | 69 |
70 |
71 | -------------------------------------------------------------------------------- /_layouts/default.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | {% include head.html %} 5 | 6 | 7 | 8 | {% include sidebar.html %} 9 | 10 | 11 | 12 |
13 | {{ content }} 14 |
15 | 16 | 17 | 18 | -------------------------------------------------------------------------------- /cpp_core_guidelines_16b.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/cpp_core_guidelines_16b.png -------------------------------------------------------------------------------- /cpp_core_guidelines_logo_text.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/cpp_core_guidelines_logo_text.png -------------------------------------------------------------------------------- /docs/Introduction to type and resource safety.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/docs/Introduction to type and resource safety.pdf -------------------------------------------------------------------------------- /docs/Lifetime.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/docs/Lifetime.pdf -------------------------------------------------------------------------------- /docs/P0122R4.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/docs/P0122R4.pdf -------------------------------------------------------------------------------- /docs/ctor-dtor-raii-popl12.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/docs/ctor-dtor-raii-popl12.pdf -------------------------------------------------------------------------------- /docs/gsl-intro.md: -------------------------------------------------------------------------------- 1 | 2 | # Using the Guidelines Support Library (GSL): A Tutorial and FAQ 3 | 4 | by Herb Sutter 5 | 6 | updated 2018-01-08 7 | 8 | 9 | ## Overview: "Is this document a tutorial or a FAQ?" 10 | 11 | It aims to be both: 12 | 13 | - a tutorial you can read in order, following a similar style as the introduction of [K&R](https://en.wikipedia.org/wiki/The_C_Programming_Language) by building up examples of increasing complexity; and 14 | 15 | - a FAQ you can use as a reference, with each section showing the answer to a specific question. 16 | 17 | 18 | ## Motivation: "Why would I use GSL, and where can I get it?" 19 | 20 | First look at the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines); this is a support library for that document. Select a set of guidelines you want to adopt, then bring in the GSL as directed by those guidelines. 21 | 22 | You can try out the examples in this document on all major compilers and platforms using [this GSL reference implementation](https://github.com/microsoft/gsl). 23 | 24 | 25 | # gsl::span: "What is gsl::span, and what is it for?" 26 | 27 | `gsl::span` is a replacement for `(pointer, length)` pairs to refer to a sequence of contiguous objects. It can be thought of as a pointer to an array, but that knows its bounds. 28 | 29 | For example, a `span` refers to a sequence of seven contiguous integers. 30 | 31 | A `span` does not own the elements it points to. It is not a container like an `array` or a `vector`, it is a view into the contents of such a container. 32 | 33 | 34 | ## span parameters: "How should I choose between span and traditional (ptr, length) parameters?" 35 | 36 | In new code, prefer the bounds-checkable `span` instead of separate pointer and length parameters. In older code, adopt `span` where reasonable as you maintain the code. 37 | 38 | A function that takes a pointer to an array and a separate length, such as: 39 | 40 | ~~~cpp 41 | // Error-prone: Process n contiguous ints starting at *p 42 | void dangerous_process_ints(const int* p, size_t n); 43 | ~~~ 44 | 45 | is error-prone and difficult to use correctly: 46 | 47 | ~~~cpp 48 | int a[100]; 49 | dangerous_process_ints(a, 1000); // oops: buffer overflow 50 | 51 | vector v(200); 52 | dangerous_process_ints(v.data(), 1000); // oops: buffer overflow 53 | 54 | auto remainder = find(v.begin(), v.end(), some_value); 55 | // now call dangerous_process_ints() to fill the rest of the container from *remainder to the end 56 | dangerous_process_ints(&*remainder, v.end() - remainder); // correct but convoluted 57 | ~~~ 58 | 59 | Instead, using `span` encapsulates the pointer and the length: 60 | 61 | ~~~cpp 62 | // BETTER: Read s.size() contiguous ints starting at s[0] 63 | void process_ints(span s); 64 | ~~~ 65 | 66 | which makes `process_ints` easier to use correctly because it conveniently deduces from common types: 67 | 68 | ~~~cpp 69 | int a[100]; 70 | process_ints(a); // deduces correct length: 100 (constructs the span from a container) 71 | 72 | vector v(200); 73 | process_ints(v); // deduces correct length: 200 (constructs the span from a container) 74 | ~~~ 75 | 76 | and conveniently supports modern C++ argument initialization when the calling code does have distinct pointer and length arguments: 77 | 78 | ~~~cpp 79 | auto remainder = find(v.begin(), v.end(), some_value); 80 | // now call process_ints() to fill the rest of the container from *remainder to the end 81 | process_ints({remainder, v.end()}); // correct and clear (constructs the span from an iterator pair) 82 | ~~~ 83 | 84 | > Things to remember 85 | > - Prefer `span` instead of (pointer, length) pairs. 86 | > - Pass a `span` like a pointer (i.e., by value for "in" parameters). Treat it like a pointer range. 87 | 88 | 89 | ## span and const: "What's the difference between `span` and `const span`?" 90 | 91 | `span` means that the `T` objects are read-only. Prefer this by default, especially as a parameter, if you don't need to modify the `T`s. 92 | 93 | `const span` means that the `span` itself can't be made to point at a different target. 94 | 95 | `const span` means both. 96 | 97 | > Things to remember 98 | > - Prefer a `span` by default to denote that the contents are read-only, unless you do need read-write access. 99 | 100 | 101 | ## Iteration: "How do I iterate over a span?" 102 | 103 | A `span` is an encapsulated range, and so can be visited using a range-based `for` loop. 104 | 105 | Consider the implementation of a function like the `process_ints` that we saw in an earlier example. Visiting every object using a (pointer, length) pair requires an explicit index: 106 | 107 | ~~~cpp 108 | void dangerous_process_ints(int* p, size_t n) { 109 | for (auto i = 0; i < n; ++i) { 110 | p[i] = next_character(); 111 | } 112 | } 113 | ~~~ 114 | 115 | A `span` supports range-`for` -- note this is zero-overhead and does not need to perform any range check, because the range-`for` loop is known by construction not to exceed the range's bounds: 116 | 117 | ~~~cpp 118 | void process_ints(span s) { 119 | for (auto& c : s) { 120 | c = next_character(); 121 | } 122 | } 123 | ~~~ 124 | 125 | A `span` also supports normal iteration using `.begin()` and `.end()`. 126 | 127 | Note that you cannot compare iterators from different spans, even if they refer to the same array. 128 | 129 | An iterator is valid as long as the `span` that it is iterating over exists. 130 | 131 | 132 | ## Element access: "How do I access a single element in a span?" 133 | 134 | Use `myspan[offset]` to subscript, or equivalently use `iter + offset` wheren `iter` is a `span::iterator`. Both are range-checked. 135 | 136 | 137 | 138 | ## Sub-spans: "What if I need a subrange of a span?" 139 | 140 | To refer to a sub-span, use `first`, `last`, or `subspan`. 141 | 142 | ~~~cpp 143 | void process_ints(span s) { 144 | if (s.length() > 10) { 145 | read_header(s.first(10)); // first 10 entries 146 | read_rest(s.subspan(10)); // remaining entries 147 | // ... 148 | } 149 | } 150 | ~~~ 151 | 152 | In rarer cases, when you know the number of elements at compile time and want to enable `constexpr` use of `span`, you can pass the length of the sub-span as a template argument: 153 | 154 | ~~~cpp 155 | constexpr int process_ints(span s) { 156 | if (s.length() > 10) { 157 | read_header(s.first<10>()); // first 10 entries 158 | read_rest(s.subspan<10>()); // remaining entries 159 | // ... 160 | } 161 | return s.size(); 162 | } 163 | ~~~ 164 | 165 | 166 | ## span and STL: "How do I pass a span to an STL-style [begin,end) function?" 167 | 168 | Use `span::iterator`s. A `span` is iterable like any STL range. 169 | 170 | To call an STL `[begin,end)`-style interface, use `begin` and `end` by default, or other valid iterators if you don't want to pass the whole range: 171 | 172 | ~~~cpp 173 | void f(span s) { 174 | // ... 175 | auto found = find_if(s.begin(), s.end(), some_value); 176 | // ... 177 | } 178 | ~~~ 179 | 180 | If you are using a range-based algorithm such as from [Range-V3](https://github.com/ericniebler/range-v3), you can use a `span` as a range directly: 181 | 182 | ~~~cpp 183 | void f(span s) { 184 | // ... 185 | auto found = find_if(s, some_value); 186 | // ... 187 | } 188 | ~~~ 189 | 190 | 191 | ## Comparison: "When I compare `span`s, do I compare the `T` values or the underlying pointers?" 192 | 193 | Comparing two `span`s compares the `T` values. To compare two spans for identity, to see if they're pointing to the same thing, use `.data()`. 194 | 195 | ~~~cpp 196 | int a[] = { 1, 2, 3}; 197 | span sa{a}; 198 | 199 | vector v = { 1, 2, 3 }; 200 | span sv{v}; 201 | 202 | assert(sa == sv); // sa and sv both point to contiguous ints with values 1, 2, 3 203 | assert(sa.data() != sv.data()); // but sa and sv point to different memory areas 204 | ~~~ 205 | 206 | > Things to remember 207 | > - Comparing spans compares their contents, not whether they point to the same location. 208 | 209 | 210 | ## Empty vs null: "Do I have to explicitly check whether a span is null?" 211 | 212 | Usually not, because the thing you usually want to check for is that the `span` is not empty, which means its size is not zero. It's safe to test the size of a span even if it's null. 213 | 214 | Remember that the following all have identical meaning for a `span s`: 215 | 216 | - `!s.empty()` 217 | - `s.size() != 0` 218 | - `s.data() != nullptr && s.size() != 0` (the first condition is actually redundant) 219 | 220 | The following is also functionally equivalent as it just tests whether there are zero elements: 221 | 222 | - `s != nullptr` (compares `s` against a null-constructed empty `span`) 223 | 224 | For example: 225 | 226 | ~~~cpp 227 | void f(span s) { 228 | if (s != nullptr && s.size() > 0) { // bad: redundant, overkill 229 | // ... 230 | } 231 | 232 | if (s.size() > 0) { // good: not redundant 233 | // ... 234 | } 235 | 236 | if (!s.empty()) { // good: same as "s.size() > 0" 237 | // ... 238 | } 239 | } 240 | 241 | ~~~ 242 | 243 | > Things to remember 244 | > - Usually you shouldn't check for a null `span`. For a `span s`, if you're comparing `s != nullptr` or `s.data() != nullptr`, check to make sure you shouldn't just be asking `!s.empty()`. 245 | 246 | 247 | ## as_bytes: "Why would I convert a span to `span`?" 248 | 249 | Because it's a type-safe way to get a read-only view of the objects' bytes. 250 | 251 | Without `span`, to view the bytes of an object requires writing a brittle cast: 252 | 253 | ~~~cpp 254 | void serialize(char* p, int length); // bad: forgot const 255 | 256 | void f(widget* p, int length) { 257 | // serialize one object's bytes (incl. padding) 258 | serialize(p, 1); // bad: copies just the first byte, forgot sizeof(widget) 259 | } 260 | ~~~ 261 | 262 | With `span` the code is safer and cleaner: 263 | 264 | ~~~cpp 265 | void serialize(span); // can't forget const, the first test call site won't compile 266 | 267 | void f(span s) { 268 | // ... 269 | // serialize one object's bytes (incl. padding) 270 | serialize(as_bytes(s)); // ok 271 | } 272 | ~~~ 273 | 274 | Also, `span` lets you distinguish between `.size()` and `.size_bytes()`; make use of that distinction instead of multiplying by `sizeof(T)`. 275 | 276 | > Things to remember 277 | > - Prefer `span`'s `.size_bytes()` instead of `.size() * sizeof(T)`. 278 | 279 | 280 | ## And a few `span`-related hints 281 | 282 | These are not directly related to `span` but can often come up while using `span`. 283 | 284 | * Use `byte` everywhere you are handling memory (as opposed to characters or integers). That is, when accessing a chunk of raw memory, use `gsl::span`. 285 | 286 | * Use `narrow()` when you cannot afford to be surprised by a value change during conversion to a smaller range. This includes going between a signed `span` size or index and an unsigned today's-STL-container `.size()`, though the `span` constructors from containers nicely encapsulate many of these conversions. 287 | 288 | * Similarly, use `narrow_cast()` when you are *sure* you won’t be surprised by a value change during conversion to a smaller range 289 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 |

This site is copy of the C++ Core Guidelines rendered for easier browsing. As the text on this page is integrated manually 6 | you should refer to the C++ Core Guidelines repo for the most up-to-date version. 7 |

8 | 9 | 10 |
11 |
12 | 18 |
19 |
20 | 21 | {% capture readme %}{% include_relative README.md %}{% endcapture %} 22 | {{ readme | markdownify }} 23 | -------------------------------------------------------------------------------- /param-passing-advanced.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/param-passing-advanced.png -------------------------------------------------------------------------------- /param-passing-normal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/param-passing-normal.png -------------------------------------------------------------------------------- /params.json: -------------------------------------------------------------------------------- 1 | {"name":"Cppcoreguidelines","tagline":"The C++ Core Guidelines are a set of tried-and-true guidelines, rules, and best practices about coding in C++","body":"# C++ Core Guidelines\r\n\r\n>\"Within C++ is a smaller, simpler, safer language struggling to get out.\" \r\n>-- Bjarne Stroustrup\r\n\r\nThe C++ Core Guidelines are a collaborative effort led by Bjarne Stroustrup, much like the C++ language itself. They are the result of many \r\nperson-years of discussion and design across a number of organizations. Their design encourages general applicability and broad adoption but \r\nthey can be freely copied and modified to meet your organization's needs. \r\n\r\nThe aim of the guidelines is to help people to use modern C++ effectively. By \"modern C++\" we mean C++11 and C++14 (and soon C++17). In other \r\nwords, what would you like your code to look like in 5 years' time, given that you can start now? In 10 years' time?\r\n\r\nThe guidelines are focused on relatively higher-level issues, such as interfaces, resource management, memory management, and concurrency. Such \r\nrules affect application architecture and library design. Following the rules will lead to code that is statically type safe, has no resource \r\nleaks, and catches many more programming logic errors than is common in code today. And it will run fast - you can afford to do things right.\r\n\r\nWe are less concerned with low-level issues, such as naming conventions and indentation style. However, no topic that can help a programmer is \r\nout of bounds.\r\n\r\nOur initial set of rules emphasize safety (of various forms) and simplicity. They may very well be too strict. We expect to have to introduce \r\nmore exceptions to better accommodate real-world needs. We also need more rules.\r\n\r\nYou will find some of the rules contrary to your expectations or even contrary to your experience. If we haven't suggested you change your \r\ncoding style in any way, we have failed! Please try to verify or disprove rules! In particular, we'd really like to have some of our rules \r\nbacked up with measurements or better examples.\r\n\r\nYou will find some of the rules obvious or even trivial. Please remember that one purpose of a guideline is to help someone who is less \r\nexperienced or coming from a different background or language to get up to speed.\r\n\r\nThe rules are designed to be supported by an analysis tool. Violations of rules will be flagged with references (or links) to the relevant rule. \r\nWe do not expect you to memorize all the rules before trying to write code.\r\n\r\nThe rules are meant for gradual introduction into a code base. We plan to build tools for that and hope others will too.\r\n\r\nComments and suggestions for improvements are most welcome. We plan to modify and extend this document as our understanding improves and the \r\nlanguage and the set of available libraries improve.\r\n","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."} -------------------------------------------------------------------------------- /public/css/custom.css: -------------------------------------------------------------------------------- 1 | .outer { 2 | width: 100%; 3 | } 4 | 5 | .inner { 6 | position: relative; 7 | max-width: 1280px; 8 | padding: 20px 10px; 9 | margin: 0 auto; 10 | } 11 | 12 | 13 | #header_wrap { 14 | background: #212121; 15 | background: -moz-linear-gradient(top, #373737, #212121); 16 | background: -webkit-linear-gradient(top, #373737, #212121); 17 | background: -ms-linear-gradient(top, #373737, #212121); 18 | background: -o-linear-gradient(top, #373737, #212121); 19 | background: linear-gradient(top, #373737, #212121); 20 | } 21 | 22 | #header_wrap .inner { 23 | padding: 50px 10px 30px 10px; 24 | } 25 | 26 | #downloads { 27 | position: absolute; 28 | width: 210px; 29 | z-index: 10; 30 | bottom: -40px; 31 | right: 0; 32 | height: 70px; 33 | background: url('../images/icon_download.png') no-repeat 0% 90%; 34 | } 35 | 36 | /** same style for highlighted, non-highlight */ 37 | .cpp.hljs { 38 | overflow-x: unset; 39 | } 40 | 41 | /** override poole.css */ 42 | pre code { 43 | /* same as hljs */ 44 | padding: 0.5em; 45 | } 46 | 47 | /** highlight js change colors (overrides style) */ 48 | .hljs-comment { 49 | color: #008000; 50 | } 51 | .hljs-meta { 52 | color: #2b91af; 53 | } 54 | 55 | .zip_download_link { 56 | display: block; 57 | float: right; 58 | width: 90px; 59 | height:70px; 60 | text-indent: -5000px; 61 | overflow: hidden; 62 | background: url(../images/sprite_download.png) no-repeat bottom left; 63 | } 64 | 65 | .tar_download_link { 66 | display: block; 67 | float: right; 68 | width: 90px; 69 | height:70px; 70 | text-indent: -5000px; 71 | overflow: hidden; 72 | background: url(../images/sprite_download.png) no-repeat bottom right; 73 | margin-left: 10px; 74 | } 75 | 76 | .zip_download_link:hover { 77 | background: url(../images/sprite_download.png) no-repeat top left; 78 | } 79 | 80 | .tar_download_link:hover { 81 | background: url(../images/sprite_download.png) no-repeat top right; 82 | } 83 | 84 | /** 85 | * Try to display h5 headers left of paragraphs 86 | */ 87 | 88 | h5 { 89 | display: inline; 90 | } 91 | 92 | h5:before { 93 | content: '\A'; white-space:pre-line; 94 | } 95 | 96 | h5 + p { 97 | display: inline; 98 | } 99 | 100 | p:after { 101 | content: '\A'; white-space:pre-line; 102 | } 103 | 104 | @media print { 105 | .sidebar,.banner, a:after { 106 | display: none; 107 | } 108 | .container { 109 | width: 90%; 110 | margin: 2em; 111 | padding: 0px; 112 | } 113 | .* { 114 | color: #000; 115 | background-color: #fff; 116 | @include box-shadow(none); 117 | @include text-shadow(none); 118 | } 119 | code,p { 120 | page-break-inside:avoid; 121 | page-break-before:avoid; 122 | } 123 | pre code { 124 | /* try to fit 100 max chars into one A4 line */ 125 | font-size: 2.8mm; 126 | } 127 | h1,h2,h3,h4,h5,strong { 128 | page-break-after:avoid; 129 | } 130 | h1,h2 { 131 | page-break-before:always; 132 | } 133 | a:link, a:visited { 134 | color: #000; 135 | } 136 | } 137 | 138 | 139 | .tgl { 140 | display: none; 141 | } 142 | .tgl + .tgl-btn { 143 | outline: 0; 144 | display: block; 145 | width: 8em; 146 | height: 2em; 147 | position: relative; 148 | cursor: pointer; 149 | -webkit-user-select: none; 150 | -moz-user-select: none; 151 | -ms-user-select: none; 152 | user-select: none; 153 | } 154 | .tgl + .tgl-btn:after, .tgl + .tgl-btn:before { 155 | position: relative; 156 | display: block; 157 | content: ""; 158 | width: 50%; 159 | height: 100%; 160 | } 161 | .tgl + .tgl-btn:after { 162 | left: 0; 163 | } 164 | .tgl + .tgl-btn:before { 165 | display: none; 166 | } 167 | .tgl:checked + .tgl-btn:after { 168 | left: 50%; 169 | } 170 | 171 | .tgl-cpp + .tgl-btn { 172 | overflow: hidden; 173 | -webkit-backface-visibility: hidden; 174 | backface-visibility: hidden; 175 | background: #888; 176 | } 177 | .tgl-cpp + .tgl-btn:after, .tgl-cpp + .tgl-btn:before { 178 | display: inline-block; 179 | width: 100%; 180 | text-align: center; 181 | position: absolute; 182 | line-height: 2em; 183 | font-weight: bold; 184 | color: #fff; 185 | } 186 | .tgl-cpp + .tgl-btn:after { 187 | left: 100%; 188 | content: attr(data-tg-on); 189 | } 190 | .tgl-cpp + .tgl-btn:before { 191 | left: 0; 192 | content: attr(data-tg-off); 193 | } 194 | .tgl-cpp + .tgl-btn:active { 195 | background: #888; 196 | } 197 | .tgl-cpp:checked + .tgl-btn { 198 | background: #268bd2; 199 | } 200 | .tgl-cpp:checked + .tgl-btn:before { 201 | left: -100%; 202 | } 203 | .tgl-cpp:checked + .tgl-btn:after { 204 | left: 0; 205 | } 206 | 207 | // 208 | // rougify style github 209 | // 210 | .highlight table td { padding: 5px; } 211 | .highlight table pre { margin: 0; } 212 | .highlight .cm { 213 | color: #999988; 214 | font-style: italic; 215 | } 216 | .highlight .cp { 217 | color: #999999; 218 | font-weight: bold; 219 | } 220 | .highlight .c1 { 221 | color: #999988; 222 | font-style: italic; 223 | } 224 | .highlight .cs { 225 | color: #999999; 226 | font-weight: bold; 227 | font-style: italic; 228 | } 229 | .highlight .c, .highlight .ch, .highlight .cd, .highlight .cpf { 230 | color: #999988; 231 | font-style: italic; 232 | } 233 | .highlight .err { 234 | color: #a61717; 235 | background-color: #e3d2d2; 236 | } 237 | .highlight .gd { 238 | color: #000000; 239 | background-color: #ffdddd; 240 | } 241 | .highlight .ge { 242 | color: #000000; 243 | font-style: italic; 244 | } 245 | .highlight .gr { 246 | color: #aa0000; 247 | } 248 | .highlight .gh { 249 | color: #999999; 250 | } 251 | .highlight .gi { 252 | color: #000000; 253 | background-color: #ddffdd; 254 | } 255 | .highlight .go { 256 | color: #888888; 257 | } 258 | .highlight .gp { 259 | color: #555555; 260 | } 261 | .highlight .gs { 262 | font-weight: bold; 263 | } 264 | .highlight .gu { 265 | color: #aaaaaa; 266 | } 267 | .highlight .gt { 268 | color: #aa0000; 269 | } 270 | .highlight .kc { 271 | color: #000000; 272 | font-weight: bold; 273 | } 274 | .highlight .kd { 275 | color: #000000; 276 | font-weight: bold; 277 | } 278 | .highlight .kn { 279 | color: #000000; 280 | font-weight: bold; 281 | } 282 | .highlight .kp { 283 | color: #000000; 284 | font-weight: bold; 285 | } 286 | .highlight .kr { 287 | color: #000000; 288 | font-weight: bold; 289 | } 290 | .highlight .kt { 291 | color: #445588; 292 | font-weight: bold; 293 | } 294 | .highlight .k, .highlight .kv { 295 | color: #000000; 296 | font-weight: bold; 297 | } 298 | .highlight .mf { 299 | color: #009999; 300 | } 301 | .highlight .mh { 302 | color: #009999; 303 | } 304 | .highlight .il { 305 | color: #009999; 306 | } 307 | .highlight .mi { 308 | color: #009999; 309 | } 310 | .highlight .mo { 311 | color: #009999; 312 | } 313 | .highlight .m, .highlight .mb, .highlight .mx { 314 | color: #009999; 315 | } 316 | .highlight .sb { 317 | color: #d14; 318 | } 319 | .highlight .sc { 320 | color: #d14; 321 | } 322 | .highlight .sd { 323 | color: #d14; 324 | } 325 | .highlight .s2 { 326 | color: #d14; 327 | } 328 | .highlight .se { 329 | color: #d14; 330 | } 331 | .highlight .sh { 332 | color: #d14; 333 | } 334 | .highlight .si { 335 | color: #d14; 336 | } 337 | .highlight .sx { 338 | color: #d14; 339 | } 340 | .highlight .sr { 341 | color: #009926; 342 | } 343 | .highlight .s1 { 344 | color: #d14; 345 | } 346 | .highlight .ss { 347 | color: #990073; 348 | } 349 | .highlight .s, .highlight .sa, .highlight .dl { 350 | color: #d14; 351 | } 352 | .highlight .na { 353 | color: #008080; 354 | } 355 | .highlight .bp { 356 | color: #999999; 357 | } 358 | .highlight .nb { 359 | color: #0086B3; 360 | } 361 | .highlight .nc { 362 | color: #445588; 363 | font-weight: bold; 364 | } 365 | .highlight .no { 366 | color: #008080; 367 | } 368 | .highlight .nd { 369 | color: #3c5d5d; 370 | font-weight: bold; 371 | } 372 | .highlight .ni { 373 | color: #800080; 374 | } 375 | .highlight .ne { 376 | color: #990000; 377 | font-weight: bold; 378 | } 379 | .highlight .nf, .highlight .fm { 380 | color: #990000; 381 | font-weight: bold; 382 | } 383 | .highlight .nl { 384 | color: #990000; 385 | font-weight: bold; 386 | } 387 | .highlight .nn { 388 | color: #555555; 389 | } 390 | .highlight .nt { 391 | color: #000080; 392 | } 393 | .highlight .vc { 394 | color: #008080; 395 | } 396 | .highlight .vg { 397 | color: #008080; 398 | } 399 | .highlight .vi { 400 | color: #008080; 401 | } 402 | .highlight .nv, .highlight .vm { 403 | color: #008080; 404 | } 405 | .highlight .ow { 406 | color: #000000; 407 | font-weight: bold; 408 | } 409 | .highlight .o { 410 | color: #000000; 411 | font-weight: bold; 412 | } 413 | .highlight .w { 414 | color: #bbbbbb; 415 | } 416 | .highlight { 417 | background-color: #f8f8f8; 418 | } 419 | -------------------------------------------------------------------------------- /public/css/hyde.css: -------------------------------------------------------------------------------- 1 | /* 2 | * __ __ 3 | * /\ \ /\ \ 4 | * \ \ \___ __ __ \_\ \ __ 5 | * \ \ _ `\/\ \/\ \ /'_` \ /'__`\ 6 | * \ \ \ \ \ \ \_\ \/\ \_\ \/\ __/ 7 | * \ \_\ \_\/`____ \ \___,_\ \____\ 8 | * \/_/\/_/`/___/> \/__,_ /\/____/ 9 | * /\___/ 10 | * \/__/ 11 | * 12 | * Designed, built, and released under MIT license by @mdo. Learn more at 13 | * https://github.com/poole/hyde. 14 | */ 15 | 16 | 17 | /* 18 | * Contents 19 | * 20 | * Global resets 21 | * Sidebar 22 | * Container 23 | * Reverse layout 24 | * Themes 25 | */ 26 | 27 | 28 | /* 29 | * Global resets 30 | * 31 | * Update the foundational and global aspects of the page. 32 | */ 33 | 34 | html { 35 | font-family: "PT Sans", Helvetica, Arial, sans-serif; 36 | } 37 | @media (min-width: 48em) { 38 | html { 39 | font-size: 16px; 40 | } 41 | } 42 | @media (min-width: 58em) { 43 | html { 44 | font-size: 20px; 45 | } 46 | } 47 | 48 | 49 | /* 50 | * Sidebar 51 | * 52 | * Flexible banner for housing site name, intro, and "footer" content. Starts 53 | * out above content in mobile and later moves to the side with wider viewports. 54 | */ 55 | 56 | .sidebar { 57 | text-align: center; 58 | padding: none; 59 | color: rgba(255,255,255,.5); 60 | background-color: #202020; 61 | } 62 | @media (min-width: 48em) { 63 | .sidebar { 64 | overflow-y: scroll; 65 | position: fixed; 66 | top: 0; 67 | left: 0; 68 | bottom: 0; 69 | width: 18rem; 70 | text-align: left; 71 | } 72 | } 73 | 74 | /* Sidebar links */ 75 | .sidebar a { 76 | color: #fff; 77 | } 78 | 79 | /* About section */ 80 | .sidebar-about h1 { 81 | color: #fff; 82 | margin-top: 0; 83 | font-family: "Abril Fatface", serif; 84 | font-size: 3.25rem; 85 | } 86 | 87 | /* Sidebar nav */ 88 | .sidebar-nav { 89 | margin-bottom: 1rem; 90 | } 91 | .sidebar-nav-item { 92 | display: block; 93 | line-height: 1.75; 94 | } 95 | a.sidebar-nav-item:hover, 96 | a.sidebar-nav-item:focus { 97 | text-decoration: underline; 98 | } 99 | .sidebar-nav-item.active { 100 | font-weight: bold; 101 | } 102 | 103 | /* Sticky sidebar 104 | * 105 | * Add the `sidebar-sticky` class to the sidebar's container to affix it the 106 | * contents to the bottom of the sidebar in tablets and up. 107 | */ 108 | 109 | @media (min-width: 48em) { 110 | .sidebar-sticky { 111 | position: absolute; 112 | right: 1rem; 113 | bottom: 1rem; 114 | left: 1rem; 115 | top: 0rem; 116 | } 117 | } 118 | 119 | 120 | /* Container 121 | * 122 | * Align the contents of the site above the proper threshold with some margin-fu 123 | * with a 25%-wide `.sidebar`. 124 | */ 125 | 126 | .content { 127 | padding-top: 4rem; 128 | padding-bottom: 4rem; 129 | } 130 | 131 | @media (min-width: 48em) { 132 | .content { 133 | max-width: 38rem; 134 | margin-left: 20rem; 135 | margin-right: 2rem; 136 | } 137 | } 138 | 139 | @media (min-width: 64em) { 140 | .content { 141 | margin-left: 22rem; 142 | margin-right: 4rem; 143 | } 144 | } 145 | 146 | 147 | /* 148 | * Reverse layout 149 | * 150 | * Flip the orientation of the page by placing the `.sidebar` on the right. 151 | */ 152 | 153 | @media (min-width: 48em) { 154 | .layout-reverse .sidebar { 155 | left: auto; 156 | right: 0; 157 | } 158 | .layout-reverse .content { 159 | margin-left: 2rem; 160 | margin-right: 20rem; 161 | } 162 | } 163 | 164 | @media (min-width: 64em) { 165 | .layout-reverse .content { 166 | margin-left: 4rem; 167 | margin-right: 22rem; 168 | } 169 | } 170 | 171 | 172 | 173 | /* 174 | * Themes 175 | * 176 | * As of v1.1, Hyde includes optional themes to color the sidebar and links 177 | * within blog posts. To use, add the class of your choosing to the `body`. 178 | */ 179 | 180 | /* Base16 (http://chriskempson.github.io/base16/#default) */ 181 | 182 | /* Red */ 183 | .theme-base-08 .sidebar { 184 | background-color: #ac4142; 185 | } 186 | .theme-base-08 .content a, 187 | .theme-base-08 .related-posts li a:hover { 188 | color: #ac4142; 189 | } 190 | 191 | /* Orange */ 192 | .theme-base-09 .sidebar { 193 | background-color: #d28445; 194 | } 195 | .theme-base-09 .content a, 196 | .theme-base-09 .related-posts li a:hover { 197 | color: #d28445; 198 | } 199 | 200 | /* Yellow */ 201 | .theme-base-0a .sidebar { 202 | background-color: #f4bf75; 203 | } 204 | .theme-base-0a .content a, 205 | .theme-base-0a .related-posts li a:hover { 206 | color: #f4bf75; 207 | } 208 | 209 | /* Green */ 210 | .theme-base-0b .sidebar { 211 | background-color: #90a959; 212 | } 213 | .theme-base-0b .content a, 214 | .theme-base-0b .related-posts li a:hover { 215 | color: #90a959; 216 | } 217 | 218 | /* Cyan */ 219 | .theme-base-0c .sidebar { 220 | background-color: #75b5aa; 221 | } 222 | .theme-base-0c .content a, 223 | .theme-base-0c .related-posts li a:hover { 224 | color: #75b5aa; 225 | } 226 | 227 | /* Blue */ 228 | .theme-base-0d .sidebar { 229 | background-color: #6a9fb5; 230 | } 231 | .theme-base-0d .content a, 232 | .theme-base-0d .related-posts li a:hover { 233 | color: #6a9fb5; 234 | } 235 | 236 | /* Magenta */ 237 | .theme-base-0e .sidebar { 238 | background-color: #aa759f; 239 | } 240 | .theme-base-0e .content a, 241 | .theme-base-0e .related-posts li a:hover { 242 | color: #aa759f; 243 | } 244 | 245 | /* Brown */ 246 | .theme-base-0f .sidebar { 247 | background-color: #8f5536; 248 | } 249 | .theme-base-0f .content a, 250 | .theme-base-0f .related-posts li a:hover { 251 | color: #8f5536; 252 | } 253 | -------------------------------------------------------------------------------- /public/css/poole.css: -------------------------------------------------------------------------------- 1 | /* 2 | * ___ 3 | * /\_ \ 4 | * _____ ___ ___\//\ \ __ 5 | * /\ '__`\ / __`\ / __`\\ \ \ /'__`\ 6 | * \ \ \_\ \/\ \_\ \/\ \_\ \\_\ \_/\ __/ 7 | * \ \ ,__/\ \____/\ \____//\____\ \____\ 8 | * \ \ \/ \/___/ \/___/ \/____/\/____/ 9 | * \ \_\ 10 | * \/_/ 11 | * 12 | * Designed, built, and released under MIT license by @mdo. Learn more at 13 | * https://github.com/poole/poole. 14 | */ 15 | 16 | 17 | /* 18 | * Contents 19 | * 20 | * Body resets 21 | * Custom type 22 | * Messages 23 | * Container 24 | * Masthead 25 | * Posts and pages 26 | * Pagination 27 | * Reverse layout 28 | * Themes 29 | */ 30 | 31 | 32 | /* 33 | * Body resets 34 | * 35 | * Update the foundational and global aspects of the page. 36 | */ 37 | 38 | 39 | html, 40 | body { 41 | margin: 0; 42 | padding: 0; 43 | } 44 | 45 | html { 46 | font-family: "Helvetica Neue", Helvetica, Arial, sans-serif; 47 | font-size: 16px; 48 | line-height: 1.5; 49 | } 50 | @media (min-width: 38em) { 51 | html { 52 | font-size: 20px; 53 | } 54 | } 55 | 56 | body { 57 | color: #515151; 58 | background-color: #fff; 59 | -webkit-text-size-adjust: 100%; 60 | -ms-text-size-adjust: 100%; 61 | } 62 | 63 | /* No `:visited` state is required by default (browsers will use `a`) */ 64 | a { 65 | color: #268bd2; 66 | text-decoration: none; 67 | } 68 | a strong { 69 | color: inherit; 70 | } 71 | /* `:focus` is linked to `:hover` for basic accessibility */ 72 | a:hover, 73 | a:focus { 74 | text-decoration: underline; 75 | } 76 | 77 | /* Headings */ 78 | h1, h2, h3, h4, h5, h6 { 79 | margin-bottom: .5rem; 80 | font-weight: bold; 81 | line-height: 1.25; 82 | color: #313131; 83 | text-rendering: optimizeLegibility; 84 | } 85 | h1 { 86 | font-size: 2rem; 87 | } 88 | h2 { 89 | margin-top: 1rem; 90 | font-size: 1.5rem; 91 | } 92 | h3 { 93 | margin-top: 1.5rem; 94 | font-size: 1.25rem; 95 | } 96 | h4, h5, h6 { 97 | margin-top: 1rem; 98 | font-size: 1rem; 99 | } 100 | 101 | /* Body text */ 102 | p { 103 | margin-top: 0; 104 | margin-bottom: 1rem; 105 | } 106 | 107 | strong { 108 | color: #303030; 109 | } 110 | 111 | 112 | /* Lists */ 113 | ul, ol, dl { 114 | margin-top: 0; 115 | margin-bottom: 1rem; 116 | } 117 | 118 | dt { 119 | font-weight: bold; 120 | } 121 | dd { 122 | margin-bottom: .5rem; 123 | } 124 | 125 | /* Misc */ 126 | hr { 127 | position: relative; 128 | margin: 1.5rem 0; 129 | border: 0; 130 | border-top: 1px solid #eee; 131 | border-bottom: 1px solid #fff; 132 | } 133 | 134 | abbr { 135 | font-size: 85%; 136 | font-weight: bold; 137 | color: #555; 138 | text-transform: uppercase; 139 | } 140 | abbr[title] { 141 | cursor: help; 142 | border-bottom: 1px dotted #e5e5e5; 143 | } 144 | 145 | /* Code */ 146 | code, 147 | pre { 148 | font-family: "Roboto Mono", monospace; 149 | } 150 | code { 151 | padding: .2em .2em; 152 | font-size: 90%; 153 | background-color: #f9f9f9; 154 | border-radius: 3px; 155 | } 156 | 157 | @media (max-width: 70em) { 158 | code { 159 | white-space: pre-wrap; 160 | word-break: break-all; 161 | word-wrap: break-word; 162 | } 163 | } 164 | pre { 165 | display: block; 166 | margin-top: 0; 167 | font-size: .8rem; 168 | line-height: 1.4; 169 | background-color: #f9f9f9; 170 | } 171 | @media (min-width: 70em) { 172 | pre { 173 | display: inline-block; 174 | min-width: 50em; 175 | white-space: pre; 176 | } 177 | } 178 | @media (min-width: 70em) { 179 | pre code { 180 | display: inline-block; 181 | min-width: 50em; 182 | } 183 | } 184 | pre code { 185 | padding: 0; 186 | font-size: 100%; 187 | color: black; 188 | background-color: transparent; 189 | } 190 | 191 | /* Pygments via Jekyll */ 192 | .highlight { 193 | margin-bottom: 1rem; 194 | border-radius: 4px; 195 | } 196 | .highlight pre { 197 | margin-bottom: 0; 198 | } 199 | 200 | /* Gist via GitHub Pages */ 201 | .gist .gist-file { 202 | font-family: Menlo, Monaco, "Courier New", monospace !important; 203 | } 204 | .gist .markdown-body { 205 | padding: 15px; 206 | } 207 | .gist pre { 208 | padding: 0; 209 | background-color: transparent; 210 | } 211 | .gist .gist-file .gist-data { 212 | font-size: .8rem !important; 213 | line-height: 1.4; 214 | } 215 | .gist code { 216 | padding: 0; 217 | color: inherit; 218 | background-color: transparent; 219 | border-radius: 0; 220 | } 221 | 222 | /* Quotes */ 223 | blockquote { 224 | padding: .5rem 1rem; 225 | margin: .8rem 0; 226 | color: #7a7a7a; 227 | border-left: .25rem solid #e5e5e5; 228 | } 229 | blockquote p:last-child { 230 | margin-bottom: 0; 231 | } 232 | @media (min-width: 30em) { 233 | blockquote { 234 | padding-right: 5rem; 235 | padding-left: 1.25rem; 236 | } 237 | } 238 | 239 | img { 240 | display: block; 241 | max-width: 100%; 242 | margin: 0 0 1rem; 243 | border-radius: 5px; 244 | } 245 | 246 | /* Tables */ 247 | table { 248 | margin-bottom: 1rem; 249 | width: 100%; 250 | border: 1px solid #e5e5e5; 251 | border-collapse: collapse; 252 | } 253 | td, 254 | th { 255 | padding: .25rem .5rem; 256 | border: 1px solid #e5e5e5; 257 | } 258 | tbody tr:nth-child(odd) td, 259 | tbody tr:nth-child(odd) th { 260 | background-color: #f9f9f9; 261 | } 262 | 263 | 264 | /* 265 | * Custom type 266 | * 267 | * Extend paragraphs with `.lead` for larger introductory text. 268 | */ 269 | 270 | .lead { 271 | font-size: 1.25rem; 272 | font-weight: 300; 273 | } 274 | 275 | 276 | /* 277 | * Messages 278 | * 279 | * Show alert messages to users. You may add it to single elements like a `

`, 280 | * or to a parent if there are multiple elements to show. 281 | */ 282 | 283 | .message { 284 | margin-bottom: 1rem; 285 | padding: 1rem; 286 | color: #717171; 287 | background-color: #f9f9f9; 288 | } 289 | 290 | 291 | /* 292 | * Container 293 | * 294 | * Center the page content. 295 | */ 296 | 297 | .container { 298 | max-width: 38rem; 299 | padding-left: 1rem; 300 | padding-right: 1rem; 301 | margin-left: auto; 302 | margin-right: auto; 303 | } 304 | 305 | 306 | /* 307 | * Masthead 308 | * 309 | * Super small header above the content for site name and short description. 310 | */ 311 | 312 | .masthead { 313 | padding-top: 1rem; 314 | padding-bottom: 1rem; 315 | margin-bottom: 3rem; 316 | } 317 | .masthead-title { 318 | margin-top: 0; 319 | margin-bottom: 0; 320 | color: #505050; 321 | } 322 | .masthead-title a { 323 | color: #505050; 324 | } 325 | .masthead-title small { 326 | font-size: 75%; 327 | font-weight: 400; 328 | color: #c0c0c0; 329 | letter-spacing: 0; 330 | } 331 | 332 | 333 | /* 334 | * Posts and pages 335 | * 336 | * Each post is wrapped in `.post` and is used on default and post layouts. Each 337 | * page is wrapped in `.page` and is only used on the page layout. 338 | */ 339 | 340 | .page, 341 | .post { 342 | margin-bottom: 4em; 343 | } 344 | 345 | /* Blog post or page title */ 346 | .page-title, 347 | .post-title, 348 | .post-title a { 349 | color: #303030; 350 | } 351 | .page-title, 352 | .post-title { 353 | margin-top: 0; 354 | } 355 | 356 | /* Meta data line below post title */ 357 | .post-date { 358 | display: block; 359 | margin-top: -.5rem; 360 | margin-bottom: 1rem; 361 | color: #9a9a9a; 362 | } 363 | 364 | /* Related posts */ 365 | .related { 366 | padding-top: 2rem; 367 | padding-bottom: 2rem; 368 | border-top: 1px solid #eee; 369 | } 370 | .related-posts { 371 | padding-left: 0; 372 | list-style: none; 373 | } 374 | .related-posts h3 { 375 | margin-top: 0; 376 | } 377 | .related-posts li small { 378 | font-size: 75%; 379 | color: #999; 380 | } 381 | .related-posts li a:hover { 382 | color: #268bd2; 383 | text-decoration: none; 384 | } 385 | .related-posts li a:hover small { 386 | color: inherit; 387 | } 388 | 389 | 390 | /* 391 | * Pagination 392 | * 393 | * Super lightweight (HTML-wise) blog pagination. `span`s are provide for when 394 | * there are no more previous or next posts to show. 395 | */ 396 | 397 | .pagination { 398 | overflow: hidden; /* clearfix */ 399 | margin-left: -1rem; 400 | margin-right: -1rem; 401 | font-family: "PT Sans", Helvetica, Arial, sans-serif; 402 | color: #ccc; 403 | text-align: center; 404 | } 405 | 406 | /* Pagination items can be `span`s or `a`s */ 407 | .pagination-item { 408 | display: block; 409 | padding: 1rem; 410 | border: 1px solid #eee; 411 | } 412 | .pagination-item:first-child { 413 | margin-bottom: -1px; 414 | } 415 | 416 | /* Only provide a hover state for linked pagination items */ 417 | a.pagination-item:hover { 418 | background-color: #f5f5f5; 419 | } 420 | 421 | @media (min-width: 30em) { 422 | .pagination { 423 | margin: 3rem 0; 424 | } 425 | .pagination-item { 426 | float: left; 427 | width: 50%; 428 | } 429 | .pagination-item:first-child { 430 | margin-bottom: 0; 431 | border-top-left-radius: 4px; 432 | border-bottom-left-radius: 4px; 433 | } 434 | .pagination-item:last-child { 435 | margin-left: -1px; 436 | border-top-right-radius: 4px; 437 | border-bottom-right-radius: 4px; 438 | } 439 | } 440 | -------------------------------------------------------------------------------- /public/images/bg_hr.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/public/images/bg_hr.png -------------------------------------------------------------------------------- /public/images/blacktocat.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/public/images/blacktocat.png -------------------------------------------------------------------------------- /public/images/icon_download.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/public/images/icon_download.png -------------------------------------------------------------------------------- /public/images/sprite_download.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/public/images/sprite_download.png -------------------------------------------------------------------------------- /scripts/Makefile: -------------------------------------------------------------------------------- 1 | # This Makefile is supposed to run on the Travis CI server and also locally 2 | # it assumes the nodejs package managaer npm is installed 3 | 4 | # make magic not needed 5 | MAKEFLAGS += --no-builtin-rules 6 | .SUFFIXES: 7 | 8 | BUILD_DIR=build 9 | SOURCEFILE = CppCoreGuidelines.md 10 | SOURCEPATH = ../$(SOURCEFILE) 11 | 12 | .PHONY: default 13 | default: all 14 | 15 | .PHONY: all 16 | all: \ 17 | check-markdown \ 18 | check-references \ 19 | check-notabs \ 20 | hunspell-check \ 21 | cpplint-all \ 22 | check-badchars 23 | 24 | $(BUILD_DIR): 25 | @mkdir -p $(BUILD_DIR) 26 | 27 | #### clean: remove all files generated by the productive rules 28 | .PHONY: clean 29 | clean: 30 | rm -rf $(BUILD_DIR) 31 | 32 | #### distclean: remove all helper executables that may be downloaded by the Makefile 33 | .PHONY: distclean 34 | distclean: 35 | rm -rf ./nodejs/node_modules 36 | 37 | 38 | #### check markdown 39 | 40 | ## run remark markdown checker based on configuration in .remarkrc 41 | .PHONY: check-markdown 42 | check-markdown: nodejs/node_modules/remark nodejs/remark/.remarkrc $(SOURCEPATH) $(BUILD_DIR) Makefile 43 | echo '##################### Markdown check ##################' 44 | ## run remark, paste output to temporary file 45 | cd nodejs; ./node_modules/.bin/remark ../$(SOURCEPATH) --no-color -q --config-path ./remark/.remarkrc 1> ../$(BUILD_DIR)/$(SOURCEFILE).fixed --frail 46 | 47 | ## show a diff with changes remark suggests 48 | .PHONY: show-diff 49 | show-diff: nodejs/node_modules/remark nodejs/remark/.remarkrc $(SOURCEPATH) $(BUILD_DIR) Makefile 50 | cd nodejs; ./node_modules/.bin/remark ../$(SOURCEPATH) --no-color -q --config-path ./remark/.remarkrc 1> ../$(BUILD_DIR)/$(SOURCEFILE).fixed 51 | ## compare temporary file to original, error and fail with message if differences exist 52 | diff $(SOURCEPATH) $(BUILD_DIR)/$(SOURCEFILE).fixed -u3 || \ 53 | (echo "Error: remark found bad markdown syntax, see output above" && false) 54 | 55 | 56 | .PHONY: check-references 57 | check-references: $(SOURCEPATH) $(BUILD_DIR) Makefile 58 | @echo '##################### References check ##################' 59 | ## check references unique 60 | @rm -f $(BUILD_DIR)/$(SOURCEFILE).uniq 61 | @cat $(SOURCEPATH) | perl -ne 'print "$$1\n" if (/ $(BUILD_DIR)/$(SOURCEFILE).uniq 62 | ## check if output has data 63 | @if [ -s "build/CppCoreGuidelines.md.uniq" ]; then echo 'Found duplicate anchors:'; cat $(BUILD_DIR)/$(SOURCEFILE).uniq; false; fi 64 | 65 | .PHONY: check-notabs 66 | check-notabs: $(SOURCEPATH) $(BUILD_DIR) Makefile 67 | @echo '##################### Tabs check ##################' 68 | # find lines with tabs 69 | # old file still might be around 70 | @rm -f $(BUILD_DIR)/CppCoreGuidelines.md.tabs 71 | # print file, add line numbers, remove tabs from nl tool, grep for remaining tabs, replace with stars 72 | @cat ../$(SOURCEFILE) | nl -ba | perl -pe 's/(^[^\t]*)\t/$1--/g' | perl -ne 'print if /\t/' | perl -pe 's/\t/\*\*\*\*/g' > $(BUILD_DIR)/$(SOURCEFILE).tabs 73 | @if [ -s $(BUILD_DIR)/CppCoreGuidelines.md.tabs ]; then echo 'Warning: Tabs found:'; cat $(BUILD_DIR)/CppCoreGuidelines.md.tabs; false; fi; 74 | 75 | .PHONY: check-badchars 76 | check-badchars: $(SOURCEPATH) $(BUILD_DIR) Makefile 77 | @echo '##################### Bad chars check ##################' 78 | # find lines with tabs 79 | # old file still might be around 80 | @rm -f $(BUILD_DIR)/CppCoreGuidelines.md.badchars 81 | # print file, add line numbers, grep for bad chars 82 | @cat ../$(SOURCEFILE) | nl -ba | perl -ne 'print if /’|‘|”|“|¸| |–|…|¦/' > $(BUILD_DIR)/$(SOURCEFILE).badchars || true 83 | @if [ -s $(BUILD_DIR)/CppCoreGuidelines.md.badchars ]; then echo 'Warning: Undesired chars (–’‘“”¸…¦) or Unicode EN SPACE found, use markdown-compatible symbols instead:'; cat $(BUILD_DIR)/CppCoreGuidelines.md.badchars; false; fi; 84 | 85 | 86 | .PHONY: hunspell-check 87 | hunspell-check: $(BUILD_DIR)/plain-nohtml.txt 88 | @echo '##################### Spell check ##################' 89 | sed -e 's!http\(s\)\{0,1\}://[^[:space:]]*!!g' build/plain-nohtml.txt | hunspell -d hunspell/en_US -p hunspell/isocpp.dic -u > $(BUILD_DIR)/hunspell-report.txt 90 | @if [ -s $(BUILD_DIR)/hunspell-report.txt ]; then echo 'Warning: Spellcheck failed, fix words or add to dictionary:'; cat $(BUILD_DIR)/hunspell-report.txt; false; fi; 91 | 92 | # only list words that are not in dict 93 | # to include all add them to bottom of hunspell/isocpp.dict, and run 94 | # cat hunspell/isocpp.dic | sort | uniq > hunspell/isocpp.dic2; mv hunspell/isocpp.dic2 hunspell/isocpp.dic 95 | .PHONY: hunspell-list 96 | hunspell-list: $(BUILD_DIR)/plain.txt 97 | sed -e 's!http\(s\)\{0,1\}://[^[:space:]]*!!g' build/plain-nohtml.txt | hunspell -p hunspell/isocpp.dic -l 98 | 99 | #### Cpplint 100 | 101 | .PHONY: cpplint-all 102 | cpplint-all: $(BUILD_DIR)/codeblocks $(BUILD_DIR)/Makefile python/Makefile.in 103 | @echo '##################### C++ Style check ##################' 104 | cd $(BUILD_DIR)/codeblocks; $(MAKE) cpplint-all -k 105 | 106 | #### generic makefile for sourceblocks (need to be evaluated after c++ file generation) 107 | 108 | $(BUILD_DIR)/Makefile: python/Makefile.in 109 | @cp python/Makefile.in $(BUILD_DIR)/codeblocks/Makefile 110 | 111 | #### split md file into plain text and code 112 | 113 | $(BUILD_DIR)/codeblocks: splitfile 114 | 115 | $(BUILD_DIR)/plain.txt: splitfile 116 | 117 | $(BUILD_DIR)/plain-nohtml.txt: $(BUILD_DIR)/plain.txt 118 | sed 's;|<[^>]*>)') 15 | NAMED_A_TAG_REGEX = re.compile(r'.*name ?= ?"([^"]*)"') 16 | 17 | def main(): 18 | """ 19 | This script ended up ugly, so in case somebody wants to reimplement, here is the spec that grew by time. 20 | 21 | What it should do it take a markdown file, and split it into more files. A targetfile should have the same 22 | number of lines as the original, with source code snippets and markdown non-words removed, for spell-checking. 23 | 24 | Each code snipped should go into a separate file in codedir. 25 | 26 | Each code snipped should get additional C++ code around it to help compile the line in context, with 27 | some heuristic guessing of what is needed around. The wrapping code should have a token in each line allowing 28 | other tools to filter out these lines 29 | 30 | The name for each file chosen consists os the section id in the markdown document, a counter for the snippet inside the section. 31 | 32 | Snippets without code (only comments) or containing lines starting with ??? should not yeld files, 33 | but the counter for naming snippets should still increment. 34 | """ 35 | parser = argparse.ArgumentParser(description='Split md file into plain text and code blocks') 36 | parser.add_argument('sourcefile', 37 | help='which file to read') 38 | parser.add_argument('targetfile', 39 | help='where to put plain text') 40 | parser.add_argument('codedir', 41 | help='where to put codeblocks') 42 | args = parser.parse_args() 43 | 44 | # ensure folder exists 45 | if not os.path.exists(args.codedir): 46 | os.makedirs(args.codedir) 47 | 48 | 49 | if os.path.exists(args.targetfile): 50 | os.remove(args.targetfile) 51 | 52 | code_block_index = 0 53 | last_header = '' 54 | linenum = 0 55 | with io.open(args.sourcefile, 'r') as read_filehandle: 56 | with io.open(args.targetfile, 'w') as text_filehandle: 57 | for line in read_filehandle: 58 | linenum += 1 59 | indent_depth = is_code(line) 60 | if indent_depth: 61 | (line, linenum) = process_code(read_filehandle, 62 | text_filehandle, 63 | line, linenum, 64 | args.sourcefile, args.codedir, 65 | last_header, code_block_index, 66 | indent_depth) 67 | code_block_index += 1 68 | # reach here either line was not code, or was code 69 | # and we dealt with n code lines 70 | if indent_depth < 4 or not is_code(line, indent_depth): 71 | # store header id for codeblock 72 | section_id = get_marker(line) 73 | if section_id is not None: 74 | code_block_index = 0 75 | last_header = section_id 76 | sline = stripped(line) 77 | text_filehandle.write(sline) 78 | 79 | assert line_length(args.sourcefile) == line_length(args.targetfile) 80 | 81 | 82 | def process_code(read_filehandle, text_filehandle, line, linenum, sourcefile, codedir, name, index, indent_depth): 83 | fenced = (line.strip() == '```') 84 | if fenced: 85 | try: 86 | line = read_filehandle.readLine() 87 | linenum += 1 88 | text_filehandle.write('\n') 89 | except StopIteration: 90 | return ('', linenum) 91 | start_linenum = linenum 92 | has_actual_code = False 93 | has_question_marks = False 94 | linebuffer = [] 95 | while ((fenced and line.strip() != '```') or (not fenced and is_inside_code(line, indent_depth))): 96 | # copy comments to plain text for spell check 97 | comment_idx = line.find('//') 98 | no_comment_line = line 99 | if comment_idx >= 0: 100 | no_comment_line = line[:comment_idx].strip() 101 | text_filehandle.write(line[comment_idx + 2:]) 102 | else: 103 | # write empty line so line numbers stay stable 104 | text_filehandle.write('\n') 105 | 106 | if (not has_actual_code 107 | and not line.strip().startswith('//') 108 | and not line.strip().startswith('???') 109 | and not line.strip() == ''): 110 | has_actual_code = True 111 | 112 | if (not line.strip() == '```'): 113 | if ('???' == no_comment_line or '...' == no_comment_line): 114 | has_question_marks = True 115 | linebuffer.append(dedent(line, indent_depth) if not fenced else line) 116 | try: 117 | line = read_filehandle.readline() 118 | linenum += 1 119 | except StopIteration: 120 | line = '' 121 | break 122 | codefile = os.path.join(codedir, '%s%s.cpp' % (name, index)) 123 | if fenced: 124 | text_filehandle.write('\n') 125 | 126 | if (has_actual_code and not has_question_marks): 127 | linebuffer = clean_trailing_newlines(linebuffer) 128 | write_with_harness(codefile, sourcefile, start_linenum, linebuffer) 129 | return (line, linenum) 130 | 131 | 132 | def clean_trailing_newlines(linebuffer): 133 | result = [] 134 | code_started = False 135 | linebuffer.reverse() 136 | for line in linebuffer: 137 | if not code_started and line == '\n': 138 | continue 139 | code_started = True 140 | result.append(line) 141 | result.reverse() 142 | return result 143 | 144 | 145 | def write_with_harness(codefile, sourcefile, start_linenum, linebuffer): 146 | '''write output with additional lines to make code likely compilable''' 147 | # add commonly used headers, so that lines can likely compile. 148 | # This is work in progress, the main issue remains handling class 149 | # declarations in in-function code differently 150 | with io.open(codefile, 'w') as code_filehandle: 151 | code_filehandle.write('''\ 152 | #include // by md-split 153 | #include // by md-split 154 | #include // by md-split 155 | #include // by md-split 156 | #include // by md-split 157 | #include // by md-split 158 | #include // by md-split 159 | #include // by md-split 160 | #include // by md-split 161 | #include // by md-split 162 | #include // by md-split 163 | #include // by md-split 164 | using namespace std; // by md-split 165 | // %s : %s 166 | ''' % (sourcefile, start_linenum)) 167 | # TODO: if not toplevel code, wrap inside class 168 | for codeline in linebuffer: 169 | code_filehandle.write(codeline) 170 | 171 | 172 | def is_code(line, indent_depth = 4): 173 | '''returns the indent depth, 0 means not code in markup''' 174 | if line.startswith(' ' * indent_depth): 175 | return len(line) - len(line.lstrip(' ')) 176 | return 0 177 | 178 | def is_inside_code(line, indent_depth): 179 | return is_code(line, indent_depth) > 0 or line.strip() == '' 180 | 181 | def stripped(line): 182 | # Remove well-formed html tags, fixing mistakes by legitimate users 183 | sline = TAG_REGEX.sub('', line) 184 | sline = re.sub('[()\[\]#*]', ' ', line) 185 | return sline 186 | 187 | def dedent(line, indent_depth): 188 | if line.startswith(' ' * indent_depth): 189 | return line[indent_depth:] 190 | if line.startswith('\t'): 191 | return line[1:] 192 | return line 193 | 194 | def get_marker(line): 195 | matchlist = TAG_REGEX.findall(line) 196 | if matchlist: 197 | namematch = NAMED_A_TAG_REGEX.match(line) 198 | if namematch: 199 | return namematch.group(1) # group 0 is full match 200 | 201 | return None 202 | 203 | def line_length(filename): 204 | return sum(1 for line in open(filename)) 205 | 206 | if __name__ == '__main__': 207 | main() 208 | -------------------------------------------------------------------------------- /talks/Contracts-for-Dependable-C++.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/talks/Contracts-for-Dependable-C++.pdf -------------------------------------------------------------------------------- /talks/Large-Scale-C++-With-Modules.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/talks/Large-Scale-C++-With-Modules.pdf -------------------------------------------------------------------------------- /talks/MacIntosh - A Few Good Types.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/talks/MacIntosh - A Few Good Types.pdf -------------------------------------------------------------------------------- /talks/MacIntosh - Static Analysis and C++.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/talks/MacIntosh - Static Analysis and C++.pdf -------------------------------------------------------------------------------- /talks/README.md: -------------------------------------------------------------------------------- 1 | The guidelines were introduced during a number of talks at [CppCon](http://cppcon.org) 2015. 2 | Here are video recordings of those talks: 3 | 4 | - [Keynote: Writing Good C++ 14 (Bjarne Stroustrup)](https://www.youtube.com/watch?t=9&v=1OEu9C51K2A) 5 | - [Writing good C++ 14 By Default (Herb Sutter)](https://www.youtube.com/watch?v=hEx5DNLWGgA]) 6 | - [Large Scale C++ With Modules: What You Should Know (Gabriel Dos Reis)](https://www.youtube.com/watch?v=RwdQA0pGWa4) 7 | - [Contracts for Dependable C++ (Gabriel Dos Reis)](https://www.youtube.com/watch?v=Hjz1eBx91g8) 8 | - [Static analysis and C++: more than lint (Neil MacIntosh)](https://www.youtube.com/watch?v=rKlHvAw1z50) 9 | - [A few good types: Evolving `array_view` and `string_view` for safe C++ code (Neil MacIntosh)](https://www.youtube.com/watch?v=C4Z3c4Sv52U) 10 | 11 | The YouTube channel for [CppCon](http://cppcon.org) is [here](https://www.youtube.com/channel/UCMlGfpWw-RUdWX_JbLCukXg). 12 | 13 | Slides from the talks are available in this folder. 14 | -------------------------------------------------------------------------------- /talks/Stroustrup - CppCon 2015 keynote.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/talks/Stroustrup - CppCon 2015 keynote.pdf -------------------------------------------------------------------------------- /talks/Sutter - CppCon 2015 day 2 plenary .pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/cb0744e931fd9f441649d9a31b6acdbaa789109d/talks/Sutter - CppCon 2015 day 2 plenary .pdf --------------------------------------------------------------------------------