Error Handling . Boost , Math Toolkit 2.5.0 , Chapter 1. Overview

Error Handling

Quick Reference

Обработка ошибок этой библиотекой разделена на две ортогональные части:

Какая ошибка была допущена?
Что делать, если ошибка поднята?

	Warning
	Действия ошибки по умолчанию включают исключение с информативным сообщением об ошибке. Если вы не попытаетесь поймать исключение, вы не увидите сообщение!

Виды ошибок, которые могут быть подняты:

Domain Error: Возникает, когда один или несколько аргументов для функции находятся вне диапазона.
Pole Error: Возникает, когда конкретные аргументы вызывают оценку функции на полюсе без четко определенной остаточной стоимости. Например, еслиtgammaоценивается в точности -2, функция приближается к различным предельным значениям в зависимости от того, приближаетесь ли вы к чуть выше или чуть ниже -2. Следовательно, функция не имеет четко определенного значения, и ошибка полюса будет повышена.
Overflow Error: Возникает, когда результат либо бесконечен, либо слишком велик, чтобы представлять в численном типе возвращаемую функцией.
Underflow Error: Возникает, когда результат не равен нулю, но слишком мал, чтобы быть представленным каким-либо другим значением в типе, возвращаемом функцией.
Denormalisation Error: Возникает, когда возвращаемый результат будет денормализованным.
Rounding Error: Возникает, когда аргумент в пользу одной из функций округленияtrunc,roundиmodfне может быть представлен в виде целого типа, находящегося за пределами диапазона типа результата.
Evaluation Error: Возникает, если метод оценки неизвестен или когда произошла внутренняя ошибка, которая не позволила оценить результат: это никогда не должно произойти, но если это произойдет, то это, вероятно, будет связано с итеративным методом, который не сходится достаточно быстро.
Indeterminate Result Error: Возникает, когда результат функции не определен для значений, которые были ему переданы.

Действие, предпринятое каждым условием ошибки, определяется действующей Политикой. Это может быть изменено по всей программе путем установки некоторых макросов конфигурации, или в области пространства имен, или на сайте вызова (путем указания конкретной политики в вызове функции).

Имеющиеся меры включают:

throw_on_error: Бросает исключение, наиболее соответствующее условию ошибки.
errno_on_error: Устанавливает::errno на соответствующее значение, а затем возвращает наиболее подходящий результат
ignore_error: Игнорирует ошибку и просто возвращает наиболее подходящий результат.
user_error: Называетсяпоставляемый пользователем обработчик ошибок.

Следующие таблицы показывают все перестановки ошибок и действий, причемпо умолчанию для каждой ошибки показано жирным шрифтом:

Table 1.1. Possible Actions for Domain Errors

Меры	поведение
throw_on_error	Бросает<`std::domain_error`>
errno_on_error	Устанавливает<`::errno`>до<`EDOM`>и возвращает<`std::numeric_limits<T>::quiet_NaN()`>
Ошибка	Возвращение<`std::numeric_limits<T>::quiet_NaN()`>
Ошибка пользователя	Возвращает результат<`boost::math::policies::user_domain_error`>:эта функция должна быть определена пользователем.

Table 1.2. Possible Actions for Pole Errors

Меры	поведение
throw_on_error	Бросает<`std::domain_error`>
errno_on_error	Устанавливает<`::errno`>до<`EDOM`>и возвращает<`std::numeric_limits<T>::quiet_NaN()`>
Ошибка	Возвращение<`std::numeric_limits<T>::quiet_NaN()`>
Ошибка пользователя	Возвращает результат<`boost::math::policies::user_pole_error`>:эта функция должна быть определена пользователем.

Table 1.3. Possible Actions for Overflow Errors

Меры	поведение
throw_on_error	Бросает<`std::overflow_error`>
errno_on_error	Устанавливает<`::errno`>до<`ERANGE`>и возвращает<`std::numeric_limits<T>::infinity()`>
Ошибка	Возвращение<`std::numeric_limits<T>::infinity()`>
Ошибка пользователя	Возвращает результат<`boost::math::policies::user_overflow_error`>:эта функция должна быть определена пользователем.

