PlatformException< pltfrm_code_t > Class Template Reference

A class template designed specifically for using with externally defined error codes. More...

#include <chsvexception.h>

Inheritance diagram for PlatformException< pltfrm_code_t >:

Collaboration diagram for PlatformException< pltfrm_code_t >:

Public Member Functions
	PlatformException (platform_code_t nPlatformCode) noexcept
template<class GetDescriptionFn , class = decltype(std::declval<GetDescriptionFn&&>()(std::declval<platform_code_t>()))>
	PlatformException (platform_code_t nPlatformCode, GetDescriptionFn &&fnGetDescription) noexcept
template<class CharType , class = std::enable_if_t<std::is_integral<CharType>::value>>
	PlatformException (platform_code_t nPlatformCode, Exception::vararg_tag_t, const CharType *restrict pszDescription, std::va_list ap) noexcept
template<class CharType , class ... DescriptionFormatParams, class = std::enable_if_t<std::is_integral<CharType>::value>>
	PlatformException (platform_code_t nPlatformCode, const CharType *restrict pszDescription, DescriptionFormatParams ... formatting_params) noexcept
template<class CharType , class GetDescriptionFn , class = std::enable_if_t<std::is_integral<CharType>::value, decltype(std::declval<GetDescriptionFn&&>()(std::declval<platform_code_t>()))>>
	PlatformException (platform_code_t nPlatformCode, GetDescriptionFn &&fnGetDescription, Exception::vararg_tag_t, const CharType *restrict pszDescription, std::va_list ap) noexcept
template<class CharType , class GetDescriptionFn , class ... DescriptionFormatParams, class = std::enable_if_t<std::is_integral<CharType>::value, decltype(std::declval<GetDescriptionFn&&>()(std::declval<platform_code_t>()))>>
	PlatformException (platform_code_t nPlatformCode, GetDescriptionFn &&fnGetDescription, const CharType *restrict pszDescription, DescriptionFormatParams ... formatting_params) noexcept
template<class GetDescriptionFn , class CharType , class traits_t , class alloc_t , class = decltype(std::declval<GetDescriptionFn&&>()(std::declval<platform_code_t>()))>
	PlatformException (platform_code_t nPlatformCode, GetDescriptionFn &&fnGetDescription, std::basic_string< CharType, traits_t, alloc_t > strDescription) noexcept
	Constructs an exception object from a specified platform-specific error code, an optional user-defined function object calling system functions to map the code to the corresponding textual description, and a formatting string. More...
template<class CharType , class traits_t , class alloc_t >
	PlatformException (platform_code_t nPlatformCode, std::nullptr_t, std::basic_string< CharType, traits_t, alloc_t > strDescription) noexcept
	Constructs an exception object from a specified platform-specific error code, and a description format string. This is an overload of a constructor that receives a reference to a callable object specifying a mapping from a system error code to system defined description of the error. This form is supplied to provide an opportunity to specify a nullptr value as a callable object to discard calling the user defined callback. More...
	PlatformException (const std::system_error &sys_err) noexcept
	Constructs an exception object and generates a description, retrieving information from the [std::system_error] object. More...
virtual const char *	what () const noexcept
	Returns a description, corresponding to the exception, represented as a multi-byte string constructed using the current locale.
Public Member Functions inherited from ChsvCodeExceptionTempl< CHSVERROR_PLATFORM_ERROR >
	ChsvCodeExceptionTempl () noexcept
	ChsvCodeExceptionTempl (Exception::vararg_tag_t, const char_t *restrict pszUserDescription, std::va_list ap) noexcept
	Constructs an exception object of the specified (by class template parameter) type. The description, the constructed object is associated with, is constructed as specified using the format string and additional parameters, as specified by the Chusov::String::Printf function. Also, the <DESCRIPTION> tag can be specified in the format string to be changed by the string returned by the Chusov::ChsvErrorDescriptionW function for the error code. . More...
	ChsvCodeExceptionTempl (const char_t *restrict pszUserDescription, DescriptionFormatParams ... formatting_params) noexcept
	Constructs an exception object of the specified (by the class template parameter) type. The description, the constructed object is associated with, is constructed as specified using the format string and additional parameters, as specified by the Chusov::String::Printf function. Also, the <DESCRIPTION> tag can be specified in the format string to be changed by the string returned by the Chusov::ChsvErrorDescriptionW function for the error code. . More...
	ChsvCodeExceptionTempl (const std::basic_string< char_t, traits_t, alloc_t > &strDescription) noexcept
	Constructs an exception object with the description copied directly from a value of std::basic_string object, without any formatting. If the string is empty, the constructed exception description is a value returned by the Chusov::ChsvErrorDescriptionW function. . More...
	ChsvCodeExceptionTempl (const ChsvCodeExceptionTempl &)=default
	A standard copy constructor.
	ChsvCodeExceptionTempl (ChsvCodeExceptionTempl &&rr)=default
	A standard move constructor.
