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
• What's new

Synopsis

namespace boost
{

  typedef implementation-defined static_log2_argument_type;
  typedef implementation-defined static_log2_result_type;

  template < static_log2_argument_type arg >
  struct static_log2
  {
    static const static_log2_result_type value = implementation-defined;
  };


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


}  // namespace boost

Usage

The boost::static_log2 class template takes one template parameter, a value of type static_log2_argument_type. The template only defines one member, value, which gives the truncated base-two logarithm of the template argument.

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

Note:

• static_log2_argument_type is an unsigned integer type (C++ standard, 3.9.1p3).
• static_log2_result_type is an integer type (C++ standard, 3.9.1p7).

Example

#include "boost/integer/static_log2.hpp"


template < boost::static_log2_argument_type 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.

Changes from previous versions:

• New in version 1.32.0:
  
  The argument type and the result type of boost::static_log2 are now typedef'd. Formerly, they were hardcoded as unsigned long and int respectively. Please, use the provided typedefs in new code (and update old code as soon as possible).

Credits

The original version of the Boost binary logarithm class template was written by Daryle Walker 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.

Revised July 19, 2004

© Copyright Daryle Walker 2001.
© Copyright Gennaro Prota 2004.