wip handling std::error_*

annotations/yo/advancedtemplates.yo

@@ -67,6 +67,12 @@ includefile(advancedtemplates/trait)
     lsubsect(TYPETRAITS)(Available type traits)
     includefile(advancedtemplates/availabletraits)
 
+    lsubsect(ERRCODEENUM)(Defining your own enum for std::error_code)
+    includefile(advancedtemplates/errcodeenum)
+
+    lsubsect(ERRCONDITONENUM)(Defining your own enum for std::error_condition)
+    includefile(advancedtemplates/errconditionenum)
+
 lsect(NOEXCEPT)(Using `noexcept' when offering the `strong guarantee')
 includefile(advancedtemplates/noexcept)
 

annotations/yo/exceptions.yo

@@ -42,7 +42,8 @@ includefile(exceptions/standard)
     subsect(Standard exceptions: to use or not to use?)
     includefile(exceptions/usestandard.yo)
 
-lsect(SYSTEMERROR)(System error, error code and error category)
+lsect(SYSTEMERROR)(System error, error_code, error_category and
+                    error_condition)
 includefile(exceptions/systemerror)
 
     subsect(The class `std::error_code')
@@ -51,6 +52,9 @@ includefile(exceptions/systemerror)
     subsect(The class `std::error_category')
     includefile(exceptions/errorcategory)
 
+    subsect(The class `std::error_condition)
+    includefile(exceptions/errorcondition)
+
     subsect(The class system_error)
     includefile(exceptions/systemerroruse)
 

annotations/yo/exceptions/errorcategory.yo

@@ -1,6 +1,6 @@
 Objects of classes derived from the base class tt(std::error_category)
 (cf. section ref(ERRCAT)) identify the source and encoding of a particular
-categories of error codes.
+category of error codes.
 
 In addition to the standard available tt(error_category) classes new
 tt(error_category) classes may be derived from tt(std::error_category) which
@@ -11,37 +11,41 @@ Error categories are designed as em(Singletons): only one object of each class
 may exist. Therefore the equality of tt(error_category) objects can be deduced
 from the equality of their addresses. 
 
-All tt(error_category) classes provide the following members:
+tt(Error_category) classes offer the following members:
     itemization(
     ithtq(name)(char const *name() const noexcept) 
        (returns a textual name of the error category (like tt(generic));)
+
     ithtq(message)(string message(int ev) const)
        (returns a string describing the error condition denoted by tt(ev);)
+
     ithtq(default_error_condition)
         (error_condition default_error_condition(int ev) const noexcept)
        (returns an object of type tt(error_condition) corresponding to the
-        error value tt(ev));)
+        error value tt(ev). Error conditions are platform-independent
+        (portable) error codes (see the next section);)
+
     ithtq(equivalent)
-        (bool equivalent(int code, error_condition const &condition) const
-        noexcept)
-       (returns tt(true) if, for the category of error represented by the
-        tt(error_category) object, tt(code) is considered equivalent to
-        tt(condition);)
-    ittq(bool equivalent(error_code const &code, int condition) const noexcept)
-       (returns tt(true) if, for the category of error represented by the
-        tt(error_category) object, tt(error_code code) (see the next section)
-        is considered equivalent to tt(condition);)
+       (bool equivalent(int ev, error_condition const &condition) const
+            noexcept)
+       (returns tt(true) if, for the current tt(error_category) object,
+        the error value `tt(ev)' is considered equivalent to
+        tt(error_condition condition);)
+
+    ittq(bool equivalent(error_code const &code, int value) const noexcept)
+       (returns tt(true) if, for the current tt(error_category) object,
+        tt(error_code code) is considered equivalent to tt(value);)
+
     ittq(bool operator<(error_category const &rhs) const noexcept)
-      (returns tt(less<const error_category*>()(this, &rhs)).)
+       (returns tt(less<const error_category*>()(this, &rhs)).)
     )
 
     Functions returning predefined error categories:
     itemization(
     ithtq(generic_category)(error_category const &generic_category() noexcept)
-       (returns a reference to the (note: a singleton, so there's only one
-        object) em(generic) tt(error_category) object. This function therefore
-        returns the same object when repeatedly called.  The returned object's
-        tt(name) member returns a pointer to the string tt("generic");)
+       (returns a reference to the em(generic) tt(error_category) object.
+        The returned object's tt(name) member returns a pointer to the string
+        tt("generic");)
 
     ithtq(system_category)(error_category const &system_category() noexcept)
        (returns a reference to the em(operating system) tt(error_category)
@@ -50,15 +54,15 @@ All tt(error_category) classes provide the following members:
         tt("system");)
 
     ithtq(iostream_category)(error_category const &iostream_category() noexcept)
-       (returns a reference to the em(operating system) tt(error_category)
+       (returns a reference to the em(iostream) tt(error_category)
         object: it is used for errors reported by stream objects. The
         object's tt(name) member returns a pointer to the string
         tt("iostream");)
 
     ithtq(future_category)(error_category const &future_category() noexcept)
-       (returns a reference to the em(operating system) tt(error_category)
-        object: it is used for errors reported by `future' objects
-        (cf. section ref(FUTURE)). The object's tt(name) member returns a
-        pointer to the string tt("future");)
+       (returns a reference to the em(future) tt(error_category) object: it is
+        used for errors reported by `future' objects (cf. section
+        ref(FUTURE)). The object's tt(name) member returns a pointer to the
+        string tt("future");)
     )
 

annotations/yo/exceptions/errorcode.yo

@@ -1,22 +1,27 @@
 Error code objects are used by tt(error_category) or tt(system_error)
-objects. E.g., some constructors of the class tt(system_error) accept
-tt(std:error_code) hi(error_code) objects. The main purpose of tt(error_code)
-objects is to encapsulate platform dependent em(error code values), as
-determined by the operating system or comparable low-level functions (like
-bf(chmod)(2)), and which are commonly assigned to tt(errno). In addition, an
-tt(error_category) defining the encountered error's general category (see the
-next section) is usually specified when constructing an tt(erroc_code) object.
+objects. E.g., some constructors of tt(system_error) accept
+tt(std::error_code) hi(error_code) objects. 
 
