• Table of Contents
• Previous Chapter
• Next Chapter

Chapter 18: The Standard Template Library

Don't hesitate to send in feedback: send an e-mail if you like the C++ Annotations; if you think that important material was omitted; if you find errors or typos in the text or the code examples; or if you just feel like e-mailing. Send your e-mail to Frank B. Brokken.

Please state the document version you're referring to, as found in the title (in this document: 8.3.1) and please state chapter and paragraph name or number you're referring to.

All received mail is processed conscientiously, and received suggestions for improvements will usually have been processed by the time a new version of the Annotations is released. Except for the incidental case I will normally not acknowledge the receipt of suggestions for improvements. Please don't interpret this as me not appreciating your efforts.

The Standard Template Library ( STL) is a general purpose library consisting of containers, generic algorithms, iterators, function objects, allocators, adaptors and data structures. The data structures used by the algorithms are abstract in the sense that the algorithms can be used with (practically) any data type.

The algorithms can process these abstract data types because they are template based. This chapter does not cover template construction (but see chapter 20 for that). Rather, it focuses on the use of the algorithms.

Several elements also used by the standard template library have already been discussed in the C++ Annotations. In chapter 12 abstract containers were discussed, and in section 10.10 function objects were introduced. Also, iterators were mentioned at several places in this document.

The main components of the STL will be covered in this and the next chapter. Iterators, adaptors, smart pointers, multi threading and other features of the STL will be discussed in coming sections. Generic algorithms are covered in the next chapter (19).

Allocators take care of the memory allocation within the STL. The default allocator class suffices for most applications, and is not further discussed in the C++ Annotations.

All elements of the STL are defined in the standard namespace. Therefore, a using namespace std or a comparable directive is required unless it is preferred to specify the required namespace explicitly. In header files the std namespace should explicitly be used (cf. section 7.9.1).

In this chapter the empty angle bracket notation is frequently used. In code a typename must be supplied between the angle brackets. E.g., plus<> is used in the C++ Annotations, but in code plus<string> may be encountered.

18.1: Predefined function objects

Function objects play important roles in generic algorithms. For example, there exists a generic algorithm sort expecting two iterators defining the range of objects that should be sorted, as well as a function object calling the appropriate comparison operator for two objects. Let's take a quick look at this situation. Assume strings are stored in a vector, and we want to sort the vector in descending order. In that case, sorting the vector stringVec is as simple as:

        sort(stringVec.begin(), stringVec.end(), greater<string>());

The function object's operator() itself is not visible at this point. Don't confuse the parentheses in the `greater<string>()' argument with calling operator(). When operator() is actually used inside sort, it receives two arguments: two strings to compare for `greaterness'. Since greater<string>::operator() is defined inline, the call itself is not actually present in the above sort call. Instead sort calls string::operator> through greater<string>::operator().

Now that we know that a constructor is passed as argument to (many) generic algorithms, we can design our own function objects. Assume we want to sort our vector case-insensitively. How do we proceed? First we note that the default string::operator< (for an incremental sort) is not appropriate, as it does case sensitive comparisons. So, we provide our own CaseInsensitive class, which compares two strings case insensitively. Using the standard C function strcasecmp, the following program performs the trick. It case-insensitively sorts its command-line arguments in ascending alphabetic order:

    #include <iostream>
    #include <string>
    #include <cstring>
    #include <algorithm>
    using namespace std;

    class CaseInsensitive
    {
        public:
            bool operator()(string const &left, string const &right) const
            {
                return strcasecmp(left.c_str(), right.c_str()) < 0;
            }
    };
    int main(int argc, char **argv)
    {
        sort(argv, argv + argc, CaseInsensitive());
        for (int idx = 0; idx < argc; ++idx)
            cout << argv[idx] << " ";
        cout << '\n';
    }

The comparison function object is often a predefined function object. Predefined function object classes are available for many commonly used operations. In the following sections the available predefined function objects are presented, together with some examples showing their use. Near the end of the section about function objects function adaptors are introduced.

Predefined function objects are used predominantly with generic algorithms. Predefined function objects exists for arithmetic, relational, and logical operations. In section 23.4 predefined function objects are developed performing bitwise operations.

18.1.1: Arithmetic function objects

    #include <iostream>
    #include <string>
    #include <functional>
    using namespace std;

    int main(int argc, char **argv)
    {
        plus<size_t> uAdd;              // function object to add size_ts

        cout << "3 + 5 = " << uAdd(3, 5) << '\n';

        plus<string> sAdd;              // function object to add strings

        cout << "argv[0] + argv[1] = " << sAdd(argv[0], argv[1]) << '\n';
    }
    /*
        Output when called as: a.out going

        3 + 5 = 8
        argv[0] + argv[1] = a.outgoing
    */

Suppose we want to perform an operation on a left hand side operand which is always the same variable and a right hand side argument for which, in turn, all elements of an array should be used. E.g., we want to compute the sum of all elements in an array; or we want to concatenate all the strings in a text-array. In situations like these function objects come in handy.

As stated, function objects are heavily used in the context of the generic algorithms, so let's take a quick look ahead at yet another one.

The generic algorithm accumulate visits all elements specified by an iterator-range, and performs a requested binary operation on a common element and each of the elements in the range, returning the accumulated result after visiting all elements specified by the iterator range. It's easy to use this algorithm. The next program accumulates all command line arguments and prints the final string:

    #include <iostream>
    #include <string>
    #include <functional>
    #include <numeric>
    using namespace std;

    int main(int argc, char **argv)
    {
        string result =
                accumulate(argv, argv + argc, string(), plus<string>());

        cout << "All concatenated arguments: " << result << '\n';
    }

    string("All concatenated arguments: ")

Now we define a class Time, overloading operator+. Again, we can apply the predefined function object plus, now tailored to our newly defined datatype, to add times:

    #include <iostream>
    #include <string>
    #include <vector>
    #include <functional>
    #include <numeric>
    using namespace std;

    class Time
    {
        friend ostream &operator<<(ostream &str, Time const &time);
        size_t d_days;
        size_t d_hours;
        size_t d_minutes;
        size_t d_seconds;
        public:
            Time(size_t hours, size_t minutes, size_t seconds);
            Time &operator+=(Time const &rValue);
    };
    Time const operator+(Time const &lValue, Time const &rValue)
    {
        Time ret(lValue);
        ret += rValue;
        return ret;
    }
    Time::Time(size_t hours, size_t minutes, size_t seconds)
    :
        d_days(0),
        d_hours(hours),
        d_minutes(minutes),
        d_seconds(seconds)
    {}
    Time &Time::operator+=(Time const &rValue)
    {
        d_seconds   += rValue.d_seconds;
        d_minutes   += rValue.d_minutes   + d_seconds / 60;
        d_hours     += rValue.d_hours     + d_minutes / 60;
        d_days      += rValue.d_days      + d_hours   / 24;
        d_seconds   %= 60;
        d_minutes   %= 60;
        d_hours     %= 24;
        return *this;
    }
    ostream &operator<<(ostream &str, Time const &time)
    {
        return cout << time.d_days << " days, " << time.d_hours <<
                                                    " hours, " <<
                        time.d_minutes << " minutes and " <<
                        time.d_seconds << " seconds.";
    }
    int main(int argc, char **argv)
    {
        vector<Time> tvector;

        tvector.push_back(Time( 1, 10, 20));
        tvector.push_back(Time(10, 30, 40));
        tvector.push_back(Time(20, 50,  0));
        tvector.push_back(Time(30, 20, 30));

        cout <<
            accumulate
            (
                tvector.begin(), tvector.end(), Time(0, 0, 0), plus<Time>()
            ) <<
            '\n';
    }
    //  Displays: 2 days, 14 hours, 51 minutes and 30 seconds.

While the first example did show the use of a named function object, the last two examples showed the use of anonymous objects that were passed to the (accumulate) function.

The STL supports the following set of arithmetic function objects. The function call operator (operator()) of these function objects calls the matching arithmetic operator for the objects that are passed to the function call operator, returning that arithmetic operator's return value. The arithmetic operator that is actually called is mentioned below:

• plus<>: calls the binary operator+;
• minus<>: calls the binary operator-;
• multiplies<>: calls the binary operator*;
• divides<>: calls operator/;
• modulus<>: calls operator%;
• negate<>: calls the unary operator-. This arithmetic function object is a unary function object as it expects one argument.

    #include <iostream>
    #include <string>
    #include <functional>
    #include <algorithm>
    using namespace std;

    int main(int argc, char **argv)
    {
        int iArr[] = { 1, -2, 3, -4, 5, -6 };

        transform(iArr, iArr + 6, iArr, negate<int>());

        for (int idx = 0; idx < 6; ++idx)
            cout << iArr[idx] << ", ";
        cout << '\n';
    }
    // Displays:  -1, 2, -3, 4, -5, 6,

18.1.2: Relational function objects

The STL supports the following set of relational function objects. The function call operator (operator()) of these function objects calls the matching relational operator for the objects that are passed to the function call operator, returning that relational operator's return value. The relational operator that is actually called is mentioned below:

• equal_to<>: calls operator==;
• not_equal_to<>: calls operator!=;
• greater<>: calls operator>;
• greater_equal<>: calls operator>=;
• less<>: this object's operator() member calls operator<;
• less_equal<>: calls operator<=.

    #include <iostream>
    #include <string>
    #include <functional>
    #include <algorithm>
    using namespace std;

    int main(int argc, char **argv)
    {
        sort(argv, argv + argc, greater_equal<string>());

        for (int idx = 0; idx < argc; ++idx)
            cout << argv[idx] << " ";
        cout << '\n';

        sort(argv, argv + argc, less<string>());

        for (int idx = 0; idx < argc; ++idx)
            cout << argv[idx] << " ";
        cout << '\n';
    }

