# HG changeset patch
# User Teemu Piippo <teemu@compsta2.com>
# Date 1469022720 -10800
# Node ID 81357dcd3da4c153641e7788e8e6794bdff9b255
# Parent  d0aedc9be4486cfcb1d4ac3c119cf2ba2ff6d030
Added doxygen documentation to mystring.h

diff -r d0aedc9be448 -r 81357dcd3da4 sources/mystring.h
--- a/sources/mystring.h	Wed Jul 20 16:01:10 2016 +0300
+++ b/sources/mystring.h	Wed Jul 20 16:52:00 2016 +0300
@@ -50,9 +50,9 @@
 	String(const std::string& data);
 	String(const Vector<char>& data);
 
-	void                        append(const char* data);
-	void                        append(char data);
-	void                        append(const String& data);
+	void                        append(const char* text);
+	void                        append(char character);
+	void                        append(const String& text);
 	ConstIterator               begin() const;
 	Iterator                    begin();
 	int                         compare(const String &other) const;
@@ -65,8 +65,8 @@
 	int                         find(const char* c, int a = 0) const;
 	int                         find(char ch, int a = 0) const;
 	int                         indexDifference(int a, int b);
-	void                        insert(int pos, char c);
-	void                        insert(int pos, const char* c);
+	void                        insert(int position, char character);
+	void                        insert(int position, const char* string);
 	bool                        isEmpty() const;
 	bool                        isNumeric() const;
 	void                        modifyIndex(int &a) const;
@@ -77,13 +77,13 @@
 	String                      mid(int a, int b) const;
 	void                        normalize(int(*filter)(int) = &isspace);
 	String                      normalized(int(*filter)(int) = &isspace) const;
-	void                        prepend(String a);
-	void                        remove(int pos, int len);
-	void                        removeAt(int pos);
-	void                        removeFromEnd(int len);
-	void                        removeFromStart(int len);
+	void                        prepend(String text);
+	void                        remove(int position, int length);
+	void                        removeAt(int position);
+	void                        removeFromEnd(int length);
+	void                        removeFromStart(int length);
 	void                        replace(const char* a, const char* b);
-	void                        replace(int pos, int n, const String &a);
+	void                        replace(int position, int amount, const String &text);
 	String                      right(int length) const;
 	void                        shrinkToFit();
 	class StringList            split(const String &del) const;
@@ -137,16 +137,9 @@
 class StringList : public List<String>
 {
 public:
-	typedef List<String> Super;
-
-	StringList() {}
-
-	StringList(int numvalues) :
-		Super(numvalues) {}
-
-	StringList(const Super& other) :
-		Super(other) {}
-
+	StringList();
+	StringList(int numvalues);
+	StringList(const List<String>& other);
 	String join(const String& delim);
 };
 
@@ -155,103 +148,148 @@
 inline String operator+(const char* a, const String& b);
 
 // --------------------------------------------------------------------------------------------------------------------
-// Inline implementations
 
-
+/*!
+ * \brief Constructs an empty string.
+ */
 inline String::String() {}
 
-
-inline String::String(char a)
+/*!
+ * \brief Constructs a string from a single character.
+ * \param character Character to create a string out of.
+ */
+inline String::String(char character)
 {
-	char buffer[2] = { a, '\0' };
+	char buffer[2] = { character, '\0' };
 	m_string = buffer;
 }
 
-
-inline String::String(const char* data) :
-	m_string(data) {}
-
+/*!
+ * \brief Constructs a string from a char-array.
+ * \param string char-array to convert.
+ */
+inline String::String(const char* string) :
+	m_string(string) {}
 
-inline String::String(const std::string& data) :
-	m_string(data) {}
-
+/*!
+ * \brief Constructs a string out of a \c std::string .
+ * \param string \c std::string to base the construction on.
+ */
+inline String::String(const std::string& string) :
+	m_string(string) {}
 