Public Member Functions inherited from ExceptionWithGenericCode< code_t, class >
template<class char_t , class fn_t , class = decltype(std::declval<fn_t&&>()(std::declval<code_t>()))>
	ExceptionWithGenericCode (code_t nCode, fn_t &&GetDescription, Exception::vararg_tag_t, const char_t *restrict lpszDescriptionFormat, std::va_list ap) noexcept
	Constructs an exception object by a specified error code, a functor, mapping the code to a description text, a format string and parameters for the formatting as specified by the Chusov::String::Printf function. . More...
template<class char_t >
	ExceptionWithGenericCode (code_t nCode, Exception::vararg_tag_t, const char_t *restrict lpszDescriptionFormat, std::va_list ap) noexcept
	Constructs an exception object by a specified error code, a format string and Printf formatting parameters. . More...
template<class char_t , class fn_t , class = decltype(std::declval<fn_t>()(code_t())), class ... DescriptionFormatParams>
	ExceptionWithGenericCode (code_t nCode, fn_t &&GetDescription, const char_t *restrict lpszDescriptionFormat, DescriptionFormatParams ... formatting_params) noexcept
	Constructs an exception object by a specified error code, a functor, mapping the code to a description text, a format string and parameters for the formatting as specified by the Chusov::String::Printf function. . More...
template<class char_t , class ... DescriptionFormatParams>
	ExceptionWithGenericCode (code_t nCode, const char_t *restrict lpszDescriptionFormat, DescriptionFormatParams ... formatting_params) noexcept
	Constructs an exception object with a specified error code, a format string and parameters for the formatting as specified by the Chusov::String::Printf function. . More...
template<class char_t , class ... DescriptionFormatParams>
	ExceptionWithGenericCode (code_t nCode, std::nullptr_t, const char_t *restrict lpszDescriptionFormat, DescriptionFormatParams ... formatting_params) noexcept
	Constructs an exception object with a specified error code, a format string and parameters for the formatting as specified by the Chusov::String::Printf function. . More...
template<class fn_t , class = decltype(std::declval<fn_t&&>()(std::declval<code_t>()))>
	ExceptionWithGenericCode (code_t nCode, fn_t &&GetDescription) noexcept
	Constructs an exception object by a specified error code and a functor, mapping the code to a textual description. More...
	ExceptionWithGenericCode (code_t nCode) noexcept
	Constructs an exception object with the specified error code. . More...
template<class fn_t , class char_t , class traits_t , class alloc_t , class = decltype(std::declval<fn_t>()(code_t()))>
	ExceptionWithGenericCode (code_t nCode, fn_t &&GetDescription, const std::basic_string< char_t, traits_t, alloc_t > &strDescriptionFormat) noexcept
	Constructs an exception object by a specified error code, and an std::basic_string string object. . More...
template<class char_t , class traits_t , class alloc_t >
	ExceptionWithGenericCode (code_t nCode, const std::basic_string< char_t, traits_t, alloc_t > &strDescriptionFormat) noexcept
	Constructs an exception object by a specified error code, and a description provided by an std::basic_string object. . More...