Table 1.4. Possible Actions for Underflow Errors

Меры	поведение
throw_on_error	Броски<`std::underflow_error`>
errno_on_error	Устанавливает<`::errno`>на<`ERANGE`>и возвращает 0.
Ошибка	Возвращение 0
Ошибка пользователя	Возвращает результат<`boost::math::policies::user_underflow_error`>:эта функция должна быть определена пользователем.

Table 1.5. Possible Actions for Denorm Errors

Меры	поведение
throw_on_error	Броски<`std::underflow_error`>
errno_on_error	Устанавливает<`::errno`>на<`ERANGE`>и возвращает денормализованное значение.
Ошибка	Возвращает денормализованное значение.
Ошибка пользователя	Возвращает результат<`boost::math::policies::user_denorm_error`>:эта функция должна быть определена пользователем.

Table 1.6. Possible Actions for Rounding Errors

Меры	поведение
throw_on_error	Бросок<`boost::math::rounding_error`>
errno_on_error	Устанавливает<`::errno`>на<`ERANGE`>и возвращает наибольшее репрезентабельное значение целевого целого типа (или самое отрицательное значение, если аргумент функции был меньше нуля).
Ошибка	Возвращает наибольшее репрезентабельное значение целевого целого типа (или самое отрицательное значение, если аргумент функции был меньше нуля).
Ошибка пользователя	Возвращает результат<`boost::math::policies::user_rounding_error`>:эта функция должна быть определена пользователем.

Table 1.7. Possible Actions for Internal Evaluation Errors

Меры	поведение
throw_on_error	Броски<`boost::math::evaluation_error`>
errno_on_error	Устанавливает<`::errno`>на<`EDOM`>и возвращает наиболее близкое приближение.
Ошибка	Возвращает самое близкое приближение.
Ошибка пользователя	Возвращает результат<`boost::math::policies::user_evaluation_error`>:эта функция должна быть определена пользователем.

Table 1.8. Possible Actions for Indeterminate Result Errors

Меры	поведение
throw_on_error	Броски<`std::domain_error`>
errno_on_error	Устанавливает<`::errno`>на<`EDOM`>и возвращает то же значение, что<`ignore_error`> .
Ошибка	Возвращает результат по умолчанию, который зависит от функции, где произошла ошибка.
Ошибка пользователя	Возвращает результат<`boost::math::policies::user_indeterminate_result_error`>:эта функция должна быть определена пользователем.

Все эти условия погрешности приведены в усилителе пространства имен::math::policies, сделанном доступным, например, заявлением пространства имен с использованием<namespace boost::math::policies;>или индивидуальным использованием деклараций<usingboost::math::policies::overflow_error;>.

Rationale

Гибкость текущей реализации должна быть достаточно очевидной: поведение по умолчанию было выбрано на основе обратной связи во время официального обзора этой библиотеки. Было сочтено, что:

Подлинные ошибки следует помечать исключениями, а не следовать C-совместимому поведению и настройке<::errno>.
Числовой отток и денормализованные результаты в большинстве случаев не считались фатальными ошибками, поэтому было сочтено, что их следует игнорировать.
При наличии более чем одной ошибки в бросок-сообщении будет сообщено только первое обнаруженное.

Finding More Information

Существуют некоторые макро-определения предварительного процессора, которые можно использовать дляизменения по умолчанию политики. См. также раздел политики.

В качестве примера можно привести учебник по политике. Изменение политических дефолтов.

Полный исходный код этого типичного примера передачи «плохого» аргумента (отрицательных степеней свободы) в распределение t Студентав примере обработки ошибок.

Различные типы ошибок описаны более подробно ниже.

Domain Errors

Когда специальная функция проходит аргумент, который находится за пределами диапазона значений, для которых эта функция определена, то функция возвращает результат:

