lib/file: Clarify what the functions do, take cursor position into account for cut functions and add missing cut function

I hope I didn’t forget anything. Not exactly capable of thinking rn.

copyright_notice_template

@@ -1,5 +1,8 @@
 Copyright <year>, FOSS-VG Developers and Contributers
 
+Author(s):
+  <names or pseudonyms here>
+
 This program is free software: you can redistribute it and/or modify it
 under the terms of the GNU Affero General Public License as published
 by the Free Software Foundation, version 3.

src/lib/error.hpp

@@ -23,37 +23,43 @@ struct ErrorOr {
     uint8_t errorCode;
     T value;
 
-    ErrorOr();
-    ErrorOr(T);
-    ErrorOr(bool, uint8_t);
-    ErrorOr(bool, uint8_t, T);
+    ErrorOr() {
+        this->isError = false;
+        this->errorCode = 0;
+    }
+
+    ErrorOr(T value) {
+        this->isError = false;
+        this->errorCode = 0;
+        this->value = value;
+    }
+
+    ErrorOr(bool isError, uint8_t errorCode) {
+        this->isError = isError;
+        this->errorCode = errorCode;
+    }
+
+    ErrorOr(bool isError, uint8_t errorCode, T value) {
+        this->isError = isError;
+        this->errorCode = errorCode;
+        this->value = value;
+    }
 };
 
-template <typename T>
-ErrorOr<T>::ErrorOr() {
-    this->isError = false;
-    this->errorCode = 0;
-}
+struct ErrorOrVoid {
+    bool isError;
+    uint8_t errorCode;
 
-template <typename T>
-ErrorOr<T>::ErrorOr(T value) {
-    this->isError = false;
-    this->errorCode = 0;
-    this->value = value;
-}
+    ErrorOrVoid() {
+        this->isError = false;
+        this->errorCode = 0;
+    }
 
-template <typename T>
-ErrorOr<T>::ErrorOr(bool isError, uint8_t errorCode) {
-    this->isError = isError;
-    this->errorCode = errorCode;
-}
-
-template <typename T>
-ErrorOr<T>::ErrorOr(bool isError, uint8_t errorCode, T value) {
-    this->isError = isError;
-    this->errorCode = errorCode;
-    this->value = value;
-}
+    ErrorOrVoid(bool isError, uint8_t errorCode) {
+        this->isError = isError;
+        this->errorCode = errorCode;
+    }
+};
 
 namespace ErrorCodes {
     // These are all arbitrary values used to assign error codes to different

src/lib/file.cpp

@@ -0,0 +1,19 @@
+// Copyright 2022, FOSS-VG Developers and Contributers
+//
+// Author(s):
+//   <add authors here>
+//
+// This program is free software: you can redistribute it and/or modify it
+// under the terms of the GNU Affero General Public License as published
+// by the Free Software Foundation, version 3.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied
+// warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+// See the GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// version 3 along with this program.
+// If not, see https://www.gnu.org/licenses/agpl-3.0.en.html
+
+#include "file.hpp"

src/lib/file.hpp

@@ -0,0 +1,90 @@
+// Copyright 2022, FOSS-VG Developers and Contributers
+//
+// Author(s):
+//   BodgeMaster
+//
+// This program is free software: you can redistribute it and/or modify it
+// under the terms of the GNU Affero General Public License as published
+// by the Free Software Foundation, version 3.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied
+// warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+// See the GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// version 3 along with this program.
+// If not, see https://www.gnu.org/licenses/agpl-3.0.en.html
+
+#include <cstdint>
+#include <string>
+#include <vector>
+#include <tinyutf8/tinyutf8.h>
+
+#include "error.hpp"
+
+class File {
+    private:
+        //TODO: add other necessary internals to this section as needed
+        char mode;
+        //TODO: add other necessary details to the constructor as needed
+        // For example, the fstream (or whatever mechanism is used) needs
+        // to be handed over from File::open() to the File object.
+        //
+        // Remember to add a destructor to the public section if pointers
+        // are to be used.
+        File(char mode, uint64_t cursorPosition);
+    public:
+        bool isOpen;
+        bool eof;
+        uint64_t cursorPosition;
+        // may be error if not a regular file or size cannot be determined
+        ErrorOr<uint64_t> size;
+
+        void open();
+        void close();
+
+        // only applicable to read and edit modes
+        // moves the cursor to the right of the read section
+        ErrorOr<uint8_t> readByte();
+        ErrorOr<std::vector<uint8_t>> read(uint64_t bytes);
+        // @SodaFountain (or whoever ends up implementing this):
+        // Tiny-UTF8 uses UTF-32 internally IIRC.
+        // There is a constructor for it that takes std::string and
+        // converts it to the internal format.
+        //TODO: remove this comment when it served its purpose
+        ErrorOr<tiny_utf8::string> readString(uint64_t bytes);
+
+        // only applicable to write, modify, append, and edit modes
+        // in modify and edit modes, overwrite whatever is at the
+        // cursor position if there is anything there
+        // moves the cursor to the right of the written section
+        ErrorOrVoid writeByte(uint8_t byte);
+        ErrorOrVoid write(std::vector<uint8_t> data);
+        ErrorOrVoid writeString(tiny_utf8::string string);
+
+        // only applicable to modify and edit modes
+        // insert at cursor position and move other contents to the right
+        // moves the cursor to the right of the inserted section
+        ErrorOrVoid insertByte(uint8_t byte);
+        ErrorOrVoid insert(std::vector<uint8_t> data);
+        ErrorOrVoid insertString(tiny_utf8::string string);
+
+        // only applicable to edit mode
+        // return the cut section, remove cut section from file
+        // moves the cursor to the right of where it happened
+        ErrorOr<uint8_t> cutByte();
+        ErrorOr<std::vector<uint8_t>> cut(uint64_t length);
+        ErrorOr<tiny_utf8::string> cutString(uint64_t length);
+
+        // modes:
+        //  r (read)
+        //  w (write: overwrite file deleting its previous contents)
+        //  a (append: write to end of file)
+        //  m (modify: write to file modifying its previous contents)
+        //  e (edit: like read+modify)
+        //
+        // A startPosition of 0xFFFFFFFF is considered to be the end of
+        // the file whatever its size.
+        static ErrorOr<File> open(std::string path, char mode, uint64_t startPosition=0);
+};