template<class char_t , class traits_t , class alloc_t >
	ExceptionWithGenericCode (code_t nCode, std::nullptr_t, const std::basic_string< char_t, traits_t, alloc_t > &strDescriptionFormat) noexcept
	Constructs an exception object by a specified error code, and a description provided by an std::basic_string object. . More...
	ExceptionWithGenericCode (const ExceptionWithGenericCode &refRight)=default
	Default copy constructor.
	ExceptionWithGenericCode (ExceptionWithGenericCode &&refRight)=default
	Default move constructor.
code_t	Code () const noexcept
	Returns an error code, the exception object is bound with.
Public Member Functions inherited from Exception
	Exception ()=default
	Construct a default exception object without specified description. The default description is a valid but unspecified C string.
template<class ... DescriptionFormatParams>
	Exception (const char *restrict lpszDescriptionFormat, DescriptionFormatParams ... formatting_params) noexcept
	Constructs an exception object with an optional description, specified by Chusov::String::PrintfA formatting rules. More...
template<class ... DescriptionFormatParams>
	Exception (const wchar_t *restrict lpszDescriptionFormat, DescriptionFormatParams ... formatting_params) noexcept
	Constructs an exception object with an optional description, specified by Chusov::String::PrintfW formatting rules. More...
	Exception (vararg_tag_t, const char *restrict lpszDescriptionFormat, std::va_list ap) noexcept
	Constructs an exception object with an optional description, specified by Chusov::String::PrintfA formatting rules. More...
	Exception (vararg_tag_t, const wchar_t *restrict lpszDescriptionFormat, std::va_list ap) noexcept
	Constructs an exception object with an optional description, specified by Chusov::String::PrintfW formatting rules. More...
template<class traits_t , class alloc_t >
	Exception (const std::basic_string< char, traits_t, alloc_t > &strDescription) noexcept
	Constructs an exception based on a textual description, represented as a multi-byte std::basic_string object. More...
template<class traits_t , class alloc_t >
	Exception (const std::basic_string< wchar_t, traits_t, alloc_t > &strDescription) noexcept
	Constructs an exception based on a textual description, represented as a wide std::basic_string object. More...
	Exception (const Exception &refRight)=default
	Standard copy constructor.
	Exception (Exception &&ex)=default
	Standard move constructor.
template<class StdExcept , class = std::enable_if_t<Implementation::is_std_except<StdExcept>::value>>
	Exception (StdExcept &&ex) noexcept
virtual	~Exception () noexcept
	A default destructor.
Exception &	operator= (const Exception &)=default
	Standard copy assignment operator.
Exception &	operator= (Exception &&)=default
	Standard move assignment operator.
virtual const wchar_t *	What () const noexcept
	Returns a description, corresponding to the exception, represented as a wide string.

Protected Member Functions
template<class CharType , class GetDescriptionFn , class = std::enable_if_t<std::is_integral<CharType>::value, decltype(std::declval<GetDescriptionFn&&>()(std::declval<platform_code_t>()))>>
void	ConstructPlatformException (platform_code_t nPlatformCode, GetDescriptionFn &&fnGetDescription, Exception::vararg_tag_t, const CharType *restrict pszDescription, std::va_list ap) noexcept
	A template function performing a construction of the class template instantiation. More...
template<class CharType , class GetDescriptionFn , class ... DescriptionFormatParams, class = std::enable_if_t<std::is_integral<CharType>::value, decltype(std::declval<GetDescriptionFn&&>()(std::declval<platform_code_t>()))>>
void	ConstructPlatformException (platform_code_t nPlatformCode, GetDescriptionFn &&fnGetDescription, const CharType *restrict pszDescription, DescriptionFormatParams ... formatting_params) noexcept
	A template function performing a construction of the class template instantiation. More...
template<class CharType , class = std::enable_if_t<std::is_integral<CharType>::value>>
void	ConstructPlatformException (platform_code_t nPlatformCode, Exception::vararg_tag_t, const CharType *restrict pszDescription, std::va_list ap) noexcept
	Constructs an exception with a given platform-specific error code and a description specified with respect to the Printf format specification rules and to tag specification rules. More...
template<class CharType , class ... DescriptionFormatParams, class = std::enable_if_t<std::is_integral<CharType>::value>>
void	ConstructPlatformException (platform_code_t nPlatformCode, const CharType *restrict pszDescription, DescriptionFormatParams ... formatting_params) noexcept
	Constructs an exception with a given platform-specific error code and a description specified with respect to the Printf format specification rules and to tag specification rules. More...