Note that argv contains char * values, and that the relational function object expects a string. The promotion from char const * to string is silently performed.

18.1.3: Logical function objects

The STL supports the following set of logical function objects. The function call operator (operator()) of these function objects calls the matching logical operator for the objects that are passed to the function call operator, returning that logical operator's return value. The logical operator that is actually called is mentioned below:

• logical_and<>: calls operator&&;
• logical_or<>: calls operator||;
• logical_not<>: calls operator!.

    #include <iostream>
    #include <string>
    #include <functional>
    #include <algorithm>
    using namespace std;

    int main(int argc, char **argv)
    {
        bool bArr[] = {true, true, true, false, false, false};
        size_t const bArrSize = sizeof(bArr) / sizeof(bool);

        for (size_t idx = 0; idx < bArrSize; ++idx)
            cout << bArr[idx] << " ";
        cout << '\n';

        transform(bArr, bArr + bArrSize, bArr, logical_not<bool>());

        for (size_t idx = 0; idx < bArrSize; ++idx)
            cout << bArr[idx] << " ";
        cout << '\n';
    }
    /*
      Displays:

        1 1 1 0 0 0
        0 0 0 1 1 1
    */

18.1.4: Function adaptors

18.1.4.1: Binders

Either the first or the second parameter may be bound to a specific value. To bind the constant value to the function object's first parameter the function adaptor bind1st is used. To bind the constant value to the function object's second parameter the function adaptor bind2nd is used. As an example, assume we want to count all elements of a vector of string objects that occur later in the alphabetical ordering than some reference string.

The count_if generic algorithm is the algorithm of choice for solving these kinds of problems. It expects the usual iterator range and a function object. However, instead of providing it with a function object it is provided with the bind2nd adaptor which in turn is initialized with a relational function object (greater<string>) and a reference string against which all strings in the iterator range are compared. Here is the required bind2nd specification:

    bind2nd(greater<string>(), referenceString)

• To begin with, an adaptor (and so a binder) is a function object, so it defines operator(). In this case the binder function object is a unary function object.
• The binder's operator() receives each of the strings referred to by the iterator range in turn.
• Next it passes these strings and the binder's second argument (the reference object) to the (binary) operator() defined by the function object that is passed as the binder's first argument.
• It returns the return value of that latter function object

    class bind2nd
    {
        FunctionObject d_object;
        Operand const &d_operand;
        public:
            bind2nd(FunctionObject const &object, Operand const &operand);
            ReturnType operator()(Operand const &lvalue);
    };
    inline bind2nd::bind2nd(FunctionObject const &object,
                            Operand const &operand)
    :
        d_object(object),
        d_operand(operand)
    {}
    inline ReturnType bind2nd::operator()(Operand const &lvalue)
    {
        return d_object(lvalue, d_operand);
    }

The above application of the bind2nd adaptor has another important characteristic. Its return type is identical to the return type of the function object that it receives as its first argument, which is bool. Functions returning bool values are also called predicate functions. In the above application the bind2nd adaptor therefore becomes a predicate function itself.

The count_if generic algorithm visits all the elements in an iterator range, returning the number of times the predicate specified as its final argument returns true. Each of the elements of the iterator range is passed to this predicate, which is therefore a unary predicate. Through the binder the binary function object greater<> is adapted to a unary function object, that now compares each of the elements referred to by the iterator range to the reference string. Eventually, the count_if function is called like this:

    count_if(stringVector.begin(), stringVector.end(),
             bind2nd(greater<string>(), referenceString));

18.1.4.2: Negators

Example: to count the number of persons in a vector<string> vector ordered alphabetically before (i.e., not exceeding) a certain reference text one of the following alternatives could be used:

• a binary predicate that directly offers the required comparison:

      count_if(stringVector.begin(), stringVector.end(),
          bind2nd(less_equal<string>(), referenceText))
  

• not2 in combination with the greater<> predicate:

      count_if(stringVector.begin(), stringVector.end(),
          bind2nd(not2(greater<string>()), referenceText))
  

  Here not2 is used as it negates the truth value of a binary operator(), in this case the greater<string>::operator() member function.
• not1 in combination with the bind2nd predicate:

      count_if(stringVector.begin(), stringVector.end(),
          not1(bind2nd(greater<string>(), referenceText)))
  

  Here not1 is used as it negates the truth value of a unary operator(), in this case the bind2nd function adaptor.

    #include <iostream>
    #include <functional>
    #include <algorithm>
    #include <vector>
    using namespace std;

    int main(int argc, char **argv)
    {
        int iArr[] = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10};

        cout << count_if(iArr, iArr + 10, bind2nd(less_equal<int>(), 6)) <<
            ' ';
        cout << count_if(iArr, iArr + 10, bind2nd(not2(greater<int>()), 6)) <<
            ' ';
        cout << count_if(iArr, iArr + 10, not1(bind2nd(greater<int>(), 6))) <<
            '\n';
    }
    // Displays: 6 6 6

One may wonder which of these alternative approaches is the faster. Using the first approach, in which a directly available function object was used, two actions must be performed for each iteration by count_if:

• The binder's operator() is called;
• The operation <= is performed.

Using the second approach, using the not2 negator to negate the truth value of the complementary logical function object, three actions must be performed for each iteration by count_if:

• The binder's operator() is called;
• The negator's operator() is called;
• The operation > is performed.

Using the third approach, using not1 negator to negate the truth value of the binder, three actions must be performed for each iteration by count_if:

• The negator's operator() is called;
• The binder's operator() is called;
• The operation > is performed.

With a commonly used optimization flag like -O2 the compiler will try to grant inline requests. However, if the compiler ignores the inline requests the first variant will be faster.

18.2: Iterators

Iterators are objects acting like pointers. Iterators have the following general characteristics:

• Two iterators may be compared for (in)equality using the == and != operators. The ordering operators (e.g., >, <) can usually not be used.
• Given an iterator iter, *iter represents the object the iterator points to (alternatively, iter-> can be used to reach the members of the object the iterator points to).
• ++iter or iter++ advances the iterator to the next element. The notion of advancing an iterator to the next element is consequently applied: several containers support reversed_iterator types, in which the ++iter operation actually reaches a previous element in a sequence.
• Pointer arithmetic may be used with iterators of containers storing their elements consecutively in memory like vector and deque. For such containers iter + 2 points to the second element beyond the one to which iter points.
• Merely defining an iterator is comparable to having a 0-pointer. Example:

      #include <vector>
      #include <iostream>
      using namespace std;
  
      int main()
      {
          vector<int>::iterator vi;
  
          cout << &*vi;       // prints 0
      }
  

Standard practice requires iterator ranges to be left inclusive. The notation [left, right) indicates that left is an iterator pointing to the first element, while right is an iterator pointing just beyond the last element. The iterator range is empty when left == right.

The following example shows how all elements of a vector of strings can be inserted into cout using its iterator ranges [begin(), end()), and [rbegin(), rend()). Note that the for-loops for both ranges are identical. Furthermore it nicely illustrates how the auto keyword can be used to define the type of the loop control variable instead of using a much more verbose variable definition like vector<string>::iterator (see also section 3.3.6):

    #include <iostream>
    #include <vector>
    #include <string>
    using namespace std;

    int main(int argc, char **argv)
    {
        vector<string> args(argv, argv + argc);

        for (auto iter = args.begin(); iter != args.end(); ++iter)
            cout << *iter << " ";
        cout << '\n';

        for (auto iter = args.rbegin(); iter != args.rend(); ++iter)
            cout << *iter << " ";
        cout << '\n';
    }

Furthermore, the STL defines const_iterator types that must be used when visiting a series of elements in a constant container. Whereas the elements of the vector in the previous example could have been altered, the elements of the vector in the next example are immutable, and const_iterators are required:

    #include <iostream>
    #include <vector>
    #include <string>
    using namespace std;

    int main(int argc, char **argv)
    {
        vector<string> const args(argv, argv + argc);

        for
        (
            vector<string>::const_iterator iter = args.begin();
                iter != args.end();
                    ++iter
        )
            cout << *iter << " ";
        cout << '\n';

        for
        (
            vector<string>::const_reverse_iterator iter = args.rbegin();
                iter != args.rend();
                    ++iter
        )
            cout << *iter << " ";
        cout << '\n';

        return 0;
    }

The STL defines five types of iterators. These iterator types are expected by generic algorithms, and in order to create a particular type of iterator yourself it is important to know their characteristics. In general, iterators must define:

• operator==, testing two iterators for equality,
• operator++, incrementing the iterator, as prefix operator,
• operator*, to access the element the iterator refers to,