boost::math::policies::raise_domain_error<T>(FunctionName, Message, Val, Policy);

Если<T>— это тип плавающей точки, переданный функции,<FunctionName>— название функции,<Message>— сообщение об ошибке, описывающее проблему, Val — значение, которое было вне диапазона, аPolicy— текущая политика, используемая для функции, которая была названа.

Политика по умолчанию этой функции заключается в том, чтобы добавить исключение std::domain_error C++. Но если политиказаключается в том, чтобы игнорировать ошибку или установить глобальную<::errno>, то NaN будет возвращен.

Это поведение выбрано для обеспечения совместимости с поведением.ISO/IEC 9899:1999 Языки программирования - Cи сПроект технического доклада о расширении библиотеки C++, 2005-06-24, раздел 5.2.1, пункт 6:

"Каждая из функций, заявленных выше, возвращает NaN (Not a Number), если какое-либо значение аргумента является NaN, но не сообщает об ошибке домена. В противном случае каждая из указанных выше функций должна сообщать об ошибке домена только для тех значений аргументов, для которых:

"описание функции возвращает пункт явно указывает домен, и эти аргументы выходят за пределы указанного домена; или

"соответствующее математическое значение функции имеет ненулевой воображаемый компонент; или

"соответствующая математическая функция математически не определена.

«Примечание 2: математическая функция математически определена для данного набора значений аргумента, если она явно определена для этого набора значений аргумента или если ее ограничивающее значение существует и не зависит от направления подхода».

Обратите внимание, что для поддержки сообщений об ошибках, богатых информацией, при броске исключений<Message>должно содержатьувеличение. Форматраспознанный спецификатор формата: аргумент<Val>вставляется в сообщение об ошибке в соответствии с используемым спецификатором.

Например, если<Message>содержит «%1%», то оно заменяется значением<Val>с полной точностью T, где как «%.3g» будет содержать значение<Val>до 3 цифр. Подробнее см. документациюBoost.Format.

Evaluation at a pole

Когда специальная функция проходит аргумент, который находится на полюсе без четко определенной остаточной стоимости, то функция возвращает результат:

boost::math::policies::raise_pole_error<T>(FunctionName, Message, Val, Policy);

Если<T>— это тип плавающей точки, переданный функции,<FunctionName>— название функции,<Message>— сообщение об ошибке, описывающее проблему,<Val>— значение аргумента, находящегося на полюсе, иПолитика— текущая политика, используемая для функции, которая была названа.

По умолчанию эта функция выполняет исключение std::domain_error. Нополитики обработки ошибокмогут быть использованы для изменения этого, например, на<ignore_error>и возврата NaN.

Обратите внимание, что для поддержки сообщений об ошибках, богатых информацией, при броске исключений<Message>должно содержатьувеличение. Форматпризнанный спецификатор формата: аргумент<val>вставляется в сообщение об ошибке в соответствии с используемым спецификатором.

Например, если<Message>содержит «%1%», то оно заменяется значением<val>с полной точностью T, где как «%.3g» будет содержать значение<val>до 3 цифр. Подробнее см. документациюBoost.Format.

Numeric Overflow

Когда результат специальной функции слишком велик, чтобы вписаться в аргумент типа плавающей точки, то функция возвращает результат:

boost::math::policies::raise_overflow_error<T>(FunctionName, Message, Policy);

Если<T>— это тип с плавающей точкой, переданный функции,<FunctionName>— это название функции,<Message>— сообщение об ошибке, описывающее проблему, иПолитика— это текущая политика, используемая для функции, которая была названа.

Политика по умолчанию для этой функции заключается в том, что<std::overflow_error>C++ исключен. Но если, например, используется политика<ignore_error>, то возвращается<std::numeric_limits<T>::infinity()>. В этой ситуации, если тип<T>не поддерживает бесконечности, возвращается максимальное значение для типа.

Numeric Underflow