Protected Member Functions inherited from ChsvCodeExceptionTempl< CHSVERROR_PLATFORM_ERROR >
void	SetDescription (noformat, const char_t *pszDescription) noexcept
	Sets a new description for the class object. The description is bound to the exception without any formatting. More...
void	SetDescription (const Chusov::String::TAG_DESCRIPTION_PARAM< char_t > *restrict pTags, std::size_t cTags, Exception::vararg_tag_t, const char_t *restrict pszDescriptionFormat, std::va_list ap) noexcept
	Sets a new description for the class object. The description is specified by Printf formatting sequences and by tags. More...
void	SetDescription (const Chusov::String::TAG_DESCRIPTION_PARAM< char_t > *restrict pTags, std::size_t cTags, const char_t *restrict pszDescriptionFormat, DescriptionFormatParams ... formatting_params) noexcept
	Sets a new description for the class object. The description is specified by Printf formatting sequences and by tags. More...
auto	SetDescription (Exception::vararg_tag_t, const char_t *restrict pszDescriptionFormat, std::va_list ap) noexcept -> std::enable_if_t< std::is_integral< char_t >::value >
	Sets a result of the Printf formatting as a new description for the exception object. More...
auto	SetDescription (const char_t *restrict pszDescriptionFormat, DescriptionFormatParams ... formatting_params) noexcept -> std::enable_if_t< std::is_integral< char_t >::value >
	Sets a result of the Printf formatting as a new description for the exception object. More...
void	SetDescription ()
	Sets the default description for the exception object stating that textual definition, which is returned by what method is unspecified.
	ChsvCodeExceptionTempl (DoNotConstruct)
	A constructor that does not do anything except for calling default constructors for the parent class. It is used to avoid unnecessary operations performed by the default constructor, and to let the inheritors of the class instance to call the ExceptionWithGenericCode::SetCodeAndDescription method to construct the description. .
Protected Member Functions inherited from ExceptionWithGenericCode< code_t, class >
	ExceptionWithGenericCode ()=default
	A default protected constructor of the exception object.
template<class char_t >
auto	SetCodeAndDescription (code_t nCode, const char_t *lpszDescription) noexcept -> std::enable_if_t< std::is_integral< char_t >::value >
	Sets a new error code and description without any formatting. More...
template<class char_t , class fn_t , class = decltype(std::declval<fn_t&&>()(std::declval<code_t>()))>
auto	SetCodeAndDescription (code_t nCode, fn_t &&GetDescription, const String::TAG_DESCRIPTION_PARAM< char_t > *restrict pTags, std::size_t cTags, noprintf, const char_t *restrict lpszDescriptionFormat) noexcept -> std::enable_if_t< std::is_integral< char_t >::value, decltype(void(std::declval< fn_t && >()(std::declval< code_t >())))>
	Sets a new exception description, according to the specified error code, formatting rules and a functor object mapping the error code to its default string description. . More...
template<class char_t , class fn_t , class = decltype(std::declval<fn_t&&>()(std::declval<code_t>()))>
auto	SetCodeAndDescription (code_t nCode, fn_t &&GetDescription, const String::TAG_DESCRIPTION_PARAM< char_t > *restrict pTags, std::size_t cTags, Exception::vararg_tag_t, const char_t *restrict lpszDescriptionFormat, std::va_list ap) noexcept -> std::enable_if_t< std::is_integral< char_t >::value, decltype(void(std::declval< fn_t && >()(std::declval< code_t >())))>
	Sets a new exception description, according to the specified error code, formatting rules (with custom tags), variadic list of parameters and a function object mapping the error code to its default string description. . More...
template<class char_t , class fn_t , class = decltype(std::declval<fn_t&&>()(std::declval<code_t>()))>
auto	SetCodeAndDescription (code_t nCode, fn_t &&GetDescription, Exception::vararg_tag_t, const char_t *restrict lpszDescriptionFormat, std::va_list ap) noexcept -> std::enable_if_t< std::is_integral< char_t >::value, decltype(void(std::declval< fn_t && >()(std::declval< code_t >())))>
	Sets a new exception description, according to the specified error code, formatting rules (without tag customization), variadic list of parameters and a function object mapping the error code to its default string description. More...
