Changes between Version 2 and Version 3 of Guidelines/IntegralConstants

Timestamp:

Aug 18, 2010, 10:54:38 PM (12 years ago)

Author:

Daniel James

Comment:

--

Guidelines/IntegralConstants

@@ -1 @@
-[[PageOutline]]
-
-= Coding Guidelines for Integral Constant Expressions = #intro
-
-Integral Constant Expressions are used in many places in
-C++; as array bounds, as bit-field lengths, as enumerator
-initialisers, and as arguments to non-type template parameters.
-However many compilers have problems handling integral constant
-expressions; as a result of this, programming using non-type
-template parameters in particular can be fraught with
-difficulty, often leading to the incorrect assumption that
-non-type template parameters are unsupported by a particular
-compiler. This short article is designed to provide a set of
-guidelines and workarounds that, if followed, will allow
-integral constant expressions to be used in a manner portable
-to all the compilers currently supported by boost. Although
-this article is mainly targeted at boost library authors, it
-may also be useful for users who want to understand why boost
-code is written in a particular way, or who want to write
-portable code themselves.
-
-== What is an Integral Constant Expression? == #whatis
-
-Integral constant expressions are described in section 5.19
-of the standard, and are sometimes referred to as "compile time
-constants". An integral constant expression can be one of the
-following:
-
- 1. A literal integral value, for example `0u` or `3L`.
- 1. An enumerator value.
- 1. Global integral constants, for example:
-    {{{
-const int my_INTEGRAL_CONSTANT = 3;
-    }}}
- 1. Static member constants, for example:
-    {{{
-struct myclass
-{ static const int value = 0; };
-    }}}
- 1. Member enumerator values, for example:
-    {{{
-struct myclass
-{ enum{ value = 0 }; };
-    }}}
- 1. Non-type template parameters of integral or enumerator type.
- 1. The result of a `sizeof` expression, for example:
-    {{{
-sizeof(foo(a, b, c))
-    }}}
- 1. The result of a `static_cast`, where the
-    target type is an integral or enumerator type, and the
-    argument is either another integral constant expression, or a
-    floating-point literal.
- 1. The result of applying a binary operator to two integral
-    constant expressions:
-    {{{
-INTEGRAL_CONSTANT1 op INTEGRAL_CONSTANT2
-    }}}
-    provided that the operator is not an assignment operator, or comma operator.
- 1. The result of applying a unary operator to an integral
-    constant expression:
-    {{{
-op INTEGRAL_CONSTANT1
-    }}}
-    provided that the operator is not the increment or decrement operator.
-
-== Coding Guidelines == #guidelines
-
-The following guidelines are declared in no particular order
-(in other words you need to obey all of them - sorry!), and may
-also be incomplete, more guidelines may be added as compilers
-change and/or more problems are encountered.
-
-=== When declaring constants that are class members always use the macro `BOOST_STATIC_CONSTANT.` === #boost-static-constant
-{{{
-template <class T>
-struct myclass
-{
-    BOOST_STATIC_CONSTANT(int, value = sizeof(T));
-};
-}}}
-
-Rationale: not all compilers support inline initialisation
-of member constants, others treat member enumerators in strange
-ways (they're not always treated as integral constant
-expressions). The BOOST_STATIC_CONSTANT macro uses the most
-appropriate method for the compiler in question.
-
-=== Don't declare integral constant expressions whose type is wider than int. === #wider-int
-
-Rationale: while in theory all integral types are usable in
-integral constant expressions, in practice many compilers limit
-integral constant expressions to types no wider than
-`int`.
-
-=== Don't use logical operators in integral constant expressions; use template meta-programming instead. === #logical-ops
-
-The header `<boost/type_traits/ice.hpp>`
-contains a number of workaround templates, that fulfil the role
-of logical operators, for example instead of:
-{{{
-INTEGRAL_CONSTANT1 || INTEGRAL_CONSTANT2
-}}}
-
-Use:
-{{{
-::boost::type_traits::ice_or<INTEGRAL_CONSTANT1,INTEGRAL_CONSTANT2>::value
-}}}
-
-Rationale: A number of compilers (particularly the Borland
-and Microsoft compilers), tend to not to recognise integral
-constant expressions involving logical operators as genuine
-integral constant expressions. The problem generally only shows
-up when the integral constant expression is nested deep inside
-template code, and is hard to reproduce and diagnose.
-
-=== Don't use any operators in an integral constant expression used as a non-type template parameter === #non-type-parameter
-
-Rather than:
-{{{
-typedef myclass<INTEGRAL_CONSTANT1 == INTEGRAL_CONSTANT2> mytypedef;
-}}}
-
-Use:
-{{{
-typedef myclass< some_symbol> mytypedef;
-}}}
-
-Where `some_symbol` is the symbolic name of a an
-integral constant expression whose value is
-`(INTEGRAL_CONSTANT1 == INTEGRAL_CONSTANT2).`
-
-Rationale: the older EDG based compilers (some of which are
-used in the most recent version of that platform's compiler),
-don't recognise expressions containing operators as non-type
-template parameters, even though such expressions can be used
-as integral constant expressions elsewhere.
-
-=== Always use a fully qualified name to refer to an integral constant expression. === #fully-qualified-name
-
-For example:
-{{{
-typedef myclass< ::boost::is_integral<some_type>::value> mytypedef;
-}}}
-
-Rationale: at least one compiler (Borland's), doesn't
-recognise the name of a constant as an integral constant
-expression unless the name is fully qualified (which is to say
-it starts with `::`).
-
-=== Always leave a space after a '`<`' and before '`::`' === #spaces
-
-For example:
-{{{
-typedef myclass< ::boost::is_integral<some_type>::value> mytypedef;
-                ^
-                ensure there is space here!
-}}}
-
-Rationale: `<:` is a legal digraph in it's own
-right, so `<::` is interpreted as the same as
-`[:`.
-
-=== Don't use local names as integral constant expressions === #local-names
-
-Example:
-{{{
-template <class T>
-struct foobar
-{
-    BOOST_STATIC_CONSTANT(int, temp = computed_value);
-    typedef myclass<temp> mytypedef;  // error
-};
-}}}
-
-Rationale: At least one compiler (Borland's) doesn't accept
-this.
-
-Although it is possible to fix this by using:
-{{{
-template <class T>
-struct foobar
-{
-    BOOST_STATIC_CONSTANT(int, temp = computed_value);
-    typedef foobar self_type;
-    typedef myclass<(self_type::temp)> mytypedef;  // OK
-};
-}}}
-
-This breaks at least one other compiler (VC6), it is better
-to move the integral constant expression computation out into a
-separate traits class:
-{{{
-template <class T>
-struct foobar_helper
-{
-    BOOST_STATIC_CONSTANT(int, value = computed_value);
-};
-
-template <class T>
-struct foobar
-{
-    typedef myclass< ::foobar_helper<T>::value> mytypedef;  // OK
-};
-}}}
-
-=== Don't use dependent default parameters for non-type template parameters. === #dependent
-
-For example:
-{{{
-template <class T, int I = ::boost::is_integral<T>::value>  // Error can't deduce value of I in some cases.
-struct foobar;
-}}}
-
-Rationale: this kind of usage fails for Borland C++. Note
-that this is only an issue where the default value is dependent
-upon a previous template parameter, for example the following
-is fine:
-{{{
-template <class T, int I = 3>  // OK, default value is not dependent
-struct foobar;
-}}}
-
-== Unresolved Issues == #unresolved
-
-The following issues are either unresolved or have fixes
-that are compiler specific, and/or break one or more of the
-coding guidelines.
-
-=== Be careful of numeric_limits === #numeric-limits
-
-There are three issues here:
-
- 1. The header <limits> may be absent - it is
-    recommended that you never include <limits> directly
-    but use <boost/pending/limits.hpp> instead. This header
-    includes the "real" <limits> header if it is available,
-    otherwise it supplies it's own std::numeric_limits
-    definition. Boost also defines the macro BOOST_NO_LIMITS if
-    <limits> is absent.
- 1. The implementation of std::numeric_limits may be defined
-    in such a way that its static-const members may not be usable
-    as integral constant expressions. This contradicts the
-    standard but seems to be a bug that affects at least two
-    standard library vendors; boost defines
-    BOOST_NO_LIMITS_COMPILE_TIME_CONSTANTS in
-    <boost/config.hpp> when this is the case.
- 1. There is a strange bug in VC6, where the members of
-    std::numeric_limits can be "prematurely evaluated" in
-    template code, for example:
-
-{{{
-template <class T>
-struct limits_test
-{
-    BOOST_STATIC_ASSERT(::std::numeric_limits<T>::is_specialized);
-};
-}}}
-
-This code fails to compile with VC6 even though no instances
-of the template are ever created; for some bizarre reason
-`::std::numeric_limits<T>::is_specialized`
-always evaluates to false, irrespective of what the template
-parameter T is. The problem seems to be confined to expressions
-which depend on std::numeric_limts: for example if you replace
-`::std::numeric_limits<T>::is_specialized`
-with `::boost::is_arithmetic<T>::value`, then
-everything is fine. The following workaround also works but
-conflicts with the coding guidelines:
-{{{
-template <class T>
-struct limits_test
-{
-    BOOST_STATIC_CONSTANT(bool, check = ::std::numeric_limits<T>::is_specialized);
-    BOOST_STATIC_ASSERT(check);
-};
-}}}
-
-So it is probably best to resort to something like this:
-{{{
-template <class T>
-struct limits_test
-{
-#ifdef BOOST_MSVC
-   BOOST_STATIC_CONSTANT(bool, check = ::std::numeric_limits<T>::is_specialized);
-   BOOST_STATIC_ASSERT(check);
-#else
-   BOOST_STATIC_ASSERT(::std::numeric_limits<T>::is_specialized);
-#endif
-};
-}}}
-
-=== Be careful how you use the sizeof operator === #sizeof
-
-As far as I can tell, all compilers treat sizeof expressions
-correctly when the argument is the name of a type (or a
-template-id), however problems can occur if:
-
-
- 1. The argument is the name of a member-variable, or a local
-    variable (code may not compile with VC6).
- 1. The argument is an expression which involves the creation
-    of a temporary (code will not compile with Borland C++).
- 1. The argument is an expression involving an overloaded
-    function call (code compiles but the result is a garbage
-    value with Metroworks C++).
-
-=== Don't use boost::is_convertible unless you have to === #is_convertible
-
-Since is_convertible is implemented in terms of the sizeof
-operator, it consistently gives the wrong value when used with
-the Metroworks compiler, and may not compile with the Borland's
-compiler (depending upon the template arguments used).
-
-Copyright Dr John Maddock 2001.
+This has been move back to the [http://www.boost.org/development/int_const_guidelines.html main site]