comments.hpp

# comments.hpp #

In `comments.hpp`, comment containers are provided.

# `toml::preserve_comments` #

`preserve_comments` is a container that preserves comments.

It has all the member functions of `std::vector<std::string>`.

Comments are preserved as `std::string`. If the comment does not start with `#`, it will be prefixed with `#` during output. However, this prefixing is not done when adding comments to the container.

Spaces are not automatically added, so if you want a space immediately after `#`, either start the comment with a space or pass the comment with `#`.

    namespace toml
    {
    class preserve_comments;

    bool operator==(const preserve_comments&, const preserve_comments&);
    bool operator!=(const preserve_comments&, const preserve_comments&);
    bool operator< (const preserve_comments&, const preserve_comments&);
    bool operator<=(const preserve_comments&, const preserve_comments&);
    bool operator> (const preserve_comments&, const preserve_comments&);
    bool operator>=(const preserve_comments&, const preserve_comments&);

    void swap(preserve_comments&,        preserve_comments&);
    void swap(preserve_comments&,        std::vector<std::string>&);
    void swap(std::vector<std::string>&, preserve_comments&);

    std::ostream& operator<<(std::ostream&, const preserve_comments&);
    } //toml

## Member types #

    using container_type         = std::vector<std::string>;
    using size_type              = container_type::size_type;
    using difference_type        = container_type::difference_type;
    using value_type             = container_type::value_type;
    using reference              = container_type::reference;
    using const_reference        = container_type::const_reference;
    using pointer                = container_type::pointer;
    using const_pointer          = container_type::const_pointer;
    using iterator               = container_type::iterator;
    using const_iterator         = container_type::const_iterator;
    using reverse_iterator       = container_type::reverse_iterator;
    using const_reverse_iterator = container_type::const_reverse_iterator;

## Member Functions #

### Default Constructor #

    preserve_comments() = default;

Constructs an empty `preserve_comments`.

### Copy and Move Constructors #

    preserve_comments(preserve_comments const&) = default;
    preserve_comments(preserve_comments &&)     = default;

Constructs a `preserve_comments` by copying or moving.

### Constructor (`std::vector<std::string>`) #

    explicit preserve_comments(const std::vector<std::string>& c);
    explicit preserve_comments(std::vector<std::string>&& c);

Constructs a `preserve_comments` holding the contents of `std::vector<std::string>`.

### Constructor (`discard_comments`) #

    explicit preserve_comments(const discard_comments&);

Constructs an empty `preserve_comments`.

### Constructor (`Iterator`) #

    template<typename InputIterator>
    preserve_comments(InputIterator first, InputIterator last);

Constructs a `preserve_comments` from the range represented by `InputIterator` pointing to `std::string`.

### Constructor (`std::initializer_list`) #

    preserve_comments(std::initializer_list<std::string> x);

Constructs a `preserve_comments` from the range represented by `std::initializer_list<std::string>`.

### Constructor (Size Specified) #

    explicit preserve_comments(size_type n);
    preserve_comments(size_type n, const std::string& x);

Constructs a `preserve_comments` with `n` comments.

If a `std::string` is passed, it replicates that comment `n` times.

### Destructor #

    ~preserve_comments() = default;

Destroys the `preserve_comments`.

### `operator=(preserve_comments)` #

    preserve_comments& operator=(preserve_comments const&) = default;
    preserve_comments& operator=(preserve_comments &&)     = default;

Assigns a `preserve_comments` by copying or moving.

### `operator=(std::vector<std::string>)` #

    preserve_comments& operator=(const std::vector<std::string>& c);
    preserve_comments& operator=(std::vector<std::string>&& c);

Assigns a `std::vector<std::string>` by copying or moving.

### `assign` #

    template<typename InputIterator>
    void assign(InputIterator first, InputIterator last);
    void assign(std::initializer_list<std::string> ini);
    void assign(size_type n, const std::string& val);

