From 68937b3ff59d3e8de42cb77be0a33e4ec10784dd Mon Sep 17 00:00:00 2001
From: Jan Travnicek <Jan.Travnicek@fit.cvut.cz>
Date: Tue, 19 Feb 2019 14:19:35 +0100
Subject: [PATCH] update documentation of string algos
---
.../string/generate/RandomStringFactory.cpp | 26 +++++++++++--
.../generate/RandomSubstringFactory.cpp | 7 +++-
.../string/generate/RandomSubstringFactory.h | 16 +++++++-
alib2algo/src/string/naive/ExactCompare.cpp | 23 +++++++++--
alib2algo/src/string/naive/ExactCompare.h | 36 ++++++++++++++++++
alib2algo/src/string/naive/ExactEqual.cpp | 23 +++++++++--
alib2algo/src/string/naive/ExactEqual.h | 36 ++++++++++++++++++
.../src/string/simplify/NormalizeAlphabet.cpp | 6 ++-
.../src/string/simplify/NormalizeAlphabet.h | 38 +++++++++++--------
.../src/string/simplify/NormalizeRotation.cpp | 8 +++-
.../src/string/simplify/NormalizeRotation.h | 23 ++++++-----
11 files changed, 203 insertions(+), 39 deletions(-)
diff --git a/alib2algo/src/string/generate/RandomStringFactory.cpp b/alib2algo/src/string/generate/RandomStringFactory.cpp
index c2ed626b7a..a9414c0635 100644
--- a/alib2algo/src/string/generate/RandomStringFactory.cpp
+++ b/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 */
diff --git a/alib2algo/src/string/generate/RandomSubstringFactory.cpp b/alib2algo/src/string/generate/RandomSubstringFactory.cpp
index 68646544e5..9220febeec 100644
--- a/alib2algo/src/string/generate/RandomSubstringFactory.cpp
+++ b/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 */
diff --git a/alib2algo/src/string/generate/RandomSubstringFactory.h b/alib2algo/src/string/generate/RandomSubstringFactory.h
index e002e3086b..adb5a9f55b 100644
--- a/alib2algo/src/string/generate/RandomSubstringFactory.h
+++ b/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 );
};
diff --git a/alib2algo/src/string/naive/ExactCompare.cpp b/alib2algo/src/string/naive/ExactCompare.cpp
index 95ae5c853a..6012247067 100644
--- a/alib2algo/src/string/naive/ExactCompare.cpp
+++ b/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 */
diff --git a/alib2algo/src/string/naive/ExactCompare.h b/alib2algo/src/string/naive/ExactCompare.h
index 42abccc91e..6f263b9cd3 100644
--- a/alib2algo/src/string/naive/ExactCompare.h
+++ b/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);
};
diff --git a/alib2algo/src/string/naive/ExactEqual.cpp b/alib2algo/src/string/naive/ExactEqual.cpp
index 44bdbd9af0..682d3639f3 100644
--- a/alib2algo/src/string/naive/ExactEqual.cpp
+++ b/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 */
diff --git a/alib2algo/src/string/naive/ExactEqual.h b/alib2algo/src/string/naive/ExactEqual.h
index 3fa4db0025..f22eb8a042 100644
--- a/alib2algo/src/string/naive/ExactEqual.h
+++ b/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);
};
diff --git a/alib2algo/src/string/simplify/NormalizeAlphabet.cpp b/alib2algo/src/string/simplify/NormalizeAlphabet.cpp
index 62ed204c56..8058ef3cc3 100644
--- a/alib2algo/src/string/simplify/NormalizeAlphabet.cpp
+++ b/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 */
diff --git a/alib2algo/src/string/simplify/NormalizeAlphabet.h b/alib2algo/src/string/simplify/NormalizeAlphabet.h
index 458d7c99f1..f3876203bd 100644
--- a/alib2algo/src/string/simplify/NormalizeAlphabet.h
+++ b/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;
+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, counter++));
- }
- }
+ for(const SymbolType& symbol : string.getContent())
+ if(normalizationData.find(symbol) == normalizationData.end())
+ normalizationData.insert ( std::make_pair ( symbol, std::string ( 1, counter ++ ) ) );
- ext::set<SymbolType> alphabet;
+ 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 */
diff --git a/alib2algo/src/string/simplify/NormalizeRotation.cpp b/alib2algo/src/string/simplify/NormalizeRotation.cpp
index d5d992b6ef..29c90120ad 100644
--- a/alib2algo/src/string/simplify/NormalizeRotation.cpp
+++ b/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 */
diff --git a/alib2algo/src/string/simplify/NormalizeRotation.h b/alib2algo/src/string/simplify/NormalizeRotation.h
index 57c618f981..b2627d236f 100644
--- a/alib2algo/src/string/simplify/NormalizeRotation.h
+++ b/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 */
--
GitLab