From f15253586551b1d52666af8e268fde7cf4a795b0 Mon Sep 17 00:00:00 2001
From: Vadim Pisarevsky <no@email>
Date: Thu, 20 May 2010 11:37:37 +0000
Subject: [PATCH] extended description of the error handling mechanism with
 OpenCV C++ API

---
 doc/cxcore_introduction.tex               | 32 ++++++++++++++++++++++-
 doc/cxcore_utilities_system_functions.tex |  2 +-
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/doc/cxcore_introduction.tex b/doc/cxcore_introduction.tex
index 628c9ec7c0..6f1f8049fd 100644
--- a/doc/cxcore_introduction.tex
+++ b/doc/cxcore_introduction.tex
@@ -406,7 +406,37 @@ It is not a new feature of OpenCV v2.x, it was there from very beginning. In the
 
 \section{Error handling}
 
-The modern error handling mechanism in OpenCV uses exceptions, as opposite to the manual stack unrolling used in previous versions. When OpenCV is built in DEBUG configuration, the error handler provokes memory access violation, so that the full call stack and context can be analyzed with debugger.
+The modern error handling mechanism in OpenCV uses exceptions, as opposite to the manual stack unrolling used in previous versions.
+
+If you to check some conditions in your code and raise an error if they are not satisfied, use \hyperref[CV Assert]{CV\_Assert}() or \hyperref[cppfunc.error]{CV\_Error}().
+
+\begin{lstlisting}
+CV_Assert(mymat.type() == CV_32FC1);
+...
+
+if( scaleValue < 0 || scaleValue > 1000 )
+   CV_Error(CV_StsOutOfRange, "The scale value is out of range");
+\end{lstlisting}
+
+There is also \hyperref[CV Assert]{CV\_DbgAssert} that yields no code in the Release configuration.
+
+To handle the errors, use the standard exception handling mechanism:
+
+\begin{lstlisting}
+try
+{
+    ...
+}
+catch( cv::Exception& e )
+{
+    const char* err_msg = e.what();
+    ...
+}
+\end{lstlisting}
+ 
+instead of \hyperref[Exception]{cv::Exception} you can write \texttt{std::exception}, since the former is derived from the latter.
+
+Then, obviously, to make it all work and do not worry about the object destruction, try not to use \texttt{IplImage*}, \texttt{CvMat*} and plain pointers in general. Use \hyperref[Mat]{cv::Mat}, \texttt{std::vector<>}, \hyperref[Ptr]{cv::Ptr} etc.
 
 \section{Threading and Reenterability}
 
diff --git a/doc/cxcore_utilities_system_functions.tex b/doc/cxcore_utilities_system_functions.tex
index 9d912baf99..5c87023c57 100644
--- a/doc/cxcore_utilities_system_functions.tex
+++ b/doc/cxcore_utilities_system_functions.tex
@@ -636,7 +636,7 @@ CV_Error_(CV_StsOutOfRange,
 \end{lstlisting}
 
 
-\cvclass{Exception}
+\cvclass{Exception}\label{Exception}
 The exception class passed to error
 
 \begin{lstlisting}
-- 
GitLab