• InputIterators:

  InputIterators are used to read from a container. The dereference operator is guaranteed to work as rvalue in expressions. Instead of an InputIterator it is also possible to use (see below) Forward-, Bidirectional- or RandomAccessIterators. Notations like InputIterator1 and InputIterator2 may be used as well. In these cases, numbers are used to indicate which iterators `belong together'. E.g., the generic algorithm inner_product has the following prototype:

      Type inner_product(InputIterator1 first1, InputIterator1 last1,
                     InputIterator2 first2, Type init);
  

  InputIterator1 first1 and InputIterator1 last1 define a pair of input iterators on one range, while InputIterator2 first2 defines the beginning of another range. Analogous notations may be used with other iterator types.

• OutputIterators:

  OutputIterators can be used to write to a container. The dereference operator is guaranteed to work as an lvalue in expressions, but not necessarily as rvalue. Instead of an OutputIterator it is also possible to use (see below) Forward-, Bidirectional- or RandomAccessIterators.

• ForwardIterators:

  ForwardIterators combine InputIterators and OutputIterators. They can be used to traverse containers in one direction, for reading and/or writing. Instead of a ForwardIterator it is also possible to use (see below) Bidirectional- or RandomAccessIterators.

• BidirectionalIterators:

  BidirectionalIterators can be used to traverse containers in both directions, for reading and writing. Instead of a BidirectionalIterator it is also possible to use (see below) a RandomAccessIterator.

• RandomAccessIterators:

  RandomAccessIterators provide random access to container elements. An algorithm like sort requires a RandomAccessIterator, and can therefore not be used to sort the elements of lists or maps, which only provide BidirectionalIterators.

18.2.1: Insert iterators

With the copy algorithm the number of elements to copy is usually available beforehand, since that number can usually be provided by pointer arithmetic. However, situations exist where pointer arithmetic cannot be used. Analogously, the number of resulting elements sometimes differs from the number of elements in the initial range. The generic algorithm unique_copy is a case in point. Here the number of elements that are copied to the destination container is normally not known beforehand.

In situations like these an inserter adaptor function can often be used to create elements in the destination container. There are three types of inserter adaptors:

• back_inserter: calls the container's push_back member to add new elements at the end of the container. E.g., to copy all elements of source in reversed order to the back of destination, using the copy generic algorithm:

      copy(source.rbegin(), source.rend(), back_inserter(destination));
  

• front_inserter calls the container's push_front member, adding new elements at the beginning of the container. E.g., to copy all elements of source to the front of the destination container (thereby also reversing the order of the elements):

      copy(source.begin(), source.end(), front_inserter(destination));
  

• inserter calls the container's insert member adding new elements starting at a specified starting point. E.g., to copy all elements of source to the destination container, starting at the beginning of destination, shifting up existing elements to beyond the newly inserted elements:

      copy(source.begin(), source.end(), inserter(destination,
          destination.begin()));
  

• typedef Data value_type, where Data is the data type stored in the class offering push_back, push_front or insert members (Example: typdef std::string value_type);
• typedef value_type const &const_reference

    typedef DataType const &const_reference;

    #include <algorithm>
    #include <iterator>
    using namespace std;

    class Insertable
    {
        public:
            typedef int const &const_reference;

            void push_back(int const &)
            {}
    };

    int main()
    {
        int arr[] = {1};
        Insertable insertable;

        copy(arr, arr + 1, back_inserter(insertable));
    }

18.2.2: Iterators for `istream' objects

    istream_iterator<Type> identifier(istream &in)

The default constructor is used as the end-iterator and corresponds to the end-of-stream. For example,

    istream_iterator<string> endOfStream;

Using back_inserter and istream_iterator adaptors, all strings from a stream can easily be stored in a container. Example (using anonymous istream_iterator adaptors):

    #include <iostream>
    #include <iterator>
    #include <string>
    #include <vector>
    #include <algorithm>
    using namespace std;

    int main()
    {
        vector<string> vs;

        copy(istream_iterator<string>(cin), istream_iterator<string>(),
             back_inserter(vs));

        for
        (
            vector<string>::const_iterator begin = vs.begin(), end = vs.end();
                begin != end; ++begin
        )
            cout << *begin << ' ';
        cout << '\n';
    }

18.2.2.1: Iterators for `istreambuf' objects

To read from streambuf objects supporting input operations istreambuf_iterators can be used, supporting the operations that are also available for istream_iterator. Different from the latter iterator type istreambuf_iterators support three constructors:

• istreambuf_iterator<Type>:

  The end iterator of an iterator range is created using the default istreambuf_iterator constructor. It represents the end-of-stream condition when extracting values of type Type from the streambuf.

• istreambuf_iterator<Type>(streambuf *):

  A pointer to a streambuf may be used when defining an istreambuf_iterator. It represents the begin iterator of an iterator range.

• istreambuf_iterator<Type>(istream):

  An istream may be also used when defining an istreambuf_iterator. It accesses the istream's streambuf and it also represents the begin iterator of an iterator range.

18.2.3: Iterators for `ostream' objects

    ostream_iterator<Type> identifier(ostream &outStream);
    ostream_iterator<Type> identifier(ostream &outStream, char const *delim);

The example shows how istream_iterators and an ostream_iterator may be used to copy information of a file to another file. A subtlety here is that you probably want to use in.unsetf(ios::skipws). It is used to clear the ios::skipws flag. As a consequence white space characters are simply returned by the operator, and the file is copied character by character. Here is the program:

    #include <iostream>
    #include <algorithm>
    #include <iterator>
    using namespace std;

    int main()
    {
        cin.unsetf(ios::skipws);
        copy(istream_iterator<char>(cin), istream_iterator<char>(),
             ostream_iterator<char>(cout));
    }

18.2.3.1: Iterators for `ostreambuf' objects

To write to streambuf objects supporting output operations ostreambuf_iterators can be used, supporting the operations that are also available for ostream_iterator. Ostreambuf_iterators support two constructors:

• ostreambuf_iterator<Type>(streambuf *):

  A pointer to a streambuf may be used when defining an ostreambuf_iterator. It can be used as an OutputIterator.

• ostreambuf_iterator<Type>(ostream):

  An ostream may be also used when defining an ostreambuf_iterator. It accesses the ostream's streambuf and it can also be used as an OutputIterator.

    #include <iostream>
    #include <algorithm>
    #include <iterator>
    using namespace std;

    int main()
    {
        istreambuf_iterator<char> in(cin.rdbuf());
        istreambuf_iterator<char> eof;
        ostreambuf_iterator<char> out(cout.rdbuf());

        copy(in, eof, out);

        return 0;
    }

18.3: The class 'unique_ptr' (C++0x)

When pointers are used to access dynamically allocated memory strict bookkeeping is required to prevent memory leaks from happening. When a pointer variable referring to dynamically allocated memory goes out of scope, the dynamically allocated memory becomes inaccessible and the program suffers from a memory leak.

To prevent such memory leaks strict bookkeeping is required: the programmer has to make sure that the dynamically allocated memory is returned to the common pool just before the pointer variable goes out of scope.

When a pointer variable points to a dynamically allocated single value or object, bookkeeping requirements are greatly simplified when the pointer variable is defined as a std::unique_ptr object.

Unique_ptrs are objects masquerading as pointers. Since they are objects, their destructors are called when they go out of scope. Their destructors automatically delete the dynamically allocated memory.

Unique_ptrs have some special characteristics:

• when assigning a unique_ptr to another move semantics is used. If move semantics is not available compilation will fail. On the other hand, if compilation succeeds then the used containers or generic algorithms support the use of unique_ptrs. Here is an example:

      std::unique_ptr<int> up1(new int);
      std::unique_ptr<int> up2(up1);      // compilation error
  

  The second definition fails to compile as unique_ptr's copy constructor is private (the same holds true for the assignment operator). But the unique_ptr class does offer facilities to initialize and assign from rvalue references:

      class unique_ptr                        // interface partially shown
      {
          public:
              unique_ptr(unique_ptr &&other); // rvalues bind here
          private:
              unique_ptr(const unique_ptr &other);
      };
  

  In the next example move semantics is used and so it compiles correctly:

      unique_ptr<int> cp(unique_ptr<int>(new int));
  

• a unique_ptr object should only point to memory that was made available dynamically, as only dynamically allocated memory can be deleted.
• multiple unique_ptr objects should not be allowed to point to the same block of dynamically allocated memory. The unique_ptr's interface was designed to prevent this from happening. Once a unique_ptr object goes out of scope, it deletes the memory it points to, immediately changing any other object also pointing to the allocated memory into a wild pointer.

A unique_ptr (as well as a shared_ptr, see section 18.4) can be used as a safe alternative to the now deprecated auto_ptr. Unique_ptr also augments auto_ptr as it can be used with containers and (generic) algorithms as it adds customizable deleters. Arrays can also be handled by unique_ptrs.

18.3.1: Defining `unique_ptr' objects (C++0x)

• The default constructor simply creates a unique_ptr object that does not point to a particular block of memory. Its pointer is initialized to 0 (zero):

      unique_ptr<type> identifier;
  

  This form is discussed in section 18.3.2.
• The move constructor initializes an unique_ptr object. Following the use of the move constructor its unique_ptr argument no longer points to the dynamically allocated memory and its pointer data member is turned into a zero-pointer:

      unique_ptr<type> identifier(another unique_ptr for type);
  

  This form is discussed in section 18.3.3.
• The form that is used most often initializes a unique_ptr object to the block of dynamically allocated memory that is passed to the object's constructor. Optionally deleter can be provided. A (free) function (or function object) receiving the unique_ptr's pointer as its argument can be passed as deleter. It is supposed to return the dynamically allocated memory to the common pool (doing nothing if the pointer equals zero).

      unique_ptr<type> identifier (new-expression [, deleter]);
  

  This form is discussed in section 18.3.4.

18.3.2: Creating a plain `unique_ptr' (C++0x)

    unique_ptr<type> identifier;

    unique_ptr<int> ip;

    if (!ip)
        cout << "0-pointer with a unique_ptr object\n";

18.3.3: Moving another `unique_ptr' (C++0x)

    unique_ptr<type> identifier(other unique_ptr object);

    void mover(unique_ptr<string> &&param)
    {
        unique_ptr<string> tmp(move(param));
    }

    #include <iostream>
    #include <memory>
    #include <string>

    using namespace std;

    int main()
    {
        unique_ptr<string> hello1(new string("Hello world"));
        unique_ptr<string> hello2(move(hello1));
        unique_ptr<string> hello3;

        hello3 = move(hello2);
        cout << // *hello1 << /\n' <<   // would have segfaulted
                // *hello2 << '\n' <<   // same
                *hello3 << '\n';
    }
    // Displays:    Hello world

