From a8388cfdc47386dcb61f1b5bb9190ce382bf3f1d Mon Sep 17 00:00:00 2001
From: Syndamia <kamen.d.mladenov@protonmail.com>
Date: Sun, 8 May 2022 19:50:18 +0300
Subject: Fully documented generic classes

---
 src/Generic/String/String.cpp | 48 +++++++++++++++++++++++++++++++++++++++----
 1 file changed, 44 insertions(+), 4 deletions(-)

(limited to 'src/Generic/String/String.cpp')

diff --git a/src/Generic/String/String.cpp b/src/Generic/String/String.cpp
index eb157a2..49c0b19 100644
--- a/src/Generic/String/String.cpp
+++ b/src/Generic/String/String.cpp
@@ -15,12 +15,17 @@ void String::copyFrom(const String& other) {
 
 /* Public */
 
+/*!
+ * Allocated with length + 1 size, so there is a terminating zero at the end.
+ */
 String::String(unsigned length) {
 	this->length = length;
 	str = new char[length + 1];
 	str[length] = '\0';
 }
 
+/*! \params str C-style string
+ */
 String::String(const char* str) {
 	length = strlen(str);
 	this->str = new char[length + 1]; // capture terminating zero
@@ -35,6 +40,12 @@ unsigned String::get_length() const {
 	return length;
 }
 
+char& String::operator[](unsigned index) {
+	return str[index];
+}
+
+/*! \params str C-style string
+ */
 String& String::operator+=(const char* str) {
 	unsigned strLen = strlen(str);
 	char* newStr = new char[length + strLen + 1];
@@ -48,6 +59,9 @@ String& String::operator+=(const char* str) {
 	return *this;
 }
 
+/*!
+ * Converts the number to a C-style string and then uses += to append it.
+ */
 String& String::operator+=(unsigned number) {
 	unsigned tempLen = number / 10 + 1;
 	char* tmp = new char[tempLen + 1];
@@ -94,24 +108,45 @@ String& String::operator=(String&& other) {
 	return *this;
 }
 
+/*! \param istr An input stream
+ *
+ * Directly reads bytes from stream (calls read() function).
+ * First reads the string length, then the underlying C-style string (including terminating zero).
+ * 
+ * \remark Doesn't alter the stream in any other way.
+ * \note Best used with binary ifstream
+ */
 void String::read(std::istream& istr) {
 	istr.read((char*)&length, sizeof(length));
 	istr.read(str, sizeof(char) * (length + 1));
 }
 
+/*! \param ostr An output stream
+ *
+ * Directly writes bytes to stream (calls write() function).
+ * First writes the string length, then the underlying C-style string (including terminating zero).
+ * 
+ * \remark Doesn't alter the stream in any other way.
+ * \note Best used with binary ofstream
+ */
 void String::write(std::ostream& ostr) const {
 	ostr.write((char*)&length, sizeof(length));
 	ostr.write(str, sizeof(char) * (length + 1));
 }
 
+/*! \params other C-style string
+ *  \returns strcmp between underlying C-style string and "other"
+ */
 int String::compare(const String& other) const {
 	return strcmp(str, other.str);
 }
 
-char& String::operator[](unsigned index) {
-	return str[index];
-}
-
+/*!
+ * Uses the stream's getline function to read the data.
+ *
+ * \warning It takes at most 1024 characters from the stream!
+ * \note Best used with std::cin or text std::ifstream
+ */
 std::istream& operator>>(std::istream& istr, String& event) {
 	istr.getline(event.str, 1024);
 	event.length = strlen(event.str);
@@ -119,6 +154,11 @@ std::istream& operator>>(std::istream& istr, String& event) {
 	return istr;
 }
 
+/*!
+ * Uses the stream's << operator to write the underlying C-style string
+ *
+ * \note Best used with std::cout or text std::ofstream
+ */
 std::ostream& operator<<(std::ostream& ostr, const String& event) {
 	return ostr << event.str;
 }
-- 
cgit v1.3.1-23-gd82d