worksheet.hpp

// Copyright (c) 2014-2022 Thomas Fussell
// Copyright (c) 2010-2015 openpyxl
// Copyright (c) 2024-2026 xlnt-community
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE
//
// @license: http://www.opensource.org/licenses/mit-license.php
// @author: see AUTHORS file

#pragma once

#include <iterator>
#include <string>
#include <vector>

#include <xlnt/xlnt_config.hpp>
#include <xlnt/cell/index_types.hpp>
#include <xlnt/packaging/relationship.hpp>
#include <xlnt/worksheet/page_margins.hpp>
#include <xlnt/worksheet/page_setup.hpp>
#include <xlnt/worksheet/sheet_view.hpp>

namespace xlnt {

class cell;
class cell_reference;
class cell_vector;
class column_properties;
class comment;
class condition;
class conditional_format;
class const_range_iterator;
class footer;
class header;
class range;
class range_iterator;
class range_reference;
class relationship;
class row_properties;
class sheet_format_properties;
class workbook;
class phonetic_pr;

struct date;

namespace detail {

class xlsx_consumer;
class xlsx_producer;

struct worksheet_impl;

} // namespace detail

class XLNT_API worksheet
{
public:
    using iterator = range_iterator;

    using const_iterator = const_range_iterator;

    using reverse_iterator = std::reverse_iterator<iterator>;

    using const_reverse_iterator = std::reverse_iterator<const_iterator>;

    worksheet();

    worksheet(const worksheet &rhs);

    class workbook workbook();

    const class workbook workbook() const;

    void garbage_collect();

    // identification

    std::size_t id() const;

    void id(std::size_t id);

    std::string title() const;

    void title(const std::string &title);

    // freeze panes

    cell_reference frozen_panes() const;

    void freeze_panes(cell top_left_cell);

    void freeze_panes(const cell_reference &top_left_coordinate);

    void unfreeze_panes();

    bool has_frozen_panes() const;

    // container

    bool has_cell(const cell_reference &reference) const;

    class cell cell(const cell_reference &reference);

    const class cell cell(const cell_reference &reference) const;

    class cell cell(column_t column, row_t row);

    const class cell cell(column_t column, row_t row) const;

    class range range(const std::string &reference_string);

    const class range range(const std::string &reference_string) const;

    class range range(const range_reference &reference);

    const class range range(const range_reference &reference) const;

    class range rows(bool skip_null = true);

    const class range rows(bool skip_null = true) const;

    class range columns(bool skip_null = true);

    const class range columns(bool skip_null = true) const;

    //TODO: finish implementing cell_iterator wrapping before uncommenting
    //class cell_vector cells(bool skip_null = true);

    //TODO: finish implementing cell_iterator wrapping before uncommenting
    //const class cell_vector cells(bool skip_null = true) const;

    void clear_cell(const cell_reference &ref);

    void clear_row(row_t row);

    void insert_rows(row_t row, std::uint32_t amount);

    void insert_columns(column_t column, std::uint32_t amount);

    void delete_rows(row_t row, std::uint32_t amount);

    void delete_columns(column_t column, std::uint32_t amount);

    // properties

    xlnt::column_properties &column_properties(column_t column);

    const xlnt::column_properties &column_properties(column_t column) const;

    bool has_column_properties(column_t column) const;

    void add_column_properties(column_t column, const class column_properties &props);

    double column_width(column_t column) const;

    xlnt::row_properties &row_properties(row_t row);

    const xlnt::row_properties &row_properties(row_t row) const;

    bool has_row_properties(row_t row) const;

    void add_row_properties(row_t row, const class row_properties &props);

    double row_height(row_t row) const;

    // positioning

    cell_reference point_pos(int left, int top) const;

    // named range

    void create_named_range(const std::string &name, const std::string &reference_string);

    void create_named_range(const std::string &name, const range_reference &reference);

    bool has_named_range(const std::string &name) const;

    class range named_range(const std::string &name);

    const class range named_range(const std::string &name) const;

    void remove_named_range(const std::string &name);

    // extents

    row_t lowest_row() const;

    row_t lowest_row_or_props() const;

    row_t highest_row() const;

    row_t highest_row_or_props() const;

    row_t next_row() const;