• hello1 is initialized by a pointer to a dynamically alloctated string (see the next section).
• The unique_ptr hello2 grabs the pointer controlled by hello1 using a move constructor. This effectively changes hello1 into a 0-pointer.
• Then hello3 is defined as a default unique_ptr<string>. But then it grabs its value using move-assignment from hello2 (which, as a consequence, is changed into a 0-pointer as well)

18.3.4: Pointing to a newly allocated object (C++0x)

    unique_ptr<type [, deleter_type]> identifier(new-expression
            [, deleter = deleter_type()]);

Here is an example initializing a unique_ptr pointing to a string object:

    unique_ptr<string> strPtr(new string("Hello world"));

Here is an example showing how an explicitly defined deleter may be used to delete a dynamically allocated array of pointers to strings:

    #include <iostream>
    #include <string>
    #include <memory>
    using namespace std;

    struct Deleter
    {
        size_t d_size;
        Deleter(size_t size = 0)
        :
            d_size(size)
        {}
        void operator()(string **ptr) const
        {
            for (size_t idx = 0; idx < d_size; ++idx)
                delete ptr[idx];
            delete[] ptr;
        }
    };
    int main()
    {
        unique_ptr<string *, Deleter> sp2(new string *[10], Deleter(10));

        Deleter &obj = sp2.get_deleter();
    }

A unique_ptr can be used to reach the member functions that are available for objects allocated by the new expression. These members can be reached as if the unique_ptr was a plain pointer to the dynamically allocated object. For example, in the following program the text `C++' is inserted behind the word `hello':

    #include <iostream>
    #include <memory>
    #include <cstring>
    using namespace std;

    int main()
    {
        unique_ptr<string> sp(new string("Hello world"));

        cout << *sp << '\n';
        sp->insert(strlen("Hello "), "C++ ");
        cout << *sp << '\n';
    }
    /*
        Displays:
            Hello world
            Hello C++ world
    */

18.3.5: Operators and members (C++0x)

• unique_ptr<Type> &operator=(unique_ptr<Type> &&tmp):

  This operator transfers the memory pointed to by the rvalue unique_ptr object to the lvalue unique_ptr object using move semantics. So, the rvalue object loses the memory it pointed at and turns into a 0-pointer. An existing unique_ptr may be assigned to another unique_ptr by converting it to an rvalue reference first using std::move. Example:

      unique_ptr<int> ip1(new int);
      unique_ptr<int> ip2;
  
      ip2 = std::move(ip1);
  

• operator bool() const:

  This operator returns false if the unique_ptr does not point to memory (i.e., its get member, see below, returns 0). Otherwise, true is returned.

• Type &operator*():

  This operator returns a reference to the information accessible via a unique_ptr object . It acts like a normal pointer dereference operator.

• Type *operator->():

  This operator returns a pointer to the information accessible via a unique_ptr object. This operator allows you to select members of an object accessible via a unique_ptr object. Example:

      unique_ptr<string> sp(new string("hello"));
      cout << sp->c_str();
  

The class unique_ptr supports the following member functions:

• Type *get():

  A pointer to the information controlled by the unique_ptr object is returned. It acts like operator->. The returned pointer can be inspected. If it is zero the unique_ptr object does not point to any memory.

• Deleter &unique_ptr<Type>::get_deleter():

  A reference to the deleter object used by the unique_ptr is returned.

• Type *release():

  A pointer to the information accessible via a unique_ptr object is returned. At the same time the object itself becomes a 0-pointer (i.e., its pointer data member is turned into a 0-pointer). This member can be used to transfer the information accessible via a unique_ptr object to a plain Type pointer. After calling this member the proper destruction of the dynamically allocated memory is the responsibility of the programmer.

• void reset(Type *):

  The dynamically allocated memory controlled by the unique_ptr object is returned to the common pool; the object thereupon controls the memory to which the argument that is passed to the function points. It can also be called without argument, turning the object into a 0-pointer. This member function can be used to assign a new block of dynamically allocated memory to a unique_ptr object.

• void swap(unique_ptr<Type> &):

  Two identically typed unique_ptrs are swapped.

18.3.6: Using `unique_ptr' objects for arrays (C++0x)

With dynamically allocated arrays the following syntax is available:

• the index ([]) notation is used to specify that the smart pointer controls a dynamically allocated array. Example:

      unique_ptr<int[]> intArr(new int[3]);
  

• the index operator can be used to access the array's elements. Example:

      intArr[2] = intArr[0];
  

18.3.7: The legacy class 'auto_ptr' (deprecated)

The class unique_ptr does not have auto_ptr's drawbacks and consequently using auto_ptr is now deprecated. Auto_ptrs suffer from the following drawbacks:

• they do not support move semantics;
• they should not be used to point to arrays;
• they cannot be used as data types of abstract containers.

Because of its drawbacks and available replacements the auto_ptr class is not covered anymore by the C++ Annotations. Existing software should be modified to use smart pointers (unique_ptrs or shared_ptrs) and new software should, where applicable, directly be implemented in terms of these new smart pointer types.

18.4: The class 'shared_ptr' (C++0x)

The shared pointer automatically destroys its contents once its reference count has decayed to zero.

Shared_ptrs support copy and move constructors as well as standard and move overloaded assignment operators.

Like unique_ptrs, shared_ptrs may refer to dynamically allocated arrays.

18.4.1: Defining `shared_ptr' objects (C++0x)

• The default constructor simply creates a shared_ptr object that does not point to a particular block of memory. Its pointer is initialized to 0 (zero):

      shared_ptr<type> identifier;
  

  This form is discussed in section 18.4.2.

• The copy constructor initializes a shared_ptr so that both objects share the memory pointed at by the existing object. The copy constructor also increments the shared_ptr's reference count. Example:

      shared_ptr<string> org(new string("hi there"));
      shared_ptr<string> copy(org);   // reference count now 2
  

• The move constructor initializes a shared_ptr with the pointer and reference count of a temporary shared_ptr. The temporary shared_ptr is changed into a 0-pointer. An existing shared_ptr may have its data moved to a newly defined shared_ptr (turning the existing shared_ptr into a 0-pointer as well) by applying std::move. Example:

      shared_ptr<string> grabber(shared_ptr<string>(new string("hi there")));
  

• The form that is used most often initializes a shared_ptr object to the block of dynamically allocated memory that is passed to the object's constructor. Optionally deleter can be provided. A (free) function (or function object) receiving the shared_ptr's pointer as its argument can be passed as deleter. It is supposed to return the dynamically allocated memory to the common pool (doing nothing if the pointer equals zero).

      shared_ptr<type> identifier (new-expression [, deleter]);
  

  This form is discussed in section 18.4.3.

18.4.2: Creating a plain `shared_ptr' (C++0x)

    shared_ptr<type> identifier;

    shared_ptr<int> ip;

    if (!ip)
        cout << "0-pointer with a shared_ptr object\n";

18.4.3: Pointing to a newly allocated object (C++0x)

    shared_ptr<type [, deleter_type]> identifier(new-expression
            [, deleter = deleter_type()]);

Here is an example initializing a shared_ptr pointing to a string object:

    shared_ptr<string> strPtr(new string("Hello world"));

The next example illustrates that two shared_ptrs indeed share their information. After modifying the information controlled by one of the objects the information controlled by the other object is modified as well:

    #include <iostream>
    #include <memory>
    #include <cstring>
    using namespace std;

    int main()
    {
        shared_ptr<string> sp(new string("Hello world"));
        shared_ptr<string> sp2(sp);

        sp->insert(strlen("Hello "), "C++ ");
        cout << *sp << '\n' <<
                *sp2 << '\n';
    }
    /*
        Displays:
            Hello C++ world
            Hello C++ world
    */

18.4.4: Operators and members (C++0x)

• shared_ptr &operator=(shared_ptr<Type> const &other):

  Copy assignment: the reference count of the operator's left hand side operand is reduced. If the reference count decays to zero the dynamically allocated memory controlled by the left hand side operand is deleted. Next it will share the information with the operator's right hand side operand, incrementing the information's reference count.

• shared_ptr &operator=(shared_ptr<Type> &&tmp):

  Move assignment: the reference count of the operator's left hand side operand is reduced. If the reference count decays to zero the dynamically allocated memory controlled by the left hand side operand is deleted. Next it will grab the information controlled by the operator's right hand side operand which is turned into a 0-pointer.

• operator bool() const:

  If the shared_ptr actually points to memory true is returned, otherwise, false is returned.

• Type &operator*():

  A reference to the information stored in the shared_ptr object is returned. It acts like a normal pointer.

• Type *operator->():

  A pointer to the information controlled by the shared_ptr object is returned. Example:

      shared_ptr<string> sp(new string("hello"));
      cout << sp->c_str() << '\n';
  

The following member function member functions are supported:

• Type *get():

  A pointer to the information controlled by the shared_ptr object is returned. It acts like operator->. The returned pointer can be inspected. If it is zero the shared_ptr object does not point to any memory.

• Deleter &get_deleter():

  A reference to the shared_ptr's deleter (function or function object) is returned.

• void reset(Type *):

  The reference count of the information controlled by the shared_ptr object is reduced and if it decays to zero the memory it points to is deleted. Then the object's information will refer to the argument that is passed to the function, setting its shared count to 1. It can also be called without argument, turning the object into a 0-pointer. This member function can be used to assign a new block of dynamically allocated memory to a shared_ptr object.

• void shared_ptr<Type>::swap(shared_ptr<Type> &&):

  Two identically typed shared_ptrs are swapped.

• bool unique() const:

  If the current object is the only object referring to the memory controlled by the object true is returned otherwise (including the situation where the object is a 0-pointer) false is returned.

• size_t use_count() const:

  The number of objects sharing the memory controlled by the object is returned.

18.4.5: Casting shared pointers (C++0x)

    struct Base
    {};
    struct Derived: public Base
    {};

    Derived d;
    static_cast<Base *>(&d);

    shared_ptr<Derived> sd(new Derived);
    shared_ptr<Base> sb(static_cast<Base *>(sd.get()));

These errors can be prevented using casts that were specifically designed for being used with shared_ptrs. These casts use specialized constructors that create a shared_ptr pointing to memory but shares ownership (i.e., a reference count) with an existing shared_ptr. These special casts are:

• std::static_pointer_cast<Base>(std::shared_ptr<Derived> ptr):

  A shared_ptr to a Base class object is returned. The returned shared_ptr refers to the base class portion of the Derived class to which the shared_ptr<Derived> ptr refers. Example:

      shared_ptr<Derived> dp(new Derived());
      shared_ptr<Base> bp = static_pointer_cast<Base>(dp);
  

• std::const_pointer_cast<Class>(std::shared_ptr<Class const> ptr):

  A shared_ptr to a Class class object is returned. The returned shared_ptr refers to a non-const Class object whereas the ptr argument refers to a Class const object. Example:

      shared_ptr<Derived const> cp(new Derived());
      shared_ptr<Derived> ncp = const_pointer_cast<Derived>(cp);
  

• std::dynamic_pointer_cast<Derived>(std::shared_ptr<Base> ptr):

  A shared_ptr to a Derived class object is returned. The Base class must have at least one virtual member function, and the class Derived, inheriting from Base may have overridden Base's virtual member(s). The returned shared_ptr refers to a Derived class object if the dynamic cast from Base * to Derived * succeeded. If the dynamic cast did not succeed the shared_ptr's get member returns 0. Example (assume Derived and Derived2 were derived from Base):

      shared_ptr<Base> bp(new Derived());
      cout << dynamic_pointer_cast<Derived>(bp).get() << ' ' <<
              dynamic_pointer_cast<Derived2>(bp).get() << '\n';
  

  The first get returns a non-0 pointer value, the second get returns 0.

18.4.6: Using `shared_ptr' objects for arrays (C++0x)

