# Binary Logarithm Template

The class template in <boost/integer/static_log2.hpp> determines the position of the highest bit in a given value. This facility is useful for solving generic programming problems.

## Contents

- Contents
- Synopsis
- Usage
- Example
- Demonstration Program
- Rationale
- Credits

## Synopsis

>     namespace boost
>     {

>     template < unsigned long Value >
>     struct static_log2
>     {
>         static const int  value = implementation_defined;
>     };

>     template < >
>     struct static_log2< 0ul >
>     {
>         // The logarithm of zero is undefined.
>     };

>     }  // namespace boost

## Usage

The `boost::static_log2` class template takes one template parameter, a value of type `unsigned long`. The template only defines one member, `value`, that returns the truncated base-two logarithm of the template parameter.

Since the logarithm of zero, for any base, is undefined, there is a specialization of `static_log2` for a template parameter of zero. This specialization has no members, so an attempt to use the base-two logarithm of zero results in a compile-time error.

## Example

>     #include <boost/integer/static_log2.hpp>

>     template < unsigned long Value >
>     bool is_it_what()
>     {
>         typedef boost::static_log2<Value>  lb_type;

>         int  temp = lb_type::value;
>         //...

>         return (temp % 2) != 0;
>     }

>     //...

>     int main()
>     {
>         bool  temp = is_it_what<2000>();
>         //...

>         #if 0
>         temp = is_it_what<0>();  // would give an error
>         #endif
>         //...

>         temp = is_it_what<24>();
>         //...
>     }

## Demonstration Program

The program static_log2_test.cpp is a simplistic demonstration of the results from instantiating various examples of the binary logarithm class template.

## Rationale

The base-two (binary) logarithm, abbreviated lb, function is occasionally used to give order-estimates of computer algorithms. 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 integers). Sometimes the highest-bit position could be used in generic programming, which requires the position to be statically (i.e. at compile-time) available.

## Credits

The author of the Boost binary logarithm class template is Daryle Walker.

Revised October 1, 2001

© Copyright Daryle Walker 2001. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.