Documentation bug for __builtin_choose_expr

Documentation bug for __builtin_choose_expr

[Jamie Lokier]

The documentation for __builtin_choose_expr says:

 -- Built-in Function: TYPE __builtin_choose_expr (CONST_EXP, EXP1, EXP2)
     You can use the built-in function `__builtin_choose_expr' to
     evaluate code depending on the value of a constant expression.
     This built-in function returns EXP1 if CONST_EXP, which is a
     constant expression that must be able to be determined at compile
     time, is nonzero.  Otherwise it returns 0.

     This built-in function is analogous to the `? :' operator in C,
     except that the expression returned has its type unaltered by
     promotion rules.  Also, the built-in function does not evaluate
                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     the expression that was not chosen.  For example, if CONST_EXP
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     evaluates to true, EXP2 is not evaluated even if it has
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     side-effects.
     ^^^^^^^^^^^^^

The way this is written implies that the underscored behaviour is
different from the `? :' operator in C.

But the `? :' operator does not evaluate the expression that was not
chosen either.  If the condition evaluates to true, EXP2 is not
evaluated in `COND ? EXP1 : EXP2'.

It would be better to replace that paragraph with:

     This built-in function is analogous to the `? :' operator in C,
     except that the expression returned has its type unaltered by
     promotion rules.

If there is some other effect of __builtin_choose_expr, for example if
it were to inhibit compilation or warnings in the unselected branch in
some way, it would be useful to mention that.  I don't know of any
such effects.  (Inhibiting warnings in the unselected branch and
promising to not expand large inline functions in that branch would be
a useful addition imho).

-- Jamie

Re: Documentation bug for __builtin_choose_expr

[Joseph S. Myers]

On Mon, 22 Nov 2004, Jamie Lokier wrote:

> The documentation for __builtin_choose_expr says:
> 
>  -- Built-in Function: TYPE __builtin_choose_expr (CONST_EXP, EXP1, EXP2)
>      You can use the built-in function `__builtin_choose_expr' to
>      evaluate code depending on the value of a constant expression.
>      This built-in function returns EXP1 if CONST_EXP, which is a
>      constant expression that must be able to be determined at compile
>      time, is nonzero.  Otherwise it returns 0.
> 
>      This built-in function is analogous to the `? :' operator in C,
>      except that the expression returned has its type unaltered by
>      promotion rules.  Also, the built-in function does not evaluate
>                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>      the expression that was not chosen.  For example, if CONST_EXP
>      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>      evaluates to true, EXP2 is not evaluated even if it has
>      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>      side-effects.
>      ^^^^^^^^^^^^^
> 
> The way this is written implies that the underscored behaviour is
> different from the `? :' operator in C.

I'd think the idea is actually to say that it is different from normal 
functions (built-in and otherwise), which inevitably evaluate all their 
arguments before calling the function.  (Although the syntax is that of a 
built-in function, the implementation is that of a new keyword 
__builtin_choose_expr handled specially in the parser.)  Perhaps it should 
say "Unlike most built-in functions, but like the ? : operator, ...".

-- 
Joseph S. Myers               http://www.srcf.ucam.org/~jsm28/gcc/
    jsm@polyomino.org.uk (personal mail)
    joseph@codesourcery.com (CodeSourcery mail)
    jsm28@gcc.gnu.org (Bugzilla assignments and CCs)

Re: Documentation bug for __builtin_choose_expr

[Jamie Lokier]

Joseph S. Myers wrote:
> Perhaps it should 
> say "Unlike most built-in functions, but like the ? : operator, ...".

Yes, I agree.
Here is the whole suggested replacement paragraph:

     This built-in function is analogous to the `? :' operator in C,
     except that the expression returned has its type unaltered by
     promotion rules.  Unlike most built-in functions, but like the
     `? :' operator, this built-in function does not evaluate the
     expression that was not chosen.  For example, if CONST_EXP
     evaluates to true, EXP2 is not evaluated even if it has
     side-effects.

The change is:

      Also, the...
to
      Unlike most built-in functions, but like the `? :' operator, this...

Would anyone who updates in documentation care to make this change?

-- Jamie

Re: Documentation bug for __builtin_choose_expr

[Andreas Schwab]

Jamie Lokier <jamie@shareable.org> writes:

> The documentation for __builtin_choose_expr says:
>
>  -- Built-in Function: TYPE __builtin_choose_expr (CONST_EXP, EXP1, EXP2)
>      You can use the built-in function `__builtin_choose_expr' to
>      evaluate code depending on the value of a constant expression.
>      This built-in function returns EXP1 if CONST_EXP, which is a
>      constant expression that must be able to be determined at compile
>      time, is nonzero.  Otherwise it returns 0.
>
>      This built-in function is analogous to the `? :' operator in C,
>      except that the expression returned has its type unaltered by
>      promotion rules.  Also, the built-in function does not evaluate
>                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>      the expression that was not chosen.  For example, if CONST_EXP
>      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>      evaluates to true, EXP2 is not evaluated even if it has
>      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>      side-effects.
>      ^^^^^^^^^^^^^
>
> The way this is written implies that the underscored behaviour is
> different from the `? :' operator in C.

I don't see that.  For me the word "also" implies "another analogousness".
IMHO this is fact is worth noting because the usual rules for function
calls in C is to evaluate all its arguments first, whereas this builtin
does not do that even though it uses a function-like notation.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Documentation bug for __builtin_choose_expr

[Jamie Lokier]

Andreas Schwab wrote:
> >      This built-in function is analogous to the `? :' operator in C,
> >      except that the expression returned has its type unaltered by
> >      promotion rules.  Also, the built-in function does not evaluate
> >                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >      the expression that was not chosen.  For example, if CONST_EXP
> >      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >      evaluates to true, EXP2 is not evaluated even if it has
> >      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >      side-effects.
> >      ^^^^^^^^^^^^^
> >
> > The way this is written implies that the underscored behaviour is
> > different from the `? :' operator in C.
> 
> I don't see that.  For me the word "also" implies "another analogousness".

It depends how you parse it.

> IMHO this is fact is worth noting because the usual rules for function
> calls in C is to evaluate all its arguments first, whereas this builtin
> does not do that even though it uses a function-like notation.

I agree it's worth noting.  What do you think of the alternative wording
put forth by Joseph S. Myers, which I find clearer?  This is it:

     This built-in function is analogous to the `? :' operator in C,
     except that the expression returned has its type unaltered by
     promotion rules.  Unlike most built-in functions, but like the
     `? :' operator, this built-in function does not evaluate the
     expression that was not chosen.  For example, if CONST_EXP
     evaluates to true, EXP2 is not evaluated even if it has
     side-effects.

I can't check in the change, perhaps someone else can.

-- Jamie

Re: Documentation bug for __builtin_choose_expr

[Andreas Schwab]

Jamie Lokier <jamie@shareable.org> writes:

>      This built-in function is analogous to the `? :' operator in C,
>      except that the expression returned has its type unaltered by
>      promotion rules.  Unlike most built-in functions, but like the
>      `? :' operator, this built-in function does not evaluate the
>      expression that was not chosen.  For example, if CONST_EXP
>      evaluates to true, EXP2 is not evaluated even if it has
>      side-effects.

IMHO, "but like the `? :' operator" could be removed without any negative
impact (anyone who doesn't know how the ?: operator should not look at
builtins either :-) ).

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Documentation bug for __builtin_choose_expr

[Robert Dewar]

Andreas Schwab wrote:
> Jamie Lokier <jamie@shareable.org> writes:
> 
> 
>>     This built-in function is analogous to the `? :' operator in C,
>>     except that the expression returned has its type unaltered by
>>     promotion rules.  Unlike most built-in functions, but like the
>>     `? :' operator, this built-in function does not evaluate the
>>     expression that was not chosen.  For example, if CONST_EXP
>>     evaluates to true, EXP2 is not evaluated even if it has
>>     side-effects.
> 
> 
> IMHO, "but like the `? :' operator" could be removed without any negative
> impact (anyone who doesn't know how the ?: operator should not look at
> builtins either :-) ).

Why remove it? It only makes things clearer ... Documentation is about
making things clear, we are not writing a language standard here, where
redundancy is to be avoided. Perhaps it would make things clearer to put
this parenthetical remark in parentheses
> 
> Andreas.
> 

 >>     This built-in function is analogous to the `? :' operator in C,
 >>     except that the expression returned has its type unaltered by
 >>     promotion rules.  Unlike most built-in functions (but like the
 >>     `? :' operator), this built-in function does not evaluate the
 >>     expression that was not chosen.  For example, if CONST_EXP
 >>     evaluates to true, EXP2 is not evaluated even if it has
 >>     side-effects.

Re: Documentation bug for __builtin_choose_expr

[Kai Henningsen]

jamie@shareable.org (Jamie Lokier)  wrote on 22.11.04 in <20041122042652.GA26998@mail.shareable.org>:

> The documentation for __builtin_choose_expr says:
>
>  -- Built-in Function: TYPE __builtin_choose_expr (CONST_EXP, EXP1, EXP2)
>      You can use the built-in function `__builtin_choose_expr' to
>      evaluate code depending on the value of a constant expression.
>      This built-in function returns EXP1 if CONST_EXP, which is a
>      constant expression that must be able to be determined at compile
>      time, is nonzero.  Otherwise it returns 0.
*************************************************

Surely that should be "Otherwise it returns EXP2"?!

MfG Kai