But like unique_ptrs, with shared_ptrs referring to arrays the dereferencing operator makes little sense while in these circumstances shared_ptr objects would benefit from index operators.

It is not difficult to create a class shared_array offering such facilities. The class template shared_array, derived from shared_ptr merely should provide an appropriate deleter to make sure that the array and its elements are properly destroyed. In addition it should define the index operator and optionally could declare the derefencing operators using delete.

Here is an example showing how shared_array can be defined and used:

    struct X
    {
        ~X()
        {
            cout << "destr\n";  // show the object's destruction
        }
    };
    template <typename Type>
    class shared_array: public shared_ptr<Type>
    {
        struct Deleter          // Deleter receives the pointer
        {                       // and calls delete[]
           void operator()(Type* ptr)
           {
              delete[] ptr;
           }
        };
        public:
            shared_array(Type *p)           // other constructors
            :                               // not shown here
                shared_ptr<Type>(p, Deleter())
            {}
            Type &operator[](size_t idx)    // index operators
            {
                return shared_ptr<Type>::get()[idx];
            }
            Type const &operator[](size_t idx) const
            {
                return shared_ptr<Type>::get()[idx];
            }
            Type &operator*() = delete;     // delete pointless members
            Type const &operator*() const = delete;
            Type *operator->() = delete;
            Type const *operator->() const = delete;
    };
    int main()
    {
        shared_array<X> sp(new X[3]);
        sp[0] = sp[1];
    }

18.5: Classes having pointer data members (C++0x)

    class Filter
    {
        istream *d_in;
        ostream *d_out;
        public:
            Filter(char const *in, char const *out);
    };

    Filter::Filter(char const *in, char const *out)
    :
        d_in(new ifstream(in)),
        d_out(new ofstream(out))
    {
        if (!*d_in || !*d_out)
            throw string("Input and/or output stream not available");
    }

    Filter::Filter(char const *in, char const *out)
    try
    :
        d_in(0),
        d_out(0)
    {
        d_in = new ifstream(in);
        d_out = new ofstream(out);

        if (!*d_in || !*d_out)
            throw string("Input and/or output stream not available");
    }
    catch (...)
    {
        delete d_out;
        delete d_in;
    }

    Filter::Filter(char const *in, char const *out)
    try
    :
        d_in(0),
        d_out(0)
        d_filterImp(*d_in, *d_out)    // won't work
    { ... }

    // instead:

    Filter::Filter(char const *in, char const *out)
    try
    :
        d_in(0),
        d_out(0),
        d_filterImp(0)
    {
        d_in = new ifstream(in);
        d_out = new ofstream(out);
        d_filterImp = new FilterImp(*d_in, *d_out);
        ...
    }
    catch (...)
    {
        delete d_filterImp;
        delete d_out;
        delete d_in;
    }

    class Filter
    {
        std::unique_ptr<std::ifstream> d_in;
        std::unique_ptr<std::ofstream> d_out;
        FilterImp d_filterImp;
        ...
    };

    Filter::Filter(char const *in, char const *out)
    try
    :
        d_in(new ifstream(in)),
        d_out(new ofstream(out)),
        d_filterImp(*d_in, *d_out)
    {
        if (!*d_in || !*d_out)
            throw string("Input and/or output stream not available");
    }

As a rule of thumb: when classes need to define pointer data members they should define those pointer data members as smart pointers if there's any chance that their constructors throw exceptions.

18.6: Multi Threading (C++0x)

The C++ Annotations don't discuss the concepts behind multi threading. It is a topic by itself and many good reference sources exist (cf. Nichols, B, et al.'s Pthreads Programming, O'Reilly for some good introductions to multi-threading).

Multi threading facilities are offered through the class std::thread. Its constructor and assignment operator accept a function or function object that will handle the thread created by the thread object.

Thread synchronization is handled by objects of the class std::mutex and condition variables are implemented by the class std::condition_variable.

In order to use multi threading in C++ programs the Gnu g++ compiler requires the use of the -pthread flag. E.g., to compile a multi-threaded program defined in a source file multi.cc the compiler must be called as follows:

    g++ --std=c++0x -pthread -Wall multi.cc

Threads in C++ are very much under development. It is likely that in the near future features will be added and possibly redefined. The next sections should therefore be read with this in mind.

18.6.1: The class 'std::thread' (C++0x)

Thread objects can be constructed empty (in which case no new thread is started yet) but they may also be given a function or function object, in which case the thread is started immediately.

Alternatively, a function or function object may be assigned to an existing thread object causing a new thread to be launched using that function (object).

There are several ways to end a launched thread. Currently a thread ends when the function called from the thread object ends. Since the thread object not only accepts functions but also function objects as its argument, a local context may be passed on to the thread. Here are two examples of how a thread may be started: in the first example a function is passed on to the thread, in the second example is is a function object. The example uses the thread member join, discussed below:

    #include <iostream>
    #include <thread>
    #include <cstdlib>
    using namespace std;

    void hello()
    {
        cout << "hello world\n";
    }

    class Zero
    {
        int *d_data;
        size_t d_size;
        int d_value;
        public:
            Zero(int *data, size_t size, int value)
            :
                d_data(data),
                d_size(size),
                d_value(value)
            {}
            void operator()()
            {
                for (int *ptr = d_data + d_size; ptr-- != d_data; )
                    *ptr = d_value;
            }
    };

    int main()
    {
        int data[30];
        Zero zero(data, 30, 0);
        thread t1(zero);
        thread t2(hello);
        t1.join();
        t2.join();
    };

Thread objects do not implement a copy constructor but a move constructor is provided. Threads may be swapped as well, even if they're actually running a thread. E.g.,

    std::thread t1(Thread());
    std::thread t2(Thread());
    t1.swap(t2);

The thread's overloaded assigment operator can also be used to start a thread. If the current thread object actually runs a thread it is stopped, and the function (object) assigned to the thread object becomes the new running thread. E.g.,

    std::thread thr;    // no thread runs from thr yet
    thr = Thread();     // a thread is launched

    int main()
    {
        std::thread t1(Thread());
        std::thread t2(Thread());

        t1.join();      // wait for t1 to complete
        t2.join();      // same, t2
    }

18.6.2: Synchronization (mutexes) (C++0x)

Mutexes should be used when multiple threads needs access to common data to prevent data corruption. For (a very simple) example, unless mutexes are used the following could happen when two threads access a common int variable (a context switch occurs when the operating system switches between threads. With a mult-processor system the threads can really be executed in parallel. To keep the example simple, assume multi threading is used on a single-core computer, switching between multi-threads):

Time step:    Thread1:      var        Thread2:        description
---------------------------------------------------------------------------
    0                        5
    1           starts                                  T1 active
    2           writes var                              T1 commences writing
    3           stopped                                 Context switch
    4                                   starts          T2 active
    5                                   writes var      T2 commences writing
    6                       10          assigns 10      T2 writes 10
    7                                   stopped         Context switch
    8           assigns 12                              T1 writes 12
    9                       12
----------------------------------------------------------------------------

Apart from the std::mutex class std::recursive_mutex is offered. When a recursive_mutex is called multiple times by the same thread it will increase its lock-count. Before other threads may access the protected data the recursive mutex must be unlocked again that number of times. In addition the classes std::timed_mutex and std::recursive_timed_mutex are available. Their locks will (also) expire after a preset amount of time.

