From 1704a0cb8ed091ce3fd5fa1770bf6ebab3baf67f Mon Sep 17 00:00:00 2001
From: Nina Dzugasova <dzugasova.nina@gmail.com>
Date: Wed, 24 Oct 2018 16:02:57 +0200
Subject: [PATCH] Altered documentation of String. Started with examples.
---
Doxyfile | 2 +-
src/TNL/String.h | 204 +++++++++++++++++++++++++++++++++--------------
2 files changed, 144 insertions(+), 62 deletions(-)
diff --git a/Doxyfile b/Doxyfile
index a796c7fe3c..649e477a43 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -906,7 +906,7 @@ EXCLUDE_SYMBOLS =
# that contain example code fragments that are included (see the \include
# command).
-EXAMPLE_PATH =
+EXAMPLE_PATH = src/Examples
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
diff --git a/src/TNL/String.h b/src/TNL/String.h
index 8ea736f295..20b065ba24 100644
--- a/src/TNL/String.h
+++ b/src/TNL/String.h
@@ -25,25 +25,38 @@ class String;
template< typename T >
String convertToString( const T& value );
-/////
-// Class for managing strings.
+
class String
{
public:
/////
- /// Basic constructor.
-
+ /// \brief Basic constructor.
+ ///
/// Constructs an empty string object with the length of zero characters.
+ /// \par Example
+ /// \include StringExample.cpp
+ /// \par Output
+ /// str1 = \n str2 =
String();
/////
- /// Constructor with char pointer.
-
+ /// \brief Constructor with char pointer.
+ ///
/// Copies the null-terminated character sequence (C-string) pointed by \e c.
- /// Constructs a string initialized with the 8-bit string \e c, excluding the given number of \e prefix_cut_off and \e sufix_cut_off characters.
- /// @param prefix_cut_off determines the length of the prefix that is going to be omitted from the string \e c
- /// @param sufix_cut_off determines the length of the sufix that is going to be omitted from the string \e c
+ /// Constructs a string initialized with the 8-bit string \e c, excluding
+ /// the given number of \e prefix_cut_off and \e sufix_cut_off characters.
+ ///
+ /// @param prefix_cut_off Determines the length of the prefix that is going
+ /// to be omitted from the string \e c.
+ /// @param sufix_cut_off Determines the length of the sufix that is going
+ /// to be omitted from the string \e c.
+ ///
+ /// \par Example
+ /// \code String str( "xxstringxxx", 2, 3 ); \endcode
+ ///
+ /// \par Output
+ /// str = string
String( const char* c,
int prefix_cut_off = 0,
int sufix_cut_off = 0 );
@@ -57,9 +70,17 @@ class String
static String getType();
/////
- /// Copy constructor.
-
+ /// \brief Copy constructor.
+ ///
/// Constructs a copy of the string \e str.
+ ///
+ /// \par Example
+ /// \code
+ String str1( "Something" );
+ String str2( str1 );
+ /// \endcode
+ /// \par Output
+ /// str1 = Something \n str2 = Something
String( const String& str );
/// Converts anything to a string.
@@ -70,7 +91,7 @@ class String
setString( convertToString( value ).getString() );
}
- /// Destructor.
+ /// \brief Destructor.
~String();
/// Returns the number of characters in given string. Equivalent to getSize().
@@ -82,116 +103,177 @@ class String
/// Returns size of allocated storage for given string.
int getAllocatedSize() const;
- /// Reserves space for given number of characters (\e size).
- /// Requests to allocate storage for given \e size (number of characters).
+ /////
+ /// Reserves space for given \e size.
+ /// Requests to allocate storage for given \e size.
+ /// @param size Number of characters.
void setSize( int size );
/////
- /// Sets string from given char pointer \e c.
- /// @param prefix_cut_off determines the length of the prefix that is going to be omitted from the string \e c
- /// @param sufix_cut_off determines the length of the sufix that is going to be omitted from the string \e c
+ /// \brief Sets string from given char pointer \e c.
+ ///
+ /// @param prefix_cut_off determines the length of the prefix that is
+ /// going to be omitted from the string \e c
+ /// @param sufix_cut_off determines the length of the sufix that is going
+ /// to be omitted from the string \e c
void setString( const char* c,
int prefix_cut_off = 0,
int sufix_cut_off = 0 );
- /// Returns pointer to data. It returns the content of the given string.
+ /////
+ /// \brief Returns pointer to data.
+ ///
+ /// It returns the content of the given string. The content can not be
+ /// changed by user.
const char* getString() const;
- /// Returns pointer to data.
+ /// \brief Returns pointer to data.
+ ///
+ /// It returns the content of the given string. The content can be changed
+ /// by user.
char* getString();
- /// Operator for accesing particular chars of the string.
-
- ///This function overloads operator[](). It returns a reference to the character at position \e i in given string.
+ /////
+ /// \brief Operator for accesing particular chars of the string.
+ ///
+ /// This function overloads operator[](). It returns a reference to
+ /// the character at position \e i in given string.
+ /// The character can not be changed be user.
const char& operator[]( int i ) const;
- /// Operator for accesing particular chars of the string.
-
- ///It returns the character at the position \e i in given string as a modifiable reference.
+ /// \brief Operator for accesing particular chars of the string.
+ ///
+ /// It returns the character at the position \e i in given string as
+ /// a modifiable reference.
char& operator[]( int i );
/////
- /// Operators for C strings.
+ // Operators for C strings.
- /// This function overloads operator=(). It assigns \e str to this string, replacing its current contents.
+ /// \brief This function overloads operator=().
+ ///
+ /// It assigns C string \e str to this string, replacing its current contents.
String& operator=( const char* str );
- /// This function overloads operator+=(). It appends the string \e str to this string.
+ /// \brief This function overloads operator+=().
+ ///
+ /// It appends the C string \e str to this string.
String& operator+=( const char* str );
- /// This function concatenates strings and returns a newly constructed string object.
+ /// \brief This function concatenates C strings \e str and returns a newly
+ /// constructed string object.
String operator+( const char* str ) const;
- /// This function overloads operator==().
+ /// \brief This function overloads operator==().
bool operator==( const char* str ) const;
- /// This function overloads operator!=().
+ /// \brief This function overloads operator!=().
bool operator!=( const char* str ) const;
/////
- /// Operators for Strings.
+ // Operators for Strings.
- /// This function assigns \e str to this string and returns a reference to this string.
+ /// This function assigns \e str to this string and returns a reference to
+ /// this string.
String& operator=( const String& str );
- /// This function appends the string \e str onto the end of this string and returns a reference to this string.
+ /// This function appends the string \e str onto the end of this string
+ /// and returns a reference to this string.
String& operator+=( const String& str );
- /// This function concatenates strings and returns a newly constructed string object.
+ /// This function concatenates strings \e str and returns a newly
+ /// constructed string object.
String operator+( const String& str ) const;
- /// This function overloads operator==(). It returns \c true if this string is equal to \e str, otherwise returns \c false.
+ /// \brief This function overloads operator==().
+ ///
+ /// It returns \c true if this string is equal to \e str, otherwise returns
+ /// \c false.
bool operator==( const String& str ) const;
- /// This function overloads operator!=(). It returns \c true if this string is not equal to \e str, otherwise returns \c false.
+ /// \brief This function overloads operator!=().
+ ///
+ /// It returns \c true if this string is not equal to \e str, otherwise
+ /// returns \c false.
bool operator!=( const String& str ) const;
/////
- /// Operators for single characters.
+ // Operators for single characters.
- /// This function overloads operator=(). It assigns character /e str to this string.
+ /// \brief This function overloads operator=().
+ ///
+ /// It assigns character /e str to this string.
String& operator=( char str );
- /// This function overloads operator+=(). It appends character /e str to this string.
+ /// \brief This function overloads operator+=().
+ ///
+ /// It appends character /e str to this string.
String& operator+=( char str );
// This function concatenates strings and returns a newly constructed string object.
String operator+( char str ) const;
// This function concatenates strings and returns a newly constructed string object.
bool operator==( char str ) const;
- /// This function overloads operator!=().
+ /// \brief This function overloads operator!=().
bool operator!=( char str ) const;
- /// Cast to bool operator.
-
- ///Converts string to boolean expression (true or false).
+ /// \brief Cast to bool operator.
+ ///
+ /// This function overloads operator bool(). It converts string to boolean
+ /// expression (true or false).
operator bool() const;
- /// Cast to bool with negation operator.
+ /// \brief Cast to bool with negation operator.
+ ///
+ /// This function overloads operator!(). It converts string to boolean
+ /// expression (false or true).
bool operator!() const;
/////
- /// Replaces portion of string.
-
- ///It replaces section \e pattern from this string with new piece of string \e replaceWith.
- ///If parameter \e count is defined, the function makes replacement several times, every time when it finds the same pattern in this string.
+ /// \brief Replaces portion of string.
+ ///
+ /// Replaces section \e pattern from this string with new piece of string \e replaceWith.
+ /// If parameter \e count is defined, the function makes replacement several times,
+ /// every time when it finds the same pattern in this string.
+ /// @param pattern Section of given string that will be replaced.
+ /// @param replaceWith New piece of string that will be used to replace \e pattern.
+ /// @param count A whole number that specifies how many replacements should be done.
String replace( const String& pattern,
const String& replaceWith,
int count = 0 ) const;
- /// Trims/strips given string.
-
- /// It removes all spaces from string except for single spaces between words.
+ /////
+ /// \brief Trims/strips given string.
+ ///
+ /// Removes all spaces from given string except for single spaces between words.
String strip( char strip = ' ' ) const;
- /// Splits string into list of strings with respect to given \e separator.
-
- /// It splits the string into list of substrings wherever \e separator occurs, and returs list of those strings.
- /// When \e separator does not appear anywhere in the given string, this function returns a single-element list containing given sting.
- /// @param separator Character, which separates substrings in given string. Empty character can not be used.
+ /// \brief Splits string into list of strings with respect to given \e separator.
+ ///
+ /// Splits the string into list of substrings wherever \e separator occurs,
+ /// and returs list of those strings. When \e separator does not appear
+ /// anywhere in the given string, this function returns a single-element list
+ /// containing given sting.
+ /// @param list Name of list.
+ /// @param separator Character, which separates substrings in given string.
+ /// Empty character can not be used.
int split( Containers::List< String >& list, const char separator = ' ' ) const;
- /// Writes to a binary file and returns boolean expression based on the success in writing into the file.
+ /////
+ /// \brief Function for saving file.
+ ///
+ /// Writes to a binary file and returns boolean expression based on the
+ /// success in writing into the file.
bool save( File& file ) const;
- /// Reads from binary file and returns boolean expression based on the success in reading the file.
+ /////
+ /// \brief Function for loading from file.
+ ///
+ /// Reads from binary file and returns boolean expression based on the
+ /// success in reading the file.
bool load( File& file );
+
// Mozem dat prec??? !!!!
// Broadcast to other nodes in MPI cluster
// void MPIBcast( int root, MPI_Comm mpi_comm = MPI_COMM_WORLD );
- /// Reads one line from given stream.
+
+ /////
+ /// \brief Function for getting a line from stream.
+ ///
+ /// Reads one line from given stream and returns either the line or boolean
+ /// expression based on the success in reading the line.
bool getLine( std::istream& stream );
///toto neviem co
@@ -201,7 +283,7 @@ class String
/// Pointer to char ended with zero ...Preco?
char* string;
- /// Length of the allocated piece of memory.
+ /// Length of allocated piece of memory.
int length;
};
--
GitLab