CartesianVector.hpp

/******************************************************************************
* Copyright (c) ATTX LLC 2024. All Rights Reserved.
*
* This software and associated documentation (the "Software") are the 
* proprietary and confidential information of ATTX, LLC. The Software is 
* furnished under a license agreement between ATTX and the user organization 
* and may be used or copied only in accordance with the terms of the agreement.
* Refer to 'license/attx_license.adoc' for standard license terms.
*
* EXPORT CONTROL NOTICE: THIS SOFTWARE MAY INCLUDE CONTENT CONTROLLED UNDER THE
* INTERNATIONAL TRAFFIC IN ARMS REGULATIONS (ITAR) OR THE EXPORT ADMINISTRATION 
* REGULATIONS (EAR99). No part of the Software may be used, reproduced, or 
* transmitted in any form or by any means, for any purpose, without the express 
* written permission of ATTX, LLC.
******************************************************************************/
/*
Cartesian Vector header file
 
Author: Alex Reynolds
*/
#ifndef CARTESIAN_VECTOR_HPP
#define CARTESIAN_VECTOR_HPP
 
#include <cmath>
 
#include "Matrix.hpp"
#include "safemath.hpp"
 
namespace clockwerk {
 
    /// @brief   Standard vector class derived from Matrix
    /// 
    /// This file defines a simple vector class for cartesian systems
    /// in any number of dimensions. As an inherited class from the
    /// Matrix class defined in this directory, it can perform all 
    /// matrix operations and has several operations of its own specific
    /// to vectors.
    template<typename T, unsigned int L>
    class CartesianVector : public Matrix<T, L, 1> {
    public:
        /// Redeclare constructors - note here that we're defining these to call
        /// their matrix counterparts, with the exception of the initializer list
        /// which we redefine for a vector
        /// Default constructor to initialize a vector to all zeroes
        CartesianVector<T, L>() : Matrix<T, L, 1>() {};
 
        /// Constructor to initialize a matrix with all the same element
        CartesianVector<T, L>(T elements) : Matrix<T, L, 1>(elements) {};
 
        /// Constructor for Matrix class with initialization. 
        /// Initializes matrix to values passed in via array
        CartesianVector<T, L>(const T(&initial)[L]);
 
        /// Copy constructor for Matrix class. Copies data from matrix
        /// object to the current instance
        CartesianVector<T, L>(const CartesianVector<T, L> &initial);
 
        /// Constructor for vector initialization via array
        CartesianVector<T, L>(const std::array<T, L> &initial);
 
        /// Destructor -- doesn't do anything because we don't dynamically
        /// allocate
        ~CartesianVector<T, L>() {}
 
        /// @brief Function to return a vector value
        /// @param idx The index to return
        /// @return Reference to the vector element
        /// @note This vector, much like std::array, does not check index
        ///       range and should be used accordingly
        T& operator [](unsigned int idx);
 
        /// @brief   Setter specific to the vector class
        /// @param   idx     Vector element to set
        /// @param   value   The value to set the element to
        /// @return  Integer value corresponding to error codes in clockwerkerrrors.h
        int set(const unsigned int &idx, const T &value) {return Matrix<T, L, 1>::set(idx, 0, value);}
 
        /// @brief   Getter specific to the vector class
        /// @param   idx     The index to return
        /// @param   value   PBR return of the value in the vector
        /// @return  Integer value corresponding to error codes in clockwerkerrrors.h
        int get(const unsigned int &idx, T &result) const {return Matrix<T, L, 1>::get(idx, 0, result);}
 
        /// @brief   Getter specific to the vector class
        /// @param   idx     The index to return
        /// @return  Value at index
        /// @note Does not bounds check index and should be treated safely
        T get(const unsigned int &idx) const {return Matrix<T, L, 1>::get(idx, 0);}
 
        /// @brief   Function to take the norm of a vector
        /// @param   result  PBR return of the norm operation
        int norm(T &result) const;
 
        /// @brief Function to take the norm of a vector
        /// @return return of the norm operation
        T norm() const {T tmp; norm(tmp); return tmp;}
 
        /// @brief   Function to take the squared norm of a vector
        /// @param   result  PBR return of the norm^2 operation
        int normSquared(T &result) const;
 
