Detailed Description
The PString class provides an Unicode character strings.
The class is NOT thread-safe.
When dealing with decimal numbers, PString behaviour is locale independent (only decimal point is supported, comma separator will produce truncated numbers).
PString instances are implicitly shared (i.e. copy-on-write).
#include <PString.h>
Member Enumeration Documentation
◆ ECaseSensitivity
◆ ESplitBehavior
◆ EWriteMode
enum PString::EWriteMode |
Constructor & Destructor Documentation
◆ PString() [1/16]
PString::PString | ( | ) |
Constructs an empty string.
◆ PString() [2/16]
PString::PString | ( | const PString & | other | ) |
Constructs a copy of other (implicit sharing, copy-on-write).
◆ PString() [3/16]
PString::PString | ( | const char * | str | ) |
Constructs a string initialized with the 8-bit string str.
String data are copied and converted, you can release your data pointer after the call to this constructor. The argument must be string terminated by 0. The given const char pointer is assumed to be ASCII or UTF-8 and is automatically converted to Unicode. If some invalid sequences are found (i.e. part of the encoding does not represent valid unicode characters), they will be replaced with one or more "replacement characters" or removed.
◆ PString() [4/16]
PString::PString | ( | const char * | str, |
papillon::int32 | n | ||
) |
Constructs a string initialized with the n first bytes of str (or until the end of str, if str is too short).
String data are copied and converted, you can release your data pointer after the call to this constructor. The given const char pointer is assumed to be ASCII or UTF-8 and is automatically converted to Unicode. If some invalid sequences are found (i.e. part of the encoding does not represent valid unicode characters), they will be replaced with one or more "replacement characters" or removed.
◆ PString() [5/16]
PString::PString | ( | const wchar_t * | str | ) |
Constructs a string initialized with the specified string.
String data are copied and converted, you can release your data pointer after the call to this constructor. The argument must be string terminated by 0. The specified string has to be 0 terminated. The given string is assumed to be encoded in UTF16- if the size of wchar_t is 2 bytes (e.g. on windows) or UCS-4 if the size of wchar_t is 4 bytes.
◆ PString() [6/16]
PString::PString | ( | const std::string & | str | ) |
Constructs a string initialized with the std::string str.
The given string is assumed to be ASCII or UTF-8 and is automatically converted to Unicode. If some invalid sequences are found (i.e. part of the encoding does not represent valid unicode characters), they will be replaced with one or more "replacement characters" or removed.
◆ PString() [7/16]
PString::PString | ( | const std::wstring & | str | ) |
Constructs a string initialized with the std::wstring str.
The given string is assumed to be encoded in UTF-16 if the size of wchar_t is 2 bytes (e.g. on Windows) and UCS4 if the size of wchar_t is 4 bytes.
◆ PString() [8/16]
PString::PString | ( | const std::u16string & | str | ) |
Constructs a string initialized with the std::u16string.
◆ PString() [9/16]
|
explicit |
Constructs a string from the specified character.
◆ PString() [10/16]
|
explicit |
Constructs a string from the specified 16-bit int number.
◆ PString() [11/16]
|
explicit |
Constructs a string from the specified 16-bit unsigned int number.
◆ PString() [12/16]
|
explicit |
Constructs a string from the specified 32-bit int number.
◆ PString() [13/16]
|
explicit |
Constructs a string from the specified 32-bit unsigned int number.
◆ PString() [14/16]
|
explicit |
Constructs a string from the specified 64-bit int number.
◆ PString() [15/16]
|
explicit |
Constructs a string from the specified 64-bit unsigned int number.
◆ PString() [16/16]
|
explicit |
Constructs a string equivalent of the number n, formatted according to the specified format and precision.
Format can be:
- 'e': format as [-]9.9e[+|-]999
- 'E': format as [-]9.9E[+|-]999
- 'f': format as [-]9.9
- 'g': use e or f format, whichever is the most concise
- 'G': use E or f format, whichever is the most concise
A precision is also specified with the argument format. For the 'e', 'E', and 'f' formats, the precision represents the number of digits after the decimal point. For the 'g' and 'G' formats, the precision represents the maximum number of significant digits (trailing zeroes are omitted).
◆ ~PString()
|
virtual |
Destroys this object.
Member Function Documentation
◆ AddLineNumbers()
PString PString::AddLineNumbers | ( | bool | columns = false | ) | const |
Returns a copy of this string with line numbers added (can also optionally add column numbers).
◆ Arg() [1/19]
PString PString::Arg | ( | const PString & | str, |
papillon::int32 | fieldWidth = 0 , |
||
papillon::wchar | fillChar = ' ' |
||
) | const |
Returns a copy of this string with the lowest numbered place marker replaced by string str, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
fieldWidth specified the minimum amount of space that argument str shall occupy. If str requires less space than fieldWidth, it is passed to fieldWidth with character fillChar. A positive fieldWidth produces right-aligned text. A negative fieldWidth produces left-aligned text.
◆ Arg() [2/19]
PString PString::Arg | ( | void * | value | ) | const |
Returns a copy of this string with the lowest numbered place marker replaced by the specified value, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
◆ Arg() [3/19]
PString PString::Arg | ( | const char * | value | ) | const |
Returns a copy of this string with the lowest numbered place marker replaced by the specified value, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
◆ Arg() [4/19]
PString PString::Arg | ( | const wchar_t * | str | ) | const |
Returns a copy of this string with the lowest numbered place marker replaced by the specified value, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
◆ Arg() [5/19]
PString PString::Arg | ( | bool | value | ) | const |
Returns a copy of this string with the lowest numbered place marker replaced by the specified value, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
◆ Arg() [6/19]
PString PString::Arg | ( | papillon::int32 | value, |
papillon::int32 | fieldWidth = 0 , |
||
papillon::int32 | base = 10 , |
||
papillon::wchar | fillChar = ' ' |
||
) | const |
Returns a copy of this string with the lowest numbered place marker replaced by the specified value, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
fieldWidth specified the minimum amount of space that argument value shall occupy. If str requires less space than fieldWidth, it is passed to fieldWidth with character fillChar. A positive fieldWidth produces right-aligned text. A negative fieldWidth produces left-aligned text.
◆ Arg() [7/19]
PString PString::Arg | ( | papillon::int32 | value, |
papillon::int32 | fieldWidth, | ||
papillon::int32 | base, | ||
char | fillChar | ||
) | const |
◆ Arg() [8/19]
PString PString::Arg | ( | papillon::int64 | value, |
papillon::int32 | fieldWidth = 0 , |
||
papillon::int32 | base = 10 , |
||
papillon::wchar | fillChar = ' ' |
||
) | const |
Returns a copy of this string with the lowest numbered place marker replaced by the specified value, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
fieldWidth specified the minimum amount of space that argument value shall occupy. If str requires less space than fieldWidth, it is passed to fieldWidth with character fillChar. A positive fieldWidth produces right-aligned text. A negative fieldWidth produces left-aligned text.
◆ Arg() [9/19]
PString PString::Arg | ( | papillon::int64 | value, |
papillon::int32 | fieldWidth, | ||
papillon::int32 | base, | ||
char | fillChar | ||
) | const |
◆ Arg() [10/19]
PString PString::Arg | ( | papillon::uint32 | value, |
papillon::int32 | fieldWidth = 0 , |
||
papillon::int32 | base = 10 , |
||
papillon::wchar | fillChar = ' ' |
||
) | const |
Returns a copy of this string with the lowest numbered place marker replaced by the specified value, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
fieldWidth specified the minimum amount of space that argument value shall occupy. If str requires less space than fieldWidth, it is passed to fieldWidth with character fillChar. A positive fieldWidth produces right-aligned text. A negative fieldWidth produces left-aligned text.
◆ Arg() [11/19]
PString PString::Arg | ( | papillon::uint32 | value, |
papillon::int32 | fieldWidth, | ||
papillon::int32 | base, | ||
char | fillChar | ||
) | const |
◆ Arg() [12/19]
PString PString::Arg | ( | papillon::uint64 | value, |
papillon::int32 | fieldWidth = 0 , |
||
papillon::int32 | base = 10 , |
||
papillon::wchar | fillChar = ' ' |
||
) | const |
Returns a copy of this string with the lowest numbered place marker replaced by the specified value, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
fieldWidth specified the minimum amount of space that argument value shall occupy. If str requires less space than fieldWidth, it is passed to fieldWidth with character fillChar. A positive fieldWidth produces right-aligned text. A negative fieldWidth produces left-aligned text.
◆ Arg() [13/19]
PString PString::Arg | ( | papillon::uint64 | value, |
papillon::int32 | fieldWidth, | ||
papillon::int32 | base, | ||
char | fillChar | ||
) | const |
◆ Arg() [14/19]
PString PString::Arg | ( | double | value, |
papillon::int32 | fieldWidth = 0 , |
||
char | format = 'g' , |
||
papillon::int32 | precision = -1 , |
||
papillon::wchar | fillChar = ' ' |
||
) | const |
Returns a copy of this string with the lowest numbered place marker replaced by the specified value, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
fieldWidth specified the minimum amount of space that argument value shall occupy. If str requires less space than fieldWidth, it is passed to fieldWidth with character fillChar. A positive fieldWidth produces right-aligned text. A negative fieldWidth produces left-aligned text.
Available format are the followings:
- 'e': format as [-]9.9e[+|-]999
- 'E': format as [-]9.9E[+|-]999
- 'f': format as [-]9.9
- 'g': use e or f format, whichever is the most concise
- 'G': use E or f format, whichever is the most concise
◆ Arg() [15/19]
PString PString::Arg | ( | double | value, |
papillon::int32 | fieldWidth, | ||
char | format, | ||
papillon::int32 | precision, | ||
char | fillChar | ||
) | const |
◆ Arg() [16/19]
PString PString::Arg | ( | float | value, |
papillon::int32 | fieldWidth = 0 , |
||
char | format = 'g' , |
||
papillon::int32 | precision = -1 , |
||
papillon::wchar | fillChar = ' ' |
||
) | const |
Returns a copy of this string with the lowest numbered place marker replaced by the specified value, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
fieldWidth specified the minimum amount of space that argument value shall occupy. If str requires less space than fieldWidth, it is passed to fieldWidth with character fillChar. A positive fieldWidth produces right-aligned text. A negative fieldWidth produces left-aligned text.
Available format are the followings:
- 'e': format as [-]9.9e[+|-]999
- 'E': format as [-]9.9E[+|-]999
- 'f': format as [-]9.9
- 'g': use e or f format, whichever is the most concise
- 'G': use E or f format, whichever is the most concise
◆ Arg() [17/19]
PString PString::Arg | ( | float | value, |
papillon::int32 | fieldWidth, | ||
char | format, | ||
papillon::int32 | precision, | ||
char | fillChar | ||
) | const |
◆ Arg() [18/19]
PString PString::Arg | ( | const papillon::PObject & | object | ) | const |
Returns a copy of this string with the lowest numbered place marker replaced by the specified PObject converted to PString using ToString() method, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
◆ Arg() [19/19]
PString PString::Arg | ( | const papillon::PResult & | result | ) | const |
Returns a copy of this string with the lowest numbered place marker replaced by the specified PObject converted to PString using ToString() method, i.e.
%1, %2, ... %99. If place marker i appears more than once in the string, the Arg() replaces all of them.
◆ At()
papillon::wchar PString::At | ( | papillon::int32 | position | ) | const |
Returns the character at the given index position in the string or 0 if the position is invalid.
◆ c_str()
const char* PString::c_str | ( | ) | const |
UNSAFE: The pointer will be invalid on change of the PString object returns a read-only pointer to UTF8 version of this PString.
Same as ConstUTF8().
- See also
- ConstUTF16()
◆ c_wstr()
const wchar_t* PString::c_wstr | ( | ) | const |
◆ Chop()
PString& PString::Chop | ( | papillon::int32 | n | ) |
Removes n characters from the end of this string.
If n is greater than Size(), the result is an empty string. Returns the string itself, for chaining.
◆ Compare()
papillon::int32 PString::Compare | ( | const PString & | other, |
ECaseSensitivity | caseSensitivity = E_CASE_SENSITIVE |
||
) | const |
Compares this string with another one, then returns 0 if equal, a negative number if this string object lexicographically precedes other, a positive number if this string object lexicographically follows other.
◆ ConstUTF16()
const papillon::wchar* PString::ConstUTF16 | ( | ) | const |
◆ ConstUTF8()
const char* PString::ConstUTF8 | ( | ) | const |
UNSAFE: The pointer will be invalid on change of the PString object returns a read-only pointer to UTF8 version of this PString.
Same as c_str().
- See also
- ConstUTF16()
◆ Contains()
bool PString::Contains | ( | const PString & | s, |
ECaseSensitivity | c = PString::E_CASE_SENSITIVE |
||
) | const |
Returns true if this string contains an occurrence of the string s, otherwise returns false.
Case sensitive search is enabled by default.
◆ Count()
papillon::uint32 PString::Count | ( | const PString & | s, |
ECaseSensitivity | c = PString::E_CASE_SENSITIVE |
||
) | const |
Returns the number of (potentially overlapping) occurrences of the given string s in this string.
Case sensitive search is enabled by default.
◆ DoubleBackslash()
PString PString::DoubleBackslash | ( | ) | const |
Returns a copy of this string with all backslashes '\' replaced by double backslashes "\\".
◆ DuplicateChars()
|
static |
Constructs a string of the given size with every character set to c.
◆ Empty()
|
inlinestatic |
◆ EndsWith()
bool PString::EndsWith | ( | const PString & | s, |
ECaseSensitivity | c = PString::E_CASE_SENSITIVE |
||
) | const |
Returns true if the string ends with s; otherwise returns false.
Case sensitive search is enabled by default.
◆ FromUTF8()
|
static |
Creates a PString from the specified UTF8 byte buffer.
The buffer can have a null value (byte 0) at the end or not.
◆ IndexOf()
papillon::int32 PString::IndexOf | ( | const PString & | s, |
ECaseSensitivity | c = PString::E_CASE_SENSITIVE |
||
) | const |
Returns the index position of the first occurrence of the string s in this string.
Case sensitive search is enabled by default. Returns -1 if s is not found.
◆ IsEmpty()
bool PString::IsEmpty | ( | ) | const |
Returns true if the string has no characters otherwise returns false.
◆ LastIndexOf()
papillon::int32 PString::LastIndexOf | ( | const PString & | s, |
ECaseSensitivity | c = PString::E_CASE_SENSITIVE |
||
) | const |
Returns the index position of the last occurrence of the string s in this string.
Case sensitive search is enabled by default. Returns -1 if s is not found.
◆ Load()
papillon::PResult PString::Load | ( | const PString & | textFilename | ) |
Reads a string from the specified text file (assume UTF-8 encoding).
In case of failure, the string is emptied.
Returns PResult::C_OK if success, another result otherwise.
- See also
- Save()
◆ NotEmpty()
bool PString::NotEmpty | ( | ) | const |
Returns true if the string has at least 1 character otherwise returns false.
◆ operator!=()
bool PString::operator!= | ( | const PString & | other | ) | const |
Returns true if this string is different from other; otherwise returns false.
◆ operator+=() [1/2]
◆ operator+=() [2/2]
PString& PString::operator+= | ( | papillon::wchar | car | ) |
Appends the specified character to this string.
◆ operator<()
bool PString::operator< | ( | const PString & | other | ) | const |
Returns true if the character sequence represented by this string object lexicographically precedes the argument string; otherwise returns false.
◆ operator<=()
bool PString::operator<= | ( | const PString & | other | ) | const |
Returns true if the character sequence represented by this string object lexicographically precedes the argument string or is the same; otherwise returns false.
◆ operator=()
Copies other to this string (implicit sharing, copy-on-write).
◆ operator==()
bool PString::operator== | ( | const PString & | other | ) | const |
Returns true if this string is equal to other; otherwise returns false.
◆ operator>()
bool PString::operator> | ( | const PString & | other | ) | const |
Returns true if the character sequence represented by this string object lexicographically follows the argument string; otherwise returns false.
◆ operator>=()
bool PString::operator>= | ( | const PString & | other | ) | const |
Returns true if the character sequence represented by this string object lexicographically follows the argument string or is the same; otherwise returns false.
◆ PadRight()
PString PString::PadRight | ( | papillon::int32 | size, |
papillon::wchar | separator = ' ' |
||
) | const |
Creates a new string by concatenating enough trailing pad characters to an original string to achieve a specified total length.
Pads this string n characters from the end of the string. If n is greater than Size(), the result is the original string.
◆ Quote()
PString PString::Quote | ( | ) | const |
Returns a copy of this string with quotes at the beginning and at the end.
◆ RemoveEndDigits()
PString PString::RemoveEndDigits | ( | ) | const |
Returns a copy of this string without end digits.
Examples:
- PString::RemoveEndDigits("test") gives "test".
- PString::RemoveEndDigits("test3") gives "test".
- PString::RemoveEndDigits("test001") gives "test".
- PString::RemoveEndDigits("123") gives "".
◆ Replace() [1/2]
Replaces all the occurrences of 'before' with 'after' in this string, then returns the string itself for chaining.
◆ Replace() [2/2]
Replaces n characters beginning at index position with the string after and returns a reference to this string.
Example: PString("abcdef").Replace(2, "123") -> "ab123f".
◆ Reserve()
void PString::Reserve | ( | papillon::int32 | size | ) |
Attempts to allocate memory for at least size characters.
If you know in advance how large the string will be, you can call this function, and if you resize the string often you are likely to get better performance. If size is an underestimate, the worst that will happen is that the PString will be a bit slower.
◆ Save()
papillon::PResult PString::Save | ( | const PString & | textFilename, |
EWriteMode | mode = E_OVERWRITE |
||
) | const |
Saves this string to the specified text file (use UTF-8 encoding).
Returns PResult::C_OK if success, another result otherwise.
- See also
- Load()
◆ Size()
papillon::int32 PString::Size | ( | ) | const |
Returns the number of characters in this string.
◆ Split() [1/2]
papillon::PStringList PString::Split | ( | papillon::wchar | separator, |
ESplitBehavior | splitBehavior = E_KEEP_EMPTY_PARTS |
||
) | const |
Splits the string into substrings wherever separator occurs and returns the list of those strings.
Examples:
- PString("a,,def").Split(',', PString::E_KEEP_EMPTY_PARTS).Size(); // returns 3 (second element is empty)
- PString("a,,def").Split(',', PString::E_SKIP_EMPTY_PARTS).Size(); // returns 2
◆ Split() [2/2]
papillon::PStringList PString::Split | ( | const papillon::PString & | separator, |
ESplitBehavior | splitBehavior = E_KEEP_EMPTY_PARTS |
||
) | const |
Splits the string into substrings wherever separator occurs and returns the list of those strings.
◆ SplitSameLength()
papillon::PStringList PString::SplitSameLength | ( | papillon::int32 | size | ) | const |
Splits the string into substrings (chunks) of the same length.
Example: PString("0123456789").SplitSameLength(3) -> ("012","345","678","9"). If size is <= 0, return a PStringList containing only 1 string, the string itself.
◆ StartsWith()
bool PString::StartsWith | ( | const PString & | s, |
ECaseSensitivity | c = PString::E_CASE_SENSITIVE |
||
) | const |
Returns true if the string starts with s; otherwise returns false.
Case sensitive search is enabled by default.
◆ stdString()
const std::string& PString::stdString | ( | ) | const |
returns UTF8 version of this PString wrapped into std::string
◆ Substring()
PString PString::Substring | ( | papillon::int32 | position, |
papillon::int32 | n = -1 |
||
) | const |
Creates a PString from the Latin-1 representation of the string.
Returns a string that contains n characters of this string, starting at the specified position index. Returns an empty string if the position index exceeds the length of the string. If there are less than n characters available in the string starting at the given position, or if n is -1 (default), the function returns all characters that are available from the specified position.
◆ ToBool()
bool PString::ToBool | ( | bool * | ok = NULL | ) | const |
Converts this string to a bool if possible.
Returns true if "1" or "true" or "yes", false if "0" or "false" or "no" (case insensitive). Returns false if the conversion fails.
◆ ToDouble()
double PString::ToDouble | ( | bool * | ok = NULL | ) | const |
Converts this string to a double if possible.
Only string numbers with decimal points are supported (this method does not support localization, using comma as separator will trunc the output number). Returns 0.0 if the conversion fails.
◆ ToFloat()
float PString::ToFloat | ( | bool * | ok = NULL | ) | const |
Converts this string to a float if possible.
Only string numbers with decimal points are supported (this method does not support localization, using comma as separator will trunc the output number). Returns 0.0 if the conversion fails.
◆ ToInt32()
papillon::int32 PString::ToInt32 | ( | bool * | ok = NULL | ) | const |
Converts this string to a 32-bit integer if possible.
Returns 0 if the conversion fails.
◆ ToInt64()
papillon::int64 PString::ToInt64 | ( | bool * | ok = NULL | ) | const |
Converts this string to a 64-bit integer if possible.
Returns 0 if the conversion fails.
◆ ToLower()
◆ ToUInt32()
papillon::uint32 PString::ToUInt32 | ( | bool * | ok = NULL | ) | const |
Converts this string to a 32-bit unsigned integer if possible.
Returns 0 if the conversion fails.
◆ ToUInt64()
papillon::uint64 PString::ToUInt64 | ( | bool * | ok = NULL | ) | const |
Converts this string to a 64-bit unsigned integer if possible.
Returns 0 if the conversion fails.
◆ ToUpper()
◆ ToUTF8()
papillon::PByteArray PString::ToUTF8 | ( | ) | const |
Returns the UTF-8 representation of this string; the last byte of the buffer is a 0 to indicate end of the string.
◆ Trim()
PString PString::Trim | ( | ) | const |
Returns a string that has whitespace removed from the start and the end, and that has each sequence of internal whitespace replaced with a single space.
◆ Truncate()
PString& PString::Truncate | ( | papillon::int32 | position | ) |
Truncates this string at the given position index.
If the specified position index is beyond the end of the string, nothing happens. Returns the string itself, for chaining.
◆ u16String()
const std::u16string& PString::u16String | ( | ) | const |
returns 16bit version of this PString wrapped into std::u16string
◆ Unquote()
PString PString::Unquote | ( | ) | const |
Returns a copy of this string; quotes at the beginning and at the end are removed if present.