gcc/doc/gccint/gimple/gimple-sequences.rst

   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:: GIMPLE sequences
   7
   8 .. _gimple-sequences:
   9
  10 GIMPLE sequences
  11 ****************
  12
  13 GIMPLE sequences are the tuple equivalent of ``STATEMENT_LIST`` 's
  14 used in ``GENERIC``.  They are used to chain statements together, and
  15 when used in conjunction with sequence iterators, provide a
  16 framework for iterating through statements.
  17
  18 GIMPLE sequences are of type struct ``gimple_sequence``, but are more
  19 commonly passed by reference to functions dealing with sequences.
  20 The type for a sequence pointer is ``gimple_seq`` which is the same
  21 as struct ``gimple_sequence`` \*.  When declaring a local sequence,
  22 you can define a local variable of type struct ``gimple_sequence``.
  23 When declaring a sequence allocated on the garbage collected
  24 heap, use the function ``gimple_seq_alloc`` documented below.
  25
  26 There are convenience functions for iterating through sequences
  27 in the section entitled Sequence Iterators.
  28
  29 Below is a list of functions to manipulate and query sequences.
  30
  31 .. function:: void gimple_seq_add_stmt (gimple_seq *seq, gimple g)
  32
  33   Link a gimple statement to the end of the sequence \* ``SEQ`` if ``G`` is
  34   not ``NULL``.  If \* ``SEQ`` is ``NULL``, allocate a sequence before linking.
  35
  36 .. function:: void gimple_seq_add_seq (gimple_seq *dest, gimple_seq src)
  37
  38   Append sequence ``SRC`` to the end of sequence \* ``DEST`` if ``SRC`` is not
  39   ``NULL``.  If \* ``DEST`` is ``NULL``, allocate a new sequence before
  40   appending.
  41
  42 .. function:: gimple_seq gimple_seq_deep_copy (gimple_seq src)
  43
  44   Perform a deep copy of sequence ``SRC`` and return the result.
  45
  46 .. function:: gimple_seq gimple_seq_reverse (gimple_seq seq)
  47
  48   Reverse the order of the statements in the sequence ``SEQ``.  Return
  49   ``SEQ``.
  50
  51 .. function:: gimple gimple_seq_first (gimple_seq s)
  52
  53   Return the first statement in sequence ``S``.
  54
  55 .. function:: gimple gimple_seq_last (gimple_seq s)
  56
  57   Return the last statement in sequence ``S``.
  58
  59 .. function:: void gimple_seq_set_last (gimple_seq s, gimple last)
  60
  61   Set the last statement in sequence ``S`` to the statement in ``LAST``.
  62
  63 .. function:: void gimple_seq_set_first (gimple_seq s, gimple first)
  64
  65   Set the first statement in sequence ``S`` to the statement in ``FIRST``.
  66
  67 .. function:: void gimple_seq_init (gimple_seq s)
  68
  69   Initialize sequence ``S`` to an empty sequence.
  70
  71 .. function:: gimple_seq gimple_seq_alloc (void)
  72
  73   Allocate a new sequence in the garbage collected store and return
  74   it.
  75
  76 .. function:: void gimple_seq_copy (gimple_seq dest, gimple_seq src)
  77
  78   Copy the sequence ``SRC`` into the sequence ``DEST``.
  79
  80 .. function:: bool gimple_seq_empty_p (gimple_seq s)
  81
  82   Return true if the sequence ``S`` is empty.
  83
  84 .. function:: gimple_seq bb_seq (basic_block bb)
  85
  86   Returns the sequence of statements in ``BB``.
  87
  88 .. function:: void set_bb_seq (basic_block bb, gimple_seq seq)
  89
  90   Sets the sequence of statements in ``BB`` to ``SEQ``.
  91
  92 .. function:: bool gimple_seq_singleton_p (gimple_seq seq)
  93
  94   Determine whether ``SEQ`` contains exactly one statement.