gcc/fortran/doc/gfortran/intrinsic-procedures/findloc.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 .. _findloc:
   7
   8 FINDLOC --- Search an array for a value
   9 ***************************************
  10
  11 .. index:: FINDLOC, findloc
  12
  13 .. function:: FINDLOC(ARRAY, VALUE, MASK, KIND, BACK)
  14
  15   Determines the location of the element in the array with the value
  16   given in the :samp:`{VALUE}` argument, or, if the :samp:`{DIM}` argument is
  17   supplied, determines the locations of the elements equal to the
  18   :samp:`{VALUE}` argument element along each
  19   row of the array in the :samp:`{DIM}` direction.  If :samp:`{MASK}` is
  20   present, only the elements for which :samp:`{MASK}` is ``.TRUE.`` are
  21   considered.  If more than one element in the array has the value
  22   :samp:`{VALUE}`, the location returned is that of the first such element
  23   in array element order if the :samp:`{BACK}` is not present or if it is
  24   ``.FALSE.``. If :samp:`{BACK}` is true, the location returned is that
  25   of the last such element. If the array has zero size, or all of the
  26   elements of :samp:`{MASK}` are ``.FALSE.``, then the result is an array
  27   of zeroes.  Similarly, if :samp:`{DIM}` is supplied and all of the
  28   elements of :samp:`{MASK}` along a given row are zero, the result value
  29   for that row is zero.
  30
  31   :param ARRAY:
  32     Shall be an array of intrinsic type.
  33
  34   :param VALUE:
  35     A scalar of intrinsic type which is in type
  36     conformance with :samp:`{ARRAY}`.
  37
  38   :param DIM:
  39     (Optional) Shall be a scalar of type
  40     ``INTEGER``, with a value between one and the rank of :samp:`{ARRAY}`,
  41     inclusive.  It may not be an optional dummy argument.
  42
  43   :param MASK:
  44     (Optional) Shall be of type ``LOGICAL``,
  45     and conformable with :samp:`{ARRAY}`.
  46
  47   :param KIND:
  48     (Optional) An ``INTEGER`` initialization
  49     expression indicating the kind parameter of the result.
  50
  51   :param BACK:
  52     (Optional) A scalar of type ``LOGICAL``.
  53
  54   :return:
  55     If :samp:`{DIM}` is absent, the result is a rank-one array with a length
  56     equal to the rank of :samp:`{ARRAY}`.  If :samp:`{DIM}` is present, the result
  57     is an array with a rank one less than the rank of :samp:`{ARRAY}`, and a
  58     size corresponding to the size of :samp:`{ARRAY}` with the :samp:`{DIM}`
  59     dimension removed.  If :samp:`{DIM}` is present and :samp:`{ARRAY}` has a rank
  60     of one, the result is a scalar.  If the optional argument :samp:`{KIND}`
  61     is present, the result is an integer of kind :samp:`{KIND}`, otherwise it
  62     is of default kind.
  63
  64   Standard:
  65     Fortran 2008 and later.
  66
  67   Class:
  68     Transformational function
  69
  70   Syntax:
  71     .. code-block:: fortran
  72
  73       RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])
  74       RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])
  75
  76   See also:
  77     :ref:`MAXLOC`,
  78     :ref:`MINLOC`