ls-standard-library/include/ls-std/boxing/String.hpp

/*
 * Author:          Patrick-Christopher Mattulat
 * Co-Author:       Claude Sonnet 4.6 (LLM)
 * Company:         Lynar Studios
 * E-Mail:          webmaster@lynarstudios.com
 * Created:         2020-08-14
 * Changed:         2026-06-23
 *
 * */

#ifndef LS_STD_STRING_HPP
#define LS_STD_STRING_HPP

#include <ls-std/core/Class.hpp>
#include <ls-std/core/interface/IBoxing.hpp>
#include <ls-std/core/type/Types.hpp>
#include <ls-std/os/dynamic-goal.hpp>
#include <memory>
#include <string>
#include <string_view>
#include <vector>

/*
 * @doc: class(name: 'String', package: 'boxing')
 * @doc: boxing.String.description('This class represents a string and provides operations, like filling and searching.')
 * */

namespace ls::standard::boxing
{
  class LS_STD_DYNAMIC_GOAL String : public ls::standard::core::Class, public ls::standard::core::interface_type::IBoxing
  {
    public:

      String();
      explicit String(::std::string _value);
      ~String() noexcept override;

      // assignment operators

      ls::standard::boxing::String &operator=(::std::string _value);

      // arithmetic operators

      ::std::string operator+(ls::standard::boxing::String _string) const;
      ::std::string operator+(const ::std::string &_string) const;
      ::std::string operator+(const char *_string) const;
      ::std::string operator-(::std::string::size_type _number) const;

      // compound operators

      ls::standard::boxing::String &operator+=(ls::standard::boxing::String _string);
      ls::standard::boxing::String &operator+=(const ::std::string &_text);

      // comparison operators

      bool operator==(ls::standard::boxing::String _string) const;
      bool operator==(::std::string_view _value) const;
      bool operator==(const char *_value) const;
      bool operator!=(ls::standard::boxing::String _string) const;
      bool operator!=(::std::string_view _value) const;
      bool operator!=(const char *_value) const;

      // implementation

      void parse(const ::std::string &_parseText) override;
      [[nodiscard]] ::std::string toString() override;

      // additional functionality

      [[nodiscard]] bool contains(::std::string_view _text) const;
      [[nodiscard]] bool endsWith(::std::string_view _text) const;
      [[nodiscard]] bool equalsIgnoreCase(const ls::standard::boxing::String &_string) const;
      [[nodiscard]] bool equalsIgnoreCase(::std::string _text) const;
      [[nodiscard]] ::std::vector<ls::standard::core::type::byte_type> getByteData();
      [[nodiscard]] ::std::string padLeft(size_t _width, char _fillCharacter) const;
      [[nodiscard]] ::std::string padRight(size_t _width, char _fillCharacter) const;
      [[nodiscard]] ::std::string reverse() const;
      [[nodiscard]] bool startsWith(::std::string_view _text) const;
      [[nodiscard]] ::std::string toLowerCase() const;
      [[nodiscard]] ::std::string toUpperCase() const;

    private:

      ::std::string value{};

      [[nodiscard]] static ::std::string _buildCharacterChain(size_t _amount, char _fillCharacter);
      [[nodiscard]] static ::std::string _createFillContent(::std::string_view _text, size_t _width, char _fillCharacter);
  };
}

#endif