update documentation of string algos

alib2algo/src/string/generate/RandomStringFactory.cpp

@@ -29,7 +29,14 @@ string::LinearString < std::string > RandomStringFactory::generateLinearString (
 	return string::LinearString < std::string > ( elems );
 }
-auto GenerateLinearString1 = registration::AbstractRegister < RandomStringFactory, string::LinearString < std::string >, size_t, size_t, bool, bool > ( RandomStringFactory::generateLinearString, abstraction::AlgorithmCategories::AlgorithmCategory::DEFAULT, "size", "alphabetSize", "randomizedAlphabet", "integerSymbols" );
+auto GenerateLinearString1 = registration::AbstractRegister < RandomStringFactory, string::LinearString < std::string >, size_t, size_t, bool, bool > ( RandomStringFactory::generateLinearString, abstraction::AlgorithmCategories::AlgorithmCategory::DEFAULT, "size", "alphabetSize", "randomizedAlphabet", "integerSymbols" ).setDocumentation (
+"Generates a random string of given size.\n\
+\n\
+@param size the length of the generated string\n\
+@param alphabetSize size of the alphabet (1-26 for characters and 0-INT_MAX for integers)\n\
+@param randomizedAlphabet selects random symbols from a-z range if true\n\
+@param integerSymbols use integers as symbols in the generated string is true, randomize alphabet is not used if integer alphabet is requested\n\
+@return random string" );
 string::LinearString < std::string > RandomStringFactory::generateLinearString ( size_t size, size_t alphabetSize, bool randomizedAlphabet ) {
 	if ( alphabetSize > 26 )
@@ -50,9 +57,20 @@ string::LinearString < std::string > RandomStringFactory::generateLinearString (
 	return RandomStringFactory::generateLinearString ( size, alphabet );
 }
-auto GenerateLinearString2 = registration::AbstractRegister < RandomStringFactory, string::LinearString < std::string >, size_t, size_t, bool > ( RandomStringFactory::generateLinearString, abstraction::AlgorithmCategories::AlgorithmCategory::DEFAULT, "size", "alphabetSize", "randomizedAlphabet" );
-
-auto GenerateLinearString3 = registration::AbstractRegister < RandomStringFactory, string::LinearString < >, size_t, ext::set < DefaultSymbolType > > ( RandomStringFactory::generateLinearString, abstraction::AlgorithmCategories::AlgorithmCategory::DEFAULT, "size", "alphabet" );
+auto GenerateLinearString2 = registration::AbstractRegister < RandomStringFactory, string::LinearString < std::string >, size_t, size_t, bool > ( RandomStringFactory::generateLinearString, abstraction::AlgorithmCategories::AlgorithmCategory::DEFAULT, "size", "alphabetSize", "randomizedAlphabet" ).setDocumentation (
+"Generates a random string of given size.\n\
+\n\
+@param size the length of the generated string\n\
+@param alphabetSize size of the alphabet (1-26 for characters)\n\
+@param randomizedAlphabet selects random symbols from a-z range if true\n\
+@return random string" );
+
+auto GenerateLinearString3 = registration::AbstractRegister < RandomStringFactory, string::LinearString < >, size_t, ext::set < DefaultSymbolType > > ( RandomStringFactory::generateLinearString, abstraction::AlgorithmCategories::AlgorithmCategory::DEFAULT, "size", "alphabet" ).setDocumentation (
+"Generates a random string of given size\n\
+\n\
+@param size the length of the generated string\n\
+@param alphabet alphabet of the generated string\n\
+@return random string" );
 } /* namespace generate */

alib2algo/src/string/generate/RandomSubstringFactory.cpp