The same as `std::vector<std::string>::assign`.

### `insert` #

    iterator insert(const_iterator p, const std::string& x);
    iterator insert(const_iterator p, std::string&&      x);
    iterator insert(const_iterator p, size_type n, const std::string& x);
    template<typename InputIterator>
    iterator insert(const_iterator p, InputIterator first, InputIterator last);
    iterator insert(const_iterator p, std::initializer_list<std::string> ini);

The same as `std::vector<std::string>::insert`.

### `emplace` #

    template<typename ... Ts>
    iterator emplace(const_iterator p, Ts&& ... args);

The same as `std::vector<std::string>::emplace`.

### `erase` #

    iterator erase(const_iterator pos);
    iterator erase(const_iterator first, const_iterator last);

The same as `std::vector<std::string>::erase`.

### `swap` #

    void swap(preserve_comments& other);

Swaps the comments.

### `push_back` #

    void push_back(const std::string& v);
    void push_back(std::string&&      v);

The same as `std::vector<std::string>::push_back`.

### `pop_back` #

    void pop_back();

The same as `std::vector<std::string>::pop_back`.

### `emplace_back` #

    template<typename ... Ts>
    void emplace_back(Ts&& ... args);

The same as `std::vector<std::string>::emplace_back`.

### `clear` #

    void clear();

The same as `std::vector<std::string>::clear`.

### `size` #

    size_type size() const noexcept;

The same as `std::vector<std::string>::size`.

### `max_size` #

    size_type max_size() const noexcept;

The same as `std::vector<std::string>::max_size`.

### `capacity` #

    size_type capacity() const noexcept;

The same as `std::vector<std::string>::capacity`.

### `empty` #

    bool empty() const noexcept;

The same as `std::vector<std::string>::empty`.

### `reserve` #

    void reserve(size_type n);

The same as `std::vector<std::string>::reserve`.

### `resize` #

    void resize(size_type n);
    void resize(size_type n, const std::string& c);

The same as `std::vector<std::string>::resize`.

### `shrink_to_fit` #

    void shrink_to_fit();

The same as `std::vector<std::string>::shrink_to_fit`.

### `operator[]` #

    reference       operator[](const size_type n)       noexcept;
    const_reference operator[](const size_type n) const noexcept;

The same as `std::vector<std::string>::operator[]`.

### `at` #

    reference       at(const size_type n)      ;
    const_reference at(const size_type n) const;

The same as `std::vector<std::string>::at`.

### `front` #

    reference       front()       noexcept;
    const_reference front() const noexcept;

The same as `std::vector<std::string>::front`.

### `back` #

    reference       back()        noexcept;
    const_reference back()  const noexcept;

The same as `std::vector<std::string>::back`.

### `data` #

    pointer         data()        noexcept;
    const_pointer   data()  const noexcept;

The same as `std::vector<std::string>::data`.

### `begin/end` #

    iterator       begin()        noexcept;
    iterator       end()          noexcept;
    const_iterator begin()  const noexcept;
    const_iterator end()    const noexcept;
    const_iterator cbegin() const noexcept;
    const_iterator cend()   const noexcept;

The same as `std::vector<std::string>::begin/end`.

### `rbegin/rend` #

    reverse_iterator       rbegin()        noexcept;
    reverse_iterator       rend()          noexcept;
    const_reverse_iterator rbegin()  const noexcept;
    const_reverse_iterator rend()    const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend()   const noexcept;

The same as `std::vector<std::string>::rbegin/rend`

## non-member functions #

### Comparison operator #

    bool operator==(const preserve_comments&, const preserve_comments&);
    bool operator!=(const preserve_comments&, const preserve_comments&);
    bool operator< (const preserve_comments&, const preserve_comments&);
    bool operator<=(const preserve_comments&, const preserve_comments&);
    bool operator> (const preserve_comments&, const preserve_comments&);
    bool operator>=(const preserve_comments&, const preserve_comments&);

