icarus::ns::util::FixedBins< T, C > Class Template Reference

Binned counts of data. More...

#include <FixedBins.h>

Public Types
using	Data_t = T
	Type on the bin axis. More...
using	Count_t = C
	Type on the bin content. More...
using	Interval_t = decltype(std::declval< T >()-std::declval< T >())
	Type of interval in on the bin axis. More...
using	BinIndex_t = std::ptrdiff_t
	Type of bin index. More...

Public Member Functions
	FixedBins (Interval_t width, Data_t offset=Data_t{}) noexcept
	Constructor: initializes the binning. More...
Content modification
BinIndex_t	add (Data_t value)
	Increases by a unit the count at the bin including value. More...
void	clear () noexcept
	Resets all counts to 0. More...
Query interface
std::size_t	nBins () const noexcept
	Returns how many bins currently have storage. More...
bool	empty () const noexcept
	Returns whether there is no storage at all. More...
Interval_t	binWidth () const noexcept
	Returns the width of the bins. More...
Data_t	offset () const noexcept
	Returns the alignment offset of the bins. More...
Data_t	lowerEdge (BinIndex_t index) const noexcept
Data_t	upperEdge (BinIndex_t index) const noexcept
BinIndex_t	binWith (Data_t value) const noexcept
	Returns the index of the bin including the specified value. More...
Interval_t	range () const noexcept
BinIndex_t	minBin () const noexcept
BinIndex_t	maxBin () const noexcept
Data_t	min () const noexcept
Data_t	max () const noexcept
Count_t	count (BinIndex_t index) const noexcept
	Returns the count of the bin with the specified index. More...
Count_t	countFor (Data_t value) const noexcept
	Returns the count of the bin including the specified value. More...
Count_t	operator[] (BinIndex_t index) const noexcept
	Returns the count of the bin with the specified index. More...
std::size_t	size () const noexcept
	Returns the number of bins with storage. More...
auto	cbegin () const noexcept
	Returns an iterator pointing to the content of the first bin with storage. More...
auto	begin () const noexcept
	Returns an iterator pointing to the content of the first bin with storage. More...
auto	cend () const noexcept
	Returns an iterator pointing to the content of the first bin with storage. More...
auto	end () const noexcept
	Returns an iterator pointing to the content of the first bin with storage. More...

Private Types
using	Storage_t = std::vector< Count_t >
	Type of storage for bin counts. More...

Private Member Functions
std::ptrdiff_t	storageIndex (BinIndex_t index) const noexcept
	Returns the index in the data storage corresponding to bin index. More...
bool	hasStorageIndex (std::ptrdiff_t stIndex) const noexcept
	Returns whether the specified stotage index is available. More...
BinIndex_t	relativeBinIndex (Data_t value, Data_t ref) const noexcept
	Returns the number of bins passing from ref to value. More...
std::size_t	initializeWith (Data_t value)
std::size_t	allocateBin (BinIndex_t index)

Private Attributes
Data_t	fWidth
	Bin width. More...
Data_t	fOffset
	Bin offset from 0. More...
Storage_t	fCounters
	Bin counters. More...
Data_t	fMin
	The lower edge of the bin with storage index 0. More...
BinIndex_t	fMinBin
	The index of bin fCounters[0]. More...

Static Private Attributes
static constexpr Count_t	CountZero = 0
	Starting value of a counter, and ending value of a trilogy. More...

Detailed Description

template<typename T, typename C = unsigned int>
class icarus::ns::util::FixedBins< T, C >

Binned counts of data.

Parameters

T	type of data on the binning axis
C	(default: unsigned int) data type for the bin count