@@ -12,7 +12,12 @@ namespace string {
 namespace generate {
-auto RandomSubstringFactoryLinearString = registration::AbstractRegister < RandomSubstringFactory, string::LinearString < >, size_t, const string::LinearString < > & > ( RandomSubstringFactory::generateSubstring );
+auto RandomSubstringFactoryLinearString = registration::AbstractRegister < RandomSubstringFactory, string::LinearString < >, size_t, const string::LinearString < > & > ( RandomSubstringFactory::generateSubstring, "size", "string" ).setDocumentation (
+"Generates a random substring of a given size from a string.\n\
+\n\
+@param size the length of generated substring\n\
+@param string the source string of the substring\n\
+@return a substring of the @p string" );
 } /* namespace generate */

alib2algo/src/string/generate/RandomSubstringFactory.h

@@ -18,10 +18,24 @@ namespace string {
 namespace generate {
+/**
+ * Generates a radnom substring of given size from a string.
+ *
+ */
 class RandomSubstringFactory {
 public:
+	/**
+	 * Generates a random substring of a given size from a string.
+	 *
+	 * \tparam SymbolType the type of symbols in the string
+	 *
+	 * \param size the length of generated substring
+	 * \param string the source string of the substring
+	 *
+	 * \return a substring of the @p string
+	 */
 	template < class SymbolType >
-	static string::LinearString < SymbolType > generateSubstring ( size_t size, const string::LinearString < SymbolType > & );
+	static string::LinearString < SymbolType > generateSubstring ( size_t size, const string::LinearString < SymbolType > & string );
 };

alib2algo/src/string/naive/ExactCompare.cpp

@@ -11,9 +11,26 @@ namespace string {
 namespace naive {
-auto ExactCompareEpsilon = registration::AbstractRegister < ExactCompare, int, const string::Epsilon < > &, const string::Epsilon < > & > ( ExactCompare::compare );
-auto ExactCompareLinearString = registration::AbstractRegister < ExactCompare, int, const string::LinearString < > &, const string::LinearString < > & > ( ExactCompare::compare );
-auto ExactCompareCyclicString = registration::AbstractRegister < ExactCompare, int, const string::CyclicString < > &, const string::CyclicString < > & > ( ExactCompare::compare );
+auto ExactCompareEpsilon = registration::AbstractRegister < ExactCompare, int, const string::Epsilon < > &, const string::Epsilon < > & > ( ExactCompare::compare, "u", "v" ).setDocumentation (
+"Implementation of exact comparison of strings.\n\
+\n\
+@param u the first string to compare\n\
+@param v the second string to compare\n\
+@return zero as epsilons are equal" );
+
+auto ExactCompareLinearString = registration::AbstractRegister < ExactCompare, int, const string::LinearString < > &, const string::LinearString < > & > ( ExactCompare::compare, "u", "v" ).setDocumentation (
+"Implementation of exact comparison of strings.\n\
+\n\
+@param u the first string to compare\n\
+@param v the second string to compare\n\
+@return negative value if u compares smaller than v, positive value if u compares bigger than v, zero if u and v are equal" );
+
+auto ExactCompareCyclicString = registration::AbstractRegister < ExactCompare, int, const string::CyclicString < > &, const string::CyclicString < > & > ( ExactCompare::compare, "u", "v" ).setDocumentation (
+"Implementation of exact comparison of strings without taking rotation into account.\n\
+\n\
+@param u the first string to compare\n\
+@param v the second string to compare\n\
+@return negative value if u compares smaller than v, positive value if u compares bigger than v, zero if u and v are equal" );
 } /* namespace naive */

alib2algo/src/string/naive/ExactCompare.h

@@ -16,12 +16,48 @@ namespace string {
 namespace naive {
+/**
+ * Implements exact comparison of string contents.
+ *
+ */
 class ExactCompare {
 public:
+	/**
+	 * Implementation of exact comparison of strings.
+	 *
+	 * \tparam SymbolType the of symbols in the string
+	 *
+	 * \param u the first string to compare
+	 * \param v the second string to compare
+	 *
+	 * \return zero as epsilons are equal
+	 */
 	template < class SymbolType >
 	static int compare(const string::Epsilon < SymbolType >& u, const string::Epsilon < SymbolType >& v);
+
+	/**
+	 * Implementation of exact comparison of strings.
+	 *
+	 * \tparam SymbolType the of symbols in the string
+	 *
+	 * \param u the first string to compare
+	 * \param v the second string to compare
+	 *
+	 * \return negative value if u compares smaller than v, positive value if u compares bigger than v, zero if u and v are equal
+	 */
 	template < class SymbolType >
 	static int compare(const string::LinearString < SymbolType >& u, const string::LinearString < SymbolType >& v);
+
+	/**
+	 * Implementation of exact comparison of strings. The algorithm also handles rotated strings.
+	 *
+	 * \tparam SymbolType the of symbols in the string
+	 *
+	 * \param u the first string to compare
+	 * \param v the second string to compare
+	 *
+	 * \return negative value if u compares smaller than v, positive value if u compares bigger than v, zero if u and v are equal
+	 */
 	template < class SymbolType >
 	static int compare(const string::CyclicString < SymbolType >& u, const string::CyclicString < SymbolType >& v);
 };

alib2algo/src/string/naive/ExactEqual.cpp

@@ -11,9 +11,26 @@ namespace string {
 namespace naive {
-auto ExactEqualEpsilon = registration::AbstractRegister < ExactEqual, bool, const string::Epsilon < > &, const string::Epsilon < > & > ( ExactEqual::equals );
-auto ExactEqualLinearString = registration::AbstractRegister < ExactEqual, bool, const string::LinearString < > &, const string::LinearString < > & > ( ExactEqual::equals );
-auto ExactEqualCyclicString = registration::AbstractRegister < ExactEqual, bool, const string::CyclicString < > &, const string::CyclicString < > & > ( ExactEqual::equals );
+auto ExactEqualEpsilon = registration::AbstractRegister < ExactEqual, bool, const string::Epsilon < > &, const string::Epsilon < > & > ( ExactEqual::equals, "u", "v" ).setDocumentation (
+"Implements exact equality test of string contents.\n\
+\n\
+@param u the first string to compare\n\
+@param v the second string to compare\n\
+@return true as epsilons are equal" );
+
+auto ExactEqualLinearString = registration::AbstractRegister < ExactEqual, bool, const string::LinearString < > &, const string::LinearString < > & > ( ExactEqual::equals, "u", "v" ).setDocumentation (
+"Implements exact equality test of string contents.\n\
+\n\
+@param u the first string to compare\n\
+@param v the second string to compare\n\
+@return true if strings are equal, false othervise" );
+
+auto ExactEqualCyclicString = registration::AbstractRegister < ExactEqual, bool, const string::CyclicString < > &, const string::CyclicString < > & > ( ExactEqual::equals, "u", "v" ).setDocumentation (
+"Implements exact equality test of string contens. The algorithm handles rotations of strings.\n\
+\n\
+@param u the first string to compare\n\
+@param v the second string to compare\n\
+@return true if strings are equal in some rotation, false othervise" );
 } /* namespace naive */

alib2algo/src/string/naive/ExactEqual.h

@@ -16,12 +16,48 @@ namespace string {
 namespace naive {
+/**
+ * Implements exact equality test of string contents.
+ *
+ */
 class ExactEqual {
 public:
+	/**
+	 * Implements exact equality test of string contents.
+	 *
+	 * \tparam SymbolType the of symbols in the string
+	 *
+	 * \param u the first string to compare
+	 * \param v the second string to compare
+	 *
+	 * \return true as epsilons are equal
+	 */
 	template < class SymbolType >
 	static bool equals(const string::Epsilon < SymbolType >& u, const string::Epsilon < SymbolType >& v);
+
+	/**
+	 * Implements exact equality test of string contents.
+	 *
+	 * \tparam SymbolType the of symbols in the string
+	 *
+	 * \param u the first string to compare
+	 * \param v the second string to compare
+	 *
+	 * \return true if strings are equal, false othervise
+	 */
 	template < class SymbolType >
 	static bool equals(const string::LinearString < SymbolType >& u, const string::LinearString < SymbolType >& v);
+
+	/**
+	 * Implements exact equality test of string contens. The algorithm handles rotations of strings.
+	 *
+	 * \tparam SymbolType the of symbols in the string
+	 *
+	 * \param u the first string to compare
+	 * \param v the second string to compare
+	 *
+	 * \return true if strings are equal in some rotation, false othervise
+	 */
 	template < class SymbolType >
 	static bool equals(const string::CyclicString < SymbolType >& u, const string::CyclicString < SymbolType >& v);
 };

alib2algo/src/string/simplify/NormalizeAlphabet.cpp

@@ -12,7 +12,11 @@ namespace string {
 namespace simplify {
-auto NormalizeAlphabetLinearString = registration::AbstractRegister < NormalizeAlphabet, string::LinearString < >, const string::LinearString < > & > ( NormalizeAlphabet::normalize );
+auto NormalizeAlphabetLinearString = registration::AbstractRegister < NormalizeAlphabet, string::LinearString < std::string >, const string::LinearString < > & > ( NormalizeAlphabet::normalize, "str" ).setDocumentation (
+"Applies a homomorphism asigning characters 'a', 'b', ... to the first, second, ... occurring symbol in the string content.\n\
+\n\
+@param str the input string\n\
+@return the normalized string" );
 } /* namespace simplify */

alib2algo/src/string/simplify/NormalizeAlphabet.h

@@ -14,38 +14,44 @@ namespace string {
 namespace simplify {
+/**
+ * Applies a homomorphism asigning characters 'a', 'b', ... to the first, second, ... occurring symbol in the string content
+ */
 class NormalizeAlphabet {
 public:
 	/**
-	 * @param dfa automaton to normalize
+	 * Applies a homomorphism asigning characters 'a', 'b', ... to the first, second, ... occurring symbol in the string content.
+	 *
+	 * \tparam SymbolType the type of symbols in the string
+	 *
+	 * \param str the input string
+	 *
+	 * \return the normalized string
 	 */
 	template < class SymbolType >
-	static string::LinearString < SymbolType > normalize(const string::LinearString < SymbolType > & str);
+	static string::LinearString < std::string > normalize(const string::LinearString < SymbolType > & str);
 };
 template < class SymbolType >
-string::LinearString < SymbolType > NormalizeAlphabet::normalize(const string::LinearString < SymbolType > & string) {
-	int counter = 0;
-	ext::map<SymbolType, char > normalizationData;
-	for(const SymbolType& symbol : string.getContent()) {
-		if(normalizationData.find(symbol) == normalizationData.end()) {
-			normalizationData.insert(std::make_pair(symbol, counter++));
-		}
-	}
-	ext::set<SymbolType> alphabet;
+string::LinearString < std::string > NormalizeAlphabet::normalize(const string::LinearString < SymbolType > & string) {
+	char counter = 'a';
+	ext::map<SymbolType, std::string > normalizationData;
+	for(const SymbolType& symbol : string.getContent())
+		if(normalizationData.find(symbol) == normalizationData.end())
+			normalizationData.insert ( std::make_pair ( symbol, std::string ( 1, counter ++ ) ) );
+	ext::set < std::string > alphabet;
 	for(const auto& symbol : normalizationData) {
-		alphabet.insert(SymbolType((char) (symbol.second + 'a')));
+		alphabet.insert ( symbol.second );
 	}
-	ext::vector<SymbolType> data;
+	ext::vector < std::string > data;
 	for(const SymbolType& symbol : string.getContent()) {
-		data.push_back(SymbolType((char) (normalizationData.find(symbol)->second + 'a')));
+		data.push_back ( normalizationData.find(symbol)->second );
 	}
-	string::LinearString < > result(alphabet, data);
-	return result;
+	return string::LinearString < std::string > ( alphabet, data );
 }
 } /* namespace simplify */

alib2algo/src/string/simplify/NormalizeRotation.cpp

@@ -12,7 +12,13 @@ namespace string {
 namespace simplify {
-auto NormalizeRotationCyclicString = registration::AbstractRegister < NormalizeRotation, string::CyclicString < >, const string::CyclicString < > & > ( NormalizeRotation::normalize );
+auto NormalizeRotationCyclicString = registration::AbstractRegister < NormalizeRotation, string::CyclicString < >, const string::CyclicString < > & > ( NormalizeRotation::normalize, "string" ).setDocumentation (
+"Computes lexicographically least circular rotation,\n\
+based on Kellogg S. Booth 1979,\n\
+modified to working code by Ladislav Vagner\n\
+\n\
+@param string the rotated string\n\
+@return the @p string in its least lexicographical rotation" );
 } /* namespace simplify */

alib2algo/src/string/simplify/NormalizeRotation.h

@@ -14,11 +14,23 @@ namespace string {
 namespace simplify {
+/**
+ * Computes lexicographically least circular rotation,
+ * based on Kellogg S. Booth 1979,
+ * modified to working code by Ladislav Vagner
+ */
 class NormalizeRotation {
 public:
 	/**
-	 * Performs conversion.
-	 * @return left regular grammar equivalent to source automaton.
+	 * Computes lexicographically least circular rotation,
+	 * based on Kellogg S. Booth 1979,
+	 * modified to working code by Ladislav Vagner
+	 *
+	 * \tparam SymbolType the type of symbols in the rotated string.
+	 *
+	 * \param string the rotated string
+	 *
+	 * \return the @p string in its least lexicographical rotation
 	 */
 	template < class SymbolType >
 	static string::CyclicString < SymbolType > normalize(const string::CyclicString < SymbolType > & string);
@@ -26,13 +38,6 @@ public:
 template < class SymbolType >
 string::CyclicString < SymbolType > NormalizeRotation::normalize(const string::CyclicString < SymbolType > & string) {
-	/**
-	 * Lexicographically least circular substrings,
-	 * based on
-	 * Kellogg S. Booth
-	 * 1979,
-	 * modified to working code by Ladislav Vagner
-	 */
 	const ext::vector < SymbolType > & data = string.getContent ( );
 	int * f = new int [ 2 * data.size ( ) ]; /** Knuth–Morris–Pratt like array */
 	int k = 0; /** Least circular string shift value */