It compares two `preserve_comments` in the same way as `std::vector<std::string>`.

### `swap` #

    void swap(preserve_comments&,        preserve_comments&);
    void swap(preserve_comments&,        std::vector<std::string>&);
    void swap(std::vector<std::string>&, preserve_comments&);

### Stream operator #

    std::ostream& operator<<(std::ostream&, const preserve_comments&);

Outputs as TOML comments.

If the first character is not `#`, it adds `#`.

# `toml::discard_comments` #

`discard_comments` serves as a container for discarding comments.

It encompasses all the member functions of `std::vector<std::string>`, but invoking functions that modify the content has no effect, leaving it perpetually empty.

    namespace toml
    {
    class discard_comments;

    bool operator==(const discard_comments&, const discard_comments&);
    bool operator!=(const discard_comments&, const discard_comments&);
    bool operator< (const discard_comments&, const discard_comments&);
    bool operator<=(const discard_comments&, const discard_comments&);
    bool operator> (const discard_comments&, const discard_comments&);
    bool operator>=(const discard_comments&, const discard_comments&);

    void swap(discard_comments&, discard_comments&);

    std::ostream& operator<<(std::ostream&, const discard_comments&);
    } //toml

## Member types #

    // container_type is not defined
    using size_type              = std::size_t;
    using difference_type        = std::ptrdiff_t;
    using value_type             = std::string;
    using reference              = std::string&;
    using const_reference        = std::string const&;
    using pointer                = std::string*;
    using const_pointer          = std::string const*;
    using iterator               = /* internal type: empty-iterator */
    using const_iterator         = /* internal type: empty-iterator */
    using reverse_iterator       = /* internal type: empty-iterator */
    using const_reverse_iterator = /* internal type: empty-iterator */

### Default Constructor #

    discard_comments() = default;

Constructs an empty `discard_comments`.

### Copy / Move Constructor #

    discard_comments(discard_comments const&) = default;
    discard_comments(discard_comments &&)     = default;

Constructs a `discard_comments` by copying or moving.

### Constructor(`std::vector<std::string>`) #

    explicit discard_comments(const std::vector<std::string>& c);
    explicit discard_comments(std::vector<std::string>&& c);

Constructs an empty `discard_comments`. Arguments are ignored.

### Constructor(`preserve_comments`) #

    explicit discard_comments(const preserve_comments&);

Constructs an empty `discard_comments`. Arguments are ignored.

### Constructor(`Iterator`) #

    template<typename InputIterator>
    discard_comments(InputIterator first, InputIterator last);

Constructs an empty `discard_comments`. Arguments are ignored.

### Constructor(`std::initializer_list`) #

    discard_comments(std::initializer_list<std::string> x);

Constructs an empty `discard_comments`. Arguments are ignored.

### Constructor(サイズ指定) #

    explicit discard_comments(size_type n);
    discard_comments(size_type n, const std::string& x);

Constructs an empty `discard_comments`. Arguments are ignored.

### Destructor #

    ~discard_comments() = default;

Destroys `discard_comments`.

### `operator=(discard_comments)` #

    discard_comments& operator=(discard_comments const&) = default;
    discard_comments& operator=(discard_comments &&)     = default;

Assigns `discard_comments` by copying or moving.

### `operator=(std::vector<std::string>)` #

    discard_comments& operator=(const std::vector<std::string>& c);
    discard_comments& operator=(std::vector<std::string>&& c);

Does nothing.

### `assign` #

    template<typename InputIterator>
    void assign(InputIterator first, InputIterator last);
    void assign(std::initializer_list<std::string> ini);
    void assign(size_type n, const std::string& val);

Does nothing.

### `insert` #

    iterator insert(const_iterator p, const std::string& x);
    iterator insert(const_iterator p, std::string&&      x);
    iterator insert(const_iterator p, size_type n, const std::string& x);
    template<typename InputIterator>
    iterator insert(const_iterator p, InputIterator first, InputIterator last);
    iterator insert(const_iterator p, std::initializer_list<std::string> ini);