    column_t lowest_column() const;

    column_t lowest_column_or_props() const;

    column_t highest_column() const;

    column_t highest_column_or_props() const;

    range_reference calculate_dimension(bool skip_null=true, bool skip_row_props=false) const;

    // cell merge

    void merge_cells(const std::string &reference_string);

    void merge_cells(const range_reference &reference);

    void unmerge_cells(const std::string &reference_string);

    void unmerge_cells(const range_reference &reference);

    std::vector<range_reference> merged_ranges() const;

    // operators

    bool operator==(const worksheet &other) const;

    bool operator!=(const worksheet &other) const;

    bool operator==(std::nullptr_t) const;

    bool operator!=(std::nullptr_t) const;

    void operator=(const worksheet &other);

    class cell operator[](const cell_reference &reference);

    const class cell operator[](const cell_reference &reference) const;

    bool compare(const worksheet &other, bool compare_by_reference) const;

    // page

    bool has_page_setup() const;

    xlnt::page_setup page_setup() const;

    void page_setup(const struct page_setup &setup);

    bool has_page_margins() const;

    xlnt::page_margins page_margins() const;

    void page_margins(const class page_margins &margins);

    void clear_page_margins();

    // auto filter

    range_reference auto_filter() const;

    void auto_filter(const std::string &range_string);

    void auto_filter(const xlnt::range &range);

    void auto_filter(const range_reference &reference);

    void clear_auto_filter();

    bool has_auto_filter() const;

    void reserve(std::size_t n);

    bool has_phonetic_properties() const;

    phonetic_pr phonetic_properties() const;

    void phonetic_properties(const phonetic_pr &phonetic_props);

    bool has_header_footer() const;

    class header_footer header_footer() const;

    void header_footer(const class header_footer &new_header_footer);

    xlnt::sheet_state sheet_state() const;

    void sheet_state(xlnt::sheet_state state);

    iterator begin();

    iterator end();

    const_iterator begin() const;

    const_iterator end() const;

    const_iterator cbegin() const;

    const_iterator cend() const;

    void print_title_rows(row_t start, row_t end);

    optional<std::pair<row_t, row_t>> print_title_rows() const;

    void print_title_cols(column_t start, column_t end);

    optional<std::pair<column_t, column_t>> print_title_cols() const;

    bool has_print_titles() const;

    void clear_print_titles();

    void print_area(const std::string &print_area);

    void clear_print_area();

    range_reference print_area() const;

    bool has_print_area() const;

    bool has_view() const;

    const std::vector<sheet_view> & views() const;

    sheet_view &view(std::size_t index = 0) const;

    void add_view(const sheet_view &new_view);

    void remove_view(std::size_t index);

    void clear_views();

    void active_cell(const cell_reference &ref);

    bool has_active_cell() const;

    cell_reference active_cell() const;

    // page breaks

    void clear_page_breaks();

    const std::vector<row_t> &page_break_rows() const;

    void page_break_at_row(row_t row);

    const std::vector<column_t> &page_break_columns() const;

    void page_break_at_column(column_t column);

    xlnt::conditional_format conditional_format(const range_reference &ref, const condition &when);

    xlnt::path path() const;

    relationship referring_relationship() const;

    sheet_format_properties format_properties() const;

    void format_properties(const sheet_format_properties &properties);

    bool has_drawing() const;

    bool is_empty() const;

    int zoom_scale() const;

    void zoom_scale(int scale);

    void outline_settings(bool visible, bool symbols_below, bool symbols_right, bool apply_styles);

    bool show_outline_symbols() const;

    bool summary_below() const;

    bool summary_right() const;

    bool apply_styles() const;

private:
    friend class cell;
    friend class const_range_iterator;
    friend class range_iterator;
    friend class workbook;
    friend class detail::xlsx_consumer;
    friend class detail::xlsx_producer;

    worksheet(detail::worksheet_impl *d);

    void register_comments_in_manifest();

    void register_calc_chain_in_manifest();

    void garbage_collect_formulae();

    void parent(class workbook &wb);

    void move_cells(std::uint32_t index, std::uint32_t amount, row_or_col_t row_or_col, bool reverse = false);

    detail::worksheet_impl *d_ = nullptr;
};

} // namespace xlnt