/*

 *

 *  Copyright (C) 2017-2021, OFFIS e.V.

 *  All rights reserved.  See COPYRIGHT file for details.

 *

 *  This software and supporting documentation were developed by

 *

 *    OFFIS e.V.

 *    R&D Division Health

 *    Escherweg 2

 *    D-26121 Oldenburg, Germany

 *

 *

 *  Module:  ofstd

 *

 *  Author: Nikolas Goldhammer

 *

 *  Purpose:

 *      Implementing platform abstracting error code handling.

 *

 */

#ifndef OFERROR_H

#define OFERROR_H

#include "dcmtk/config/osconfig.h"    /* make sure OS specific configuration is included first */

// also require STL string, since otherwise OFsystem_error would become incompatible with OFString

#if defined(HAVE_STL_SYSTEM_ERROR) && defined(HAVE_STL_STRING)

#include <system_error>

typedef STD_NAMESPACE error_category OFerror_category;

typedef STD_NAMESPACE error_code OFerror_code;

inline const OFerror_category& OFsystem_category() { return STD_NAMESPACE system_category(); }

inline const OFerror_category& OFgeneric_category() { return STD_NAMESPACE generic_category(); }

#else // fallback implementations

#include "dcmtk/ofstd/ofstring.h"

// for Doxygen such that it does not ignore the globally declared functions

/// @file oferror.h Declares classes and functions for platform abstracting error code handling.

/** OFerror_category serves as the base class for specific error category types,

 *  such as OFsystem_category. It is possible to make your own error_category class.

 *  The objects of error category classes are treated as singletons, passed by reference.

 *  @note this implementation is meant to be a subset of the C++11's std::error_category

 *  that lacks the following features: error condition support, iostream category,

 *                                     future category.

 *  See: http://en.cppreference.com/w/cpp/error/error_category to compare OFerror_category

 *  against std::error_category.

 *

 *  The following table describes the possible operations on two instances <i>a</i> and <i>b</i>

 *  of %OFerror_category:

 *  <table border>

 *    <tr><th>Expression</th><th>Meaning</th></tr>

 *    <tr>

 *      <td><center><kbd>a != b</kbd></center></td>

 *      <td>Compares two OFerror_category objects and evaluates to OFTrue if both objects refer to different error categories.</td>

 *    </tr>

 *    <tr>

 *      <td><center><kbd>a == b</kbd></center></td>

 *      <td>Compares two OFerror_category objects and evaluates to OFTrue if both objects refer to the same error category.</td>

 *    </tr>

 *    <tr>

 *      <td><center><kbd>a &lt; b</kbd></center></td>

 *      <td>

 *        Implements a total order on OFerror_category objects. The semantics of one category being compared less than another

 *        are intentionally not defined, but, if one category compares less than to another it will stay that way during the

 *        remaining execution of the program and one and the same category will never compare less than to itself.

 *      </td>

 *    </tr>

 *  </Table>

 *  @see OFgeneric_category()

 *  @see OFsystem_category()

 */

class DCMTK_OFSTD_EXPORT OFerror_category

{

public:

    /** Default constructor, used by derived classes.

     */

    inline OFerror_category() {}

    /** Virtual destructor, does nothing.

     */

    virtual ~OFerror_category() {}

    /** Obtains the name of the category, for example "generic".

     *  @return a character pointer that refers to the name of the category.

     */

    virtual const char* name() const = 0;

    /** Constructs an explanatory string for an error code.

     *  @param code an integer that shall be interpreted as an error code.

     *  @return an explanatory error message for the given code as an OFString.

     */

    virtual OFString message( int code ) const = 0;

    // operator implementations, see above table for documentation

#ifndef DOXYGEN

    inline OFBool operator==(const OFerror_category& rhs) const { return this == &rhs; }

    inline OFBool operator!=(const OFerror_category& rhs) const { return this != &rhs; }

    inline OFBool operator<(const OFerror_category& rhs) const { return this < &rhs; }

#endif // NOT DOXYGEN

private:

    // ensure singleton behavior by disabling the copy constructor and assignment

    // operator

#ifndef DOXYGEN

    OFerror_category(const OFerror_category& other);

    OFerror_category& operator=(const OFerror_category& rhs);

#endif // NOT DOXYGEN

};

