/**++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 * 
 *
 *                                              PANIC
 *                              Portable Algorithms and Numerics In C++
 *
 *                       Scientific computing from scratch, with feeling.
 *
 * Copyright (c) 2026 Michelle Bausager
 *
 * This file is part of PANIC.
 *
 * PANIC is free software licensed under the GNU General Public License v3.0 or later.
 * You may redistribute and/or modify it under the terms of the GPL.
 *
 * PANIC is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the LICENSE file for the full license text.
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 *++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 *
 * Project Name:      PANIC
 * Module Name:       math
 * File Name:         maximum.hpp
 * Revision:          0.1.0
 * Date:              29-07-2026
 * Author:            Michelle Bausager
 *
 * Description:
 * Functions that finds the maximum
 *
 *++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
#pragma once

#include <tensor/vector.hpp> // for panic::vector
#include <tensor/matrix.hpp> // for panic::matrix

namespace panic{
namespace math{


/**
 * @brief Clips the maximum values in the vector or scalar.
 *
 * Computes:
 * @code
 * if (a[i] < k)
 * 	c[i] = k
 * else
 * 	c[i] = a[i]
 * @endcode
 *
 * @tparam T Numeric element type.
 * @param a Input vector.
 * @param k Scalar value compared to each element of @p a.
 * @param c Output vector. Resized to match @p a.
 *
 * @return true if @p c was resized and filled successfully.
 * @return false if resizing @p c failed.
 *
 * @note This overload writes the result into an existing vector to avoid
 *       unnecessary temporary allocations.
 */
template <typename T>
bool maximum(const panic::tensor::vector<T>& a, const T k, panic::tensor::vector<T>& c);

/**
 * @brief Returns a cliped maximum value in the vector.
 *
 * Computes:
 * @code
 * if (a[i] < k)
 * 	result[i] = k
 * else
 * 	result[i] = a[i]
 * @endcode
 *
 * @tparam T Numeric element type.
 * @param a Input vector.
 * @param k Scalar value compared to each element of @p a.
 *
 * @return A new vector containing the result.
 * @return An empty vector if the operation fails.
 *
 * @note This overload is convenient, but may allocate a new vector.
 */
template <typename T>
panic::tensor::vector<T> maximum(const panic::tensor::vector<T>& a, const T k);



/**
 * @brief Clips the maximum elementwise in the vector.
 *
 * Computes:
 * @code
 * if (a[i] < b[i])
 * 	c[i] = b[i]
 * else
 * 	c[i] = a[i]
 * @endcode
 *
 * @tparam T Numeric element type.
 * @param a First vector.
 * @param b Second vector. Must have size of @p a
 * @param c Output vector. Resized to match @p a.
 *
 * @return true if @p c was resized and filled successfully.
 * @return false if vector sizes do not match or resizing @p c failed.
 */
template <typename T>
bool maximum(const panic::tensor::vector<T>& a, const panic::tensor::vector<T>& b, panic::tensor::vector<T>& c);

/**
 * @brief Returns a new vector containing cliped maximum elementwise of a vector.
 *
 * Computes:
 * @code
 * if (a[i] < b[i])
 * 	result[i] = b[i]
 * else
 * 	result[i] = a[i]
 * @endcode
 *
 * @tparam T Numeric element type.
 * @param a First vector.
 * @param b Second vector. Must have size of @p a
 *
 * @return A new vector containing the result.
 * @return An empty vector if the operation fails.
 *
 * @note This overload is convenient, but may allocate a new vector.
 */
template <typename T>
panic::tensor::vector<T> maximum(const panic::tensor::vector<T>& a, const panic::tensor::vector<T>& b);







/**
 * @brief Clips the maximum elementwise in the matrix.
 *
 * Computes:
 * @code
 * if (A(i,j) < k)
 * 	C(i,j) = k
 * else
 * 	C(i,j) = A(i,j)
 * @endcode
 *
 * @tparam T Numeric element type.
 * @param A Input matrix.
 * @param k Scalar value compared to each element of @p a.
 * @param C Output Matrix. Resized to match @p A.
 *
 * @return true if @p C was resized and filled successfully.
 * @return false if resizing @p C failed.
 *
 * @note This overload writes the result into an existing matrix to avoid
 *       unnecessary temporary allocations.
 */
template <typename T>
bool maximum(const panic::tensor::matrix<T>& A, const T k, panic::tensor::matrix<T>& C);

/**
 * @brief Returns a new matrix containing the cliped maximum elementwise in the matrix.
 *
 * Computes:
 * @code
 * if (A(i,j) < k)
 * 	result(i,j) = k
 * else
 * 	result(i,j) = A(i,j)
 * @endcode
 *
 * @tparam T Numeric element type.
 * @param A Input matrix.
 * @param k Scalar value compared to each element of @p a.
 *
 * @return A new matrix containing the result.
 * @return An empty matrix if the operation fails.
 *
 * @note This overload is convenient, but may allocate a new matrix.
 */