template<class char_t >
auto	SetCodeAndDescription (code_t nCode, Exception::vararg_tag_t, const char_t *restrict lpszDescriptionFormat, std::va_list ap) noexcept -> std::enable_if_t< std::is_integral< char_t >::value >
	Sets a new exception description, according to the specified error code, formatting rules (without tag customization), variadic list of parameters and a function object mapping the error code to its default string description. More...
template<class char_t , class fn_t , class ... DescriptionFormatParams>
auto	SetCodeAndDescription (code_t nCode, fn_t &&GetDescription, const String::TAG_DESCRIPTION_PARAM< char_t > *restrict pTags, std::size_t cTags, const char_t *restrict lpszDescriptionFormat, DescriptionFormatParams ... formatting_params) noexcept -> std::enable_if_t< std::is_integral< char_t >::value &&Chusov::String::is_valid_printf_type_set_v< DescriptionFormatParams... >, decltype(void(std::declval< fn_t && >()(std::declval< code_t >())))>
	Sets a new exception description, according to the specified error code, formatting rules (with custom tags), formatting parameter pack and a functor object mapping the error code to its default string description. . More...
template<class char_t , class fn_t , class ... DescriptionFormatParams>
auto	SetCodeAndDescription (code_t nCode, fn_t &&GetDescription, const char_t *restrict lpszDescriptionFormat, DescriptionFormatParams ... formatting_params) noexcept -> std::enable_if_t< std::is_integral< char_t >::value &&Chusov::String::is_valid_printf_type_set_v< DescriptionFormatParams... >, decltype(void(std::declval< fn_t && >()(std::declval< code_t >())))>
	Sets a new exception description, according to the specified error code, formatting rules (without tag customization), formatting parameter pack and a functor object mapping the error code to its default string description. More...
template<class char_t , class ... DescriptionFormatParams>
auto	SetCodeAndDescription (code_t nCode, const char_t *restrict lpszDescriptionFormat, DescriptionFormatParams ... formatting_params) noexcept -> std::enable_if_t< Chusov::String::is_valid_printf_type_set_v< DescriptionFormatParams... >>
	Sets a new exception description, according to the specified error code, formatting rules (without tag customization), variadic list of parameters and a function object mapping the error code to its default string description. More...
Protected Member Functions inherited from Exception
void	SetWhat (wchar_t *lpszOwnedWhat) noexcept
void	SetWhat (char *lpszOwnedWhat) noexcept

Additional Inherited Members
Public Types inherited from ChsvCodeExceptionTempl< CHSVERROR_PLATFORM_ERROR >
typedef chsverror_t	code_t
	A type alias for an error code type.
Public Types inherited from Exception
enum	vararg_tag_t { vararg_tag }
Static Public Member Functions inherited from ChsvCodeExceptionTempl< CHSVERROR_PLATFORM_ERROR >
static const char_t *	get_description (code_t nErr) noexcept
	A unary function wrapped around the Chusov::ChsvErrorDescription function in order for the latter to be provided as a function object mapping an integral error code to a string description to replace <DESCRIPTION> tags during by-tag formatting of an exception description. More...
Protected Types inherited from ChsvCodeExceptionTempl< CHSVERROR_PLATFORM_ERROR >
enum class	DoNotConstruct
	A type of the parameter of the protected ChsvCodeExceptionTempl(DoNotConstruct) constructor.
Static Protected Member Functions inherited from ExceptionWithGenericCode< code_t, class >
template<class char_t >
static const char_t *	GetDefaultDescription (code_t) noexcept
	A default function object as a stub for methods that do not specify user-defined functors. It maps any integral code to a NULL description. More...

Detailed Description

template<class pltfrm_code_t>
class Chusov::Exceptions::PlatformException< pltfrm_code_t >

A class template designed specifically for using with externally defined error codes.

Template Parameters

pltfrm_code_t

is a type of externally defined error codes.