        /// @brief Function to take the squared norm of a vector
        /// @return return of the norm squared operation
        T normSquared() const {T tmp; normSquared(tmp); return tmp;}
 
        /// @brief   Function to return the unitized version of the vector
        /// @param   result  PBR return of the unit vector
        /// @return  Error code corresponding to those in clockwerkerrors.h
        int unit(CartesianVector<T, L> &result) const;
 
        /// @brief   Function to unitize the current vector
        /// @return  Error code corresponding to those in clockwerkerrors.h
        int unitize();
 
        /// @brief   Function to unitize the current vector
        /// @return  Error code corresponding to those in clockwerkerrors.h
        int normalize();
 
        /// @brief Function to write out vector as a string
        /// @return Vector written as a square brace enclosed string
        std::string str() const;
    };
 
    template <typename T, unsigned int L>
    CartesianVector<T, L>::CartesianVector(const T(&initial)[L]) {
        /// Note -- one absolutely essential check that's occurring here is that the size
        /// of the initializer list matches the size of the matrix. This is occurring implicitly
        /// at compile time via templating and is the reason why an array is used rather than
        /// a std::initializer_list
 
        /// Initialize to values from initializer list
        unsigned int i;
        for(i = 0; i < L; i++) {
            Matrix<T, L, 1>::values[i][0] = initial[i];
        }
    }
 
    template <typename T, unsigned int L>
    CartesianVector<T, L>::CartesianVector(const std::array<T, L> &initial) {
        unsigned int i;
        for(i = 0; i < L; i++) {
            Matrix<T, L, 1>::values[i][0] = initial[i];
        }
    }
 
    template <typename T, unsigned int L>
    CartesianVector<T, L>::CartesianVector(const CartesianVector<T, L> &initial)
        : Matrix<T, L, 1>::Matrix(initial) {}
 
    template <typename T, unsigned int L>
    T& CartesianVector<T, L>::operator [](unsigned int idx) {
        return Matrix<T, L, 1>::values[idx][0];
    }
 
    template <typename T, unsigned int L>
    int CartesianVector<T, L>::norm(T &result) const {
        unsigned int i;
        /// Loop through vector to get norm squared value
        result = 0.0;
        for(i = 0; i < L; i++) {
            result += Matrix<T, L, 1>::values[i][0]*Matrix<T, L, 1>::values[i][0];
        }
 
        /// Take square root to get norm. 
        int err = safeSqrt(result, result);
 
        return err;
    }
 
    template <typename T, unsigned int L>
    int CartesianVector<T, L>::normSquared(T &result) const {
        unsigned int i;
        /// Loop through vector to get norm squared value
        result = 0.0;
        for(i = 0; i < L; i++) {
            result += Matrix<T, L, 1>::values[i][0]*Matrix<T, L, 1>::values[i][0];
        }
 
        return NO_ERROR;
    }
 
    template <typename T, unsigned int L>
    int CartesianVector<T, L>::unit(CartesianVector<T, L> &result) const {
        /// Calculate the norm of our vector
        T mag = T();
        norm(mag);
 
        /// Ensure magnitude is not zero -- if it is, throw error and return
        if(mag == 0) {
            return ERROR_DIVIDE_BY_ZERO;
        }
 
        unsigned int i;
        for(i = 0; i < L; i++) {
            result.values[i][0] = Matrix<T, L, 1>::values[i][0]/mag;
        }
        return NO_ERROR;
    }
 
    template <typename T, unsigned int L>
    int CartesianVector<T, L>::unitize() {
        int err = unit(*this);
        if(err) {
            return err;
        } else {
            return NO_ERROR;
        }
    }
 
    template <typename T, unsigned int L>
    int CartesianVector<T, L>::normalize() {
        return unitize();
    }
 
    template <typename T, unsigned int L>
    std::string CartesianVector<T, L>::str() const {
        std::string out = "[";
        /// Loop through vector and write out values
        for(unsigned int i = 0; i < L; i++) {
            if(i > 0) {
                out += ",";
            }
            out += std::to_string(Matrix<T, L, 1>::values[i][0]);
        }
 
        out += "]";
        return out;
    }
 
}
 
#endif