template <typename T>
panic::tensor::matrix<T> maximum(const panic::tensor::matrix<T>& A, const T k);

/**
 * @brief Clips the maximum of a matrix elementwise too a matrix.
 *
 * Computes:
 * @code
 * if (A(i,j) < B(i,j))
 * 	C(i,j) = B(i,j)
 * else
 * 	C(i,j) = A(i,j)
 * @endcode
 *
 * @tparam T Numeric element type.
 * @param A First matrix.
 * @param B Second matrix. Must have size of @p A.
 * @param C Output matrix. Resized to match @p A.
 *
 * @return true if @p C was resized and filled successfully.
 * @return false if matrix sizes do not match or resizing @p c failed.
 */
template <typename T>
bool maximum(const panic::tensor::matrix<T>& A, const panic::tensor::matrix<T>& B, panic::tensor::matrix<T>& C);

/**
 * @brief Returns a new matrix containing a matrix elementwise cliped to the maixmum.
 *
 * Computes:
 * @code
 * if (A(i,j) < B(i,j))
 * 	result(i,j) = B(i,j)
 * else
 * 	result(i,j) = A(i,j)
 * @endcode
 *
 * @tparam T Numeric element type.
 * @param A Input matrix.
 * @param B Second matrix. Must have size of @p A.
 *
 * @return A new matrix containing the result.
 * @return An empty matrix if the operation fails.
 *
 * @note This overload is convenient, but may allocate a new matrix.
 */
template <typename T>
panic::tensor::matrix<T> maximum(const panic::tensor::matrix<T>& A, const panic::tensor::matrix<T>& B);

/**
 * @brief Clips the maximum of a vector rowwise too a matrix.
 *
 * Computes:
 * @code
 * if (A(i,j) < b[j])
 * 	C(i,j) = b[j])
 * else
 * 	C(i,j) = A(i,j)
 * @endcode
 *
 * @tparam T Numeric element type.
 * @param A Matrix.
 * @param b Vector. Must have size of @p A.cols().
 * @param C Output matrix. Resized to match @p A.
 *
 * @return true if @p C was resized and filled successfully.
 * @return false if matrix sizes do not match or resizing @p c failed.
 */
template <typename T>
bool maximum_rowwise(const panic::tensor::matrix<T>& A, const panic::tensor::vector<T>& b, panic::tensor::matrix<T>& C);

/**
 * @brief Returns a new matrix containing a vector rowwise cliped to the maixmum.
 *
 * Computes:
 * @code
 * if (A(i,j) < b[j])
 * 	result(i,j) = b[j])
 * else
 * 	result(i,j) = A(i,j)
 * @endcode
 *
 * @tparam T Numeric element type.
 * @param A Matrix.
 * @param b Vector. Must have size of @p A.cols().
 *
 * @return A new matrix containing the result.
 * @return An empty matrix if the operation fails.
 *
 * @note This overload is convenient, but may allocate a new vector.
 */
template <typename T>
panic::tensor::matrix<T> maximum_rowwise(const panic::tensor::matrix<T>& A, const panic::tensor::vector<T>& b);

/**
 * @brief Clips the maximum of a vector rowwise too a matrix.
 *
 * Computes:
 * @code
 * if (A(i,j) < b[i])
 * 	C(i,j) = b[i])
 * else
 * 	C(i,j) = A(i,j)
 * @endcode
 *
 * @tparam T Numeric element type.
 * @param A Matrix.
 * @param b Vector. Must have size of @p A.rows().
 * @param C Output matrix. Resized to match @p A.
 *
 * @return true if @p C was resized and filled successfully.
 * @return false if matrix sizes do not match or resizing @p c failed.
 */
template <typename T>
bool maximum_colwise(const panic::tensor::matrix<T>& A, const panic::tensor::vector<T>& b, panic::tensor::matrix<T>& C);

/**
 * @brief Returns a new matrix containing a vector rowwise cliped to the maixmum.
 *
 * Computes:
 * @code
 * if (A(i,j) < b[i])
 * 	result(i,j) = b[i])
 * else
 * 	result(i,j) = A(i,j)
 * @endcode
 *
 * @tparam T Numeric element type.
 * @param A Matrix.
 * @param b Vector. Must have size of @p A.rows().
 *
 * @return A new matrix containing the result.
 * @return An empty matrix if the operation fails.
 *
 * @note This overload is convenient, but may allocate a new vector.
 */
template <typename T>
panic::tensor::matrix<T> maximum_colwise(const panic::tensor::matrix<T>& A, const panic::tensor::vector<T>& b);

























} // namespace math
} // namespace panic