Document undefined behavior of accumulator::mean and accumulator::weighted_mean (#298)

.github/workflows/cov.yml

@@ -0,0 +1,62 @@
+name: Coverage
+
+on:
+  pull_request:
+    branches:
+      - master
+      - develop
+    paths-ignore:
+      - 'doc/**'
+      - 'examples/**'
+      - 'tools/**'
+
+env:
+  B2_OPTS: -q -j2 warnings-as-errors=on
+
+jobs:
+  cov:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Fetch Boost superproject
+      run: |
+        cd ..
+        git clone -b $GITHUB_BASE_REF --depth 5 https://github.com/boostorg/boost.git
+        cd boost
+        mv -f $GITHUB_WORKSPACE/* libs/histogram
+        git submodule update --init --depth 5 tools/build tools/boostdep
+        python tools/boostdep/depinst/depinst.py --git_args "--depth 5 --jobs 3" histogram
+        mv -f * $GITHUB_WORKSPACE
+
+        # # use hdembinski/serialization due to frequent errors in boostorg/serialization
+        # pushd libs/serialization
+        # git remote add patch https://github.com/HDembinski/serialization.git
+        # git fetch patch
+        # git checkout patch/boost_histogram
+        # popd
+
+    - name: Prepare b2
+      run: |
+        ./bootstrap.sh
+        ./b2 headers
+
+        # simulate bundled boost by moving the headers instead of symlinking
+        rm -rf boost/histogram.pp boost/histogram
+        mv -f libs/histogram/include/boost/* boost
+
+    - name: Test gcc-8 cxxstd=latest coverage=on
+      run: |
+        cd libs/histogram
+
+        # don't compile examples in coverage build, coverage must come from tests alone
+        ../../b2 $B2_OPTS toolset=gcc-8 cxxstd=latest coverage=on test//all
+
+    - name: Process coverage data
+      run: |
+        cd libs/histogram
+        GCOV=gcov-8 tools/cov.sh
+
+    - uses: coverallsapp/github-action@v1.1.2
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        path-to-lcov: libs/histogram/coverage.info

.github/workflows/fast.yml

@@ -11,7 +11,7 @@ on:
       - 'tools/**'
 
 jobs:
-  default:
+  cmake:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:

.github/workflows/slow.yml

@@ -17,108 +17,113 @@ env:
   COVERALLS_TOKEN: ${{ secrets.COVERALLS_TOKEN }}
 
 jobs:
-  superproject_cmake_and_b2:
+  superproject_cmake:
     runs-on: macos-latest
     steps:
     - uses: actions/checkout@v2
-    - name: cmake from superproject
+    - name: Fetch Boost superproject
       run: |
         cd ..
         git clone -b $GITHUB_BASE_REF --depth 5 https://github.com/boostorg/boost.git
         cd boost
-        git submodule update --init --depth 5 --jobs 3
+        git submodule update --init --depth 5
         rm -rf libs/histogram/*
         mv -f $GITHUB_WORKSPACE/* libs/histogram
-
-        cd ..
-        cmake -DBOOST_ENABLE_CMAKE=1 -DBoost_VERBOSE=1 boost
-        ctest -j2 --output-on-failure -R boost_histogram
-    - name: prepare b2
+        mv -f * $GITHUB_WORKSPACE
+    - name: CMake from superproject
+      run: |
+        cd ..
+        cmake -DBOOST_ENABLE_CMAKE=1 -DBoost_VERBOSE=1 $GITHUB_WORKSPACE
+        ctest -j2 --output-on-failure -R boost_histogram
+
+  appleclang:
+    runs-on: macos-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Fetch Boost superproject
+      run: |
+        cd ..
+        git clone -b $GITHUB_BASE_REF --depth 5 https://github.com/boostorg/boost.git
+        cd boost
+        mv -f $GITHUB_WORKSPACE/* libs/histogram
+        git submodule update --init --depth 5 tools/build tools/boostdep
+        python tools/boostdep/depinst/depinst.py --git_args "--depth 5 --jobs 3" histogram
+        mv -f * $GITHUB_WORKSPACE
+    - name: Prepare b2
       run: |
-        cd ../boost
         ./bootstrap.sh
         ./b2 headers
-    - name: b2 cxxstd=14 exception-handling=off rtti=off
+    - name: Test cxxstd=14 exception-handling=off rtti=off
       run: |
-        cd ../boost/libs/histogram
+        cd libs/histogram
         ../../b2 $B2_OPTS cxxstd=14 exception-handling=off rtti=off test//minimal
-    - name: b2 cxxstd=17
+    - name: Test cxxstd=17
       run: |
-        cd ../boost/libs/histogram
+        cd libs/histogram
         ../../b2 $B2_OPTS cxxstd=17 test//all
 
-  cov:
+  gcc7:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
-    - uses: actions/setup-python@v2
-      with:
-        python-version: '3.x'
-    - name: install cpp-coveralls
-      run: |
-        python --version
-        pip install cpp-coveralls
-    - name: prepare
+    - name: Fetch Boost superproject
       run: |
         cd ..
         git clone -b $GITHUB_BASE_REF --depth 5 https://github.com/boostorg/boost.git
         cd boost
-        git submodule update --init --depth 5 tools/build tools/boostdep
         mv -f $GITHUB_WORKSPACE/* libs/histogram
-
+        git submodule update --init --depth 5 tools/build tools/boostdep
         python tools/boostdep/depinst/depinst.py --git_args "--depth 5 --jobs 3" histogram
-
-        # # use hdembinski/serialization due to frequent errors in boostorg/serialization
-        # pushd libs/serialization
-        # git remote add patch https://github.com/HDembinski/serialization.git
-        # git fetch patch
-        # git checkout patch/boost_histogram
-        # popd
-
-        # prepare build
+        mv -f * $GITHUB_WORKSPACE
+    - name: Prepare b2
+      run: |
         ./bootstrap.sh
         ./b2 headers
-
-        # simulate bundled boost by moving the headers instead of symlinking
-        rm -rf boost/histogram.pp boost/histogram
-        mv -f libs/histogram/include/boost/* boost
-
-    - name: test gcc-8 cxxstd=latest coverage=on test//all
+    - name: Test gcc-7 cxxstd=14
       run: |
-        cd ../boost/libs/histogram
-
-        # don't compile examples in coverage build, coverage must come from tests alone
-        ../../b2 $B2_OPTS toolset=gcc-8 cxxstd=latest coverage=on test//all
-
-        # process and send coverage data
-        GCOV=gcov-8 tools/cov.sh $COVERALLS_TOKEN
-
-  stress:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v2
-    - name: prepare b2
-      run: |
-        cd ..
-        git clone -b $GITHUB_BASE_REF --depth 5 https://github.com/boostorg/boost.git
-        cd boost
-        git submodule update --init --depth 5 tools/build tools/boostdep
-        mv -f $GITHUB_WORKSPACE/* libs/histogram
-
-        python tools/boostdep/depinst/depinst.py --git_args "--depth 5 --jobs 3" histogram
-
-        # prepare build
-        ./bootstrap.sh
-        ./b2 headers
-    - name: test gcc-7 cxxstd=14
-      run: |
-        cd ../boost/libs/histogram
+        cd libs/histogram
         ../../b2 $B2_OPTS toolset=gcc-7 cxxstd=14 test//all examples
-    - name: test gcc-10 cxxstd=20 -O3 -funsafe-math-optimizations
+
+  gcc10:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Fetch Boost superproject
       run: |
-        cd ../boost/libs/histogram
+        cd ..
+        git clone -b $GITHUB_BASE_REF --depth 5 https://github.com/boostorg/boost.git
+        cd boost
+        mv -f $GITHUB_WORKSPACE/* libs/histogram
+        git submodule update --init --depth 5 tools/build tools/boostdep
+        python tools/boostdep/depinst/depinst.py --git_args "--depth 5 --jobs 3" histogram
+        mv -f * $GITHUB_WORKSPACE
+    - name: Prepare b2
+      run: |
+        ./bootstrap.sh
+        ./b2 headers
+    - name: Test gcc-10 cxxstd=20 -O3 -funsafe-math-optimizations
+      run: |
+        cd libs/histogram
         ../../b2 $B2_OPTS toolset=gcc-10 cxxstd=20 cxxflags="-O3 -funsafe-math-optimizations" test//all examples
-    - name: test clang-6 cxxstd=17 ubsan asan
+
+  clang6:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Fetch Boost superproject
       run: |
-        cd ../boost/libs/histogram
+        cd ..
+        git clone -b $GITHUB_BASE_REF --depth 5 https://github.com/boostorg/boost.git
+        cd boost
+        mv -f $GITHUB_WORKSPACE/* libs/histogram
+        git submodule update --init --depth 5 tools/build tools/boostdep
+        python tools/boostdep/depinst/depinst.py --git_args "--depth 5 --jobs 3" histogram
+        mv -f * $GITHUB_WORKSPACE
+    - name: Prepare b2
+      run: |
+        ./bootstrap.sh
+        ./b2 headers
+    - name: Test clang-6 cxxstd=17 ubsan asan
+      run: |
+        cd libs/histogram
         ../../b2 $B2_OPTS toolset=clang-6 cxxstd=17 variant=histogram_ubasan test//all

include/boost/histogram/accumulators/mean.hpp

@@ -87,10 +87,16 @@ public:
   /// Return how many samples were accumulated
   const_reference count() const noexcept { return sum_; }
 
-  /// Return mean value of accumulated samples
+  /** Return mean value of accumulated samples.
+
+    The result is undefined, if `count() < 1`.
+  */
   const_reference value() const noexcept { return mean_; }
 
-  /// Return variance of accumulated samples
+  /** Return variance of accumulated samples
+
+    The result is undefined, if `count() < 2`.
+  */
   value_type variance() const noexcept { return sum_of_deltas_squared_ / (sum_ - 1); }
 
   template <class Archive>

include/boost/histogram/accumulators/weighted_mean.hpp

@@ -100,10 +100,17 @@ public:
     return sum_of_weights_squared_;
   }
 