-inline String::String(const Vector<char>& data) :
-	m_string(data.data(), data.size()) {}
+/*!
+ * \brief Constructs a string out of a vector of characters. The vector does not have to be null-terminated.
+ * \param charVector Vector of characters to construct the string out of.
+ */
+inline String::String(const Vector<char>& charVector) :
+	m_string(charVector.data(), charVector.size()) {}
 
-
+/*!
+ * \returns a constant iterator to the beginning of the string.
+ */
 inline String::ConstIterator String::begin() const
 {
 	return m_string.cbegin();
 }
 
-
+/*!
+ * \returns the string's contents as a char-array.
+ */
 inline const char* String::chars() const
 {
 	return m_string.c_str();
 }
 
-
+/*!
+ * \returns the string's constant end-iterator.
+ */
 inline String::ConstIterator String::end() const
 {
 	return m_string.end();
 }
 
-
+/*!
+ * \returns whether or not the string is empty.
+ */
 inline bool String::isEmpty() const
 {
 	return m_string[0] == '\0';
 }
 
-
+/*!
+ * \returns the length of the string.
+ */
 inline int String::length() const
 {
 	return m_string.length();
 }
 
-
+/*!
+ * \returns the underlying \c std::string .
+ */
 inline const std::string& String::stdString() const
 {
 	return m_string;
 }
 
-
-inline void String::append(const char* data)
+/*!
+ * \brief Adds text from a char-array to the end of the string.
+ * \param text Text to append.
+ */
+inline void String::append(const char* text)
 {
-	m_string.append(data);
+	m_string.append(text);
 }
 
-
-inline void String::append(char data)
+/*!
+ * \brief Adds text to the end of the string.
+ * \param text Text to append.
+ */
+inline void String::append(char character)
 {
-	m_string.push_back(data);
+	m_string.push_back(character);
 }
 
-
-inline void String::append(const String& data)
+/*!
+ * \brief Adds text from another string to the end of this string.
+ * \param text Text to append.
+ */
+inline void String::append(const String& text)
 {
-	m_string.append(data.chars());
+	m_string.append(text.chars());
 }
 
-
+/*!
+ * \returns a mutable iterator to the beginning of the string.
+ */
 inline String::Iterator String::begin()
 {
 	return m_string.begin();
 }
 
-
+/*!
+ * \brief Clears the string.
+ */
 inline void String::clear()
 {
 	m_string.clear();
 }
 
-
+/*!
+ * \returns the string's mutable end-iterator.
+ */
 inline String::Iterator String::end()
 {
 	return m_string.end();
 }
 
-
+/*!
+ * \brief Compares two string indices, supporting negatives as offsets from the end of string.
+ * \param a First index to compare
+ * \param b Second index to compare
+ * \returns the difference of two indices.
+ */
 inline int String::indexDifference(int a, int b)
 {
 	modifyIndex(a);
@@ -259,183 +297,303 @@
 	return b - a;
 }
 
-
-inline void String::insert(int pos, char c)
+/*!
+ * \brief Inserts a character into the string.
+ * \param position Position in the string where to insert the character into.
+ * \param character Character to insert into the string.
+ */
+inline void String::insert(int position, char character)
 {
-	m_string.insert(m_string.begin() + pos, c);
+	m_string.insert(m_string.begin() + position, character);
 }
 
-
-inline void String::insert(int pos, const char* c)
+/*!
+ * \brief Inserts a substring into the string.
+ * \param position Position in the string where to insert the substring.
+ * \param string Substring to insert.
+ */
+inline void String::insert(int position, const char* string)
 {
-	m_string.insert(pos, c);
+	m_string.insert(position, string);
 }
 
-
-inline void String::modifyIndex(int& a) const
+/*!
+ * \brief Modifies the given index so that if it is negative, it is translated into a positive index starting from the
+ *        end of the string. For example, an index of -1 will be modified to point to the last character in the string,
+ *        -2 to the second last, etc.
+ * \param index Index to translate.
+ */
+inline void String::modifyIndex(int& index) const
 {
-	if (a < 0)
-		a = length() - a;
+	if (index < 0)
+		index = length() - index;
 }
 