/** OFerror_code is a platform abstracting wrapper for platform specific error codes.

 *  Each OFerror_code object holds an error code originating from the operating system

 *  or some low-level interface and a pointer to an object of type OFerror_category,

 *  which corresponds to the said interface. The error code values may be not unique across

 *  different error categories.

 *  @note This implementation is meant to be a subset of the C++11's std::error_code

 *  that lacks the following features: error condition support, iostream category,

 *                                     future category.

 *  See: http://en.cppreference.com/w/cpp/error/error_code to compare OFerror_code against

 *  std::error_code.

 *

 *  The following table describes the possible operations on two instances <i>a</i> and <i>b</i>

 *  of %OFerror_code:

 *  <table border>

 *    <tr><th>Expression</th><th>Meaning</th></tr>

 *    <tr>

 *      <td><center><kbd>if(a), while(a), ...</kbd></center></td>

 *      <td>

 *        Test whether the error code refers to an error message or means that everything went fine.

 *        OFTrue if the object refers to an error, OFFalse otherwise.

 *      </td>

 *    </tr>

 *    <tr>

 *      <td><center><kbd>a != b</kbd></center></td>

 *      <td>

 *        Compares two OFerror_code objects, evaluates to OFTrue if both objects refer to a different

 *        error code, that is, if either the code or the category (or both) differ, OFFalse otherwise.

 *      </td>

 *    </tr>

 *    <tr>

 *      <td><center><kbd>a == b</kbd></center></td>

 *      <td>

 *        Compares two OFerror_code objects, evaluates to OFTrue if both objects refer to the same

 *        error code, that is, if both the code and the category are equal, OFFalse otherwise.

 *      </td>

 *    </tr>

 *    <tr>

 *      <td><center><kbd>a &lt; b</kbd></center></td>

 *      <td>

 *        Implements a total order on OFerror_code objects. Will return OFTrue if the category of <i>a</i>

 *        compares less than to the category of <i>b</i>. Will return OFFalse if the category of <i>b</i>

 *        compares less than to the category of <i>a</i>. If both objects refer to the same category, they

 *        will be ordered using the actual error code integer.

 *      </td>

 *    </tr>

 *  </Table>

 */

class DCMTK_OFSTD_EXPORT OFerror_code

{

public:

    /** Default constructor.

     *  Initializes an error code with value 0 (success)

     *  and category OFsystem_category().

     */

    OFerror_code();

    /** Constructs an error code from the given arguments.

     *  @param code the actual error code.

     *  @param category a reference to the OFerror_category that shall be used.

     */

    OFerror_code( int code, const OFerror_category& category );

    /** Replaces the contents with the given error code and category.

     *  @param code the actual error code.

     *  @param category a reference to the OFerror_category that shall be used.

     */

    void assign( int code, const OFerror_category& category );

    /** Sets the error code to value 0 (success) and the category

     *  to OFsystem_category().

     */

    void clear();

    /** Obtains the actual error code.

     *  @return the error code as an integer.

     */

    int value() const;

    /** Obtains the category linked to this error code.

     *  @return a reference to the linked error category.

     */

    const OFerror_category& category() const;

    /** Constructs an explanatory string for this error code using the

     *  linked error category.

     *  @return the error message as an OFString.

     */

    OFString message() const;

    // declare overloaded operators, see above table for documentation

#ifndef DOXYGEN

#ifdef HAVE_CXX11

    explicit

#endif

    operator OFBool() const;

    OFBool operator!=( const OFerror_code& rhs ) const;

    OFBool operator==( const OFerror_code& rhs ) const;

    OFBool operator<( const OFerror_code& rhs ) const;

#endif // NOT DOXYGEN

private:

    /// holds the error value.

    int m_Code;

    /// holds the error category

    const OFerror_category* m_Category;

};

/** Retrieves a reference to an OFerror_category object used for operating system

 *  specific error codes.

 *  The object is required to override the virtual function OFerror_category::name()

 *  to return a pointer to the string "system".

 *  @return a reference to the system error category.

 */

DCMTK_OFSTD_EXPORT const OFerror_category& OFsystem_category();

/** Retrieves a reference to an OFerror_category object used for generic error codes.

 *  The object is required to override the virtual function OFerror_category::name()

 *  to return a pointer to the string "generic".

 *  @return a reference to the generic error category.

 */

DCMTK_OFSTD_EXPORT const OFerror_category& OFgeneric_category();

#endif // NOT HAVE_STL_SYSTEM_ERROR && HAVE_STL_STRING

#endif // OFERROR_H