-  /// Return mean of accumulated weighted samples
+  /** Return mean value of accumulated weighted samples.
+
+    The result is undefined, if `sum_of_weights() == 0`.
+  */
   const_reference value() const noexcept { return weighted_mean_; }
 
-  /// Return variance of accumulated weighted samples
+  /** Return variance of accumulated weighted samples
+
+    The result is undefined, if `sum_of_weights() == 0` or
+    `sum_of_weights() == sum_of_weights_squared()`.
+  */
   value_type variance() const {
     return sum_of_weighted_deltas_squared_ /
            (sum_of_weights_ - sum_of_weights_squared_ / sum_of_weights_);

include/boost/histogram/axis/boolean.hpp

@@ -25,8 +25,8 @@ namespace axis {
 
   Binning is a pass-though operation with zero cost, making this the
   fastest possible axis. The axis has no internal state apart from the
-  optional metadata state. The axis has no under- and overflow bins. It cannot grow and
-  cannot be reduced.
+  optional metadata state. The axis has no under- and overflow bins.
+  It cannot grow and cannot be reduced.
 
   @tparam MetaData type to store meta data.
  */

tools/cov.sh

@@ -36,15 +36,11 @@ $LCOV --base-directory `pwd` \
 # remove uninteresting entries
 $LCOV --extract coverage.info "*/boost/histogram/*" --output-file coverage.info
 
-if [ $CI ] || [ $1 ]; then
+if [ $1 ]; then
   # upload if on CI or when token is passed as argument
   which cpp-coveralls || echo "Error: you need to install cpp-coveralls"
-  if [ $1 ]; then
-    cpp-coveralls -l coverage.info -r ../.. -n -t $1
-  else
-    cpp-coveralls -l coverage.info -r ../.. -n
-  fi
-else
+  cpp-coveralls -l coverage.info -r ../.. -n -t $1
+elif [ ! $CI ]; then
   # otherwise generate html report
   $LCOV_DIR/bin/genhtml coverage.info --demangle-cpp -o coverage-report
 fi