In many situations locks will be released at the end of some action block. To simplify locking additional template classes std::unique_lock<> and std::lock_guard<> are provided. As their constructors lock the data and their destructors unlock the data they can be defined as local variables, unlocking their data once their scope terminates. Here is a simple example showing the use of a lock_guard. Once safeProcess ends guard is destroyed, thereby releasing the lock on data:

    std::mutex dataMutex;
    Data data;

    void safeProcess()
    {
        std::lock_guard<std::mutex> guard(dataMutex);
        process(data);
    }

    std::timed_mutex dataMutex;
    Data data;

    void safeProcess()
    {
        std::unique_lock<std::timed_mutex>
            guard(dataMutex, std::chrono::milliseconds(3));
        if (guard)
            process(data);
    }

subsubsection(Deadlocks) Although they should be avoided, Deadlocks are commonly encountered in multi threaded programs. A deadlock occurs when two locks are required to process data, but one thread obtains the first lock and another thread obtains the second lock. The C++0x standard defines a generic std::lock function that can be used to help preventing problems like these. The std::lock function can be used to lock multiple mutexes in one atomic action. Here is an example:

    struct SafeString
    {
        std::mutex  d_mutex;
        std::string d_text;
    };

    void calledByThread(SafeString &first, SafeString &second)
    {
        std::unique_lock<std::mutex>                        // 1
                lock_first(first.d_mutex, std::defer_lock);

        std::unique_lock<std::mutex>                        // 2
                lock_second(second.d_mutex, std::defer_lock);

        std::lock(lock_first, lock_second);                 // 3

        safeProcess(first.d_text, second.d_text);
    }

Another problematic issue with threads involves initialization. If multiple threads are running and only the first thread encountering the initialization code should perform the initialization then this problem should not be solved using mutexes. Although proper synchronization is realized, the synchronization will be performed time and again for every thread. The C++0x standard offers several ways to perform a proper initialization:

• First, a constexpr constructor may be defined. Constexpr constructors are currently not yet supported by the g++ compiler and they are not yet discussed in the C++ Annotations.

• Second, a static variable defined within a compound statement may be used (e.g., a static local variable within a function body). In C++ static variables defined within a compound statement are initialized the first time the function is called at the point in the code where the static variable is defined as illustrated by the following example:

          #include <iostream>
  
          struct Cons
          {
              Cons()
              {
                  std::cout << "Cons called\n";
              }
          };
          void called(char const *time)
          {
              std::cout << time << "time called() activated\n";
              static Cons cons;
          }
          int main()
          {
              std::cout << "Pre-1\n";
              called("first");
              called("second");
              std::cout << "Pre-2\n";
              Cons cons;
          }
      /*
          Displays:
              Pre-1
              firsttime called() activated
              Cons called
              secondtime called() activated
              Pre-2
              Cons called
      */
  

  This feature causes a thread to wait automatically if another thread is still initializing the static data (note that non-static data never cause problems, as each non-static local variables have lifes that are completely restricted to their own threads).
• If the above two approaches can't be used. The combined use of std::call_once and std::once_flag result in one-time execution of a specified function as illustrated by the next example:

      std::string *global;
      std::once_flag globalFlag;
  
      void initializeGlobal()
      {
          global = new std::string("Hello world (why not?)");
      }
      void safeUse()
      {
          std::call_once(globalFlag, initializeGlobal);
          process(*global);
      }
  

18.6.3: Event handling (condition variables) (C++0x)

At some point the producer will therefore have to wait until the client has consumed enough so there's again space available in the producer's storage. Similarly, the client will have to wait until the producer has produced at least some items.

Locking and polling the amount of available items/storage at fixed time intervals usually isn't a good option as it is in essence a wasteful scheme: threads continue to wait during the full interval even though the condition to continue may already have been met; reducing the interval, on the other hand, isn't an attractive option either as it results in a relative increase of the overhead associated with handling the associated mutexes.

Condition variables may be used to solve these kinds of problems. A thread simply sleeps until it is notified by another thread. Generally this may be accomplished as follows:

    producer loop:
        - produce the next item
        - wait until there's room to store the item,
            then reduce the available room
        - store the item
        - increment the number of items in store

    consumer loop:
        - wait until there's an item in store,
            then reduce the number of items in store
        - remove the item from the store
        - increment the number of available storage locations
        - do something with the retrieved item

It is important that the two storage administrative tasks (registering the number of available items and available storage locations) are either performed by the client or by the producer. `Waiting' in this case means:

• Get a lock on the variable containing the actual count
• As long as the count is zero: wait, relase the lock until another thread has increased the count, re-acquire the lock.
• Reduce the count
• Release the lock.

    void down()
    {
        unique_lock<mutex> lock(sem_mutex);   // get the lock
        while (semaphore == 0)
            condition.wait(lock);           // see 1, below.
        --semaphore;                        // dec. semaphore count
    }                                       // the lock is released

What about notifying the condition variable? This is handled by the `increment the number ...' parts in the abovementioned produced and consumer loops. These parts are defined by the following up function:

    void up()
    {
        lock_guard<std::mutex> lock(sem_mutex); // get the lock
        if (semaphore++ == 0)
            condition.notify_one();             // see 2, below
    }                                           // the lock is released

Handling semaphore can very well be encapsulated in a class Semaphore, offering members down and up. For a more extensive discussion of semaphores see Tanenbaum, A.S. (2006) Structured Computer Organization, Pearson Prentice-Hall.

