-
Notifications
You must be signed in to change notification settings - Fork 29.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
A headers only library to support following the C++ Core Guidelines. Refs: https://github.com/Microsoft/GSL Refs: http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-gsl
- Loading branch information
Showing
14 changed files
with
4,762 additions
and
12 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
## Contributing to the Guideline Support Library | ||
|
||
The Guideline Support Library (GSL) contains functions and types that are suggested for use by the | ||
[C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines). GSL design changes are made only as a result of modifications to the Guidelines. | ||
|
||
GSL is accepting contributions that improve or refine any of the types in this library as well as ports to other platforms. Changes should have an issue | ||
tracking the suggestion that has been approved by the maintainers. Your pull request should include a link to the bug that you are fixing. If you've submitted | ||
a PR, please post a comment in the associated issue to avoid duplication of effort. | ||
|
||
## Legal | ||
You will need to complete a Contributor License Agreement (CLA). Briefly, this agreement testifies that you are granting us and the community permission to | ||
use the submitted change according to the terms of the project's license, and that the work being submitted is under appropriate copyright. | ||
|
||
Please submit a Contributor License Agreement (CLA) before submitting a pull request. You may visit https://cla.microsoft.com to sign digitally. | ||
|
||
## Housekeeping | ||
Your pull request should: | ||
|
||
* Include a description of what your change intends to do | ||
* Be a child commit of a reasonably recent commit in the **master** branch | ||
* Requests need not be a single commit, but should be a linear sequence of commits (i.e. no merge commits in your PR) | ||
* It is desirable, but not necessary, for the tests to pass at each commit. Please see [README.md](./README.md) for instructions to build the test suite. | ||
* Have clear commit messages | ||
* e.g. "Fix issue", "Add tests for type", etc. | ||
* Include appropriate tests | ||
* Tests should include reasonable permutations of the target fix/change | ||
* Include baseline changes with your change | ||
* All changed code must have 100% code coverage | ||
* To avoid line ending issues, set `autocrlf = input` and `whitespace = cr-at-eol` in your git configuration |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
Copyright (c) 2015 Microsoft Corporation. All rights reserved. | ||
|
||
This code is licensed under the MIT License (MIT). | ||
|
||
Permission is hereby granted, free of charge, to any person obtaining a copy | ||
of this software and associated documentation files (the "Software"), to deal | ||
in the Software without restriction, including without limitation the rights | ||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies | ||
of the Software, and to permit persons to whom the Software is furnished to do | ||
so, subject to the following conditions: | ||
|
||
The above copyright notice and this permission notice shall be included in all | ||
copies or substantial portions of the Software. | ||
|
||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN | ||
THE SOFTWARE. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,94 @@ | ||
# GSL: Guideline Support Library [![Build Status](https://travis-ci.org/Microsoft/GSL.svg?branch=master)](https://travis-ci.org/Microsoft/GSL) [![Build status](https://ci.appveyor.com/api/projects/status/github/Microsoft/GSL?svg=true)](https://ci.appveyor.com/project/neilmacintosh/GSL) | ||
|
||
The Guideline Support Library (GSL) contains functions and types that are suggested for use by the | ||
[C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines) maintained by the [Standard C++ Foundation](https://isocpp.org). | ||
This repo contains Microsoft's implementation of GSL. | ||
|
||
The library includes types like `span<T>`, `string_span`, `owner<>` and others. | ||
|
||
The entire implementation is provided inline in the headers under the [gsl](./include/gsl) directory. The implementation generally assumes a platform that implements C++14 support. There are specific workarounds to support MSVC 2015. | ||
|
||
While some types have been broken out into their own headers (e.g. [gsl/span](./include/gsl/span)), | ||
it is simplest to just include [gsl/gsl](./include/gsl/gsl) and gain access to the entire library. | ||
|
||
> NOTE: We encourage contributions that improve or refine any of the types in this library as well as ports to | ||
other platforms. Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for more information about contributing. | ||
|
||
# Project Code of Conduct | ||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. | ||
|
||
# Usage of Third Party Libraries | ||
This project makes use of the [Catch](https://github.com/philsquared/catch) testing library. Please see the [ThirdPartyNotices.txt](./ThirdPartyNotices.txt) file for details regarding the licensing of Catch. | ||
|
||
# Quick Start | ||
## Supported Platforms | ||
The test suite that exercises GSL has been built and passes successfully on the following platforms:<sup>1)</sup> | ||
|
||
* Windows using Visual Studio 2015 | ||
* Windows using Visual Studio 2017 | ||
* Windows using Clang/LLVM 3.6 | ||
* Windows using GCC 5.1 | ||
* Windows using Intel C++ Compiler 18.0 | ||
* GNU/Linux using Clang/LLVM 3.6 | ||
* GNU/Linux using GCC 5.1 | ||
* OS X Yosemite using Xcode with Apple Clang 7.0.0.7000072 | ||
* OS X Yosemite using GCC-5.2.0 | ||
* OS X Sierra 10.12.4 using Apple LLVM version 8.1.0 (Clang-802.0.42) | ||
* OS X El Capitan (10.11) using Xcode with AppleClang 8.0.0.8000042 | ||
* OS X High Sierra 10.13.2 (17C88) using Apple LLVM version 9.0.0 (clang-900.0.39.2) | ||
* FreeBSD 10.x with Clang/LLVM 3.6 | ||
|
||
> If you successfully port GSL to another platform, we would love to hear from you. Please submit an issue to let us know. Also please consider | ||
contributing any changes that were necessary back to this project to benefit the wider community. | ||
|
||
<sup>1)</sup> For `gsl::byte` to work correctly with Clang and GCC you might have to use the ` -fno-strict-aliasing` compiler option. | ||
|
||
## Building the tests | ||
To build the tests, you will require the following: | ||
|
||
* [CMake](http://cmake.org), version 3.1.3 or later to be installed and in your PATH. | ||
|
||
These steps assume the source code of this repository has been cloned into a directory named `c:\GSL`. | ||
|
||
1. Create a directory to contain the build outputs for a particular architecture (we name it c:\GSL\build-x86 in this example). | ||
|
||
cd GSL | ||
md build-x86 | ||
cd build-x86 | ||
|
||
2. Configure CMake to use the compiler of your choice (you can see a list by running `cmake --help`). | ||
|
||
cmake -G "Visual Studio 14 2015" c:\GSL | ||
|
||
3. Build the test suite (in this case, in the Debug configuration, Release is another good choice). | ||
|
||
cmake --build . --config Debug | ||
|
||
4. Run the test suite. | ||
|
||
ctest -C Debug | ||
|
||
All tests should pass - indicating your platform is fully supported and you are ready to use the GSL types! | ||
|
||
## Using the libraries | ||
As the types are entirely implemented inline in headers, there are no linking requirements. | ||
|
||
You can copy the [gsl](./include/gsl) directory into your source tree so it is available | ||
to your compiler, then include the appropriate headers in your program. | ||
|
||
Alternatively set your compiler's *include path* flag to point to the GSL development folder (`c:\GSL\include` in the example above) or installation folder (after running the install). Eg. | ||
|
||
MSVC++ | ||
|
||
/I c:\GSL\include | ||
|
||
GCC/clang | ||
|
||
-I$HOME/dev/GSL/include | ||
|
||
Include the library using: | ||
|
||
#include <gsl/gsl> | ||
|
||
## Debugging visualization support | ||
For Visual Studio users, the file [GSL.natvis](./GSL.natvis) in the root directory of the repository can be added to your project if you would like more helpful visualization of GSL types in the Visual Studio debugger than would be offered by default. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
/////////////////////////////////////////////////////////////////////////////// | ||
// | ||
// Copyright (c) 2015 Microsoft Corporation. All rights reserved. | ||
// | ||
// This code is licensed under the MIT License (MIT). | ||
// | ||
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN | ||
// THE SOFTWARE. | ||
// | ||
/////////////////////////////////////////////////////////////////////////////// | ||
|
||
#ifndef GSL_GSL_H | ||
#define GSL_GSL_H | ||
|
||
#include <gsl/gsl_algorithm> // copy | ||
#include <gsl/gsl_assert> // Ensures/Expects | ||
#include <gsl/gsl_byte> // byte | ||
#include <gsl/gsl_util> // finally()/narrow()/narrow_cast()... | ||
#include <gsl/multi_span> // multi_span, strided_span... | ||
#include <gsl/pointers> // owner, not_null | ||
#include <gsl/span> // span | ||
#include <gsl/string_span> // zstring, string_span, zstring_builder... | ||
|
||
#endif // GSL_GSL_H |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,61 @@ | ||
/////////////////////////////////////////////////////////////////////////////// | ||
// | ||
// Copyright (c) 2015 Microsoft Corporation. All rights reserved. | ||
// | ||
// This code is licensed under the MIT License (MIT). | ||
// | ||
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN | ||
// THE SOFTWARE. | ||
// | ||
/////////////////////////////////////////////////////////////////////////////// | ||
|
||
#ifndef GSL_ALGORITHM_H | ||
#define GSL_ALGORITHM_H | ||
|
||
#include <gsl/gsl_assert> // for Expects | ||
#include <gsl/span> // for dynamic_extent, span | ||
|
||
#include <algorithm> // for copy_n | ||
#include <cstddef> // for ptrdiff_t | ||
#include <type_traits> // for is_assignable | ||
|
||
#ifdef _MSC_VER | ||
#pragma warning(push) | ||
|
||
// turn off some warnings that are noisy about our Expects statements | ||
#pragma warning(disable : 4127) // conditional expression is constant | ||
#pragma warning(disable : 4996) // unsafe use of std::copy_n | ||
|
||
#endif // _MSC_VER | ||
|
||
namespace gsl | ||
{ | ||
// Note: this will generate faster code than std::copy using span iterator in older msvc+stl | ||
// not necessary for msvc since VS2017 15.8 (_MSC_VER >= 1915) | ||
template <class SrcElementType, std::ptrdiff_t SrcExtent, class DestElementType, | ||
std::ptrdiff_t DestExtent> | ||
void copy(span<SrcElementType, SrcExtent> src, span<DestElementType, DestExtent> dest) | ||
{ | ||
static_assert(std::is_assignable<decltype(*dest.data()), decltype(*src.data())>::value, | ||
"Elements of source span can not be assigned to elements of destination span"); | ||
static_assert(SrcExtent == dynamic_extent || DestExtent == dynamic_extent || | ||
(SrcExtent <= DestExtent), | ||
"Source range is longer than target range"); | ||
|
||
Expects(dest.size() >= src.size()); | ||
GSL_SUPPRESS(stl.1) // NO-FORMAT: attribute | ||
std::copy_n(src.data(), src.size(), dest.data()); | ||
} | ||
|
||
} // namespace gsl | ||
|
||
#ifdef _MSC_VER | ||
#pragma warning(pop) | ||
#endif // _MSC_VER | ||
|
||
#endif // GSL_ALGORITHM_H |
Oops, something went wrong.