The instantiations of the class template directly inherit the ChsvCodeExceptionTempl<CHSVERROR_PLATFORM_ERROR> template instantiation. Therefore, the PlatformException template defines inheritance of all of the properties, including the formatting rules. Consequently, <CODE> and <DESCRIPTION> tags resolve to a numeric representation of the CHSVERROR_PLATFORM_ERROR error code and its corresponding description respectively, and not to the representation of the platform error code or a platform-defined description. For these purposes the caller of the constructors of the class template can use <PLATFORM_CODE> and <PLATFORM_DESCRIPTION> respectively.

The description of an error code is specified during constructions of template instantiations. The description can be specified by a class user with respect to the supported tags (<CODE>, <DESCRIPTION>, <PLATFORM_CODE> and <PLATFORM_DESCRIPTION>) and to the rules given for the Chusov::String::Printf function. Also, the description can be omitted at all. In this case instantiations of the class template generate default descriptions which may or may not include either of the tags.

If a function object, mapping the error code to the corresponding textual description, is not specified or returns a NULL string, the constructors of the template instantiations specify a corresponding unspecified string saying that the description is not specified.

Defining a type of a functor mapping an error code to the corresponding textual description.

If we define it as a class template parameter

• A type of the exception directly upon the functor type. That means that the exceptions with different functor types will always be of different types as well. This can matter in cases like this:

  struct get_descr_t
  {
      const char* operator() (errno_t errc) const
      {
          return strerror(errc);
      }
  };
  void ThrowException()
  {
      try
      {
          throw PlatformExceprtion<errno_t, decltype(&strerror)>(errno, strerror);
      }catch (PlatformException<errno_t, get_descr_t>& ex)
      {
          //...
      }
  }

  An importance of this problem can be decreased providing aliases like in the following example :

  struct get_descr_t
  {
      const char* operator() (errno_t errc) const
      {
          return strerror(errc);
      }
  };
  typedef PlatformException<errno_t, get_descr_t> PosixException;
  void ThrowException()
  {
      try
      {
          throw PosixException(errno);
      }catch (PosixException&)
      {
          //...
      }
  }

  But a probability of errors, like the one shown in the first example, is still significant.
• Storing the function object as a class member would require additional code on our side to support copying and moving semantics. Although, we are not obliged to store the functor, but to construct the description during construction of an exception object.
• There's no need to specify a functor object in every constructor, since we can use the default-constructed functor.
• The client always needs to specify a type of the functor, even if he does not need the description. Although, an importance of this problem is diminished, since the client can use type aliases. And if the functor is default constructible and a type alias is used, then the client doe not need to care about the functor at all.
• If we want to free a client from an obligation to provide a functor, we can create a default function object type which will return "not specified" description, and pass a type of the functor as a default argument of the PlatformException.

If we define the functor type as a template parameter of a class constructor

• Many exceptions, described by the class template, having different nature can be of the same type, since the type only depends on the type of an integral error code. Functors of different types will not affect a type of the exception created. So there is a risk of type conflicts.
• A client does not need to specify a type of the functor, even if the one needs a description, in which case he only needs to specify the functor object itself within the appropriate constructor template, arguments for which are deduced.
• If we want the platform_exception_default_category_t object to provide a message, that returns a client's definition of an error code, it will violate a singleton design pattern, error category classes implemented according to, since it will require passing either a functor or a description string to constructors and creating multiple error category objects. Although, we can create a template of the error category class, which will depend upon a functor type. But this can lead to situations when exception objects of the same type belong to different error categories although [std::system_error], [std::error_category] and [std::error_code] are objects, but not a template, and such objects will always be of the same type but may belong to different categories, and the PlatformException is an [std::system_error] object.

See also

ChsvExceptionByPosixCode_format_params_char ChsvExceptionByPosixCode(errno_t nCode, const char* restrict pszDescription, DescriptionFormatParams... formatting_params);

ChsvExceptionByPosixCode_format_params_wchar_t ChsvExceptionByPosixCode(errno_t nCode, const wchar_t* restrict pszDescription, DescriptionFormatParams... formatting_params);
ChsvExceptionByPosixCode(errno_t nCode);
ChsvExceptionByPosixCode().

---

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

• chsvexception.h