-
-inline void String::prepend(String a)
+/*!
+ * \brief Prepends the given text to the beginning of the string.
+ * \param text Text to prepend.
+ */
+inline void String::prepend(String text)
 {
-	m_string = (a + m_string).stdString();
+	m_string = (text + m_string).stdString();
 }
 
-
-inline void String::remove(int pos, int len)
+/*!
+ * \brief Removes a range of text from the string.
+ * \param position Position where to start removing text.
+ * \param length Amount of characters to remove.
+ */
+inline void String::remove(int position, int length)
 {
-	m_string.replace(pos, len, "");
+	m_string.replace(position, length, "");
 }
 
-
-inline void String::removeAt(int pos)
+/*!
+ * \brief Removes a single character from the string.
+ * \param position Position of the character to remove string from.
+ */
+inline void String::removeAt(int position)
 {
-	m_string.erase(m_string.begin() + pos);
+	m_string.erase(m_string.begin() + position);
 }
 
-
-inline void String::removeFromEnd(int len)
+/*!
+ * \brief Removes a number of characters from the end of the string.
+ * \param length Amount of characters to remove.
+ */
+inline void String::removeFromEnd(int length)
 {
-	remove(length() - len, len);
+	remove(this->length() - length, length);
 }
 
-
-inline void String::removeFromStart(int len)
+/*!
+ * \brief Removes a number of characters from the beginning of the string.
+ * \param length Amount of characters to remove.
+ */
+inline void String::removeFromStart(int length)
 {
-	remove(0, len);
+	remove(0, length);
 }
 
-
-inline void String::replace(int pos, int n, const String& a)
+/*!
+ * \brief Replaces a range of text in the string with another.
+ * \param position Position where to start replacing text.
+ * \param amount Amount of characters to replace.
+ * \param text Replacement string.
+ */
+inline void String::replace(int position, int amount, const String& text)
 {
-	m_string.replace(pos, n, a.chars());
+	m_string.replace(position, amount, text.chars());
 }
 
-
+/*!
+ * \brief Shrinks the string so that it does not allocate more characters than necessary.
+ */
 inline void String::shrinkToFit()
 {
 	m_string.shrink_to_fit();
 }
 
-
-inline String String::operator+(int num) const
+/*!
+ * \brief Converts a number into a string, and returns a new string with the number appended to the end of the string.
+ * \param number Number to convert and append.
+ * \returns the resulting string.
+ */
+inline String String::operator+(int number) const
 {
-	return *this + String::fromNumber(num);
+	return *this + String::fromNumber(number);
 }
 
-
-inline String& String::operator+=(const String& data)
+/*!
+ * \brief Appends text into the string.
+ * \param text Text to append.
+ * \returns a reference to this string.
+ */
+inline String& String::operator+=(const String& text)
 {
-	append(data);
+	append(text);
 	return *this;
 }
 
-
-inline String& String::operator+=(const char* data)
+/*!
+ * \brief Appends text into the string.
+ * \param text Text to append.
+ * \returns a reference to this string.
+ */
+inline String& String::operator+=(const char* text)
 {
-	append(data);
+	append(text);
 	return *this;
 }
 
-
-inline String& String::operator+=(int num)
+/*!
+ * \brief Converts a number into a string, and appends it into this string.
+ * \param number The number to append.
+ * \returns a refence to this string.
+ */
+inline String& String::operator+=(int number)
 {
-	return operator+=(String::fromNumber(num));
+	return operator+=(String::fromNumber(number));
 }
 
-
-inline String& String::operator+=(char data)
+/*!
+ * \brief Appends a character into this string.
+ * \param character The character to append.
+ * \return a reference to this string.
+ */
+inline String& String::operator+=(char character)
 {
-	append(data);
+	append(character);
 	return *this;
 }
 