Does nothing.

### `emplace` #

    template<typename ... Ts>
    iterator emplace(const_iterator p, Ts&& ... args);

Does nothing.

### `erase` #

    iterator erase(const_iterator pos);
    iterator erase(const_iterator first, const_iterator last);

Does nothing.

### `swap` #

    void swap(discard_comments& other);

Swaps two `discard_comments`. Effectively it does nothing.

### `push_back` #

    void push_back(const std::string& v);
    void push_back(std::string&&      v);

Does nothing.

### `pop_back` #

    void pop_back();

Does nothing.

### `emplace_back` #

    template<typename ... Ts>
    void emplace_back(Ts&& ... args);

Does nothing.

### `clear` #

    void clear();

Does nothing.

### `size` #

    size_type size() const noexcept;

Returns `0`.

### `max_size` #

    size_type max_size() const noexcept;

Returns `0`.

### `capacity` #

    size_type capacity() const noexcept;

Returns `0`.

### `empty` #

    bool empty() const noexcept;

Returns `true`.

### `reserve` #

    void reserve(size_type n);

Does nothing.

### `resize` #

    void resize(size_type n);
    void resize(size_type n, const std::string& c);

Does nothing.

### `shrink_to_fit` #

    void shrink_to_fit();

Does nothing.

### `operator[]` #

    reference       operator[](const size_type n)       noexcept;
    const_reference operator[](const size_type n) const noexcept;

Causes undefined behavior.

### `at` #

    reference       at(const size_type n)      ;
    const_reference at(const size_type n) const;

Throws `std::out_of_range`.

### `front` #

    reference       front()       noexcept;
    const_reference front() const noexcept;

Causes undefined behavior.

### `back` #

    reference       back()        noexcept;
    const_reference back()  const noexcept;

Causes undefined behavior.

### `data` #

    pointer         data()        noexcept;
    const_pointer   data()  const noexcept;

Returns `nullptr`.

### `begin/end` #

    iterator       begin()        noexcept;
    iterator       end()          noexcept;
    const_iterator begin()  const noexcept;
    const_iterator end()    const noexcept;
    const_iterator cbegin() const noexcept;
    const_iterator cend()   const noexcept;

Returns an internally defined `empty-iterator`.

The `empty-iterator` remains at the same value after incrementing or decrementing and all values are equivalent.

Accessing the target of the `empty-iterator` always calls `std::terminate`.

### `rbegin/rend` #

    reverse_iterator       rbegin()        noexcept;
    reverse_iterator       rend()          noexcept;
    const_reverse_iterator rbegin()  const noexcept;
    const_reverse_iterator rend()    const noexcept;
    const_reverse_iterator crbegin() const noexcept;
    const_reverse_iterator crend()   const noexcept;

Returns an internally defined `empty-iterator`.

The `empty-iterator` remains at the same value after incrementing or decrementing and all values are equivalent.

Accessing the target of the `empty-iterator` always calls `std::terminate`.

## non-member functions #

### Comparison operator #

    bool operator==(const discard_comments&, const discard_comments&);
    bool operator!=(const discard_comments&, const discard_comments&);
    bool operator< (const discard_comments&, const discard_comments&);
    bool operator<=(const discard_comments&, const discard_comments&);
    bool operator> (const discard_comments&, const discard_comments&);
    bool operator>=(const discard_comments&, const discard_comments&);

All the instances of `discard_comments` are the same value. `operator==` returns `true`, `operator=!` returns `false`.

### `swap` #

    void swap(discard_comments&, discard_comments&);

Swaps `discard_comments`. Effectively it does nothing.

### Stream operator #

    std::ostream& operator<<(std::ostream&, const discard_comments&);

Outputs nothing.

# Related #

- value.hpp