code: def diagonal(
      x: Union[ivy.Array, ivy.NativeArray],
      /,
      *,
      offset: int = 0,
      axis1: int = -2,
      axis2: int = -1,
      out: Optional[ivy.Array] = None,
  ) -> ivy.Array:
      """Return the specified diagonals of a matrix (or a stack of matrices)
      ``x``.
  
      Parameters
      ----------
      x
          input array having shape ``(..., M, N)`` and whose innermost two dimensions form
          ``MxN`` matrices.
      offset
          offset specifying the off-diagonal relative to the main diagonal.
          - ``offset = 0``: the main diagonal.
          - ``offset > 0``: off-diagonal above the main diagonal.
          - ``offset < 0``: off-diagonal below the main diagonal.
          Default: `0`.
      axis1
          axis to be used as the first axis of the 2-D sub-arrays from which the diagonals
          should be taken.
          Defaults to first axis (-2).
      axis2
          axis to be used as the second axis of the 2-D sub-arrays from which the
          diagonals should be taken. Defaults to second axis (-1).
      out
          optional output array, for writing the result to. It must have a shape that the
          inputs broadcast to.
  
      Returns
      -------
      ret
          an array containing the diagonals and whose shape is determined by removing the
          last two dimensions and appending a dimension equal to the size of the resulting
          diagonals. The returned array must have the same data type as ``x``.
  
  
      This function conforms to the `Array API Standard
      <https://data-apis.org/array-api/latest/>`_. This docstring is an extension of the
      `docstring <https://data-apis.org/array-api/latest/
      extensions/generated/array_api.linalg.diagonal.html>`_
      in the standard.
  
      Both the description and the type hints above assumes an array input for simplicity,
      but this function is *nestable*, and therefore also accepts :class:`ivy.Container`
      instances in place of any of the arguments.
  
      Examples
      --------
      With :class:`ivy.Array` inputs:
  
      >>> x = ivy.array([[1., 2.],
      ...                [3., 4.]])
  
      >>> d = ivy.diagonal(x)
      >>> print(d)
      ivy.array([1., 4.])
  
  
      >>> x = ivy.array([[[1., 2.],
      ...                 [3., 4.]],
      ...                [[5., 6.],
      ...                 [7., 8.]]])
      >>> d = ivy.diagonal(x)
      >>> print(d)
      ivy.array([[1., 4.],
                 [5., 8.]])
  
      >>> x = ivy.array([[1., 2.],
      ...                [3., 4.]])
  
      >>> d = ivy.diagonal(x, offset=1)
      >>> print(d)
      ivy.array([2.])
  
  
      >>> x = ivy.array([[0, 1, 2],
      ...                   [3, 4, 5],
      ...                   [6, 7, 8]])
      >>> d = ivy.diagonal(x, offset=-1, axis1=0)
      >>> print(d)
      ivy.array([3, 7])
  
      >>> x = ivy.array([[[ 0,  1,  2],
      ...                 [ 3,  4,  5],
      ...                 [ 6,  7,  8]],
      ...                [[ 9, 10, 11],
      ...                 [12, 13, 14],
      ...                 [15, 16, 17]],
      ...                [[18, 19, 20],
      ...                 [21, 22, 23],
      ...                 [24, 25, 26]]])
      >>> d = ivy.diagonal(x, offset=1, axis1=-3)
      >>> print(d)
      ivy.array([[1, 11],
                 [4, 14],
                 [7, 17]])
  
      >>> x = ivy.array([[[0, 1],
      ...                 [2, 3]],
      ...                [[4, 5],
      ...                 [6, 7]]])
      >>> d = ivy.diagonal(x, offset=0, axis1=0, axis2=1)
      >>> print(d)
      ivy.array([[0, 6],
                 [1, 7]])
  
      >>> x = ivy.array([[[1., 2.],
      ...                 [3., 4.]],
      ...                [[5., 6.],
      ...                 [7., 8.]]])
      >>> d = ivy.diagonal(x, offset=1, axis1=0, axis2=1)
      >>> print(d)
      ivy.array([[3.],
                 [4.]])
  
      >>> x = ivy.array([[1., 2.],
      ...                [3., 4.]])
      >>> d = ivy.diagonal(x)
      >>> print(d)
      ivy.array([1., 4.])
  
      >>> x = ivy.array([[[ 0,  1,  2],
      ...                 [ 3,  4,  5],
      ...                 [ 6,  7,  8]],
      ...                [[ 9, 10, 11],
      ...                 [12, 13, 14],
      ...                 [15, 16, 17]],
      ...                [[18, 19, 20],
      ...                 [21, 22, 23],
      ...                 [24, 25, 26]]])
      >>> d = ivy.diagonal(x, offset=1, axis1=1, axis2=-1)
      >>> print(d)
      ivy.array([[ 1,  5],
                 [10, 14],
                 [19, 23]])
  
      >>> x = ivy.array([[0, 1, 2],
      ...                [3, 4, 5],
      ...                [6, 7, 8]])
      >>> d = ivy.diagonal(x)
      >>> print(d)
      ivy.array([0, 4, 8])
  
  
      With :class:`ivy.Container` inputs:
  
      >>> x = ivy.Container(
      ...        a = ivy.array([[7, 1, 2],
      ...                       [1, 3, 5],
      ...                       [0, 7, 4]]),
      ...        b = ivy.array([[4, 3, 2],
      ...                       [1, 9, 5],
      ...                       [7, 0, 6]])
      ...    )
      >>> d = ivy.diagonal(x)
      >>> print(d)
      {
          a: ivy.array([7, 3, 4]),
          b: ivy.array([4, 9, 6])
      }
      """
      return current_backend(x).diagonal(
          x, offset=offset, axis1=axis1, axis2=axis2, out=out
      )
  
imports: from typing import Union, Optional, Tuple, Literal, List, Sequence
  import ivy
  from ivy.utils.backend import current_backend
  from ivy.func_wrapper import handle_array_function, to_native_arrays_and_back, handle_out_argument, handle_nestable, handle_array_like_without_promotion, handle_device, handle_backend_invalid
  from ivy.utils.exceptions import handle_exceptions
label_desc: Use image node_id 4 for calling a global function with example usage: diagonal() and returns: current_backend