-
-inline char& String::operator[](int i)
+/*!
+ * \param index Index referring to a character of this string.
+ * \returns an editable reference to the character pointed by the given index.
+ */
+inline char& String::operator[](int index)
 {
-	return m_string[i];
+	return m_string[index];
 }
 
-
-inline char String::operator[](int i) const
+/*!
+ * \param index Index referring to a character of this string.
+ * \returns an const reference to the character pointed by the given index.
+ */
+inline char String::operator[](int index) const
 {
-	return m_string[i];
+	return m_string[index];
 }
 
-
+/*!
+ * \param other String to compare with.
+ * \returns whether or not this string is the same as the other string.
+ */
 inline bool String::operator==(const String& other) const
 {
 	return stdString() == other.stdString();
 }
 
-
+/*!
+ * \param other String to compare with.
+ * \returns whether or not this string is the same as the other string.
+ */
 inline bool String::operator==(const char* other) const
 {
 	return m_string == other;
 }
 
-
+/*!
+ * \param other String to compare with.
+ * \returns whether or not this string is different than the other string.
+ */
 inline bool String::operator!=(const String& other) const
 {
 	return stdString() != other.stdString();
 }
 
-
+/*!
+ * \param other String to compare with.
+ * \returns whether or not this string is different than the other string.
+ */
 inline bool String::operator!=(const char* other) const
 {
 	return m_string != other;
 }
 
-
+/*!
+ * \param other String to compare with.
+ * \return whether or not this string is lexicographically greater than the other string.
+ */
 inline bool String::operator>(const String& other) const
 {
 	return stdString() > other.stdString();
 }
 
-
+/*!
+ * \param other String to compare with.
+ * \return whether or not this string is lexicographically lesser than the other string.
+ */
 inline bool String::operator<(const String& other) const
 {
 	return stdString() < other.stdString();
 }
 
-
+/*!
+ * \param other String to compare with.
+ * \return whether or not this string is lexicographically at least as great as the other string.
+ */
 inline bool String::operator>=(const String& other) const
 {
 	return stdString() >= other.stdString();
 }
 
-
+/*!
+ * \param other String to compare with.
+ * \return whether or not this string is lexicographically at most as great as the other string.
+ */
 inline bool String::operator<=(const String& other) const
 {
 	return stdString() <= other.stdString();
 }
 
-
+/*!
+ * \returns a char-array representation of this string.
+ */
 inline String::operator const char*() const
 {
 	return chars();
 }
 
-
+/*!
+ * \returns the underlying \c std::string of this string.
+ */
 inline String::operator const std::string&() const
 {
 	return stdString();
 }
 
+/*!
+ * \brief Constructs an empty string list.
+ */
+StringList::StringList() {}
 
+/*!
+ * \brief Constructs a string list containing \c numvalues empty strings.
+ * \param numvalues Amount of empty strings to fill.
+ */
+StringList::StringList(int numvalues) :
+	List<String>(numvalues) {}
 
-inline bool operator==(const char* a, const String& b)
+/*!
+ * \brief Constructs a string list from another list of strings.
+ * \param other The list of strings to use for construction.
+ */
+StringList::StringList(const List<String>& other) :
+	List<String>(other) {}
+
+/*!
+ * \brief An \c operator== implementation that allows a char-array to be at the left side of a string comparison
+ *        with a \c String.
+ * \param one A char-array representation of a string to compare.
+ * \param other A string to compare.
+ * \returns whether or not the two parameters are equal.
+ */
+inline bool operator==(const char* one, const String& other)
 {
-	return b == a;
+	return other == one;
 }
 
-
-inline String operator+(const char* a, const String& b)
+/*!
+ * \brief An \c operator+ implementation that allows a char-array to be at the left side of a string catenation
+ *        with a \c String.
+ * \param one A char-array representation of a string to catenate.
+ * \param other A string to catenate.
+ * \returns the catenated string.
+ */
+inline String operator+(const char* one, const String& other)
 {
-	return String(a) + b;
+	return String(one) + other;
 }