<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>Eigen: Assertions</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
$(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="eigendoxy.css" rel="stylesheet" type="text/css">
<!-- -->
<script type="text/javascript" src="eigen_navtree_hacks.js"></script>
<!-- <script type="text/javascript"> -->
<!-- </script> -->
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<!-- <a name="top"></a> -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="Eigen_Silly_Professor_64x64.png"/></td>
<td style="padding-left: 0.5em;">
<div id="projectname"><a href="http://eigen.tuxfamily.org">Eigen</a>
 <span id="projectnumber">3.2.0</span>
</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('TopicAssertions.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Friends</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark"> </span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Assertions </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="PlainAssert"></a>
Assertions</h1>
<p>The macro eigen_assert is defined to be <code>eigen_plain_assert</code> by default. We use eigen_plain_assert instead of <code>assert</code> to work around a known bug for GCC <= 4.3. Basically, eigen_plain_assert <em>is</em> <code>assert</code>.</p>
<h2><a class="anchor" id="RedefineAssert"></a>
Redefining assertions</h2>
<p>Both eigen_assert and eigen_plain_assert are defined in <a class="el" href="Macros_8h_source.html">Macros.h</a>. Defining eigen_assert indirectly gives you a chance to change its behavior. You can redefine this macro if you want to do something else such as throwing an exception, and fall back to its default behavior with eigen_plain_assert. The code below tells <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> to throw an std::runtime_error:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <stdexcept></span></div>
<div class="line"><span class="preprocessor">#undef eigen_assert</span></div>
<div class="line"><span class="preprocessor"></span><span class="preprocessor">#define eigen_assert(x) \</span></div>
<div class="line"><span class="preprocessor"> if (!x) { throw (std::runtime_error("Put your message here")); }</span></div>
</div><!-- fragment --><h2><a class="anchor" id="DisableAssert"></a>
Disabling assertions</h2>
<p>Assertions cost run time and can be turned off. You can suppress eigen_assert by defining <code>EIGEN_NO_DEBUG</code> <b>before</b> including <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> headers. <code>EIGEN_NO_DEBUG</code> is undefined by default unless <code>NDEBUG</code> is defined.</p>
<h1><a class="anchor" id="StaticAssert"></a>
Static assertions</h1>
<p>Static assertions are not standardized until C++11. However, in the <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> library, there are many conditions can and should be detectedat compile time. For instance, we use static assertions to prevent the code below from compiling.</p>
<div class="fragment"><div class="line"><a class="code" href="group__matrixtypedefs.html#ga45a14b423c687c3e2e8325f148e27bf3">Matrix3d</a>() + <a class="code" href="group__matrixtypedefs.html#gacd860ff07358f6a703c2c0d4a174e920">Matrix4d</a>(); <span class="comment">// adding matrices of different sizes</span></div>
<div class="line"><a class="code" href="group__matrixtypedefs.html#gab388a941709b398b716c3cc846216a90">Matrix4cd</a>() * <a class="code" href="group__matrixtypedefs.html#ga512cfe207272d8ece67a9adad344e748">Vector3cd</a>(); <span class="comment">// invalid product known at compile time</span></div>
</div><!-- fragment --><p>Static assertions are defined in <a class="el" href="StaticAssert_8h_source.html">StaticAssert.h</a>. If there is native static_assert, we use it. Otherwise, we have implemented an assertion macro that can show a limited range of messages.</p>
<p>One can easily come up with static assertions without messages, such as:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define STATIC_ASSERT(x) \</span></div>
<div class="line"><span class="preprocessor"> switch(0) { case 0: case x:; }</span></div>
</div><!-- fragment --><p>However, the example above obviously cannot tell why the assertion failed. Therefore, we define a <code>struct</code> in namespace <a class="el" href="namespaceEigen_1_1internal.html">Eigen::internal</a> to handle available messages.</p>
<div class="fragment"><div class="line"><span class="keyword">template</span><<span class="keywordtype">bool</span> condition></div>
<div class="line"><span class="keyword">struct </span>static_assertion {};</div>
<div class="line"></div>
<div class="line"><span class="keyword">template</span><></div>
<div class="line"><span class="keyword">struct </span>static_assertion<true></div>
<div class="line">{</div>
<div class="line"> <span class="keyword">enum</span> {</div>
<div class="line"> YOU_TRIED_CALLING_A_VECTOR_METHOD_ON_A_MATRIX,</div>
<div class="line"> YOU_MIXED_VECTORS_OF_DIFFERENT_SIZES,</div>
<div class="line"> <span class="comment">// see StaticAssert.h for all enums.</span></div>
<div class="line"> };</div>
<div class="line">};</div>
</div><!-- fragment --><p>And then, we define EIGEN_STATIC_ASSERT(CONDITION,MSG) to access Eigen::internal::static_assertion<bool(CONDITION)>::MSG. If the condition evaluates into <code>false</code>, your compiler displays a lot of messages explaining there is no MSG in static_assert<false>. Nevertheless, this is <em>not</em> in what we are interested. As you can see, all members of static_assert<true> are ALL_CAPS_AND_THEY_ARE_SHOUTING.</p>
<dl class="section warning"><dt>Warning</dt><dd>When using this macro, MSG should be a member of static_assertion<true>, or the static assertion <b>always</b> fails. Currently, it can only be used in function scope.</dd></dl>
<h2><a class="anchor" id="DerivedStaticAssert"></a>
Derived static assertions</h2>
<p>There are other macros derived from EIGEN_STATIC_ASSERT to enhance readability. Their names are self-explanatory.</p>
<ul>
<li><b>EIGEN_STATIC_ASSERT_FIXED_SIZE(TYPE)</b> - passes if <em>TYPE</em> is fixed size.</li>
<li><b>EIGEN_STATIC_ASSERT_DYNAMIC_SIZE(TYPE)</b> - passes if <em>TYPE</em> is dynamic size.</li>
<li><b>EIGEN_STATIC_ASSERT_LVALUE(Derived)</b> - failes if <em>Derived</em> is read-only.</li>
<li><b>EIGEN_STATIC_ASSERT_ARRAYXPR(Derived)</b> - passes if <em>Derived</em> is an array expression.</li>
<li><b>EIGEN_STATIC_ASSERT_SAME_XPR_KIND(Derived1, Derived2)</b> - failes if the two expressions are an array one and a matrix one.</li>
</ul>
<p>Because <a class="el" href="namespaceEigen.html" title="Namespace containing all symbols from the Eigen library. ">Eigen</a> handles both fixed-size and dynamic-size expressions, some conditions cannot be clearly determined at compile time. We classify them into strict assertions and permissive assertions.</p>
<h3><a class="anchor" id="StrictAssertions"></a>
Strict assertions</h3>
<p>These assertions fail if the condition <b>may not</b> be met. For example, MatrixXd may not be a vector, so it fails EIGEN_STATIC_ASSERT_VECTOR_ONLY.</p>
<ul>
<li><b>EIGEN_STATIC_ASSERT_VECTOR_ONLY(TYPE)</b> - passes if <em>TYPE</em> must be a vector type.</li>
<li><b>EIGEN_STATIC_ASSERT_VECTOR_SPECIFIC_SIZE(TYPE, SIZE)</b> - passes if <em>TYPE</em> must be a vector of the given size.</li>
<li><b>EIGEN_STATIC_ASSERT_MATRIX_SPECIFIC_SIZE(TYPE, ROWS, COLS)</b> - passes if <em>TYPE</em> must be a matrix with given rows and columns.</li>
</ul>
<h3><a class="anchor" id="PermissiveAssertions"></a>
Permissive assertions</h3>
<p>These assertions fail if the condition <b>cannot</b> be met. For example, MatrixXd and Matrix4d may have the same size, so they pass EIGEN_STATIC_ASSERT_SAME_MATRIX_SIZE.</p>
<ul>
<li><b>EIGEN_STATIC_ASSERT_SAME_VECTOR_SIZE(TYPE0,TYPE1)</b> - fails if the two vector expression types must have different sizes.</li>
<li><b>EIGEN_STATIC_ASSERT_SAME_MATRIX_SIZE(TYPE0,TYPE1)</b> - fails if the two matrix expression types must have different sizes.</li>
<li><b>EIGEN_STATIC_ASSERT_SIZE_1x1(TYPE)</b> - fails if <em>TYPE</em> cannot be an 1x1 expression.</li>
</ul>
<p>See <a class="el" href="StaticAssert_8h_source.html">StaticAssert.h</a> for details such as what messages they throw.</p>
<h2><a class="anchor" id="DisableStaticAssert"></a>
Disabling static assertions</h2>
<p>If <code>EIGEN_NO_STATIC_ASSERT</code> is defined, static assertions turn into <code>eigen_assert</code>'s, working like:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define EIGEN_STATIC_ASSERT(CONDITION,MSG) eigen_assert((CONDITION) && #MSG);</span></div>
</div><!-- fragment --><p>This saves compile time but consumes more run time. <code>EIGEN_NO_STATIC_ASSERT</code> is undefined by default. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Mon Oct 28 2013 11:04:27 for Eigen by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
</ul>
</div>
<!-- Piwik -->
<!--
<script type="text/javascript">
var pkBaseURL = (("https:" == document.location.protocol) ? "https://stats.sylphide-consulting.com/piwik/" : "http://stats.sylphide-consulting.com/piwik/");
document.write(unescape("%3Cscript src='" + pkBaseURL + "piwik.js' type='text/javascript'%3E%3C/script%3E"));
</script><script type="text/javascript">
try {
var piwikTracker = Piwik.getTracker(pkBaseURL + "piwik.php", 20);
piwikTracker.trackPageView();
piwikTracker.enableLinkTracking();
} catch( err ) {}
</script><noscript><p><img src="http://stats.sylphide-consulting.com/piwik/piwik.php?idsite=20" style="border:0" alt="" /></p></noscript>
-->
<!-- End Piwik Tracking Code -->
</body>
</html>
