README improvements, minor cleanups (#1226)

Co-authored-by: mnatsuhara <[email protected]>

Author: StephanTLavavej

README.md

@@ -1,8 +1,11 @@
 # Microsoft's C++ Standard Library
 
 This is the official repository for Microsoft's implementation of the C++ Standard Library (also known as the STL),
-which ships as part of the MSVC toolset and the Visual Studio IDE. Our [Changelog][] tracks which updates to this
-repository appear in each VS release.
+which ships as part of the MSVC toolset and the Visual Studio IDE.
+
+* Our [Changelog][] tracks which updates to this repository appear in each VS release.
+* Our [Status Chart][] displays our overall progress over time.
+* Join our [Discord server][].
 
 [![Build Status](https://dev.azure.com/vclibs/STL/_apis/build/status/microsoft.STL?branchName=master)][Pipelines]
 
@@ -147,30 +150,39 @@ acquire this dependency.
 2. Open Visual Studio, and choose the "Clone or check out code" option. Enter the URL of this repository,
    `https://github.com/microsoft/STL`.
 3. Open a terminal in the IDE with `` Ctrl + ` `` (by default) or press on "View" in the top bar, and then "Terminal".
-4. Invoke `git submodule update --init vcpkg` in the terminal.
-5. Invoke `.\vcpkg\bootstrap-vcpkg.bat` in the terminal.
-6. Invoke `.\vcpkg\vcpkg.exe install boost-math:x86-windows boost-math:x64-windows` to install the boost-math dependency.
+4. In the terminal, invoke `git submodule update --init vcpkg`
+5. In the terminal, invoke `.\vcpkg\bootstrap-vcpkg.bat`
+6. In the terminal, invoke `.\vcpkg\vcpkg.exe install boost-math:x86-windows boost-math:x64-windows`
 7. Choose the architecture you wish to build in the IDE, and build as you would any other project. All necessary CMake
    settings are set by `CMakeSettings.json`.
 
 # How To Build With A Native Tools Command Prompt
 
-These instructions assume you're targeting `x64-windows`; you can change this constant below to target other
-architectures.
-
 1. Install Visual Studio 2019 16.8 Preview 1 or later.
     * We recommend selecting "C++ CMake tools for Windows" in the VS Installer.
     This will ensure that you're using supported versions of CMake and Ninja.
     * Otherwise, install [CMake][] 3.17 or later, and [Ninja][] 1.8.2 or later.
-2. Open an "x64 Native Tools Command Prompt for VS 2019".
+2. Open a command prompt.
 3. Change directories to a location where you'd like a clone of this STL repository.
-4. Invoke `git clone https://github.com/microsoft/STL`
-5. Invoke `cd STL`
-6. Invoke `git submodule update --init vcpkg`
-7. Invoke `.\vcpkg\bootstrap-vcpkg.bat`
-8. Invoke `.\vcpkg\vcpkg.exe install boost-math:x86-windows boost-math:x64-windows` to install the boost-math dependency.
-9. Invoke `cmake -G Ninja -S . -B {wherever you want binaries}` to configure the project. For example, `cmake -G Ninja -S . -B out\build\x64`
-10. Invoke `ninja -C {wherever you want binaries}` to build the project. For example, `ninja -C out\build\x64`
+4. `git clone https://github.com/microsoft/STL`
+5. `cd STL`
+6. `git submodule update --init vcpkg`
+7. `.\vcpkg\bootstrap-vcpkg.bat`
+8. `.\vcpkg\vcpkg.exe install boost-math:x86-windows boost-math:x64-windows`
+
+To build the x86 target:
+
+1. Open an "x86 Native Tools Command Prompt for VS 2019".
+2. Change directories to the previously cloned `STL` directory.
+3. `cmake -G Ninja -S . -B out\build\x86`
+4. `ninja -C out\build\x86`
+
+To build the x64 target:
+
+1. Open an "x64 Native Tools Command Prompt for VS 2019".
+2. Change directories to the previously cloned `STL` directory.
+3. `cmake -G Ninja -S . -B out\build\x64`
+4. `ninja -C out\build\x64`
 
 # How To Consume
 
@@ -196,26 +208,26 @@ for DLL dependencies according to directories in the `PATH` environment variable
 "x64 Native Tools Command Prompt for VS 2019":
 
 ```
-C:\Users\bion\Desktop>set INCLUDE=C:\Dev\STL\out\build\x64\out\inc;%INCLUDE%
+C:\Users\username\Desktop>set INCLUDE=C:\Dev\STL\out\build\x64\out\inc;%INCLUDE%
 
-C:\Users\bion\Desktop>set LIB=C:\Dev\STL\out\build\x64\out\lib\amd64;%LIB%
+C:\Users\username\Desktop>set LIB=C:\Dev\STL\out\build\x64\out\lib\amd64;%LIB%
 
-C:\Users\bion\Desktop>set PATH=C:\Dev\STL\out\build\x64\out\bin\amd64;%PATH%
+C:\Users\username\Desktop>set PATH=C:\Dev\STL\out\build\x64\out\bin\amd64;%PATH%
 
-C:\Users\bion\Desktop>type example.cpp
+C:\Users\username\Desktop>type example.cpp
 #include <iostream>
 
 int main() {
     std::cout << "Hello STL OSS world!\n";
 }
 
-C:\Users\bion\Desktop>cl /nologo /EHsc /W4 /WX /MDd /std:c++latest .\example.cpp
+C:\Users\username\Desktop>cl /nologo /EHsc /W4 /WX /MDd /std:c++latest .\example.cpp
 example.cpp
 
-C:\Users\bion\Desktop>.\example.exe
+C:\Users\username\Desktop>.\example.exe
 Hello STL OSS world!
 
-C:\Users\bion\Desktop>dumpbin /IMPORTS .\example.exe | findstr msvcp
+C:\Users\username\Desktop>dumpbin /IMPORTS .\example.exe | findstr msvcp
     msvcp140d_oss.dll
 ```
 
@@ -244,29 +256,20 @@ under a category in libcxx, or running a single test in `std` and `tr1`.
 
 ## Examples
 
-```
-:: This command will run all of the testsuites with verbose output.
-
-C:\STL\out\build\x64>ctest -V
-
-:: This command will also run all of the testsuites.
-
-C:\STL\out\build\x64>python tests\utils\stl-lit\stl-lit.py ..\..\..\llvm-project\libcxx\test ..\..\..\tests\std ..\..\..\tests\tr1
-
-:: This command will run all of the std testsuite.
-
-C:\STL\out\build\x64>python tests\utils\stl-lit\stl-lit.py ..\..\..\tests\std
-
-:: If you want to run a subset of a testsuite you need to point it to the right place in the sources. The following
-:: will run the single test found under VSO_0000000_any_calling_conventions.
-
-C:\STL\out\build\x64>python tests\utils\stl-lit\stl-lit.py ..\..\..\tests\std\tests\VSO_0000000_any_calling_conventions
-
-:: You can invoke stl-lit with any arbitrary subdirectory of a testsuite. In libcxx this allows you to have finer
-:: control over what category of tests you would like to run. The following will run all the libcxx map tests.
-
-C:\STL\out\build\x64>python tests\utils\stl-lit\stl-lit.py ..\..\..\llvm-project\libcxx\test\std\containers\associative\map
-```
+These examples assume that your current directory is `C:\Dev\STL\out\build\x64`.
+
+* This command will run all of the testsuites with verbose output.
+  + `ctest -V`
+* This command will also run all of the testsuites.
+  + `python tests\utils\stl-lit\stl-lit.py ..\..\..\llvm-project\libcxx\test ..\..\..\tests\std ..\..\..\tests\tr1`
+* This command will run all of the std testsuite.
+  + `python tests\utils\stl-lit\stl-lit.py ..\..\..\tests\std`
+* If you want to run a subset of a testsuite, you need to point it to the right place in the sources. The following
+will run the single test found under VSO_0000000_any_calling_conventions.
+  + `python tests\utils\stl-lit\stl-lit.py ..\..\..\tests\std\tests\VSO_0000000_any_calling_conventions`
+* You can invoke `stl-lit` with any arbitrary subdirectory of a testsuite. In libcxx this allows you to have finer
+control over what category of tests you would like to run. The following will run all the libcxx map tests.
+  + `python tests\utils\stl-lit\stl-lit.py ..\..\..\llvm-project\libcxx\test\std\containers\associative\map`
 
 ## Interpreting The Results Of Tests
 
@@ -395,6 +398,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 [Code of Conduct FAQ]: https://opensource.microsoft.com/codeofconduct/faq/
 [Compiler Explorer]: https://godbolt.org
 [Developer Community]: https://developercommunity.visualstudio.com/spaces/62/index.html
+[Discord server]: https://discord.gg/XWanNww
 [How To Build With A Native Tools Command Prompt]: #how-to-build-with-a-native-tools-command-prompt
 [How To Build With The Visual Studio IDE]: #how-to-build-with-the-visual-studio-ide
 [LICENSE.txt]: LICENSE.txt
@@ -408,6 +412,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 [Pipelines]: https://dev.azure.com/vclibs/STL/_build/latest?definitionId=2&branchName=master
 [Python]: https://www.python.org/downloads/windows/
 [Roadmap]: https://github.com/microsoft/STL/wiki/Roadmap
+[Status Chart]: https://microsoft.github.io/STL/
 [Wandbox]: https://wandbox.org
 [bug tag]: https://github.com/microsoft/STL/issues?q=is%3Aopen+is%3Aissue+label%3Abug
 [cxx20 tag]: https://github.com/microsoft/STL/issues?q=is%3Aopen+is%3Aissue+label%3Acxx20

azure-devops/provision-image.ps1

@@ -99,7 +99,8 @@ $Sku = 'Enterprise'
 $VisualStudioBootstrapperUrl = 'https://aka.ms/vs/16/pre/vs_enterprise.exe'
 $PythonUrl = 'https://www.python.org/ftp/python/3.8.5/python-3.8.5-amd64.exe'
 
-$CudaUrl = 'https://developer.download.nvidia.com/compute/cuda/10.1/Prod/local_installers/cuda_10.1.243_426.00_win10.exe'
+$CudaUrl = `
+  'https://developer.download.nvidia.com/compute/cuda/10.1/Prod/local_installers/cuda_10.1.243_426.00_win10.exe'
 $CudaFeatures = 'nvcc_10.1 cuobjdump_10.1 nvprune_10.1 cupti_10.1 gpu_library_advisor_10.1 memcheck_10.1 ' + `
   'nvdisasm_10.1 nvprof_10.1 visual_profiler_10.1 visual_studio_integration_10.1 cublas_10.1 cublas_dev_10.1 ' + `
   'cudart_10.1 cufft_10.1 cufft_dev_10.1 curand_10.1 curand_dev_10.1 cusolver_10.1 cusolver_dev_10.1 cusparse_10.1 ' + `

stl/inc/valarray

@@ -1503,7 +1503,8 @@ public:
     }
 
     size_t _Off(_Sizarray& _Indexarr) const {
-        size_t _Idx, _Ans = _Start;
+        size_t _Idx;
+        size_t _Ans        = _Start;
         const size_t _Size = _Indexarr.size();
         for (_Idx = 0; _Idx < _Size; ++_Idx) {
             _Ans += _Indexarr[_Idx] * _Stride[_Idx]; // compute offset

stl/inc/xlocmon

@@ -422,7 +422,8 @@ private:
             _Ppunct_fac = _STD addressof(_STD use_facet<_Mypunct0>(_Iosbase.getloc())); // local
         }
 
-        bool _Bad = false, _Neg = false;
+        bool _Bad = false;
+        bool _Neg = false;
         string_type _Sign;
         const money_base::pattern _Pattern = _Ppunct_fac->neg_format();
         string _Val;

stl/inc/xlocnum

@@ -1297,31 +1297,35 @@ protected:
 #pragma warning(disable : 4774) // format string expected in argument N is not a string literal (/Wall)
     virtual _OutIt __CLR_OR_THIS_CALL do_put(
         _OutIt _Dest, ios_base& _Iosbase, _Elem _Fill, long _Val) const { // put formatted long to _Dest
-        char _Buf[2 * _MAX_INT_DIG], _Fmt[6];
+        char _Buf[2 * _MAX_INT_DIG];
+        char _Fmt[6];
 
         return _Iput(_Dest, _Iosbase, _Fill, _Buf,
             static_cast<size_t>(_CSTD sprintf_s(_Buf, sizeof(_Buf), _Ifmt(_Fmt, "ld", _Iosbase.flags()), _Val)));
     }
 
     virtual _OutIt __CLR_OR_THIS_CALL do_put(_OutIt _Dest, ios_base& _Iosbase, _Elem _Fill,
         unsigned long _Val) const { // put formatted unsigned long to _Dest
-        char _Buf[2 * _MAX_INT_DIG], _Fmt[6];
+        char _Buf[2 * _MAX_INT_DIG];
+        char _Fmt[6];
 
         return _Iput(_Dest, _Iosbase, _Fill, _Buf,
             static_cast<size_t>(_CSTD sprintf_s(_Buf, sizeof(_Buf), _Ifmt(_Fmt, "lu", _Iosbase.flags()), _Val)));
     }
 
     virtual _OutIt __CLR_OR_THIS_CALL do_put(
         _OutIt _Dest, ios_base& _Iosbase, _Elem _Fill, long long _Val) const { // put formatted long long to _Dest
-        char _Buf[2 * _MAX_INT_DIG], _Fmt[8];
+        char _Buf[2 * _MAX_INT_DIG];
+        char _Fmt[8];
 
         return _Iput(_Dest, _Iosbase, _Fill, _Buf,
             static_cast<size_t>(_CSTD sprintf_s(_Buf, sizeof(_Buf), _Ifmt(_Fmt, "Ld", _Iosbase.flags()), _Val)));
     }
 
     virtual _OutIt __CLR_OR_THIS_CALL do_put(_OutIt _Dest, ios_base& _Iosbase, _Elem _Fill,
         unsigned long long _Val) const { // put formatted unsigned long long to _Dest
-        char _Buf[2 * _MAX_INT_DIG], _Fmt[8];
+        char _Buf[2 * _MAX_INT_DIG];
+        char _Fmt[8];
 
         return _Iput(_Dest, _Iosbase, _Fill, _Buf,
             static_cast<size_t>(_CSTD sprintf_s(_Buf, sizeof(_Buf), _Ifmt(_Fmt, "Lu", _Iosbase.flags()), _Val)));

stl/inc/xloctime

@@ -539,7 +539,8 @@ protected:
 private:
     ios_base::iostate __CLRCALL_OR_CDECL _Getint(_InIt& _First, _InIt& _Last, int _Lo, int _Hi, int& _Val,
         const _Ctype& _Ctype_fac) const { // get integer in range [_Lo, _Hi] from [_First, _Last)
-        char _Ac[_MAX_INT_DIG], *_Ep;
+        char _Ac[_MAX_INT_DIG];
+        char* _Ep;
         char* _Ptr = _Ac;
         char _Ch;
 

stl/src/xxstod.hpp

@@ -9,15 +9,13 @@
 #define D16TO7 FLIT(268435456.0) // 16^7
 #define D10TO9 FLIT(1e9) // 10^9
 
-#if FBITS <= 24
+#if FBITS == 24
 #define NLONG 1 // 7 * NLONG == max hexadecimal digits
-
-#elif FBITS <= 64
+#elif FBITS == 53
 #define NLONG 3
-
-#else // NLONG
-#define NLONG 5
-#endif // NLONG
+#else // FBITS
+#error Unexpected value for FBITS
+#endif // FBITS
 
 // FTYPE _Stodx(const CTYPE *s, CTYPE **endptr, long pten, int *perr)
 { // convert string to FTYPE, with checking
@@ -36,7 +34,8 @@
     if ((code &= ~FL_NEG) == FL_DEC) { // parse decimal format
         const int nlo = CNAME(Stoflt)(s0, s, endptr, lo, NLONG);
         _Analysis_assume_(nlo <= NLONG);
-        FTYPE xpx[ACSIZE], xpf[ACSIZE];
+        FTYPE xpx[ACSIZE];
+        FTYPE xpf[ACSIZE];
         int i;
 
         FNAME(Xp_setw)(xpf, ACSIZE, D10TO9);
@@ -58,7 +57,8 @@
     } else if (code == FL_HEX) { // parse hexadecimal format
         const int nlo = CNAME(Stoxflt)(s0, s, endptr, lo, NLONG);
         _Analysis_assume_(nlo <= NLONG);
-        FTYPE xpx[ACSIZE], xpf[ACSIZE];
+        FTYPE xpx[ACSIZE];
+        FTYPE xpf[ACSIZE];
         int i;
 
         FNAME(Xp_setw)(xpf, ACSIZE, D16TO7);

stl/src/xxxprec.hpp

@@ -282,13 +282,15 @@ FTYPE* FNAME(Xp_mulh)(FTYPE* p, int n, FTYPE x0) { // multiply by a half-precisi
 
 FTYPE* FNAME(Xp_setn)(FTYPE* p, int n, long x) { // load a long integer
 
-#if 27 <= FBITS
+#if FBITS == 53
     FNAME(Xp_setw)(p, n, static_cast<FTYPE>(x));
-#else // 27 <= FBITS
+#elif FBITS == 24
     FNAME(Xp_setw)(p, n, static_cast<FTYPE>(x / 10000));
     FNAME(Xp_mulh)(p, n, static_cast<FTYPE>(10000));
     FNAME(Xp_addh)(p, n, static_cast<FTYPE>(x % 10000));
-#endif // 27 <= FBITS
+#else // FBITS
+#error Unexpected value for FBITS
+#endif // FBITS
 
     return p;
 }

tools/validate/validate.cpp

@@ -167,9 +167,13 @@ void scan_file(const filesystem::path& filepath, const TabPolicy tab_policy, vec
         static constexpr array checked_extensions{
             // line length should be capped in files with these extensions:
             L""sv,
+            L".cmd"sv,
             L".cpp"sv,
             L".h"sv,
             L".hpp"sv,
+            L".md"sv,
+            L".ps1"sv,
+            L".py"sv,
             L".yml"sv,
         };
         static_assert(is_sorted(checked_extensions.begin(), checked_extensions.end()));