Если результат специальной функции известен как ненулевой, но вычисленный результат недотекает до нуля, то функция возвращает результат:

boost::math::policies::raise_underflow_error<T>(FunctionName, Message, Policy);

Если<T>— это тип плавающей точки, переданный функции,<FunctionName>— название функции,<Message>— сообщение об ошибке, описывающее проблему, аполитика— текущая политика, используемая для названной функции.

Версия этой функции по умолчанию возвращает ноль. Но с другой политикой, как<throw_on_error>, бросает<std::underflow_error>C++ исключение.

Denormalisation Errors

Если результатом специальной функции является денормированное значениеz, то функция возвращает результат:

boost::math::policies::raise_denorm_error<T>(z, FunctionName, Message, Policy);

По умолчанию версия этой функции возвращаетz. Но с другой политикой, как<throw_on_error>бросает<std::underflow_error>C++ исключение.

Evaluation Errors

Когда специальная функция вычисляет результат, который, как известно, ошибочен, или где результат неисчислим, она называет:

boost::math::policies::raise_evaluation_error<T>(FunctionName, Message, Val, Policy);

Если<T>— это тип плавающей точки, переданный функции,<FunctionName>— название функции,<Message>— сообщение об ошибке, описывающее проблему,<Val>— ошибочное значение, аполитика— текущая политика, используемая для названной функции.

По умолчанию эта функция выполняется для броска<boost::math::evaluation_error>.

Обратите внимание, что для поддержки информации, богатой сообщениями об ошибках при броске исключений,<Message>должен содержатьBoost.Formatпризнанный спецификатор формата: аргумент<val>вставляется в сообщение об ошибке в соответствии с используемым спецификатором.

Indeterminate Result Errors

Когда результат специальной функции неопределён для переданного ему значения, то функция возвращает результат:

boost::math::policies::raise_overflow_error<T>(FunctionName, Message, Val, Default, Policy);

Если<T>— это тип с плавающей точкой, переданный функции,<FunctionName>— название функции,<Message>— сообщение об ошибке, описывающее проблему, Val — значение, для которого результат неопределён, Default — альтернативный результат по умолчанию, который должен быть возвращен для политик<ignore_error>и<errno_on_erro>, аПолитика— текущая политика, используемая для функции, которая была названа.

По умолчанию для этой функции<ignore_error>: Обратите внимание, что этот тип ошибки зарезервирован для ситуаций, когда результат математически неопределён или неопределён, но тем не менее существует условность того, каким должен быть результат: например, стандарт C99 указывает, что результат 0⁰равен 1, хотя результат на самом деле математически неопределён.

Rounding Errors

Когда одна из функций округления,,, truncили, modfвызывается аргументом, который не имеет целочисленного представления или слишком велик, чтобы быть представленным в типе результата, то возвращаемое значение является результатом вызова:

boost::math::policies::raise_rounding_error<T>(FunctionName, Message, Val, Policy);

Если<T>— это тип плавающей точки, переданный функции,<FunctionName>— название функции,<Message>— сообщение об ошибке, описывающее проблему,<Val>— ошибочный аргумент, аполитика— текущая политика, используемая для названной функции.

По умолчанию эта функция выполняется для броска<boost::math::rounding_error>.

Errors from typecasts

Многие специальные функции оценивают свои результаты с более высокой точностью, чем их аргументы, чтобы обеспечить полную точность машины в результате: например, функция, прошедшая поплавковый аргумент, может оценивать его результат с использованием двойной точности внутри. Поэтому многие из перечисленных выше ошибок могут возникать не во время оценки, а при преобразовании результата в более узкий тип результата. Функция:

template <class T, class Policy, class U>
T checked_narrowing_cast(U const& val, const char* function);

Используется для выполнения этих преобразований и вызовет обработчики ошибок, перечисленные выше, напереполнение,подтеканиеилиденормализацию.

Статья Error Handling раздела Math Toolkit 2.5.0 Chapter 1. Overview может быть полезна для разработчиков на c++ и boost.