xiiFormatString Class Reference

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

#include <FormatString.h>

Inheritance diagram for xiiFormatString:

Public Member Functions
XII_ALWAYS_INLINE	xiiFormatString (const char *szString)
XII_ALWAYS_INLINE	xiiFormatString (xiiStringView sString)
	xiiFormatString (const xiiStringBuilder &s)
virtual xiiStringView	GetText (xiiStringBuilder &) 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 (xiiStringBuilder &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
xiiStringView	BuildFormattedText (xiiStringBuilder &ref_sStorage, xiiStringView *pArgs, xiiUInt32 uiNumArgs) const
	Helper function to build the formatted text with the given arguments.

Protected Attributes
xiiStringView	m_sString

Detailed Description

Implements formating of strings with placeholders and formatting options.

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

A function taking a xiiFormatString can internally call xiiFormatString::GetText() to retrieve he formatted result. When calling such a function, one must wrap the parameter into 'xiiFmt' to enable formatting options, example: void MyFunc(const xiiFormatString& text); MyFunc(xiiFmt("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(xiiFormatStringImpl<ARGS...>(szFormat, std::forward<ARGS>(args)...)); }

This allows to call MyFunc() without the 'xiiFmt' 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 a xiiArgXY call: xiiArgC - for characters xiiArgI - for integer formatting xiiArgU - for unsigned integer formatting (e.g. HEX) xiiArgF - for floating point formatting xiiArgP - for pointer formatting xiiArgDateTime - for xiiDateTime formatting options xiiArgErrorCode - for Windows error code formatting xiiArgHumanReadable - for shortening numbers with common abbreviations xiiArgFileSize - for representing file sizes

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

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

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

Member Function Documentation

BuildFormattedText()

xiiStringView xiiFormatString::BuildFormattedText	(	xiiStringBuilder &	ref_sStorage,
		xiiStringView *	pArgs,
		xiiUInt32	uiNumArgs ) const

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

Note

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

GetText()

virtual xiiStringView xiiFormatString::GetText ( xiiStringBuilder & ) const

inlinenodiscardvirtual

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

Requires a xiiStringBuilder 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 xiiFormatStringImpl< ARGS >.

GetTextCStr()

const char * xiiFormatString::GetTextCStr ( xiiStringBuilder & 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 xiiFormatStringImpl< ARGS >.

---

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

• /home/runner/work/XII/XII/Source/Engine/Foundation/Strings/FormatString.h
• /home/runner/work/XII/XII/Source/Engine/Foundation/Strings/Implementation/FormatString.cpp