mirror of
https://bitbucket.org/chromiumembedded/cef
synced 2025-06-05 21:39:12 +02:00
Update include/ comments to Doxygen formatting (see issue #3384)
See related guidelines in the issue.
This commit is contained in:
Marshall Greenblatt
@ -41,7 +41,7 @@
|
||||
#endif
|
||||
|
||||
///
|
||||
// Traits implementation for wide character strings.
|
||||
/// Traits implementation for wide character strings.
|
||||
///
|
||||
struct CefStringTraitsWide {
|
||||
typedef wchar_t char_type;
|
||||
@ -139,7 +139,7 @@ struct CefStringTraitsWide {
|
||||
};
|
||||
|
||||
///
|
||||
// Traits implementation for utf8 character strings.
|
||||
/// Traits implementation for utf8 character strings.
|
||||
///
|
||||
struct CefStringTraitsUTF8 {
|
||||
typedef char char_type;
|
||||
@ -222,7 +222,7 @@ struct CefStringTraitsUTF8 {
|
||||
};
|
||||
|
||||
///
|
||||
// Traits implementation for utf16 character strings.
|
||||
/// Traits implementation for utf16 character strings.
|
||||
///
|
||||
struct CefStringTraitsUTF16 {
|
||||
typedef char16 char_type;
|
||||
@ -315,32 +315,35 @@ struct CefStringTraitsUTF16 {
|
||||
};
|
||||
|
||||
///
|
||||
// CEF string classes can convert between all supported string types. For
|
||||
// example, the CefStringWide class uses wchar_t as the underlying character
|
||||
// type and provides two approaches for converting data to/from a UTF8 string
|
||||
// (std::string).
|
||||
// <p>
|
||||
// 1. Implicit conversion using the assignment operator overload.
|
||||
// <pre>
|
||||
// CefStringWide aCefString;
|
||||
// std::string aUTF8String;
|
||||
// aCefString = aUTF8String; // Assign std::string to CefStringWide
|
||||
// aUTF8String = aCefString; // Assign CefStringWide to std::string
|
||||
// </pre>
|
||||
// 2. Explicit conversion using the FromString/ToString methods.
|
||||
// <pre>
|
||||
// CefStringWide aCefString;
|
||||
// std::string aUTF8String;
|
||||
// aCefString.FromString(aUTF8String); // Assign std::string to CefStringWide
|
||||
// aUTF8String = aCefString.ToString(); // Assign CefStringWide to std::string
|
||||
// </pre>
|
||||
// Conversion will only occur if the assigned value is a different string type.
|
||||
// Assigning a std::string to a CefStringUTF8, for example, will copy the data
|
||||
// without performing a conversion.
|
||||
// </p>
|
||||
// CEF string classes are safe for reading from multiple threads but not for
|
||||
// modification. It is the user's responsibility to provide synchronization if
|
||||
// modifying CEF strings from multiple threads.
|
||||
/// CEF string classes can convert between all supported string types. For
|
||||
/// example, the CefStringWide class uses wchar_t as the underlying character
|
||||
/// type and provides two approaches for converting data to/from a UTF8 string
|
||||
/// (std::string).
|
||||
///
|
||||
/// 1. Implicit conversion using the assignment operator overload.
|
||||
/// <pre>
|
||||
/// CefStringWide aCefString;
|
||||
/// std::string aUTF8String;
|
||||
/// aCefString = aUTF8String; // Assign std::string to CefStringWide
|
||||
/// aUTF8String = aCefString; // Assign CefStringWide to std::string
|
||||
/// </pre>
|
||||
///
|
||||
/// 2. Explicit conversion using the FromString/ToString methods.
|
||||
/// <pre>
|
||||
/// CefStringWide aCefString;
|
||||
/// std::string aUTF8String;
|
||||
/// aCefString.FromString(aUTF8String); // Assign std::string to CefStringWide
|
||||
/// aUTF8String = aCefString.ToString(); // Assign CefStringWide to
|
||||
/// std::string
|
||||
/// </pre>
|
||||
///
|
||||
/// Conversion will only occur if the assigned value is a different string type.
|
||||
/// Assigning a std::string to a CefStringUTF8, for example, will copy the data
|
||||
/// without performing a conversion.
|
||||
///
|
||||
/// CEF string classes are safe for reading from multiple threads but not for
|
||||
/// modification. It is the user's responsibility to provide synchronization if
|
||||
/// modifying CEF strings from multiple threads.
|
||||
///
|
||||
template <class traits>
|
||||
class CefStringBase {
|
||||
@ -350,21 +353,21 @@ class CefStringBase {
|
||||
typedef typename traits::userfree_struct_type userfree_struct_type;
|
||||
|
||||
///
|
||||
// Default constructor.
|
||||
/// Default constructor.
|
||||
///
|
||||
CefStringBase() : string_(NULL), owner_(false) {}
|
||||
|
||||
///
|
||||
// Create a new string from an existing string. Data will always be copied.
|
||||
/// Create a new string from an existing string. Data will always be copied.
|
||||
///
|
||||
CefStringBase(const CefStringBase& str) : string_(NULL), owner_(false) {
|
||||
FromString(str.c_str(), str.length(), true);
|
||||
}
|
||||
|
||||
///
|
||||
// Create a new string from an existing std::string. Data will be always
|
||||
// copied. Translation will occur if necessary based on the underlying string
|
||||
// type.
|
||||
/// Create a new string from an existing std::string. Data will be always
|
||||
/// copied. Translation will occur if necessary based on the underlying string
|
||||
/// type.
|
||||
///
|
||||
CefStringBase(const std::string& src) : string_(NULL), owner_(false) {
|
||||
FromString(src);
|
||||
@ -376,9 +379,9 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Create a new string from an existing std::wstring. Data will be always
|
||||
// copied. Translation will occur if necessary based on the underlying string
|
||||
// type.
|
||||
/// Create a new string from an existing std::wstring. Data will be always
|
||||
/// copied. Translation will occur if necessary based on the underlying string
|
||||
/// type.
|
||||
///
|
||||
CefStringBase(const std::wstring& src) : string_(NULL), owner_(false) {
|
||||
FromWString(src);
|
||||
@ -390,9 +393,9 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Create a new string from an existing string16. Data will be always
|
||||
// copied. Translation will occur if necessary based on the underlying string
|
||||
// type.
|
||||
/// Create a new string from an existing string16. Data will be always
|
||||
/// copied. Translation will occur if necessary based on the underlying string
|
||||
/// type.
|
||||
///
|
||||
CefStringBase(const std::u16string& src) : string_(NULL), owner_(false) {
|
||||
FromString16(src);
|
||||
@ -413,10 +416,10 @@ class CefStringBase {
|
||||
#endif // WCHAR_T_IS_UTF32
|
||||
|
||||
///
|
||||
// Create a new string from an existing character array. If |copy| is true
|
||||
// this class will copy the data. Otherwise, this class will reference the
|
||||
// existing data. Referenced data must exist for the lifetime of this class
|
||||
// and will not be freed by this class.
|
||||
/// Create a new string from an existing character array. If |copy| is true
|
||||
/// this class will copy the data. Otherwise, this class will reference the
|
||||
/// existing data. Referenced data must exist for the lifetime of this class
|
||||
/// and will not be freed by this class.
|
||||
///
|
||||
CefStringBase(const char_type* src, size_t src_len, bool copy)
|
||||
: string_(NULL), owner_(false) {
|
||||
@ -425,9 +428,9 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Create a new string referencing an existing string structure without taking
|
||||
// ownership. Referenced structures must exist for the lifetime of this class
|
||||
// and will not be freed by this class.
|
||||
/// Create a new string referencing an existing string structure without
|
||||
/// taking ownership. Referenced structures must exist for the lifetime of
|
||||
/// this class and will not be freed by this class.
|
||||
///
|
||||
CefStringBase(const struct_type* src) : string_(NULL), owner_(false) {
|
||||
if (!src)
|
||||
@ -438,31 +441,31 @@ class CefStringBase {
|
||||
|
||||
virtual ~CefStringBase() { ClearAndFree(); }
|
||||
|
||||
// The following methods are named for compatibility with the standard library
|
||||
// string template types.
|
||||
/// The following methods are named for compatibility with the standard
|
||||
/// library string template types.
|
||||
|
||||
///
|
||||
// Return a read-only pointer to the string data.
|
||||
/// Return a read-only pointer to the string data.
|
||||
///
|
||||
const char_type* c_str() const { return (string_ ? string_->str : NULL); }
|
||||
|
||||
///
|
||||
// Return the length of the string data.
|
||||
/// Return the length of the string data.
|
||||
///
|
||||
size_t length() const { return (string_ ? string_->length : 0); }
|
||||
|
||||
///
|
||||
// Return the length of the string data.
|
||||
/// Return the length of the string data.
|
||||
///
|
||||
inline size_t size() const { return length(); }
|
||||
|
||||
///
|
||||
// Returns true if the string is empty.
|
||||
/// Returns true if the string is empty.
|
||||
///
|
||||
bool empty() const { return (string_ == NULL || string_->length == 0); }
|
||||
|
||||
///
|
||||
// Compare this string to the specified string.
|
||||
/// Compare this string to the specified string.
|
||||
///
|
||||
int compare(const CefStringBase& str) const {
|
||||
if (empty() && str.empty())
|
||||
@ -475,7 +478,7 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Clear the string data.
|
||||
/// Clear the string data.
|
||||
///
|
||||
void clear() {
|
||||
if (string_)
|
||||
@ -483,7 +486,7 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Swap this string's contents with the specified string.
|
||||
/// Swap this string's contents with the specified string.
|
||||
///
|
||||
void swap(CefStringBase& str) {
|
||||
struct_type* tmp_string = string_;
|
||||
@ -497,19 +500,19 @@ class CefStringBase {
|
||||
// The following methods are unique to CEF string template types.
|
||||
|
||||
///
|
||||
// Returns true if this class owns the underlying string structure.
|
||||
/// Returns true if this class owns the underlying string structure.
|
||||
///
|
||||
bool IsOwner() const { return owner_; }
|
||||
|
||||
///
|
||||
// Returns a read-only pointer to the underlying string structure. May return
|
||||
// NULL if no structure is currently allocated.
|
||||
/// Returns a read-only pointer to the underlying string structure. May return
|
||||
/// NULL if no structure is currently allocated.
|
||||
///
|
||||
const struct_type* GetStruct() const { return string_; }
|
||||
|
||||
///
|
||||
// Returns a writable pointer to the underlying string structure. Will never
|
||||
// return NULL.
|
||||
/// Returns a writable pointer to the underlying string structure. Will never
|
||||
/// return NULL.
|
||||
///
|
||||
struct_type* GetWritableStruct() {
|
||||
AllocIfNeeded();
|
||||
@ -517,8 +520,8 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Clear the state of this class. The underlying string structure and data
|
||||
// will be freed if this class owns the structure.
|
||||
/// Clear the state of this class. The underlying string structure and data
|
||||
/// will be freed if this class owns the structure.
|
||||
///
|
||||
void ClearAndFree() {
|
||||
if (!string_)
|
||||
@ -532,8 +535,8 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Attach to the specified string structure. If |owner| is true this class
|
||||
// will take ownership of the structure.
|
||||
/// Attach to the specified string structure. If |owner| is true this class
|
||||
/// will take ownership of the structure.
|
||||
///
|
||||
void Attach(struct_type* str, bool owner) {
|
||||
// Free the previous structure and data, if any.
|
||||
@ -544,9 +547,9 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Take ownership of the specified userfree structure's string data. The
|
||||
// userfree structure itself will be freed. Only use this method with userfree
|
||||
// structures.
|
||||
/// Take ownership of the specified userfree structure's string data. The
|
||||
/// userfree structure itself will be freed. Only use this method with
|
||||
/// userfree structures.
|
||||
///
|
||||
void AttachToUserFree(userfree_struct_type str) {
|
||||
// Free the previous structure and data, if any.
|
||||
@ -559,15 +562,15 @@ class CefStringBase {
|
||||
owner_ = true;
|
||||
memcpy(string_, str, sizeof(struct_type));
|
||||
|
||||
// Free the |str| structure but not the data.
|
||||
/// Free the |str| structure but not the data.
|
||||
memset(str, 0, sizeof(struct_type));
|
||||
traits::userfree_free(str);
|
||||
}
|
||||
|
||||
///
|
||||
// Detach from the underlying string structure. To avoid memory leaks only use
|
||||
// this method if you already hold a pointer to the underlying string
|
||||
// structure.
|
||||
/// Detach from the underlying string structure. To avoid memory leaks only
|
||||
/// use this method if you already hold a pointer to the underlying string
|
||||
/// structure.
|
||||
///
|
||||
void Detach() {
|
||||
string_ = NULL;
|
||||
@ -575,9 +578,9 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Create a userfree structure and give it ownership of this class' string
|
||||
// data. This class will be disassociated from the data. May return NULL if
|
||||
// this string class currently contains no data.
|
||||
/// Create a userfree structure and give it ownership of this class' string
|
||||
/// data. This class will be disassociated from the data. May return NULL if
|
||||
/// this string class currently contains no data.
|
||||
///
|
||||
userfree_struct_type DetachToUserFree() {
|
||||
if (empty())
|
||||
@ -600,10 +603,10 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Set this string's data to the specified character array. If |copy| is true
|
||||
// this class will copy the data. Otherwise, this class will reference the
|
||||
// existing data. Referenced data must exist for the lifetime of this class
|
||||
// and will not be freed by this class.
|
||||
/// Set this string's data to the specified character array. If |copy| is true
|
||||
/// this class will copy the data. Otherwise, this class will reference the
|
||||
/// existing data. Referenced data must exist for the lifetime of this class
|
||||
/// and will not be freed by this class.
|
||||
///
|
||||
bool FromString(const char_type* src, size_t src_len, bool copy) {
|
||||
if (src == NULL || src_len == 0) {
|
||||
@ -615,9 +618,9 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Set this string's data from an existing ASCII string. Data will be always
|
||||
// copied. Translation will occur if necessary based on the underlying string
|
||||
// type.
|
||||
/// Set this string's data from an existing ASCII string. Data will be always
|
||||
/// copied. Translation will occur if necessary based on the underlying string
|
||||
/// type.
|
||||
///
|
||||
bool FromASCII(const char* str) {
|
||||
size_t len = str ? strlen(str) : 0;
|
||||
@ -630,8 +633,8 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Return this string's data as a std::string. Translation will occur if
|
||||
// necessary based on the underlying string type.
|
||||
/// Return this string's data as a std::string. Translation will occur if
|
||||
/// necessary based on the underlying string type.
|
||||
///
|
||||
std::string ToString() const {
|
||||
if (empty())
|
||||
@ -640,9 +643,9 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Set this string's data from an existing std::string. Data will be always
|
||||
// copied. Translation will occur if necessary based on the underlying string
|
||||
// type.
|
||||
/// Set this string's data from an existing std::string. Data will be always
|
||||
/// copied. Translation will occur if necessary based on the underlying string
|
||||
/// type.
|
||||
///
|
||||
bool FromString(const std::string& str) {
|
||||
if (str.empty()) {
|
||||
@ -654,9 +657,9 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Set this string's data from existing |data| and optional |length|. Data
|
||||
// will be always copied. Translation will occur if necessary based on the
|
||||
// underlying string type.
|
||||
/// Set this string's data from existing |data| and optional |length|. Data
|
||||
/// will be always copied. Translation will occur if necessary based on the
|
||||
/// underlying string type.
|
||||
///
|
||||
bool FromString(const std::string::value_type* data, size_t length = 0) {
|
||||
if (data && length == 0) {
|
||||
@ -671,8 +674,8 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Return this string's data as a std::wstring. Translation will occur if
|
||||
// necessary based on the underlying string type.
|
||||
/// Return this string's data as a std::wstring. Translation will occur if
|
||||
/// necessary based on the underlying string type.
|
||||
///
|
||||
std::wstring ToWString() const {
|
||||
if (empty())
|
||||
@ -681,9 +684,9 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Set this string's data from an existing std::wstring. Data will be always
|
||||
// copied. Translation will occur if necessary based on the underlying string
|
||||
// type.
|
||||
/// Set this string's data from an existing std::wstring. Data will be always
|
||||
/// copied. Translation will occur if necessary based on the underlying string
|
||||
/// type.
|
||||
///
|
||||
bool FromWString(const std::wstring& str) {
|
||||
if (str.empty()) {
|
||||
@ -695,9 +698,9 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Set this string's data from existing |data| and optional |length|. Data
|
||||
// will be always copied. Translation will occur if necessary based on the
|
||||
// underlying string type.
|
||||
/// Set this string's data from existing |data| and optional |length|. Data
|
||||
/// will be always copied. Translation will occur if necessary based on the
|
||||
/// underlying string type.
|
||||
///
|
||||
bool FromWString(const std::wstring::value_type* data, size_t length = 0) {
|
||||
if (data && length == 0) {
|
||||
@ -710,9 +713,10 @@ class CefStringBase {
|
||||
AllocIfNeeded();
|
||||
return traits::from_wstring(data, length, string_);
|
||||
}
|
||||
|
||||
///
|
||||
// Return this string's data as a string16. Translation will occur if
|
||||
// necessary based on the underlying string type.
|
||||
/// Return this string's data as a string16. Translation will occur if
|
||||
/// necessary based on the underlying string type.
|
||||
///
|
||||
std::u16string ToString16() const {
|
||||
if (empty())
|
||||
@ -721,9 +725,9 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Set this string's data from an existing string16. Data will be always
|
||||
// copied. Translation will occur if necessary based on the underlying string
|
||||
// type.
|
||||
/// Set this string's data from an existing string16. Data will be always
|
||||
/// copied. Translation will occur if necessary based on the underlying string
|
||||
/// type.
|
||||
///
|
||||
bool FromString16(const std::u16string& str) {
|
||||
if (str.empty()) {
|
||||
@ -735,9 +739,9 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Set this string's data from existing |data| and optional |length|. Data
|
||||
// will be always copied. Translation will occur if necessary based on the
|
||||
// underlying string type.
|
||||
/// Set this string's data from existing |data| and optional |length|. Data
|
||||
/// will be always copied. Translation will occur if necessary based on the
|
||||
/// underlying string type.
|
||||
///
|
||||
bool FromString16(const std::u16string::value_type* data, size_t length = 0) {
|
||||
if (data && length == 0) {
|
||||
@ -752,7 +756,7 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Comparison operator overloads.
|
||||
/// Comparison operator overloads.
|
||||
///
|
||||
bool operator<(const CefStringBase& str) const { return (compare(str) < 0); }
|
||||
bool operator<=(const CefStringBase& str) const {
|
||||
@ -770,7 +774,7 @@ class CefStringBase {
|
||||
}
|
||||
|
||||
///
|
||||
// Assignment operator overloads.
|
||||
/// Assignment operator overloads.
|
||||
///
|
||||
CefStringBase& operator=(const CefStringBase& str) {
|
||||
FromString(str.c_str(), str.length(), true);
|
||||
@ -822,7 +826,7 @@ class CefStringBase {
|
||||
#endif // USING_CHROMIUM_INCLUDES
|
||||
|
||||
private:
|
||||
// Allocate the string structure if it doesn't already exist.
|
||||
/// Allocate the string structure if it doesn't already exist.
|
||||
void AllocIfNeeded() {
|
||||
if (string_ == NULL) {
|
||||
string_ = new struct_type;
|
||||
|
||||
Reference in New Issue
Block a user