# HG changeset patch
# User Teemu Piippo <teemu@compsta2.com>
# Date 1469025111 -10800
# Node ID 12c93c4a137ce32261785c4e26bc274dbb0d0e14
# Parent  81357dcd3da4c153641e7788e8e6794bdff9b255
Documented mystring.cpp. String::trim removed as it does the same as String::removeFromEnd.

diff -r 81357dcd3da4 -r 12c93c4a137c sources/mystring.cpp
--- a/sources/mystring.cpp	Wed Jul 20 16:52:00 2016 +0300
+++ b/sources/mystring.cpp	Wed Jul 20 17:31:51 2016 +0300
@@ -35,50 +35,41 @@
 
 BEGIN_ZFC_NAMESPACE
 
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \brief Compares this string with another.
+ * \param other The string to compare with.
+ * \returns -1 if this string is lexicographically less than \c other,
+ *          0 if they are equal, or
+ *          1 if this string is lexicographically greater than \c other.
+ */
 int String::compare (const String& other) const
 {
 	return m_string.compare (other.stdString());
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-void String::trim (int n)
+/*!
+ * \brief Removes all instances of an unwanted character from this string.
+ * \param unwanted Character to remove.
+ */
+void String::strip (char unwanted)
 {
-	if (n > 0)
-		m_string = mid (0, length() - n).stdString();
-	else
-		m_string = mid (n, -1).stdString();
+	for (int pos = 0; (pos = find (unwanted)) != -1;)
+		removeAt (pos--);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-String String::strip (char unwanted) const
+/*!
+ * \brief Removes all instances of multiple characters from this string.
+ * \param unwanted Characters to remove.
+ */
+void String::strip (const List<char>& unwanted)
 {
-	String result (m_string);
-
-	for (int pos = 0; (pos = result.find (unwanted)) != -1;)
-		result.removeAt (pos--);
-
-	return result;
+	for (char character : unwanted)
+		strip(character);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-String String::strip (const List<char>& unwanted) const
-{
-	String result (m_string);
-
-	for (String c : unwanted)
-	for (int pos = 0; (pos = result.find (c)) != -1;)
-		result.removeAt (pos--);
-
-	return result;
-}
-
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \returns an upper-case version of this string.
+ */
 String String::toUpperCase() const
 {
 	String result (m_string);
@@ -92,8 +83,9 @@
 	return result;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \returns a lower-case version of this string.
+ */
 String String::toLowerCase() const
 {
 	String result (m_string);
@@ -107,86 +99,99 @@
 	return result;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-StringList String::split (char del) const
+/*!
+ * \brief Splits this string using the provided delimeter.
+ * \param delimeter Delimeter to use for splitting.
+ * \returns a string list containing the split strings.
+ */
+StringList String::split (char delimeter) const
 {
-	String delimstr;
-	delimstr += del;
-	return split (delimstr);
+	String delimeterString;
+	delimeterString += delimeter;
+	return split (delimeterString);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-StringList String::split (const String& del) const
+/*!
+ * \brief Splits this string using the provided delimeter.
+ * \param delimeter Delimeter to use for splitting.
+ * \returns a string list containing the split strings.
+ */
+StringList String::split (const String& delimeter) const
 {
-	StringList res;
+	StringList result;
 	int a = 0;
 	int b;
 
 	// Find all separators and store the text left to them.
-	while ((b = find (del, a)) != -1)
+	while ((b = find (delimeter, a)) != -1)
 	{
 		String sub = mid (a, b);
 
 		if (sub.length() > 0)
-			res << sub;
+			result << sub;
 
-		a = b + del.length();
+		a = b + delimeter.length();
 	}
 
 	// Add the string at the right of the last separator
 	if (a < (int) length())
-		res.append (mid (a, length()));
+		result.append (mid (a, length()));
 
-	return res;
+	return result;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-void String::replace (const char* a, const char* b)
+/*!
+ * \brief Replaces all instances of \c text with \c replacement.
+ * \param text Text to replace away.
+ * \param replacement Text to replace \c text with.
+ */
+void String::replace (const char* text, const char* replacement)
 {
-	long pos;
+	int position;
 
-	while ((pos = find (a)) != -1)
-		m_string = m_string.replace (pos, strlen (a), b);
+	while ((position = find (text)) != -1)
+		m_string = m_string.replace (position, strlen (text), replacement);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-int String::count (char needle) const
+/*!
+ * \param character Character to count.
+ * \returns the amount of \c character found in the string.
+ */
+int String::count (char character) const
 {
 	int result = 0;
 
 	for (char ch : *this)
 	{
-		if (ch == needle)
+		if (ch == character)
 			result++;
 	}
 
 	return result;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-// Returns a substring from [a, b)
-//
-String String::mid (int a, int b) const
+/*!
+ * \param a Starting index of the range.
+ * \param b Ending index of the range.
+ * \returns a sub-string containing all characters from \c a to \c b, not including the character at \c b.
+ */
+String String::mid (int rangeBegin, int rangeEnd) const
 {
-	a = max(a, 0);
-	b = min(b, length());
+	modifyIndex(rangeBegin);
+	modifyIndex(rangeEnd);
+	rangeBegin = max(rangeBegin, 0);
+	rangeEnd = min(rangeEnd, length());
 
-	if (b == -1)
-		b = length();
-
-	if (b <= a)
+	if (rangeEnd <= rangeBegin)
 		return "";
 	else
-		return m_string.substr(a, b - a);
+		return m_string.substr(rangeBegin, rangeEnd - rangeBegin);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \param length Amount of characters to return.
+ * \returns the \c length right-most characters of the string.
+ */
 String String::right(int length) const
 {
 	if (length >= this->length())
@@ -195,74 +200,93 @@
 		return String(chars() + this->length() - length);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-int String::find (const char* c, int a) const
+/*!
+ * \brief Finds the first instance of a sub-string.
+ * \param subString Sub-string to search within this string.
+ * \param startingPosition Position to start looking for the sub-string from.
+ * \returns the position the first instance of sub-string found, or -1 if not found.
+ */
+int String::find (const char* subString, int startingPosition) const
 {
-	int pos = m_string.find (c, a);
+	int position = m_string.find (subString, startingPosition);
 
-	if (pos == int (std::string::npos))
+	if (position == int (std::string::npos))
 		return -1;
-
-	return pos;
+	else
+		return position;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-int String::find (char ch, int a) const
+/*!
+ * \brief Finds the first instance of a character.
+ * \param character Character to search within this string.
+ * \param startingPosition Position to start looking for the character from.
+ * \returns the position of the first instance of the provided character found, or -1 if not found.
+ */
+int String::find (char character, int startingPosition) const
 {
-	int pos = m_string.find (ch, a);
+	int position = m_string.find (character, startingPosition);
 
-	if (pos == int (std::string::npos))
+	if (position == int (std::string::npos))
 		return -1;
-
-	return pos;
+	else
+		return position;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-int String::findLast (const char* c, int a) const
+/*!
+ * \brief Finds the last instance of a sub-string.
+ * \param subString Sub-string to search within this string.
+ * \param startingPosition Position to start looking for the sub-string from.
+ * \returns the position the last instance of sub-string found, or -1 if not found.
+ */
+int String::findLast (const char* subString, int startingPosition) const
 {
-	if (a == -1 or a >= length())
-		a = length() - 1;
+	modifyIndex(startingPosition);
 
-	for (; a > 0; a--)
-		if (m_string[a] == c[0] and strncmp (chars() + a, c, strlen (c)) == 0)
-			return a;
+	for (; startingPosition > 0; startingPosition--)
+	{
+		if (strncmp (chars() + startingPosition, subString, strlen (subString)) == 0)
+			return startingPosition;
+	}
 
 	return -1;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \brief Converts this string to an integer.
+ * \param ok An pointer to a boolean to store whether or not the conversion was successful.
+ *           If \c ok is \c NULL, the success state is not stored.
+ * \param base The base to interpret this string with.
+ * \returns the resulting integer.
+ */
 long String::toInt (bool* ok, int base) const
 {
 	errno = 0;
-	char* endptr;
-	long i = strtol (chars(), &endptr, base);
+	char* endPointer;
+	long result = strtol (chars(), &endPointer, base);
 
-	if (ok)
-		*ok = (errno == 0 and *endptr == '\0');
+	if (ok != nullptr)
+		*ok = (errno == 0 and *endPointer == '\0');
 
-	return i;
+	return result;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \brief Converts this string to a floating-point number.
+ * \param ok An pointer to a boolean to store whether or not the conversion was successful.
+ *           If \c ok is \c NULL, the success state is not stored.
+ * \returns the resulting floating-point number.
+ */
 float String::toFloat (bool* ok) const
 {
-	errno = 0;
-	char* endptr;
-	float i = (float) strtod (chars(), &endptr);
-
-	if (ok != nullptr)
-		*ok = (errno == 0 and *endptr == '\0');
-
-	return i;
+	return static_cast<float>(toDouble(ok));
 }
 
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \brief Converts this string to a double-precision floating-point number.
+ * \param ok An pointer to a boolean to store whether or not the conversion was successful.
+ *           If \c ok is \c NULL, the success state is not stored.
+ * \returns the resulting floating-point number.
+ */
 double String::toDouble (bool* ok) const
 {
 	errno = 0;
@@ -275,67 +299,89 @@
 	return i;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-String String::operator+ (const String& data) const
+/*!
+ * \brief Catenates this string with another string.
+ * \param text String to catenate to the end of this string.
+ * \returns the resulting string.
+ */
+String String::operator+ (const String& text) const
 {
 	String newString = *this;
-	newString.append (data);
+	newString.append (text);
+	return newString;
+}
+
+/*!
+ * \brief Catenates this string with another string.
+ * \param text String to catenate to the end of this string.
+ * \returns the resulting string.
+ */
+String String::operator+ (const char* text) const
+{
+	String newString = *this;
+	newString.append (text);
 	return newString;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-String String::operator+ (const char* data) const
+/*!
+ * \returns whether or not this string represents a number.
+ */
+bool String::isNumeric() const
 {
-	String newstr = *this;
-	newstr.append (data);
-	return newstr;
+	char* endPointer;
+	strtol (chars(), &endPointer, 10);
+	return (endPointer != nullptr) and (*endPointer != '\0');
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-bool String::isNumeric() const
-{
-	char* endptr;
-	strtol (chars(), &endptr, 10);
-	return not (endptr && *endptr);
-}
-
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \param other Sub-string to find from the end of this string.
+ * \return whether or not this string ends with the provided sub-string.
+ */
 bool String::endsWith (const String& other) const
 {
 	if (length() < other.length())
+	{
 		return false;
-
-	const int ofs = length() - other.length();
-	return strncmp (chars() + ofs, other.chars(), other.length()) == 0;
+	}
+	else
+	{
+		const int offset = length() - other.length();
+		return strncmp (chars() + offset, other.chars(), other.length()) == 0;
+	}
 }
 
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \param other Sub-string to find from the beginning of this string.
+ * \returns whether or not this string begins with the provided sub-string.
+ */
 bool String::startsWith (const String& other) const
 {
 	if (length() < other.length())
 		return false;
-
-	return strncmp (chars(), other.chars(), other.length()) == 0;
+	else
+		return strncmp (chars(), other.chars(), other.length()) == 0;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-void __cdecl String::sprintf (const char* fmtstr, ...)
+/*!
+ * \brief Formats this string using \c printf -like syntax.
+ * \param formatString Template string to use with formatting.
+ * \param ... Variadic arguments to use with formatting.
+ */
+void __cdecl String::sprintf (const char* formatString, ...)
 {
 	va_list args;
-	va_start (args, fmtstr);
-	this->vsprintf (fmtstr, args);
+	va_start (args, formatString);
+	this->vsprintf (formatString, args);
 	va_end (args);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-void String::vsprintf (const char* fmtstr, va_list args)
+/*!
+ * \brief Formats this string using \c vsnprintf, using the provided arguments. The buffer string will be repeatedly
+ *        allocated larger and larger until \c vsnprintf succeeds.
+ * \param formatString Template string to use with formatting.
+ * \param args Variadic arguments to use with formatting.
+ */
+void String::vsprintf (const char* formatString, va_list args)
 {
 	char* buf = nullptr;
 	int bufsize = 256;
@@ -346,22 +392,25 @@
 		delete[] buf;
 		buf = new char[bufsize];
 	}
-	while (vsnprintf (buf, bufsize, fmtstr, args) >= bufsize);
+	while (vsnprintf (buf, bufsize, formatString, args) >= bufsize);
 
 	m_string = buf;
 	delete[] buf;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-String StringList::join (const String& delim)
+/*!
+ * \brief Joins the elements of this string list into one longer string.
+ * \param delimeter The delimeter to place between the element strings.
+ * \returns the catenated string.
+ */
+String StringList::join (const String& delimeter)
 {
 	String result;
 
 	for (const String &item : container())
 	{
 		if (result.isEmpty() == false)
-			result += delim;
+			result += delimeter;
 
 		result += item;
 	}
@@ -369,8 +418,12 @@
 	return result;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \brief Tries to match this string against a mask pattern. In the pattern, '?' refers to one character, and '*' to
+ *        any number of characters.
+ * \param pattern The masking pattern to use for matching.
+ * \returns whether or not this string matches the provided pattern.
+ */
 bool String::maskAgainst (const String& pattern) const
 {
 	// Elevate to uppercase for case-insensitive matching
@@ -417,71 +470,93 @@
 	return true;
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-String String::fromNumber (short int a)
+/*!
+ * \brief Converts a short integer into a string.
+ * \param value The value to convert.
+ * \returns the resulting string.
+ */
+String String::fromNumber (short int value)
 {
-	char buf[32];
-	::sprintf (buf, "%d", a);
-	return String (buf);
+	char buffer[32];
+	::sprintf (buffer, "%d", value);
+	return String (buffer);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-String String::fromNumber (int a)
+/*!
+ * \brief Converts an integer into a string.
+ * \param value The value to convert.
+ * \returns the resulting string.
+ */
+String String::fromNumber (int value)
 {
-	char buf[32];
-	::sprintf (buf, "%d", a);
-	return String (buf);
+	char buffer[32];
+	::sprintf (buffer, "%d", value);
+	return String (buffer);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-String String::fromNumber (long int a)
+/*!
+ * \brief Converts a long integer into a string.
+ * \param value The value to convert.
+ * \returns the resulting string.
+ */
+String String::fromNumber (long int value)
 {
-	char buf[32];
-	::sprintf (buf, "%ld", a);
-	return String (buf);
+	char buffer[32];
+	::sprintf (buffer, "%ld", value);
+	return String (buffer);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-String String::fromNumber (unsigned short int a)
+/*!
+ * \brief Converts an unsigned short integer into a string.
+ * \param value The value to convert.
+ * \returns the resulting string.
+ */
+String String::fromNumber (unsigned short int value)
 {
-	char buf[32];
-	::sprintf (buf, "%u", a);
-	return String (buf);
+	char buffer[32];
+	::sprintf (buffer, "%u", value);
+	return String (buffer);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-String String::fromNumber (unsigned int a)
+/*!
+ * \brief Converts an unsigned integer into a string.
+ * \param value The value to convert.
+ * \returns the resulting string.
+ */
+String String::fromNumber (unsigned int value)
 {
-	char buf[32];
-	::sprintf (buf, "%u", a);
-	return String (buf);
+	char buffer[32];
+	::sprintf (buffer, "%u", value);
+	return String (buffer);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-String String::fromNumber (unsigned long int a)
+/*!
+ * \brief Converts an unsigned long integer into a string.
+ * \param value The value to convert.
+ * \returns the resulting string.
+ */
+String String::fromNumber (unsigned long int value)
 {
-	char buf[32];
-	::sprintf (buf, "%lu", a);
-	return String (buf);
+	char buffer[32];
+	::sprintf (buffer, "%lu", value);
+	return String (buffer);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
-String String::fromNumber (double a)
+/*!
+ * \brief Converts a double-precision floating point number into a string, using the "%f" format specifier.
+ * \param value The value to convert.
+ * \returns the resulting string.
+ */
+String String::fromNumber (double value)
 {
-	char buf[64];
-	::sprintf (buf, "%f", a);
-	return String (buf);
+	char buffer[64];
+	::sprintf (buffer, "%f", value);
+	return String (buffer);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \returns the MD5-checksum of this string.
+ */
 String String::md5() const
 {
 	char checksum[33];
@@ -490,8 +565,11 @@
 	return String (checksum);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \brief Removes leading and trailing whitespace from this string. Alternatively a custom filter can be used to strip
+ *        something else than whitespace.
+ * \param filter The filtering function to use.
+ */
 void String::normalize (int (*filter)(int))
 {
 	int a = 0;
@@ -509,8 +587,10 @@
 		m_string = m_string.substr (a, b - a + 1);
 }
 
-// -------------------------------------------------------------------------------------------------
-//
+/*!
+ * \returns a version of this string without leading or trailing whitespace. Alternatively a custom filter can be used
+ *          to strip something else than whitespace.
+ */
 String String::normalized (int (*filter)(int)) const
 {
 	String result = *this;
diff -r 81357dcd3da4 -r 12c93c4a137c sources/mystring.h
--- a/sources/mystring.h	Wed Jul 20 16:52:00 2016 +0300
+++ b/sources/mystring.h	Wed Jul 20 17:31:51 2016 +0300
@@ -56,25 +56,25 @@
 	ConstIterator               begin() const;
 	Iterator                    begin();
 	int                         compare(const String &other) const;
-	int                         count(char needle) const;
+	int                         count(char character) const;
 	const char*                 chars() const;
 	void                        clear();
 	ConstIterator               end() const;
 	Iterator                    end();
 	bool                        endsWith(const String &other) const;
-	int                         find(const char* c, int a = 0) const;
-	int                         find(char ch, int a = 0) const;
+	int                         find(const char* subString, int startingPosition = 0) const;
+	int                         find(char character, int startingPosition = 0) const;
 	int                         indexDifference(int a, int b);
 	void                        insert(int position, char character);
 	void                        insert(int position, const char* string);
 	bool                        isEmpty() const;
 	bool                        isNumeric() const;
 	void                        modifyIndex(int &a) const;
-	int                         findLast(const char*c, int a) const;
+	int                         findLast(const char* subString, int startingPosition = -1) const;
 	int                         length() const;
 	bool                        maskAgainst(const String &pattern) const;
 	String                      md5() const;
-	String                      mid(int a, int b) const;
+	String                      mid(int rangeBegin, int rangeEnd) const;
 	void                        normalize(int(*filter)(int) = &isspace);
 	String                      normalized(int(*filter)(int) = &isspace) const;
 	void                        prepend(String text);
@@ -82,23 +82,22 @@
 	void                        removeAt(int position);
 	void                        removeFromEnd(int length);
 	void                        removeFromStart(int length);
-	void                        replace(const char* a, const char* b);
+	void                        replace(const char* text, const char* replacement);
 	void                        replace(int position, int amount, const String &text);
 	String                      right(int length) const;
 	void                        shrinkToFit();
-	class StringList            split(const String &del) const;
-	class StringList            split(char del) const;
+	class StringList            split(const String &delimeter) const;
+	class StringList            split(char delimeter) const;
 	void __cdecl                sprintf(const char* fmtstr, ...);
 	bool                        startsWith(const String &other) const;
 	const std::string&          stdString() const;
-	String                      strip(char unwanted) const;
-	String                      strip(const List<char> &unwanted) const;
+	void                        strip(char unwanted);
+	void                        strip(const List<char> &unwanted);
 	double                      toDouble(bool* ok = nullptr) const;
 	float                       toFloat(bool* ok = nullptr) const;
 	long                        toInt(bool* ok = nullptr, int base = 10) const;
 	String                      toLowerCase() const;
 	String                      toUpperCase() const;
-	void                        trim(int n);
 	void                        vsprintf(const char* fmtstr, va_list args);
 
 	static String               fromNumber(short int a);
@@ -556,20 +555,20 @@
 /*!
  * \brief Constructs an empty string list.
  */
-StringList::StringList() {}
+inline StringList::StringList() {}
 
 /*!
  * \brief Constructs a string list containing \c numvalues empty strings.
  * \param numvalues Amount of empty strings to fill.
  */
-StringList::StringList(int numvalues) :
+inline StringList::StringList(int numvalues) :
 	List<String>(numvalues) {}
 
 /*!
  * \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) :
+inline StringList::StringList(const List<String>& other) :
 	List<String>(other) {}
 
 /*!