plFormatString Class Reference

Implements formating of strings with placeholders and formatting options. More...

#include <FormatString.h>

Inheritance diagram for plFormatString:

Public Member Functions
PL_ALWAYS_INLINE	plFormatString (const char *szString)
PL_ALWAYS_INLINE	plFormatString (plStringView sString)
	plFormatString (const plStringBuilder &s)
virtual plStringView	GetText (plStringBuilder &) const
	Generates the formatted text. Make sure to only call this function once and only when the formatted string is really needed.
virtual const char *	GetTextCStr (plStringBuilder &out_sString) const
	Similar to GetText() but guaranteed to copy the string into the given string builder, and thus guaranteeing that the generated string is zero terminated.
bool	IsEmpty () const
plStringView	BuildFormattedText (plStringBuilder &ref_sStorage, plStringView *pArgs, plUInt32 uiNumArgs) const
	Helper function to build the formatted text with the given arguments.

Protected Attributes
plStringView	m_sString

Detailed Description

Implements formating of strings with placeholders and formatting options.

plFormatString can be used anywhere where a string should be formatable when passing it into a function. Good examples are plStringBuilder::SetFormat() or plLog::Info().

A function taking an plFormatString can internally call plFormatString::GetText() to retrieve he formatted result. When calling such a function, one must wrap the parameter into 'plFmt' to enable formatting options, example: void MyFunc(const plFormatString& text); MyFunc(plFmt("Cool Story {}", "Bro"));

To provide more convenience, one can add a template-function overload like this: template <typename... ARGS> void MyFunc(const char* szFormat, ARGS&&... args) { MyFunc(plFormatStringImpl<ARGS...>(szFormat, std::forward<ARGS>(args)...)); }

This allows to call MyFunc() without the 'plFmt' wrapper.

=== Formatting ===

Placeholders for variables are specified using '{}'. These may use numbers from 0 to 9, ie. {0}, {3}, {2}, etc. which allows to change the order or insert duplicates. If no number is provided, each {} instance represents the next argument.

To specify special formatting, wrap the argument into an plArgXY call: plArgC - for characters plArgI - for integer formatting plArgU - for unsigned integer formatting (e.g. HEX) plArgF - for floating point formatting plArgP - for pointer formatting plArgDateTime - for plDateTime formatting options plArgErrorCode - for Windows error code formatting plArgHumanReadable - for shortening numbers with common abbreviations plArgFileSize - for representing file sizes

Example: plStringBuilder::SetFormat("HEX: {}", plArgU(1337, 8 /*width*‍/, true /*pad with zeros*‍/, 16 /*base16*‍/, true/*upper case*‍/));

Arbitrary other types can support special formatting even without an plArgXY call. E.g. plTime and plAngle do special formatting. plArgXY calls are only necessary if formatting options are needed for a specific formatting should be enforced (e.g. plArgErrorCode would otherwise just use uint32 formatting).

To implement custom formatting see the various free standing 'BuildString' functions.

Member Function Documentation

BuildFormattedText()

plStringView plFormatString::BuildFormattedText	(	plStringBuilder &	ref_sStorage,
		plStringView *	pArgs,
		plUInt32	uiNumArgs ) const

Helper function to build the formatted text with the given arguments.

Note

We can't use plArrayPtr here because of include order.

GetText()

virtual plStringView plFormatString::GetText ( plStringBuilder & ) const

inlinenodiscardvirtual

Generates the formatted text. Make sure to only call this function once and only when the formatted string is really needed.

Requires an plStringBuilder as storage, ie. POTENTIALLY writes the formatted text into it. However, if no formatting is required, it may not touch the string builder at all and just return a string directly.

Note

Do not assume that the result is stored in sb. Always only use the return value. The string builder is only used when necessary.

Reimplemented in plFormatStringImpl< ARGS >.

GetTextCStr()

const char * plFormatString::GetTextCStr ( plStringBuilder & out_sString ) const

virtual

Similar to GetText() but guaranteed to copy the string into the given string builder, and thus guaranteeing that the generated string is zero terminated.

Reimplemented in plFormatStringImpl< ARGS >.

---

The documentation for this class was generated from the following files:

• Code/Engine/Foundation/Strings/FormatString.h
• Code/Engine/Foundation/Strings/Implementation/FormatString.cpp