/**
 * @file trace.h
 * @brief Trace class for waveform data access
 *
 * The Trace class represents a single simulation vector/waveform
 * and provides access to the data as numpy arrays.
 */

#ifndef NGSPICE_PYTHON_TRACE_H
#define NGSPICE_PYTHON_TRACE_H

#include <string>
#include <vector>
#include <complex>
#include <memory>

namespace ngspice {

/**
 * @brief Represents a single trace/vector from simulation results
 *
 * This class holds waveform data and provides methods compatible
 * with PyLTSpice's Trace class.
 */
class Trace {
public:
    /**
     * @brief Construct a Trace
     * @param name The trace name (e.g., "V(out)")
     * @param is_complex Whether the data is complex
     */
    Trace(const std::string& name, bool is_complex = false);

    /**
     * @brief Get the trace name
     */
    const std::string& name() const { return name_; }

    /**
     * @brief Check if trace contains complex data
     */
    bool is_complex() const { return is_complex_; }

    /**
     * @brief Get the number of steps (for parametric sweeps)
     */
    size_t num_steps() const { return step_offsets_.empty() ? 1 : step_offsets_.size(); }

    /**
     * @brief Get waveform data for a specific step
     * @param step Step index (0 for single-step simulations)
     * @return Vector of data points
     *
     * For PyLTSpice compatibility, this returns real values.
     * Use get_wave_complex() for complex data.
     */
    std::vector<double> get_wave(size_t step = 0) const;

    /**
     * @brief Get complex waveform data for a specific step
     * @param step Step index (0 for single-step simulations)
     * @return Vector of complex data points
     */
    std::vector<std::complex<double>> get_wave_complex(size_t step = 0) const;

    /**
     * @brief Get all data points (all steps concatenated)
     */
    const std::vector<double>& get_all_real_data() const { return real_data_; }

    /**
     * @brief Get all imaginary data points
     */
    const std::vector<double>& get_all_imag_data() const { return imag_data_; }

    /**
     * @brief Get total number of data points
     */
    size_t size() const { return real_data_.size(); }

    /**
     * @brief Get number of data points for a specific step
     */
    size_t step_size(size_t step = 0) const;

    // Data loading methods (used during raw file parsing)

    /**
     * @brief Reserve space for data
     */
    void reserve(size_t count);

    /**
     * @brief Add a real data point
     */
    void add_point(double value);

    /**
     * @brief Add a complex data point
     */
    void add_point(double real, double imag);

    /**
     * @brief Mark the start of a new step
     */
    void mark_step_boundary();

    /**
     * @brief Set data directly (for efficiency)
     */
    void set_data(std::vector<double> real_data,
                  std::vector<double> imag_data = {});

    /**
     * @brief Set step offsets directly
     */
    void set_step_offsets(std::vector<size_t> offsets);

private:
    std::string name_;
    bool is_complex_;
    std::vector<double> real_data_;
    std::vector<double> imag_data_;
    std::vector<size_t> step_offsets_;  // Index where each step starts
};

} // namespace ngspice

#endif // NGSPICE_PYTHON_TRACE_H