Author: mordante
Date: Sat Sep 20 11:44:18 2008
New Revision: 29574
URL: http://svn.gna.org/viewcvs/wesnoth?rev=29574&view=rev
Log:
Update doxygen comment style.
Modified:
trunk/src/serialization/string_utils.cpp
trunk/src/serialization/string_utils.hpp
Modified: trunk/src/serialization/string_utils.cpp
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/src/serialization/string_utils.cpp?rev=29574&r1=29573&r2=29574&view=diff
==============================================================================
--- trunk/src/serialization/string_utils.cpp (original)
+++ trunk/src/serialization/string_utils.cpp Sat Sep 20 11:44:18 2008
@@ -14,8 +14,10 @@
See the COPYING file for more details.
*/
-//! @file serialization/string_utils.cpp
-//! Various string-routines.
+/**
+ * @file serialization/string_utils.cpp
+ * Various string-routines.
+ */
#include "global.hpp"
@@ -148,7 +150,6 @@
return !portable_isspace(c);
}
-//! Remove whitespace from the front and back of the string 'str'.
std::string &strip(std::string &str)
{
// If all the string contains is whitespace,
@@ -163,7 +164,6 @@
return str;
}
-//! Removes character 'c' from the first and last position of the string 'str'.
std::string& strip_char(std::string &str, const char c) {
if (*str.begin() == c)
str.erase(str.begin(), str.begin() + 1);
@@ -207,25 +207,9 @@
return res;
}
-//! Splits a string based either on a separator where text within paranthesis
-//! is protected from splitting (Note that one can use the same character for
-//! both the left and right paranthesis. In this mode it usually makes only
-//! sense to have one character for the left and right paranthesis.)
-//! or if the separator == 0 it splits a string into an odd number of parts:
-//! - The part before the first '(',
-//! - the part between the first '('
-//! - and the matching right ')', etc ...
-//! and the remainder of the string.
-//! Note that this will find the first matching char in the left string
-//! and match against the corresponding char in the right string.
-//! In this mode, a correctly processed string should return with
-//! an odd number of elements to the vector and
-//! an empty elements are never removed as they are placeholders.
-//! hence REMOVE EMPTY only works for the separator split.
-//!
-//! parenthetical_split("a(b)c{d}e(f{g})h",0,"({",")}") should return
-//! a vector of <"a","b","c","d","e","f{g}","h">
-std::vector< std::string > paranthetical_split(std::string const &val, const
char separator, std::string const &left, std::string const &right,int flags)
+std::vector< std::string > paranthetical_split(std::string const &val,
+ const char separator, std::string const &left,
+ std::string const &right,int flags)
{
std::vector< std::string > res;
std::vector<char> part;
@@ -355,7 +339,6 @@
return value;
}
-//! Prepends a configurable set of characters with a backslash
std::string &escape(std::string &str, const std::string& special_chars)
{
std::string::size_type pos = 0;
@@ -369,16 +352,12 @@
return str;
}
-//! Prepend all special characters with a backslash.
-// Special characters are:
-// [EMAIL PROTECTED],\*=
std::string& escape(std::string& str)
{
static const std::string special_chars("[EMAIL PROTECTED],\\*=");
return escape(str, special_chars);
}
-//! Remove all escape characters (backslash)
std::string &unescape(std::string &str)
{
std::string::size_type pos = 0;
@@ -408,8 +387,6 @@
return ((c == '_') || (c == '-'));
}
-//! Check if the username is valid.
-//! (all alpha-numeric characters plus underscore and hyphen)
bool isvalid_username(const std::string& username) {
const size_t alnum = std::count_if(username.begin(), username.end(),
isalnum);
const size_t valid_char =
@@ -422,12 +399,6 @@
return true;
}
-//! Try to complete the last word of 'text' with the 'wordlist'.
-//! @param[in] 'text' Text where we try to complete the last word of.
-//! @param[out] 'text' Text with completed last word.
-//! @param[in] 'wordlist' A vector of strings to complete against.
-//! @param[out] 'wordlist' A vector of strings that matched 'text'.
-//! @return 'true' iff text is just one word (no spaces)
bool word_completion(std::string& text, std::vector<std::string>& wordlist) {
std::vector<std::string> matches;
const size_t last_space = text.rfind(" ");
@@ -479,7 +450,6 @@
return (c == ' ' || c == ',' || c == ':' || c == '\'' || c == '"' || c
== '-');
}
-//! Check if a string contains a word.
bool word_match(const std::string& message, const std::string& word) {
size_t first = message.find(word);
if (first == std::string::npos) return false;
@@ -492,8 +462,6 @@
return false;
}
-//! Match using '*' as any number of characters (including none),
-//! and '?' as any one character.
bool wildcard_string_match(const std::string& str, const std::string& match) {
const bool wild_matching = (!match.empty() && match[0] == '*');
const std::string::size_type solid_begin = match.find_first_not_of('*');
@@ -541,13 +509,6 @@
return str.str();
}
-// This function is identical to split(), except it does not split
-// when it otherwise would if the previous character was identical to the
parameter 'quote'.
-// i.e. it does not split quoted commas.
-// This method was added to make it possible to quote user input,
-// particularly so commas in user input will not cause visual problems in
menus.
-//
-//! @todo Why not change split()? That would change the methods post condition.
std::vector< std::string > quoted_split(std::string const &val, char c, int
flags, char quote)
{
std::vector<std::string> res;
@@ -807,7 +768,7 @@
if(s.size() > 0) {
utf8_iterator itor(s);
#if defined(__APPLE__) || defined(__AMIGAOS4__)
- //! @todo FIXME: Should we support towupper on recent OSX
platforms?
+ /** @todo FIXME: Should we support towupper on recent OSX
platforms? */
wchar_t uchar = *itor;
if(uchar >= 0 && uchar < 0x100)
uchar = toupper(uchar);
@@ -829,7 +790,7 @@
for(;itor != utf8_iterator::end(s); ++itor) {
#if defined(__APPLE__) || defined(__AMIGAOS4__)
- //! @todo FIXME: Should we support towupper on recent
OSX platforms?
+ /** @todo FIXME: Should we support towupper on recent
OSX platforms? */
wchar_t uchar = *itor;
if(uchar >= 0 && uchar < 0x100)
uchar = toupper(uchar);
@@ -852,7 +813,7 @@
for(;itor != utf8_iterator::end(s); ++itor) {
#if defined(__APPLE__) || defined(__OpenBSD__) || defined(__AMIGAOS4__)
- //! @todo FIXME: Should we support towupper on recent
OSX platforms?
+ /** @todo FIXME: Should we support towupper on recent
OSX platforms? */
wchar_t uchar = *itor;
if(uchar >= 0 && uchar < 0x100)
uchar = tolower(uchar);
@@ -868,15 +829,6 @@
return s;
}
-//! Truncates a string.
-//!
-//! If the string send has more than size utf-8 characters it will be truncated
-//! to this size.
-//! No assumptions can be made about the actual size of the string.
-//!
-//! @param[in] str String which can be converted to utf-8.
-//! @param[out] str String which contains maximal size utf-8 characters.
-//! @param size The size to truncate at.
void truncate_as_wstring(std::string& str, const size_t size)
{
wide_string utf8_str = utils::string_to_wstring(str);
Modified: trunk/src/serialization/string_utils.hpp
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/src/serialization/string_utils.hpp?rev=29574&r1=29573&r2=29574&view=diff
==============================================================================
--- trunk/src/serialization/string_utils.hpp (original)
+++ trunk/src/serialization/string_utils.hpp Sat Sep 20 11:44:18 2008
@@ -13,8 +13,7 @@
See the COPYING file for more details.
*/
-//! @file serialization/string_utils.hpp
-//!
+/** @file serialization/string_utils.hpp. */
#ifndef SERIALIZATION_STRING_UTILS_HPP_INCLUDED
#define SERIALIZATION_STRING_UTILS_HPP_INCLUDED
@@ -34,10 +33,10 @@
virtual const t_string& get_variable_const(const std::string& id) const
= 0;
};
-//! The type we use to represent Unicode strings.
+/** The type we use to represent Unicode strings. */
typedef std::vector<wchar_t> wide_string;
-// If we append a 0 to that one,
-// we can pass it to SDL_ttf as a const Uint16*
+
+/** If we append a 0 to that one, we can pass it to SDL_ttf as a const
Uint16*. */
typedef std::vector<Uint16> ucs2_string;
typedef std::vector<Uint32> ucs4_string;
typedef std::string utf8_string;
@@ -48,47 +47,118 @@
bool portable_isspace(const char c);
bool notspace(char c);
-enum { REMOVE_EMPTY = 0x01, //!< REMOVE_EMPTY : remove empty elements
- STRIP_SPACES = 0x02 //!< STRIP_SPACES : strips leading and trailing
blank spaces
+enum { REMOVE_EMPTY = 0x01, /**< REMOVE_EMPTY : remove empty elements. */
+ STRIP_SPACES = 0x02 /**< STRIP_SPACES : strips leading and trailing
blank spaces. */
};
std::vector< std::string > split(std::string const &val, char c = ',', int
flags = REMOVE_EMPTY | STRIP_SPACES);
-std::vector< std::string > paranthetical_split(std::string const &val, const
char separator = 0 , std::string const &left="(", std::string const
&right=")",int flags = REMOVE_EMPTY | STRIP_SPACES);
+
+/**
+ * Splits a string based either on a separator where text within paranthesis
+ * is protected from splitting (Note that one can use the same character for
+ * both the left and right paranthesis. In this mode it usually makes only
+ * sense to have one character for the left and right paranthesis.)
+ * or if the separator == 0 it splits a string into an odd number of parts:
+ * - The part before the first '(',
+ * - the part between the first '('
+ * - and the matching right ')', etc ...
+ * and the remainder of the string.
+ * Note that this will find the first matching char in the left string
+ * and match against the corresponding char in the right string.
+ * In this mode, a correctly processed string should return with
+ * an odd number of elements to the vector and
+ * an empty elements are never removed as they are placeholders.
+ * hence REMOVE EMPTY only works for the separator split.
+ *
+ * parenthetical_split("a(b)c{d}e(f{g})h",0,"({",")}") should return
+ * a vector of <"a","b","c","d","e","f{g}","h">
+ */
+std::vector< std::string > paranthetical_split(std::string const &val,
+ const char separator = 0 , std::string const &left="(",
+ std::string const &right=")",int flags = REMOVE_EMPTY | STRIP_SPACES);
+
std::string join(std::vector< std::string > const &v, char c = ',');
+
+/**
+ * This function is identical to split(), except it does not split
+ * when it otherwise would if the previous character was identical to the
parameter 'quote'.
+ * i.e. it does not split quoted commas.
+ * This method was added to make it possible to quote user input,
+ * particularly so commas in user input will not cause visual problems in
menus.
+ *
+ * @todo Why not change split()? That would change the methods post condition.
+ */
std::vector< std::string > quoted_split(std::string const &val, char c= ',',
int flags = REMOVE_EMPTY |
STRIP_SPACES, char quote = '\\');
std::pair< int, int > parse_range(std::string const &str);
std::vector< std::pair< int, int > > parse_ranges(std::string const &str);
int apply_modifier( const int number, const std::string &amount, const int
minimum = 0);
+
+/** Prepends a configurable set of characters with a backslash */
std::string &escape(std::string &str, const std::string& special_chars);
+
+/**
+ * Prepend all special characters with a backslash.
+ *
+ * Special characters are:
+ * [EMAIL PROTECTED],\*=
+ */
std::string &escape(std::string &str);
+
+/** Remove all escape characters (backslash) */
std::string &unescape(std::string &str);
-//! Remove whitespace from the front and back of the string 'str'.
+
+/** Remove whitespace from the front and back of the string 'str'. */
std::string &strip(std::string &str);
-//! Removes character 'c' from the first and last position of the string 'str'.
+
+/** Removes character 'c' from the first and last position of the string
'str'. */
std::string& strip_char(std::string &str, const char c);
-//! Convert no, false, off, 0, 0.0 to false, empty to def, and others to true
+
+/** Convert no, false, off, 0, 0.0 to false, empty to def, and others to true
*/
bool string_bool(const std::string& str,bool def=false);
-//! Try to complete the last word of 'text' with the 'wordlist'.
+/**
+ * Try to complete the last word of 'text' with the 'wordlist'.
+ *
+ * @param[in] 'text' Text where we try to complete the last word of.
+ * @param[out] 'text' Text with completed last word.
+ * @param[in] 'wordlist' A vector of strings to complete against.
+ * @param[out] 'wordlist' A vector of strings that matched 'text'.
+ *
+ * @return 'true' iff text is just one word (no spaces)
+ */
bool word_completion(std::string& text, std::vector<std::string>& wordlist);
-//! Check if a message contains a word.
+
+/** Check if a message contains a word. */
bool word_match(const std::string& message, const std::string& word);
-//! Match using '*' as any number of characters (including none),
-//! and '?' as any one character.
+
+/**
+ * Match using '*' as any number of characters (including none), and '?' as any
+ * one character.
+ */
bool wildcard_string_match(const std::string& str, const std::string& match);
-//! Check if the username contains only valid characters.
+
+/**
+ * Check if the username contains only valid characters.
+ *
+ * (all alpha-numeric characters plus underscore and hyphen)
+ */
bool isvalid_username(const std::string &login);
typedef std::map< std::string, t_string > string_map;
-//! Function which will interpolate variables, starting with '$' in the string
'str'
-//! with the equivalent symbols in the given symbol table.
-//! If 'symbols' is NULL, then game event variables will be used instead.
+
+/**
+ * Function which will interpolate variables, starting with '$' in the string
+ * 'str' with the equivalent symbols in the given symbol table. If 'symbols'
+ * is NULL, then game event variables will be used instead.
+ */
std::string interpolate_variables_into_string(const std::string &str, const
string_map * const symbols);
std::string interpolate_variables_into_string(const std::string &str, const
variable_set& variables);
-//! Functions for converting Unicode wide-char strings
-//! to UTF-8 encoded strings, back and forth
+/**
+ * Functions for converting Unicode wide-char strings to UTF-8 encoded strings,
+ * back and forth.
+ */
class invalid_utf8_exception : public std::exception {
};
@@ -125,19 +195,31 @@
wide_string string_to_wstring(const std::string &);
std::string wchar_to_string(const wchar_t);
-//! Returns a version of the string with the first letter capitalized
+/** Returns a version of the string with the first letter capitalized. */
utf8_string capitalize(const utf8_string&);
-//! Returns an uppercased version of the string
+
+/** Returns an uppercased version of the string. */
utf8_string uppercase(const utf8_string&);
-//! Returns a lowercased version of the string
+
+/** Returns a lowercased version of the string. */
utf8_string lowercase(const utf8_string&);
-//! Truncates a string.
+/**
+ * Truncates a string.
+ *
+ * If the string send has more than size utf-8 characters it will be truncated
+ * to this size.
+ * No assumptions can be made about the actual size of the string.
+ *
+ * @param[in] str String which can be converted to utf-8.
+ * @param[out] str String which contains maximal size utf-8 characters.
+ * @param size The size to truncate at.
+ */
void truncate_as_wstring(std::string& str, const size_t size);
}
-// Handy wrappers around interpolate_variables_into_string and gettext
+/** Handy wrappers around interpolate_variables_into_string and gettext. */
std::string vgettext(const char*, const utils::string_map&);
std::string vngettext(const char*, const char*, int, const utils::string_map&);
_______________________________________________
Wesnoth-commits mailing list
[email protected]
https://mail.gna.org/listinfo/wesnoth-commits
