| Home | Libraries | People | FAQ | More

## Class template piecewise_constant_distribution

boost::random::piecewise_constant_distribution

## Synopsis

    // In header: <boost/random/piecewise_constant_distribution.hpp>

    template<typename RealType = double, typename WeightType = double>
    class piecewise_constant_distribution {
    public:
      // types
      typedef std::size_t input_type;
      typedef RealType    result_type;

      // member classes/structs/unions

      class param_type {
      public:
        // types
        typedef piecewise_constant_distribution distribution_type;

        // construct/copy/destruct
        param_type();
        template<typename IntervalIter, typename WeightIter>
          param_type(IntervalIter, IntervalIter, WeightIter);
        template<typename T, typename F>
          param_type(const std::initializer_list< T > &, F);
        template<typename IntervalRange, typename WeightRange>
          param_type(const IntervalRange &, const WeightRange &);
        template<typename F> param_type(std::size_t, RealType, RealType, F);

        // friend functions
        template<typename CharT, typename Traits>
          friend std::basic_ostream< CharT, Traits > &
          operator<<(std::basic_ostream< CharT, Traits > &, const param_type &);
        template<typename CharT, typename Traits>
          friend std::basic_istream< CharT, Traits > &
          operator>>(std::basic_istream< CharT, Traits > &, const param_type &);
        friend bool operator==(const param_type &, const param_type &);
        friend bool operator!=(const param_type &, const param_type &);

        // public member functions
        std::vector< RealType > intervals() const;
        std::vector< RealType > densities() const;
      };

      // construct/copy/destruct
      piecewise_constant_distribution();
      template<typename IntervalIter, typename WeightIter>
        piecewise_constant_distribution(IntervalIter, IntervalIter, WeightIter);
      template<typename T, typename F>
        piecewise_constant_distribution(std::initializer_list< T >, F);
      template<typename IntervalsRange, typename WeightsRange>
        piecewise_constant_distribution(const IntervalsRange &,
                                        const WeightsRange &);
      template<typename F>
        piecewise_constant_distribution(std::size_t, RealType, RealType, F);
      explicit piecewise_constant_distribution(const param_type &);

      // public member functions
      template<typename URNG> RealType operator()(URNG &) const;
      template<typename URNG>
        RealType operator()(URNG &, const param_type &) const;
      result_type min() const;
      result_type max() const;
      std::vector< RealType > densities() const;
      std::vector< RealType > intervals() const;
      param_type param() const;
      void param(const param_type &);
      void reset();

      // friend functions
      template<typename CharT, typename Traits>
        friend std::basic_ostream< CharT, Traits > &
        operator<<(std::basic_ostream< CharT, Traits > &,
                   const piecewise_constant_distribution &);
      template<typename CharT, typename Traits>
        friend std::basic_istream< CharT, Traits > &
        operator>>(std::basic_istream< CharT, Traits > &,
                   const piecewise_constant_distribution &);
      friend bool operator==(const piecewise_constant_distribution &,
                             const piecewise_constant_distribution &);
      friend bool operator!=(const piecewise_constant_distribution &,
                             const piecewise_constant_distribution &);
    };

## Description

The class `piecewise_constant_distribution` models a random distribution .

### `piecewise_constant_distribution` public construct/copy/destruct

1.     piecewise_constant_distribution();

   Creates a new ``piecewise_constant_distribution`` with a single interval, [0, 1).

2.     template<typename IntervalIter, typename WeightIter>
         piecewise_constant_distribution(IntervalIter first_interval,
                                         IntervalIter last_interval,
                                         WeightIter first_weight);

   Constructs a `piecewise_constant_distribution` from two iterator ranges containing the interval boundaries and the interval weights. If there are less than two boundaries, then this is equivalent to the default constructor and creates a single interval, [0, 1).

   The values of the interval boundaries must be strictly increasing, and the number of weights must be one less than the number of interval boundaries. If there are extra weights, they are ignored.

   For example,

       * double intervals[] = { 0.0, 1.0, 4.0 };
       * double weights[] = { 1.0, 1.0 };
       * piecewise_constant_distribution<> dist(
       *     &intervals[0], &intervals[0] + 3, &weights[0]);
       *

   The distribution has a 50% chance of producing a value between 0 and 1 and a 50% chance of producing a value between 1 and 4.

3.     template<typename T, typename F>
         piecewise_constant_distribution(std::initializer_list< T > il, F f);

   Constructs a `piecewise_constant_distribution` from an initializer_list containing the interval boundaries and a unary function specifying the weights. Each weight is determined by calling the function at the midpoint of the corresponding interval.

   If the initializer_list contains less than two elements, this is equivalent to the default constructor and the distribution will produce values uniformly distributed in the range [0, 1).

4.     template<typename IntervalsRange, typename WeightsRange>
         piecewise_constant_distribution(const IntervalsRange & intervals_arg,
                                         const WeightsRange & weights_arg);

   Constructs a `piecewise_constant_distribution` from Boost.Range ranges holding the interval boundaries and the weights. If there are less than two interval boundaries, this is equivalent to the default constructor and the distribution will produce values uniformly distributed in the range [0, 1). The number of weights must be one less than the number of interval boundaries.

5.     template<typename F>
         piecewise_constant_distribution(std::size_t nw, RealType xmin,
                                         RealType xmax, F f);

   Constructs a `piecewise_constant_distribution` that approximates a function. The range of the distribution is [xmin, xmax). This range is divided into nw equally sized intervals and the weights are found by calling the unary function f on the midpoints of the intervals.

6.     explicit piecewise_constant_distribution(const param_type & param);

   Constructs a `piecewise_constant_distribution` from its parameters.

### `piecewise_constant_distribution` public member functions

1.     template<typename URNG> RealType operator()(URNG & urng) const;

   Returns a value distributed according to the parameters of the piecewist_constant_distribution.

2.     template<typename URNG>
         RealType operator()(URNG & urng, const param_type & param) const;

   Returns a value distributed according to the parameters specified by param.

3.     result_type min() const;

   Returns the smallest value that the distribution can produce.

4.     result_type max() const;

   Returns the largest value that the distribution can produce.

5.     std::vector< RealType > densities() const;

   Returns a vector containing the probability density over each interval.

6.     std::vector< RealType > intervals() const;

   Returns a vector containing the interval boundaries.

7.     param_type param() const;

   Returns the parameters of the distribution.

8.     void param(const param_type & param);

   Sets the parameters of the distribution.

9.     void reset();

   Effects: Subsequent uses of the distribution do not depend on values produced by any engine prior to invoking reset.

### `piecewise_constant_distribution` friend functions

1.     template<typename CharT, typename Traits>
         friend std::basic_ostream< CharT, Traits > &
         operator<<(std::basic_ostream< CharT, Traits > & os,
                    const piecewise_constant_distribution & pcd);

   Writes a distribution to a `std::ostream`.

2.     template<typename CharT, typename Traits>
         friend std::basic_istream< CharT, Traits > &
         operator>>(std::basic_istream< CharT, Traits > & is,
                    const piecewise_constant_distribution & pcd);

   Reads a distribution from a `std::istream`

3.     friend bool operator==(const piecewise_constant_distribution & lhs,
                              const piecewise_constant_distribution & rhs);

   Returns true if the two distributions will return the same sequence of values, when passed equal generators.

4.     friend bool operator!=(const piecewise_constant_distribution & lhs,
                              const piecewise_constant_distribution & rhs);

   Returns true if the two distributions may return different sequences of values, when passed equal generators.