-The class tt(error_code) provides the following constructors, members, and
-free functions:
+The main purpose of tt(error_code) objects is to encapsulate platform
+dependent em(error code values), as determined by the operating system or
+comparable low-level functions (like bf(chmod)(2)), Error code values are
+commonly assigned by such functions to tt(errno). 
+
+In addition, an tt(error_category) defining the encountered error's general
+category (see the next section) is usually specified when constructing an
+tt(error_code) object.
+
+The class tt(error_code) provides the following public interface and free
+functions:
 
 bf(Constructors):
     itemization(
     ittq(error_code() noexcept)
        (the default constructor initializes the error code with an error
-        em(value) 0 and an error em(category) set to tt(&system_category());)
+        em(value) 0 and a tt(system_category) error category. Error value 0 is
+        normally not considered an error;)
 
-    it() The copy and move constructors are available;
+    it() The copy constructors is available;
 
     ittq(error_code(int ec, error_category const &cat) noexcept)
        (this constructor initializes the error code with error value tt(ec)
@@ -25,13 +30,17 @@ bf(Constructors):
          tt(generic_category()));)
 
     ittq(error_code(ErrorCodeEnum e) noexcept)
-       (this is a member template (cf. section ref(MEMTEMP)), defining
-        tt(template <class ErrorCodeEnum>). It initializes the object with the
-        return value of tt(make_error_code(e)).)
+       (this is a member template (cf. section ref(MEMTEMP)), using template
+        header tt(template <class ErrorCodeEnum>). It initializes the object
+        with the return value of tt(make_error_code(e)). In section
+        ref(ERRCODEENUM) defining your own tt(ErrorCodeEnum) is covered; )
     )
 
 bf(Members):
     itemization(
+    it() The copy assignment operator as well as an assignment operator
+        accepting an tt(ErrorCodeEnum) are available;
+
     ittq(void assign(int val, error_category const &cat))
        (assigns new values to the current object's em(value) and
         em(category) data members;)
@@ -41,7 +50,7 @@ bf(Members):
 
     ittq(void clear() noexcept)
        (after calling this member em(value) is set to 0 and the object's error
-        em(category) set to tt(&system_category());)
+        em(category) set to tt(system_category;)
 
     ittq(error_condition default_error_condition() const noexcept)
        (returns tt(category().default_error_condition(value()));)
@@ -49,11 +58,6 @@ bf(Members):
     ittq(string message() const)
        (returns tt(category().message(value()));)
 
-    ittq(errorcode& operator=(ErrorCodeEnum e) noexcept)
-       (a member template defining
-        tt(template <class ErrorCodeEnum>). It assigns the return value of 
-        tt(make_error_code(e)) to the current object;)
-
     ittq(explicit operator bool() const noexcept)
        (returns tt(value() != 0);)
 
@@ -63,19 +67,13 @@ bf(Members):
 
 bf(Free functions):
     itemization(
+    it() Two tt(error_code) objects can be compared for (in) equality and can
+        be ordered (using tt(operator<));
+
     ittq(error_code make_error_code(errc e) noexcept)
        (returns tt(error_code(static_cast<int>(e), generic_category()))
         (tt(errc: see below));)
 
-    ittq(bool operator<(error_code const &lhs, error_code const &rhs)
-        noexcept)
-       (returns 
-    verb(
-lhs.category() < rhs.category() 
-|| 
-lhs.category() == rhs.category() && lhs.value() < rhs.value();
-        ))
-
     ittq(std::ostream &operator<<(std::ostream & os, error_code const &ec))
        (inserts the following text into tt(os):
     verb(
@@ -84,9 +82,10 @@ os << ec.category().name() << ':' << ec.value().
     )
 
 
-The ti(enum class errc)hi(errc) defines symbols that have identical values as
-the traditional error code values as offered by bf(C) macros but whose values
-describe the error conditions in a less cryptic way , e.g.,
+The ti(enum class errc)hi(errc) defined in the tt(std) namespace, defines
+symbols whose values are equal to the traditional error code values used by
+bf(C) macros but whose values describe the error conditions in a less cryptic
+way. E.g.,
         verb(
     enum class errc 
     {
@@ -103,7 +102,8 @@ describe the error conditions in a less cryptic way , e.g.,
 
 Several other strongly typed enums also exist. E.g., the tt(enum class
 future_errc) (cf. section ref(FUTURE)) defines error symbols that are used in
-the context of multi-threading. 
+the context of multi-threading. Defining your own error code enum is covered
+in section ref(ERRCODEENUM).
 
 
 

annotations/yo/exceptions/errorcondition.yo

@@ -0,0 +1,65 @@
+tt(Error_condition)hi(error_condition) objects represent platform independent
+error codes (comparable to the platform dependent error codes represented by
+tt(error_code) objects).
+
+Error conditions can be used as `super error codes' extending the scopes of
+error codes by, e.g., combining codes that are used (differently) by different
+operating systems. Somewhat comparable to using functions like bf(htons)(3)
+and bf(ntosh)(3) to convert system dependent endianess to the (operating
+system independent) network byte order.
+
+Error condition objects are returned by the tt(default_error_condition)
+members of the classes tt(error_code) and tt(error_category), and are expected
+as argument of tt(error_category::equivalent).
+
+The class tt(error_condition) offers the following (public) interface:
+
+bf(Constructors):
+    itemization(
+    ittq(error_condition() noexcept)
+       (the default constructor initializes the error code with an error
+        em(value) 0 and a tt(system_category) error category. Error value 0 is
+        normally not considered an error;)
+
+    it() The copy constructor is available;
+
+    ittq(error_condition(int ec, error_category const &cat) noexcept)
+       (this constructor initializes the error condition with error value
+        tt(ec), and an error em(category);)
+
+    ittq(error_condition(ErrorConditionEnum e) noexcept)
+       (this is a member template (cf. section ref(MEMTEMP)), using template
+        header tt(template <class ErrorConditionEnum>). It initializes the
+        object with the return value of tt(make_error_condition(e)). In
+        section ref(ERRCONDITION) defining your own tt(ErrorConditionEnum) is
+        covered;)
+    )
+
+bf(Members):
+    itemization(
+    it() The copy assignment operator as well as an assignment operator
+        accepting an tt(ErrorConditionEnum) are available;
+
+    ittq(void assign(int val, error_category const &cat))
+       (assigns new values to the current object's em(value) and
+        em(category) data members;)
+
+    ittq(error_category const &category() const noexcept)
+       (returns a reference to the object's error category;)
+
+    ittq(void clear() noexcept)
+       (after calling this member em(value) is set to 0 and the object's error
+        em(category) set to tt(generic_category);)
+
+    ittq(string message() const)
+       (returns tt(category().message(value()));)
+
+    ittq(explicit operator bool() const noexcept)
+       (returns tt(value() != 0);)
+
+    ittq(int value() const noexcept)
+       (returns the object's error value.)
+    )
+
+Two tt(error_condition) objects can be compared for (in)equality, and can be
+ordered using tt(operator<).