Using the semaphore facilities of the class Semaphore whose constructor expects an initial value of its semaphore data member, the classic producer and consumer case can now easily be implemented in the following multi-threaded program (A more elaborate example of the producer-consumer program is found in the yo/stl/examples/events.cc file in the C++ Annotations's source archive):

    Semaphore available(10);
    Semaphore filled(0);
    std::queue itemQueue;

    void producer()
    {
        size_t item = 0;
        while (true)
        {
            ++item;
            available.down();
            itemQueue.push(item);
            filled.up();
        }
    }
    void client()
    {
        while (true)
        {
            filled.down();
            size_t item = itemQueue.front();
            itemQueue.pop();
            available.up();
            process(item);      // not implemented here
        }
    }

    int main()
    {
        thread produce(producer);
        thread consume(consumer);

        produce.join();
        return 0;
    }

To use condition_variable objects the header file condition_variable must be included.

18.7: Lambda functions (C++0x, 4.5)

The function or function object is usually not readily available. Often it must be defined in or near the location where the generic algorithm is used. Often the software engineer will resort to anonymous namespaces in which a class or function is defined that is thereupon used by the function calling the generic algorithm. If that function is itself a member function the need may be felt to allow the function called by the generic algorithm access to other members of its class. Often this results in a significant amount of code (defining the class); in complex code (to make available software elements that aren't native to the called function (object)); and -at the level of the source file- code that is irrelevant at the current level of specification. Nested classes don't solve these problems and nested classes can't be used in templates.

A lambda function is an anonymous function . Such a function may be defined on the spot and exists only during the lifetime of the statement of which it is a part.

Here is an example of a lambda function:

    [](int x, int y)
    {
        return x * y;
    }

    cout << accumulate(vi.begin(), vi.end(), 1,
                [](int x, int y) { return x * y; });

Alternatively, the return type can be explicitly specified using a late-specified return type, (cf. section 3.3.6):

    [](int x, int y) -> int
    {
        int z = x + y;
        return z + x;
    }

Variables having the same scope as the lambda function can be accessed from the lambda function using references, declared in between the lambda function's square brackets. This allows passing the local context to lambda functions. Such variables are called a closure. Here is an example:

    void showSum(vector<int> &vi)
    {
        int total = 0;
        for_each(
            vi.begin(), vi.end(),
            [&total](int x)
            {
                total += x;
            }
        );
        std::cout << total;
    }

If a closure variable is defined without the reference symbol (&) it is interpreted as a value parameter of the lambda function that is initialized by the local variable when the lambda function is passed to the generic algorithm. Usually closure variables are passed by reference. If all local variables are to be passed by reference a mere [&] can be used (to pass the full closure by value [=] should be used):

    void show(vector<int> &vi)
    {
        int sum = 0;
        int prod = 1;
        for_each(
            vi.begin(), vi.end(),
            [&](int x)
            {
                sum += x;
                prod *= x;
            }
        );
        std::cout << sum << ' ' << prod;
    }

It is also possible to pass some variables to lambda function by value and other variables by reference. In that case the default is specified using & or =. This default specifying symbol is then followed by a list of variables passed differently. Example:

    [&, value](int x)
    {
        total +=  x * value;
    };

Class members may also define lambda functions. Such lambda functions have full access to all the class's members. In other words, they are automatically defined as friends of the class. Example:

    class Data
    {
        std::vector<std::string> d_names;
        public:
            void show() const
            {
                int count = 0;
                std::for_each(d_names.begin(), d_names.d_end(),
                    [this, &count](std::string const &name)
                    {
                        std::cout << ++count <<
                            this->capitalized(name) << '\n';
                    }
                )
            }
        private:
            std::string capitalized(std::string const &name);
    }

                    [&](std::string const &name)
                    {
                        std::cout << ++count <<
                            this->capitalized(name) << '\n';
                    }

Lambda functions may be assigned to variables. An example of such an assignment (using auto to define the variable's type) is:

    auto lambdaFun = [this]()
                     {
                        this->member();
                     };

18.8: Polymorphous wrappers for function objects (C++0x, ?)

To improve handling of these situations the C++0x standard introduces polymorphous (function object) wrappers. Polymorphous wrappers can refer to function pointers, member functions or functors, as long as they match in type and number of their parameters.

18.9: Randomization and Statistical Distributions (C++0x, 4.5)

The C++0x standard introduces several standard mathematical (statistical) distributions into the STL. These distributions allow programmers to obtain randomly selected values from a selected distribution.

These statistical distributions need to be provided with a random number generating object. Several of such random number generating objects are provided, extending the traditional rand function that is part of the C standard library.

These random number generating objects produce pseudo-random numbers, which are then processed by the statistical distribution to obtain values that are randomly selected from the specified distribution.

Although the STL offers various statistical distributions their functionality is fairly limited. The distributions allow us to obtain a random number from these distributions, but probability density functions or cumulative distribution functions are currently not provided by the STL. These functions (distributions as well as the density and the cumulative distribution functions) are, however, available in other libraries, like the boost math library (specifically: http://www.boost.org/doc/libs/1_44_0/libs/math/doc/sf_and_dist/html/index.html).

It is beyond the scope of the C++ Annotations to discuss the mathematical characteristics of the various distributions that are supported by the C++0x standard. The interested reader is referred to the pertinent mathematical textbooks (like Stuart and Ord's (2009) Kendall's Advanced Theory of Statistics, Wiley) or to web-locations like http://en.wikipedia.org/wiki/Bernoulli_distribution.

18.9.1: Random Number Generators (C++0x, 4.5)

The linear_congruential_engine random number generator computes

    linear_congruential_engine<int, 10, 3, 13> lincon;

The subtract_with_carry_engine random number generator computes

    subtract_with_carry_engine<int, 13, 3, 13> subcar;

The predefined mersenne_twister_engine mt19937 (predefined using a typedef defined by the <random> header file) is used in the examples below. It can be constructed using `mt19937 mt' or it can be seeded by providing its constructor with an argument (e.g., mt19937 mt(time(0))). Other ways to initialize the mersenne_twister_engine are beyond the scope of the C++ Annotations (but see Lewis et al. ( Lewis, P.A.W., Goodman, A.S., and Miller, J.M. (1969), A pseudorandom number generator for the System/360, IBM Systems Journal, 8, 136-146.) (1969)).

The random number generators may also be seeded by calling their members seed accepting unsigned long values or generator functions (as in lc.seed(time(0)), lc.seed(mt)).

The random number generators offer members min and max returning, respectively, their minimum and maximum values (inclusive). If a reduced range is required the generators can be nested in a function or class adapting the range.

18.9.2: Statistical distributions (C++0x, 4.5)

All distributions offer the following members (result_type refers to the type name of the values returned by the distribution):

• result_type max() const
  returns the distribution's least upper bound;
• result_type min() const
  returns the distribution's greatest lower bound;
• param_type param() const
  returns the object's param_type struct;
• void param(const param_type &param) redefines the parameters of the distribution;
• void reset(): clears all of its cached values;

All distributions support the following operators (distribution-name should be replaced by the name of the intended distribution, e.g., normal_distribution):

• template<typename URNG> result_type operator()(URNG &urng)
  returns the next random value from the statistical distribution, with the function object urng returning the next random number selected from a uniform random distribution;
• template<typename URNG> result_type operator()
(URNG &urng, param_type &param)
  returns the next random value from the statistical distribution initialized with the parameters provided by the param struct. The function object urng returns the next random number selected from a uniform random distribution;
• std::istream &operator>>(std::istream &in, distribution-name &object): The parameters of the distribution are extracted from an std::istream;
• std::ostream &operator<<(std::ostream &out, distribution-name const &bd): The parameters of the distribution are inserted into an std::ostream

The following example shows how the distributions can be used. Replacing the name of the distribution (normal_distribution) by another distribution's name is all that is required to switch distributions. All distributions have parameters, like the mean and standard deviation of the normal distribution, and all parameters have default values. The names of the parameters vary over distributions and are mentioned below at the individual distributions. Distributions offer members returning or setting their parameters.

Most distributions are defined as class templates, requiring the specification of a data type that is used for the function's return type. If so, an empty template parameter type specification (<>) will get you the default type. The default types are either double (for real valued return types) or int (for integral valued return types). The template parameter type specification must be omitted with distributions that are not defined as template classes.

Here is an example showing the use of the statistical distributions, applied to the normal distribution:

#include <iostream>
#include <ctime>
#include <random>
using namespace std;

int main()
{
    std::mt19937 engine(time(0));
    std::normal_distribution<> dist;

    for (size_t idx = 0; idx < 10; ++idx)
        std::cout << "a random value: " << dist(engine) << "\n";

    cout << '\n' <<
        dist.min() << " " << dist.max() << '\n';
}

18.9.2.1: Bernoulli distribution (C++0x, 4.5)

The bernoulli distribution is not defined as a class template.

Defined types:

    typedef bool result_type;
    struct param_type
    {
      explicit param_type(double prob = 0.5);
      double p() const;                     // returns prob
    };

Constructor and members:

• bernoulli_distribution(double prob = 0.5)
  constructs a bernoulli distribution with probability prob of returning true;
• double p() const
  returns prob;
• result_type min() const
  returns false;
• result_type max() const
  returns true;

18.9.2.2: Binomial distribution (C++0x, 4.5)

The template type parameter IntType defines the type of the generated random value, which must be an integral type.

Defined types:

    typedef IntType result_type;
    struct param_type
    {
      explicit param_type(IntType trials, double prob = 0.5);
      IntType t() const;                    // returns trials
      double p() const;                     // returns prob
    };

Constructors and members and example:

• binomial_distribution<>(IntType trials = 1, double prob = 0.5) constructs a binomial distribution for trials experiments, each having probability prob of success.
• binomial_distribution<>(param_type const &param) constructs a binomial distribution according to the values stored in the param struct.
• IntType t() const
  returns trials;
• double p() const
  returns prob;
• result_type min() const
  returns 0;
• result_type max() const
  returns trials;

18.9.2.3: Cauchy distribution (C++0x, 4.5)

The mean and standard deviation of the Cauchy distribution are undefined.

Defined types:

    typedef RealType result_type;

    struct param_type
    {
        explicit param_type(RealType a = RealType(0),
                            RealType b = RealType(1));

        double a() const;
        double b() const;
    };

Constructors and members:

• cauchy_distribution<>(RealType a = RealType(0), RealType b = RealType(1)) constructs a cauchy distribution with specified a and b parameters.
• cauchy_distribution<>(param_type const &param) constructs a cauchy distribution according to the values stored in the param struct.
• RealType a() const
  returns the distribution's a parameter;
• RealType b() const
  returns the distribution's b parameter;
• result_type min() const
  returns the smallest positive result_type value;
• result_type max() const
  returns the maximum value of result_type;

18.9.2.4: Chi-squared distribution (C++0x, 4.5)

Note that even though the distribution's parameter n usually is an integral value, it doesn't have to be integral, as the chi_squared distribution is defined in terms of functions (exp and Gamma) that take real arguments (see, e.g., the formula shown in the <bits/random.h> header file, provided with the Gnu g++ compiler distribution).

The chi-squared distribution is used, e.g., when testing the goodness of fit of an observed distribution to a theoretical one.

Defined types:

    typedef RealType result_type;

    struct param_type
    {
        explicit param_type(RealType n = RealType(1));

        RealType n() const;
    };

Constructors and members:

• chi_squared_distribution<>(RealType n = 1) constructs a chi_squared distribution with specified number of degrees of freedom.
• chi_squared_distribution<>(param_type const &param) constructs a chi_squared distribution according to the value stored in the param struct;
• IntType n() const
  returns the distribution's degrees of freedom;
• result_type min() const
  returns 0;
• result_type max() const
  returns the maximum value of result_type;

18.9.2.5: Extreme value distribution (C++0x, 4.5)

It has two parameters: a location parameter a and scale parameter b. See also http://www.itl.nist.gov/div898/handbook/apr/section1/apr163.htm

Defined types:

    typedef RealType result_type;

    struct param_type
    {
        explicit param_type(RealType a = RealType(0),
                            RealType b = RealType(1));

        RealType a() const;     // the location parameter
        RealType b() const;     // the scale parameter
    };

Constructors and members:

• extreme_value_distribution<>(RealType a = 0, RealType b = 1) constructs an extreme value distribution with specified a and b parameters;
• extreme_value_distribution<>(param_type const &param) constructs an extreme value distribution according to the values stored in the param struct.
• RealType a() const
  returns the distribution's location parameter;
• RealType stddev() const
  returns the distribution's scale parameter;
• result_type min() const
  returns the smallest positive value of result_type;
• result_type max() const
  returns the maximum value of result_type;

18.9.2.6: Exponential distribution (C++0x, 4.5)

Its parameter prob defines the distribution's lambda parameter, called its rate parameter. Its expected value and standard deviation are both 1 / lambda.

Defined types:

    typedef RealType result_type;

    struct param_type
    {
        explicit param_type(RealType lambda = RealType(1));

        RealType lambda() const;
    };

Constructors and members:

• exponential_distribution<>(RealType lambda = 1) constructs an exponential distribution with specified lambda parameter.
• exponential_distribution<>(param_type const &param) constructs an exponential distribution according to the value stored in the param struct.
• RealType lambda() const
  returns the distribution's lambda parameter;
• result_type min() const
  returns 0;
• result_type max() const
  returns the maximum value of result_type;

18.9.2.7: Fisher F distribution (C++0x, 4.5)

It is characterized by two parameters, being the degrees of freedom of the two chi-squared distributions.

Note that even though the distribution's parameter n usually is an integral value, it doesn't have to be integral, as the Fisher F distribution is constructed from Chi-squared distributions that accept a non-integral parameter value (see also section 18.9.2.4).

Defined types:

    typedef RealType result_type;

    struct param_type
    {
        explicit param_type(RealType m = RealType(1),
                            RealType n = RealType(1));

        RealType m() const; // The degrees of freedom of the nominator
        RealType n() const; // The degrees of freedom of the denominator
    };

Constructors and members:

• fisher_f_distribution<>(RealType m = RealType(1), RealType n = RealType(1)) constructs a fisher_f distribution with specified degrees of freedom.
• fisher_f_distribution<>(param_type const &param) constructs a fisher_f distribution according to the values stored in the param struct.
• RealType m() const
  returns the degrees of freedom of the nominator;
• RealType n() const
  returns the degrees of freedom of the denominator;
• result_type min() const
  returns 0;
• result_type max() const
  returns the maximum value of result_type;

18.9.2.8: Gamma distribution (C++0x, 4.5)

It has two parameters, alpha and beta. Its expected value is alpha * beta and its standard deviation is alpha * beta².

Defined types:

    typedef RealType result_type;

    struct param_type
    {
        explicit param_type(RealType alpha = RealType(1),
                            RealType beta = RealType(1));

        RealType alpha() const;
        RealType beta() const;
    };

Constructors and members:

• gamma_distribution<>(RealType alpha = 1, RealType beta = 1) constructs a gamma distribution with specified alpha and beta parameters.
• gamma_distribution<>(param_type const &param) constructs a gamma distribution according to the values stored in the param struct.
• RealType alpha() const
  returns the distribution's alpha parameter;
• RealType beta() const
  returns the distribution's beta parameter;
• result_type min() const
  returns 0;
• result_type max() const
  returns the maximum value of result_type;

18.9.2.9: Geometric distribution (C++0x, 4.5)

It has one parameter, prob, representing the probability of success in an individual bernoulli trial.

Defined types:

    typedef IntType result_type;

    struct param_type
    {
        explicit param_type(double prob = 0.5);
        double p() const;
    };

Constructors, members and example:

• geometric_distribution<>(double prob = 0.5) constructs a geometric distribution for bernoulli trials each having probability prob of success.
• geometric_distribution<>(param_type const &param) constructs a geometric distribution according to the values stored in the param struct.
• double p() const
  returns the distribution's prob parameter;
• param_type param() const
  returns the object's param_type structure;
• void param(const param_type &param) redefines the parameters of the distribution;
• result_type min() const
  returns the distribution's lower bound (= 0);
• result_type max() const
  returns the distribution's upper bound;
• template<typename URNG> result_type operator()(URNG &urng)
  returns the next random value from the geometric distribution
• template<typename URNG> result_type operator()
(URNG &urng, param_type &param)
  returns the next random value from a geometric distribution initialized by the provided param struct.
• The random number generator that is passed to the generating functions must return integral values. Here is an example showing how the geometric distribution can be used:

  #include <iostream>
  #include <ctime>
  #include <random>
  
  int main()
  {
      std::linear_congruential_engine<unsigned, 7, 3, 61> engine(0);
  
      std::geometric_distribution<> dist;
  
      for (size_t idx = 0; idx < 10; ++idx)
          std::cout << "a random value: " << dist(engine) << "\n";
  
      std::cout << '\n' <<
          dist.min() << " " << dist.max() << '\n';
  
  }
  

18.9.2.10: Log-normal distribution (C++0x, 4.5)

It has two parameters, m and s representing, respectively, the mean and standard deviation of ln(X).

Defined types:

    typedef RealType result_type;

    struct param_type
    {
        explicit param_type(RealType m = RealType(0),
                            RealType s = RealType(1));

        RealType m() const;
        RealType s() const;
    };

Constructor and members:

• lognormal_distribution<>(RealType m = 0, RealType s = 1) constructs a log-normal distribution for a random variable whose mean and standard deviation is, respectively, m and s.
• lognormal_distribution<>(param_type const &param) constructs a log-normal distribution according to the values stored in the param struct.
• RealType m() const
  returns the distribution's m parameter;
• RealType stddev() const
  returns the distribution's s parameter;
• result_type min() const
  returns 0;
• result_type max() const
  returns the maximum value of result_type;

18.9.2.11: Normal distribution (C++0x, 4.5)

It has two parameters, mean and standard deviation.

Defined types:

    typedef RealType result_type;

    struct param_type
    {
        explicit param_type(RealType mean = RealType(0),
                            RealType stddev = RealType(1));

        RealType mean() const;
        RealType stddev() const;
    };

Constructors and members:

• normal_distribution<>(RealType mean = 0, RealType stddev = 1) constructs a normal distribution with specified mean and stddev parameters. The default parameter values define the standard normal distribution;
• normal_distribution<>(param_type const &param) constructs a normal distribution according to the values stored in the param struct.
• RealType mean() const
  returns the distribution's mean parameter;
• RealType stddev() const
  returns the distribution's stddev parameter;
• result_type min() const
  returns the lowest positive value of result_type;
• result_type max() const
  returns the maximum value of result_type;

18.9.2.12: Negative binomial distribution (C++0x, 4.5)

It has two parameters: (IntType) k (> 0), being the number of failures until the experiment is stopped and (double) p the probability of success in each individual experiment.

Defined types:

    typedef IntType result_type;

    struct param_type
    {
        explicit param_type(IntType k = IntType(1), double p = 0.5);

        IntType k() const;
        double p() const;
    };

Constructors and members:

• negative_binomial_distribution<>(IntType k = IntType(1), double p = 0.5) constructs a negative_binomial distribution with specified k and p parameters;
• negative_binomial_distribution<>(param_type const &param) constructs a negative_binomial distribution according to the values stored in the param struct.
• IntType k() const
  returns the distribution's k parameter;
• double p() const
  returns the distribution's p parameter;
• result_type min() const
  returns 0;
• result_type max() const
  returns the maximum value of result_type;

18.9.2.13: Poisson distribution (C++0x, 4.5)

It has one parameter, mean, specifying the expected number of events in the interval under consideration. E.g., if on average 2 events are observed in a one-minute interval and the duration of the interval under study is 10 minutes then mean = 20.

Defined types:

    typedef IntType result_type;

    struct param_type
    {
        explicit param_type(double mean = 1.0);

        double mean() const;
    };

Constructors and members:

• poisson_distribution<>(double mean = 1) constructs a poisson distribution with specified mean parameter.
• poisson_distribution<>(param_type const &param) constructs a poisson distribution according to the values stored in the param struct.
• double mean() const
  returns the distribution's mean parameter;
• result_type min() const
  returns 0;
• result_type max() const
  returns the maximum value of result_type;

18.9.2.14: Student t distribution (C++0x, 4.5)

It is characterized by one parameter: the degrees of freedom, which is equal to the sample size - 1.

Defined types:

    typedef RealType result_type;

    struct param_type
    {
        explicit param_type(RealType n = RealType(1));

        RealType n() const;    // The degrees of freedom
    };

Constructors and members:

• student_t_distribution<>(RealType n = RealType(1)) constructs a student_t distribution with indicated degrees of freedom.
• student_t_distribution<>(param_type const &param) constructs a student_t distribution according to the values stored in the param struct.
• RealType n() const
  returns the degrees of freedom;
• result_type min() const
  returns 0;
• result_type max() const
  returns the maximum value of result_type;

18.9.2.15: Uniform int distribution (C++0x, 4.5)

It has two parameters, a and b, specifying, respectively, the lowest value that can be returned and the highest value that can be returned.

Defined types:

    typedef IntType result_type;

    struct param_type
    {
        explicit param_type(IntType a = 0, IntType b = max(IntType));

        IntType a() const;
        IntType b() const;
    };

Constructors and members:

• uniform_int_distribution<>(IntType a = 0, IntType b = max(IntType)) constructs a uniform_int distribution for the specified range of values.
• uniform_int_distribution<>(param_type const &param) constructs a uniform_int distribution according to the values stored in the param struct.
• IntType a() const
  returns the distribution's a parameter;
• IntType b() const
  returns the distribution's b parameter;
• result_type min() const
  returns the distribution's a parameter;
• result_type max() const
  returns the distribution's b parameter;

18.9.2.16: Uniform real distribution (C++0x, 4.5)

It has two parameters, a and b, specifying, respectively, the half-open range of values ([a, b)) that can be returned by the distribution.

Defined types:

    typedef RealType result_type;

    struct param_type
    {
        explicit param_type(RealType a = 0, RealType b = max(RealType));

        RealType a() const;
        RealType b() const;
    };

Constructors and members:

• uniform_real_distribution<>(RealType a = 0, RealType b = max(RealType)) constructs a uniform_real distribution for the specified range of values.
• uniform_real_distribution<>(param_type const &param) constructs a uniform_real distribution according to the values stored in the param struct.
• RealType a() const
  returns the distribution's a parameter;
• RealType b() const
  returns the distribution's b parameter;
• result_type min() const
  returns the distribution's a parameter;
• result_type max() const
  returns the distribution's b parameter;

18.9.2.17: Weibull distribution (C++0x, 4.5)

It has two or three parameters and the two-parameter variant is offered by the STL. The three parameter variant has a shape (or slope) parameter, a scale parameter and a location parameter. The two parameter variant implicitly uses the location parameter value 0. In the two parameter variant the shape parameter (a) and the scale parameter (b) are provided. See http://www.weibull.com/hotwire/issue14/relbasics14.htm for an interesting coverage of the meaning of the Weibull distribution's parameters.

Defined types:

    typedef RealType result_type;

    struct param_type
    {
        explicit param_type(RealType a = RealType(1),
                            RealType b = RealType(1));

        RealType a() const;     // the shape (slope) parameter
        RealType b() const;     // the scale parameter
    };

Constructors and members:

• weibull_distribution<>(RealType a = 1, RealType b = 1) constructs a weibull distribution with specified a and b parameters;
• weibull_distribution<>(param_type const &param) constructs a weibull distribution according to the values stored in the param struct.
• RealType a() const
  returns the distribution's shape (or slope) parameter;
• RealType stddev() const
  returns the distribution's scale parameter;
• result_type min() const
  returns 0;
• result_type max() const
  returns the maximum value of result_type;

• Table of Contents
• Previous Chapter
• Next Chapter