[thirdparty/gcc.git] / gcc / doc / gcc / extensions-to-the-c-language-family / statement-attributes.rst

..
  Copyright 1988-2022 Free Software Foundation, Inc.
  This is part of the GCC manual.
  For copying conditions, see the copyright.rst file.

.. index:: Statement Attributes

.. _statement-attributes:

Statement Attributes
********************

GCC allows attributes to be set on null statements.  See :ref:`attribute-syntax`,
for details of the exact syntax for using attributes.  Other attributes are
available for functions (see :ref:`function-attributes`), variables
(see :ref:`variable-attributes`), labels (see :ref:`label-attributes`), enumerators
(see :ref:`enumerator-attributes`), and for types (see :ref:`type-attributes`).

``fallthrough``

  .. index:: fallthrough statement attribute

  The ``fallthrough`` attribute with a null statement serves as a
  fallthrough statement.  It hints to the compiler that a statement
  that falls through to another case label, or user-defined label
  in a switch statement is intentional and thus the
  :option:`-Wimplicit-fallthrough` warning must not trigger.  The
  fallthrough attribute may appear at most once in each attribute
  list, and may not be mixed with other attributes.  It can only
  be used in a switch statement (the compiler will issue an error
  otherwise), after a preceding statement and before a logically
  succeeding case label, or user-defined label.

  This example uses the ``fallthrough`` statement attribute to indicate that
  the :option:`-Wimplicit-fallthrough` warning should not be emitted:

  .. code-block:: c++

    switch (cond)
      {
      case 1:
        bar (1);
        __attribute__((fallthrough));
      case 2:
        ...
      }

``assume``

  .. index:: assume statement attribute

  The ``assume`` attribute with a null statement serves as portable
  assumption.  It should have a single argument, a conditional expression,
  which is not evaluated.  If the argument would evaluate to true
  at the point where it appears, it has no effect, otherwise there
  is undefined behavior.  This is a GNU variant of the ISO C++23
  standard ``assume`` attribute, but it can be used in any version of
  both C and C++.

  .. code-block:: c++

    int
    foo (int x, int y)
    {
      __attribute__((assume(x == 42)));
      __attribute__((assume(++y == 43)));
      return x + y;
    }

  ``y`` is not actually incremented and the compiler can but does not
  have to optimize it to just ``return 42 + 42;``.
Commit	Line	Data
c63539ff ML	1	..
	2	Copyright 1988-2022 Free Software Foundation, Inc.
	3	This is part of the GCC manual.
	4	For copying conditions, see the copyright.rst file.
	5
	6	.. index:: Statement Attributes
	7
	8	.. _statement-attributes:
	9
	10	Statement Attributes
	11	********************
	12
	13	GCC allows attributes to be set on null statements. See :ref:`attribute-syntax`,
	14	for details of the exact syntax for using attributes. Other attributes are
	15	available for functions (see :ref:`function-attributes`), variables
	16	(see :ref:`variable-attributes`), labels (see :ref:`label-attributes`), enumerators
	17	(see :ref:`enumerator-attributes`), and for types (see :ref:`type-attributes`).
	18
	19	``fallthrough``
	20
	21	.. index:: fallthrough statement attribute
	22
	23	The ``fallthrough`` attribute with a null statement serves as a
	24	fallthrough statement. It hints to the compiler that a statement
	25	that falls through to another case label, or user-defined label
	26	in a switch statement is intentional and thus the
	27	:option:`-Wimplicit-fallthrough` warning must not trigger. The
	28	fallthrough attribute may appear at most once in each attribute
	29	list, and may not be mixed with other attributes. It can only
	30	be used in a switch statement (the compiler will issue an error
	31	otherwise), after a preceding statement and before a logically
	32	succeeding case label, or user-defined label.
	33
	34	This example uses the ``fallthrough`` statement attribute to indicate that
	35	the :option:`-Wimplicit-fallthrough` warning should not be emitted:
	36
	37	.. code-block:: c++
	38
	39	switch (cond)
	40	{
	41	case 1:
	42	bar (1);
	43	__attribute__((fallthrough));
	44	case 2:
	45	...
	46	}
	47
	48	``assume``
	49
	50	.. index:: assume statement attribute
	51
	52	The ``assume`` attribute with a null statement serves as portable
	53	assumption. It should have a single argument, a conditional expression,
	54	which is not evaluated. If the argument would evaluate to true
	55	at the point where it appears, it has no effect, otherwise there
	56	is undefined behavior. This is a GNU variant of the ISO C++23
	57	standard ``assume`` attribute, but it can be used in any version of
	58	both C and C++.
	59
	60	.. code-block:: c++
	61
	62	int
	63	foo (int x, int y)
	64	{
65	__attribute__((assume(x == 42)));
66	__attribute__((assume(++y == 43)));
67	return x + y;
68	}
69
70	``y`` is not actually incremented and the compiler can but does not
3ed1b4ce	71	have to optimize it to just ``return 42 + 42;``.