A FixedBin object holds binned counts with a binning of a fixed size and alignment. For example, an object set to have 2-wide bins aligned to -1 will hold counts with bins -3 to -1, -1 to 1, 1 to 3` etc. The lower edge of the bin is included in it, while the upper edge is not.

The lowest and highest limits of the binning are not fixed. As data isadd()-ed to the object, new bins are allocated if needed, and the storage of counts is contiguous. For example, in the example above if the first added datum is +2, the bin 1 to 3 is allocated and given a count of 1. At this point there is only one bin with storage. If 6 is added next, the storage is extended to cover also bins 3 to 5 and 5 to 7, and they will be assigned counts of 0 and 1 respectively. At this point, there is storage for three bins, one of them being empty.

The query interface does report which is the first bin with storage (supposedly the first non-empty bin) and which is the last one. Bin content can be asked for any value and any bin.

Currently the modification interface is very limited: the only way to add entries to the bins is one by one by value (add()), and the only other supported modifying action is to empty all the content (clear()).

The bin index is of type ptrdiff_t.

Note

It is possible to access the counters by a bin index. That index should be provided by FixedBins itself (binWith(), minBin(), etc.), since its specific value is an implementation detail that may change.

Definition at line 25 of file FixedBins.h.

Member Typedef Documentation

template<typename T, typename C = unsigned int>

using icarus::ns::util::FixedBins< T, C >::BinIndex_t = std::ptrdiff_t

Type of bin index.

Definition at line 91 of file FixedBins.h.

template<typename T, typename C = unsigned int>

using icarus::ns::util::FixedBins< T, C >::Count_t = C

Type on the bin content.

Definition at line 86 of file FixedBins.h.

template<typename T, typename C = unsigned int>

using icarus::ns::util::FixedBins< T, C >::Data_t = T

Type on the bin axis.

Definition at line 84 of file FixedBins.h.

template<typename T, typename C = unsigned int>

using icarus::ns::util::FixedBins< T, C >::Interval_t = decltype(std::declval<T>() - std::declval<T>())

Type of interval in on the bin axis.

Definition at line 89 of file FixedBins.h.

template<typename T, typename C = unsigned int>

using icarus::ns::util::FixedBins< T, C >::Storage_t = std::vector<Count_t>

private

Type of storage for bin counts.

Definition at line 269 of file FixedBins.h.

Constructor & Destructor Documentation

template<typename T , typename C >

icarus::ns::util::FixedBins< T, C >::FixedBins ( Interval_t  width, Data_t  offset = Data_t{}  )

explicitnoexcept

Constructor: initializes the binning.

Parameters

width	the bin width
offset	(default: 0) the border of one of the bins

This constructor prepares the object to host counts in bins of the specified width. Optionally, the bins are aligned to the offset value instead than to 0 (or, more precisely, the value of a default-constructed Data_t).

No memory is allocated just yet.

Definition at line 329 of file FixedBins.h.

  : fWidth{ width }, fOffset{ offset }, fMinBin{}
{
  assert(fWidth != Interval_t{0}); // yep, we even accept negative
}

Member Function Documentation

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::add

(

Data_t

value

)

Increases by a unit the count at the bin including value.

Parameters

value

the value to be accounted for

Returns

the index of the bin including the value.

Definition at line 338 of file FixedBins.h.

                                                                {
  
  std::size_t const stIndex
    = empty()? initializeWith(value): allocateBin(binWith(value));
  ++fCounters[stIndex];
  return stIndex;
} // icarus::ns::util::FixedBins<>::add()

template<typename T , typename C >

std::size_t icarus::ns::util::FixedBins< T, C >::allocateBin ( BinIndex_t  index )

private

Ensures the bin with the specified index exists and returns its storage index. Requires some storage to exist already.

Definition at line 522 of file FixedBins.h.

                                                                   {
  assert(!empty());
  
  BinIndex_t stIndex = storageIndex(index);
  if (stIndex < 0) {
    // (changes the first index)
    
    // extend the data storage on the left, filling with zeroes
    std::size_t const nExtend = static_cast<std::size_t>(-stIndex);
    Storage_t data(nExtend + fCounters.size()); // uninitialized
    auto const itOldFirst = std::next(data.begin(), nExtend);
    std::fill(data.begin(), itOldFirst, CountZero);
    std::copy(fCounters.cbegin(), fCounters.cend(), itOldFirst);
    fCounters = std::move(data);
    
    fMinBin = index;
    fMin -= nExtend * binWidth(); // numerically not the best choice...
    stIndex = 0;
  }
  else if (static_cast<std::size_t>(stIndex) >= fCounters.size()) {
    // (does not change the first index -- nor `stIndex`)
    fCounters.resize(static_cast<std::size_t>(stIndex) + 1, CountZero);
  }
  assert(hasStorageIndex(stIndex));
  return static_cast<std::size_t>(stIndex);

} // icarus::ns::util::FixedBins<>::allocateBin()

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::begin ( ) const

noexcept

Returns an iterator pointing to the content of the first bin with storage.

Definition at line 464 of file FixedBins.h.

  { return cbegin(); }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::binWidth ( ) const

noexcept

Returns the width of the bins.

Definition at line 366 of file FixedBins.h.

  { return fWidth; }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::binWith ( Data_t  value ) const

noexcept

Returns the index of the bin including the specified value.

Parameters

value

the value that the queried bin must contain

Returns

the index of the bin including the specified value

See Also

count(), countFor()

Definition at line 392 of file FixedBins.h.

  { return empty()? 0: minBin() + relativeBinIndex(value, min()); }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::cbegin ( ) const

noexcept

Returns an iterator pointing to the content of the first bin with storage.

Definition at line 458 of file FixedBins.h.

  { return fCounters.begin(); }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::cend ( ) const

noexcept

Returns an iterator pointing to the content of the first bin with storage.

Definition at line 470 of file FixedBins.h.

  { return fCounters.end(); }

template<typename T , typename C >

void icarus::ns::util::FixedBins< T, C >::clear ( )

noexcept

Resets all counts to 0.

All the storage is removed from the object (although depending on the STL implementation its memory might still be allocated).

Definition at line 349 of file FixedBins.h.

{ fCounters.clear(); }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::count ( BinIndex_t  index ) const

noexcept

Returns the count of the bin with the specified index.

Parameters

index

the index of the bin to be queried

Returns

the count of the bin with the specified index

See Also

operator[](), countFor()

If the specified bin has no storage, the returned count is 0.

Definition at line 428 of file FixedBins.h.

{
  auto const stIndex = storageIndex(index);
  return hasStorageIndex(stIndex)? fCounters[stIndex]: CountZero;
} // icarus::ns::util::FixedBins<>::count()

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::countFor ( Data_t  value ) const

noexcept

Returns the count of the bin including the specified value.

Parameters

value

the value that the queried bin must contain

Returns

the count of the bin including the specified value

See Also

operator[](), count(), binWith()

If the bin with the specified value has no storage, the returned count is 0.

Definition at line 438 of file FixedBins.h.

  { return count(binWith(value)); }

template<typename T , typename C >

bool icarus::ns::util::FixedBins< T, C >::empty ( ) const

noexcept

Returns whether there is no storage at all.

Definition at line 360 of file FixedBins.h.

  { return fCounters.empty(); }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::end ( ) const

noexcept

Returns an iterator pointing to the content of the first bin with storage.

Definition at line 476 of file FixedBins.h.

  { return cend(); }

template<typename T , typename C >

bool icarus::ns::util::FixedBins< T, C >::hasStorageIndex ( std::ptrdiff_t  stIndex ) const

privatenoexcept

Returns whether the specified stotage index is available.

Definition at line 490 of file FixedBins.h.

{
  return 
    (stIndex >= 0) && (static_cast<std::size_t>(stIndex) < fCounters.size()); 
} // icarus::ns::util::FixedBins<>::hasStorageIndex()

template<typename T , typename C >

std::size_t icarus::ns::util::FixedBins< T, C >::initializeWith ( Data_t  value )

private

Initializes the storage to host a single bin including value.

Returns

the storage index of the new bin (that is: 0)

Definition at line 509 of file FixedBins.h.

                                                                  {
  assert(empty());
  
  fMinBin = 0;
  fMin = offset() + binWidth() * relativeBinIndex(value, offset());
  fCounters.push_back(CountZero);
  return static_cast<std::size_t>(0);
  
} // icarus::ns::util::FixedBins<>::initializeWith()

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::lowerEdge ( BinIndex_t  index ) const

noexcept

Returns

the value of the lower edge of the bin with the specified index

This value always belongs to the bin index.

Definition at line 379 of file FixedBins.h.

  { return offset() + (minBin() + index) * binWidth(); }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::max ( ) const

noexcept

Returns

the upper limit of the highest bin with storage

The return value is undefined if empty() is true (i.e. if no storage is allocated yet).

Definition at line 422 of file FixedBins.h.

  { return min() + range(); }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::maxBin ( ) const

noexcept

Returns

the index of the highest bin with storage

This value can be the same as minBin() if only one bin is stored.

The return value is undefined if empty() is true (i.e. if no storage is allocated yet).

Definition at line 410 of file FixedBins.h.

  { return minBin() + nBins() - 1; }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::min ( ) const

noexcept

Returns

the lower limit of the lowest bin with storage

The return value is undefined if empty() is true (i.e. if no storage is allocated yet).

Definition at line 416 of file FixedBins.h.

  { return fMin; }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::minBin ( ) const

noexcept

Returns

the index of the lowest bin with storage

The return value is undefined if empty() is true (i.e. if no storage is allocated yet).

Definition at line 405 of file FixedBins.h.

  { return fMinBin; }

template<typename T , typename C >

std::size_t icarus::ns::util::FixedBins< T, C >::nBins ( ) const

noexcept

Returns how many bins currently have storage.

Definition at line 354 of file FixedBins.h.

  { return fCounters.size(); }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::offset ( ) const

noexcept

Returns the alignment offset of the bins.

Returns

the alignment offset of the bins

One bin is guaranteed to have its lowerEdge() at the value returned by offset().

Definition at line 372 of file FixedBins.h.

  { return fOffset; }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::operator[] ( BinIndex_t  index ) const

noexcept

Returns the count of the bin with the specified index.

Parameters

index

the index of the bin to be queried

Returns

the count of the bin with the specified index

See Also

count()

If the specified bin has no storage, the returned count is 0.

Definition at line 446 of file FixedBins.h.

  { return count(index); }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::range ( ) const

noexcept

Returns

the span covered by the bins currently with storage

Equivalent to max() - min() and nBins() * binWidth().

Definition at line 399 of file FixedBins.h.

  { return binWidth() * nBins(); }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::relativeBinIndex ( Data_t  value, Data_t  ref  ) const

privatenoexcept

Returns the number of bins passing from ref to value.

Definition at line 500 of file FixedBins.h.

{
  using std::floor;
  return static_cast<BinIndex_t>(floor((value - ref) / binWidth()));
} // icarus::ns::util::FixedBins<>::relativeBinIndex()

template<typename T , typename C >

std::size_t icarus::ns::util::FixedBins< T, C >::size ( ) const

noexcept

Returns the number of bins with storage.

Definition at line 452 of file FixedBins.h.

  { return nBins(); }

template<typename T , typename C >

std::ptrdiff_t icarus::ns::util::FixedBins< T, C >::storageIndex ( BinIndex_t  index ) const

privatenoexcept

Returns the index in the data storage corresponding to bin index.

Definition at line 483 of file FixedBins.h.

  { return index - fMinBin; }

template<typename T , typename C >

auto icarus::ns::util::FixedBins< T, C >::upperEdge ( BinIndex_t  index ) const

noexcept

Returns

the value of the upper edge of the bin with the specified index

Note that this value always belongs to the bin index + 1.

Definition at line 386 of file FixedBins.h.

  { return lowerEdge(index + 1); }

Member Data Documentation

template<typename T, typename C = unsigned int>

constexpr Count_t icarus::ns::util::FixedBins< T, C >::CountZero = 0

staticprivate

Starting value of a counter, and ending value of a trilogy.

Definition at line 272 of file FixedBins.h.

template<typename T, typename C = unsigned int>

Storage_t icarus::ns::util::FixedBins< T, C >::fCounters

private

Bin counters.

Definition at line 278 of file FixedBins.h.

template<typename T, typename C = unsigned int>

Data_t icarus::ns::util::FixedBins< T, C >::fMin

private

The lower edge of the bin with storage index 0.

Definition at line 279 of file FixedBins.h.

template<typename T, typename C = unsigned int>

BinIndex_t icarus::ns::util::FixedBins< T, C >::fMinBin

private

The index of bin fCounters[0].

Definition at line 280 of file FixedBins.h.

template<typename T, typename C = unsigned int>

Data_t icarus::ns::util::FixedBins< T, C >::fOffset

private

Bin offset from 0.

Definition at line 276 of file FixedBins.h.

template<typename T, typename C = unsigned int>

Data_t icarus::ns::util::FixedBins< T, C >::fWidth

private

Bin width.

Definition at line 275 of file FixedBins.h.

---

The documentation for this class was generated from the following file:

• FixedBins.h