- documented the new typedefs

- added a what's new section
- reformatted a bit
- updated license reference


[SVN r23944]
This commit is contained in:
Gennaro Prota
2004-07-22 08:57:45 +00:00
parent 170a352574
commit fa5aba353f

View File

@ -1,73 +1,125 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html> <html>
<head> <head>
<title>Binary Logarithm Template</title> <title>Binary Logarithm Template</title>
</head> </head>
<body bgcolor="white" text="black"> <body bgcolor="white" text="black">
<h1><img src="../../../c++boost.gif" alt="c++boost.gif (8819 bytes)" <h1><img src="../../../c++boost.gif" alt="c++boost.gif (8819 bytes)"
align="middle" width="277" height="86">Binary Logarithm Template</h1> align="middle" width="277" height="86">Binary Logarithm Template</h1>
<p>The class template in <cite><a href="../../../boost/integer/static_log2.hpp">&lt;boost/integer/static_log2.hpp&gt;</a></cite> determines the position of the highest bit in a given value. This facility is useful for solving generic programming problems.</p> <p>The class template in <cite><a href="../../../boost/integer/static_log2.hpp">&lt;boost/integer/static_log2.hpp&gt;</a></cite> determines the position of the highest bit in a given value. This facility is useful for solving generic programming problems.</p>
<h2><a name="contents">Contents</a></h2> <h2><a name="contents">Contents</a></h2>
<ul> <ul>
<li><a href="#contents">Contents</a></li> <li><a href="#contents">Contents</a></li>
<li><a href="#synopsis">Synopsis</a></li> <li><a href="#synopsis">Synopsis</a></li>
<li><a href="#usage">Usage</a></li> <li><a href="#usage">Usage</a></li>
<li><a href="#example">Example</a></li> <li><a href="#example">Example</a></li>
<li><a href="#demo">Demonstration Program</a></li> <li><a href="#demo">Demonstration Program</a></li>
<li><a href="#rationale">Rationale</a></li> <li><a href="#rationale">Rationale</a></li>
<li><a href="#credits">Credits</a></li> <li><a href="#credits">Credits</a></li>
<li><a href="#whatsnew"><b>What's new</b></a></li>
</ul> </ul>
<h2><a name="synopsis">Synopsis</a></h2> <h2><a name="synopsis">Synopsis</a></h2>
<blockquote><pre> <blockquote><pre>
namespace boost namespace boost
{ {
template &lt; unsigned long Value &gt; typedef <em>implementation-defined</em> static_log2_argument_type;
struct static_log2 typedef <em>implementation-defined</em> static_log2_result_type;
{
static const int value = <em>implementation_defined</em>;
};
template &lt; &gt; template &lt; static_log2_argument_type arg &gt;
struct static_log2&lt; 0ul &gt; struct static_log2
{ {
static const static_log2_result_type value = <em>implementation-defined</em>;
};
template &lt; &gt;
struct static_log2&lt; 0 &gt;
{
// The logarithm of zero is undefined. // The logarithm of zero is undefined.
}; };
} // namespace boost } // namespace boost
</pre></blockquote> </pre></blockquote>
<h2><a name="usage">Usage</a></h2> <h2><a name="usage">Usage</a></h2>
<p>The <code>boost::static_log2</code> class template takes one template <p>The <code>boost::static_log2</code> class template takes one template
parameter, a value of type <code>unsigned long</code>. The template parameter, a value of type <code>static_log2_argument_type</code>. The template
only defines one member, <code>value</code>, that returns the truncated only defines one member, <code>value</code>, which gives the truncated
base-two logarithm of the template parameter.</p> base-two logarithm of the template argument.</p>
<p>Since the logarithm of zero, for any base, is undefined, there is a <p>Since the logarithm of zero, for any base, is undefined, there is a
specialization of <code>static_log2</code> for a template parameter specialization of <code>static_log2</code> for a template argument
of zero. This specialization has no members, so an attempt to use of zero. This specialization has no members, so an attempt to use
the base-two logarithm of zero results in a compile-time error.</p> the base-two logarithm of zero results in a compile-time error.</p>
<p>Note: <ul>
<li><code>static_log2_argument_type</code> is an <i>unsigned integer
type</i> (C++ standard, 3.9.1p3).</li>
<li><code>static_log2_result_type</code> is an <i>integer type</i>
(C++ standard, 3.9.1p7).</li>
</ul>
<h2><a name="example">Example</a></h2> <h2><a name="example">Example</a></h2>
<blockquote><pre>
#include &lt;boost/integer/static_log2.hpp&gt;
template &lt; unsigned long Value &gt;
<blockquote><pre>
#include "boost/integer/static_log2.hpp"
template &lt; boost::static_log2_argument_type value &gt;
bool is_it_what() bool is_it_what()
{ {
typedef boost::static_log2&lt;Value&gt; lb_type; typedef boost::static_log2&lt;value&gt; lb_type;
int temp = lb_type::value; int temp = lb_type::value;
//... //...
return (temp % 2) != 0; return (temp % 2) != 0;
} }
@ -77,47 +129,87 @@ int main()
{ {
bool temp = is_it_what&lt;2000&gt;(); bool temp = is_it_what&lt;2000&gt;();
//... //...
# if 0
#if 0
temp = is_it_what&lt;0&gt;(); // would give an error temp = is_it_what&lt;0&gt;(); // would give an error
#endif # endif
//... //...
temp = is_it_what&lt;24&gt;(); temp = is_it_what&lt;24&gt;();
//... //...
} }
</pre></blockquote> </pre></blockquote>
<h2><a name="demo">Demonstration Program</a></h2> <h2><a name="demo">Demonstration Program</a></h2>
<p>The program <a href="../test/static_log2_test.cpp">static_log2_test.cpp</a> <p>The program <a href="../test/static_log2_test.cpp">static_log2_test.cpp</a>
is a simplistic demonstration of the results from instantiating various is a simplistic demonstration of the results from instantiating various
examples of the binary logarithm class template.</p> examples of the binary logarithm class template.</p>
<h2><a name="rationale">Rationale</a></h2> <h2><a name="rationale">Rationale</a></h2>
<p>The base-two (binary) logarithm, abbreviated <dfn>lb</dfn>, function <p>The base-two (binary) logarithm, abbreviated <dfn>lb</dfn>, function
is occasionally used to give order-estimates of computer algorithms. is occasionally used to give order-estimates of computer algorithms.
The truncated logarithm can be considered the highest power-of-two in a The truncated logarithm can be considered the highest power-of-two in a
value, which corresponds to the value's highest set bit (for binary value, which corresponds to the value's highest set bit (for binary
integers). Sometimes the highest-bit position could be used in generic integers). Sometimes the highest-bit position could be used in generic
programming, which requires the position to be statically (<i>i.e.</i> programming, which requires the position to be statically (<i>i.e.</i>
at compile-time) available.</p> at compile-time) available.</p>
<h2><a name="whatsnew">Changes from previous versions:</a></h2>
<ul>
<li><i>New in version 1.32.0:</i><br><br>
The argument type and the result type of <code>boost::static_log2</code>
are now typedef'd. Formerly, they were hardcoded as <code>unsigned long</code>
and <code>int</code> respectively. Please, use the provided typedefs in new
code (and update old code as soon as possible).
</li>
</ul>
<h2><a name="credits">Credits</a></h2> <h2><a name="credits">Credits</a></h2>
<p>The author of the Boost binary logarithm class template is <a
href="../../../people/daryle_walker.html">Daryle Walker</a>. Giovanni Bajo
added support for compilers without partial template specialization.</p> <p>The original version of the Boost binary logarithm class template was
written by <a href="../../../people/daryle_walker.html">Daryle Walker</a>
and then enhanced by Giovanni Bajo with support for compilers without
partial template specialization. The current version was suggested,
together with a reference implementation, by Vesa Karvonen. Gennaro Prota
wrote the actual source file.
</p>
<hr> <hr>
<p>Revised May 14, 2002</p>
<p>&copy; Copyright Daryle Walker 2001. Permission to copy, use,
modify, sell and distribute this document is granted provided this <p>Revised July 19, 2004</p>
copyright notice appears in all copies. This document is provided
&quot;as is&quot; without express or implied warranty, and with no claim <p>&copy; Copyright Daryle Walker 2001.<br>
as to its suitability for any purpose.</p> &copy; Copyright Gennaro Prota 2004.</p>
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at
<a href="http://www.boost.org/LICENSE_1_0.txt">
http://www.boost.org/LICENSE_1_0.txt</a>)
<br>
</body> </body>
</html> </html>