CipherAlgorithm.h

#pragma once

#include "CipherView.h"

/**
 * @class Algorithm
 * @brief Abstract interface that underlying ciphering implementations must realize.
 *
 * This interface (pure virtual class) serves as the contract for all ciphering algorithms,
 * whom @ref Cipher uses. Those "algorithms" will all be handled through an @code Algorithm*
 * pointer.
 */
class Algorithm {
public:
  /**
   * @brief Virtual destructor so implementations' destructors will be called.
   */
  virtual ~Algorithm() {};

  /**
   * @brief Mode of operation for bidirectional functions.
   */
  enum class Mode {
    encrypt,
    decrypt
  };

  /**
   * @brief Transform (encrypt, decrypt) a character as requested.
   * @param direction @ref Mode / direction of the transformation.
   * @param original Character, before transformation.
   * @return The resulting character of the transformation.
   *
   * Request the underlying algorithm to transform a singular character,
   * either by encrypting or decrypting it, as passed by the parameter.
   */
  virtual char transform(Mode direction, char original) const = 0;

  /**
   * @brief Append already ciphered chars.
   * @param dest Who to append to.
   * @param src What to append.
   *
   * @ref Cipher will allocate memory to ensure `src` fits into `dest`,
   * and that the data `dest` stores has length as set in the view.
   */
  virtual void append_ciphered(CipherView &dest, ConstCipherView src) const = 0;

  /**
   * @brief Append unciphered data.
   * @param dest Who to append to.
   * @param src What to append. Not yet ciphered.
   *
   * @copydetails append_ciphered(CipherView&, ConstCipherView) const
   */
  virtual void append_unciphered(CipherView &dest, ConstCipherView src) const = 0;

  /**
   * @brief Determine whether this and another ciphering implementation are compatible with each other.
   * @param other The algorithm to check ourself against.
   * @return Are they compatible?
   *
   * Compatibility is also implementation specific, which algorithms are compatible,
   * depend on the algorithms realized. For more info, see the programmer's documenation.
   * However this has very real implications, see how @ref Cipher::operator+=(const Cipher&) is implemented.
   */
  virtual bool is_compatible_with(Algorithm *other) const = 0;

  /**
   * @brief Duplicate (clone) the algorithm.
   * @return An algorithm implementation of the same type, with the same parameters.
   * @note The returned algorithm will (almost certainly) be heap allocated.
   */
  virtual Algorithm* clone() const = 0;
};