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).

Definition at line 37 of file PString.h.

#include <PString.h>

Member Enumeration Documentation

◆ ECaseSensitivity

enum PString::ECaseSensitivity

Used to change case sensitive behavior of some methods.

Enumerator
E_CASE_INSENSITIVE
E_CASE_SENSITIVE

Definition at line 43 of file PString.h.

◆ ESplitBehavior

enum PString::ESplitBehavior

Used to control the behavior of Split().

Enumerator
E_KEEP_EMPTY_PARTS
E_SKIP_EMPTY_PARTS

Definition at line 48 of file PString.h.

◆ EWriteMode

enum PString::EWriteMode

All the available write mode.

Enumerator
E_FAIL_IF_EXIST
E_OVERWRITE
E_APPEND

Definition at line 53 of file PString.h.

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]

PString::PString ( char c )

explicit

Constructs a string from the specified character.

◆ PString() [10/16]

PString::PString ( papillon::int16 n )

explicit

Constructs a string from the specified 16-bit int number.

◆ PString() [11/16]

PString::PString ( papillon::uint16 n )

explicit

Constructs a string from the specified 16-bit unsigned int number.

◆ PString() [12/16]

PString::PString ( papillon::int32 n )

explicit

Constructs a string from the specified 32-bit int number.

◆ PString() [13/16]

PString::PString ( papillon::uint32 n )

explicit

Constructs a string from the specified 32-bit unsigned int number.

◆ PString() [14/16]

PString::PString ( papillon::int64 n )

explicit

Constructs a string from the specified 64-bit int number.

◆ PString() [15/16]

PString::PString ( papillon::uint64 n )

explicit

Constructs a string from the specified 64-bit unsigned int number.

◆ PString() [16/16]

PString::PString	(	double	n,
		char	format = `'g'`,
		papillon::int32	precision = `6`
	)

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 PString::~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

UNSAFE: The pointer will be invalid on change of the PString object returns a read-only pointer to wchar_t version of this PString.

The array is encoded in UTF-16 on platforms where wchar_t is 2 bytes wide (e.g. windows) and in UCS-4 on platforms where wchar_t is 4 bytes wide (most Unix systems).

◆ 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 PString PString::DuplicateChars	(	papillon::int32	size,
		papillon::wchar	c
	)

static

Constructs a string of the given size with every character set to c.

◆ Empty()

static const PString& PString::Empty ( )

inlinestatic

Returns the constant holding the empty string "".

Definition at line 64 of file PString.h.

◆ 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 PString PString::FromUTF8 ( const papillon::PByteArray & utf8Buffer )

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]

PString& PString::operator+= ( const PString & other )

Appends the specified string to this string.

◆ 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=()

PString& PString::operator= ( const PString & other )

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]

PString& PString::Replace	(	const PString &	before,
		const PString &	after
	)

Replaces all the occurrences of 'before' with 'after' in this string, then returns the string itself for chaining.

◆ Replace() [2/2]

PString& PString::Replace	(	papillon::int32	pos,
		papillon::int32	n,
		const PString &	after
	)

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()

PString PString::ToLower ( ) const

Returns a lower case copy of this PString.

◆ 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()

PString PString::ToUpper ( ) const

Returns an upper case copy of this PString.

◆ 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.