!-----------------------------------------------------------------
!
! Purpose
! =======
!
! LA_GGLSE solves the linear equality-constrained least squares (LSE)
! problem:
!         minimize || c - A*x ||_2   subject to   B*x = d
! where A is an m-by-n matrix, B is a p-by-n matrix, c is a given
! m-vector, and d is a given p-vector. It is assumed that
! p <= n <= m+p, and
!
!          rank(B) = p and  rank( ( A ) ) = n.
!                               ( ( B ) )
!
! These conditions ensure that the LSE problem has a unique solution,
! which is obtained using a GRQ factorization of the matrices B and A.
!
!
! Arguments
! =========
!
!  SUBROUTINE LA_GGLSE( A, B, C, D, X, INFO )
!    <type>(<wp>), INTENT( INOUT ) :: A( :, : ), B(:,:), C(:), D(:)
!    <type>(<wp>), INTENT( OUT ) :: X(:)
!    INTEGER, INTENT(OUT), OPTIONAL :: INFO
!    <type> ::= REAL | COMPLEX
!    <wp>   ::= KIND(1.0) | KIND(1.0D0)
!
! =====================
!
! A    (input/output) either REAL or COMPLEX array, shape (:,:),
!      SIZE(A,1) == m, SIZE(A,2) == n.
!      On entry, the m-by-n matrix A.
!      On exit, A is destroyed.
!      INFO = -1 if SIZE(A,1) < 0 or SIZE(A,2) < 0
!
! B    (input/output) REAL or COMPLEX array, shape (:,:),
!      SIZE(B,1) == p, SIZE(B,2) == n.
!      On entry, the p-by-n matrix B.
!      On exit, B is destroyed.
!      INFO = -2 if SIZE(B,1) < 0 or SIZE(B,2) /= SIZE(A,2) or
!                   SIZE(B,1) > SIZE(A,2) or SIZE(B,1) < SIZE(A,2)-SIZE(A,1)
!
! C    (input/output) REAL or COMPLEX array, shape (:), SIZE(C) == m.
!      On entry, C contains the right hand side vector for the
!      least squares part of the LSE problem.
!      On exit, the residual sum of squares for the solution
!      is given by the sum of squares of elements n-p+1 to m of
!      vector C.
!      INFO = -3 if SIZE(C) /= SIZE(A,1)
!
! D    (input/output) REAL or COMPLEX array, shape (:), SIZE(D) == m.
!      On entry, D contains the right hand side vector for the
!      constrained equation.
!      On exit, D is destroyed.
!      INFO = -4 if SIZE(D) /= SIZE(B,1)
!
! X    (output) REAL or COMPLEX array, shape (:), SIZE(X) == n.
!      On exit, X is the solution of the LSE problem.
!      INFO = -5 if SIZE(X) /= SIZE(A,2)
!
! INFO Optional (output) INTEGER
!      = 0:  successful exit.
!      < 0:  if INFO = -i, the i-th argument had an illegal value.
!      If INFO is not present and an error occurs, then the program is
!         terminated with an error message.
!--------------------------------------

.