Stroika::Foundation::Characters::StringBuilder< OPTIONS > Class Template Reference

Similar to String, but intended to more efficiently construct a String. Mutable type (String is largely immutable). More...

#include <StringBuilder.h>

Public Member Functions
template<IUNICODECanUnambiguouslyConvertFrom CHAR_T>
nonvirtual void	Append (span< const CHAR_T > s)
template<typename APPEND_ARG_T > requires (requires (StringBuilder& s, APPEND_ARG_T&& a) { s.Append (forward<APPEND_ARG_T> (a)); })
nonvirtual auto	operator+= (APPEND_ARG_T &&a) -> StringBuilder &
template<typename APPEND_ARG_T > requires (Characters::Private_::IToString<APPEND_ARG_T> or requires (StringBuilder& s, APPEND_ARG_T&& a) { s.Append (forward<APPEND_ARG_T> (a)); })
nonvirtual auto	operator<< (APPEND_ARG_T &&a) -> StringBuilder &
nonvirtual size_t	size () const noexcept
nonvirtual bool	empty () const noexcept
nonvirtual Character	GetAt (size_t index) const noexcept
nonvirtual void	SetAt (Character item, size_t index) noexcept
nonvirtual const Character	operator[] (size_t i) const noexcept
	return (read-only) Character object
template<Common::IAnyOf< char, Character, String, span< const Character >, span< Character > > T>
nonvirtual void	InsertAt (T c, size_t at)
nonvirtual void	ShrinkTo (size_t sz) noexcept
template<Common::IAnyOf< String, wstring, u8string, u16string, u32string > RESULT_T>
nonvirtual RESULT_T	As () const
nonvirtual String	str () const
nonvirtual size_t	length () const noexcept
	number of characters, not bytes or code-points
nonvirtual span< BufferElementType >	data ()
template<IUNICODECanUnambiguouslyConvertFrom CHAR_T> requires (not is_const_v<CHAR_T>)
nonvirtual span< const CHAR_T >	GetData (Memory::StackBuffer< CHAR_T > *probablyIgnoredBuf) const
	access a span of data located inside the StringBuilder. Return internal pointer, or pointer internal to possiblyUsedBuffer

Detailed Description

template<typename OPTIONS = StringBuilder_Options<>>
class Stroika::Foundation::Characters::StringBuilder< OPTIONS >

Similar to String, but intended to more efficiently construct a String. Mutable type (String is largely immutable).

Has operator String() co can be used by value most places you can use a String.

See also

String

.Net StringBuilder - http://msdn.microsoft.com/en-us/library/system.text.stringbuilder(v=vs.110).aspx

Java StringBuilder - http://docs.oracle.com/javase/7/docs/api/java/lang/StringBuilder.html

Note

Thread-Safety C++-Standard-Thread-Safety

Definition at line 71 of file StringBuilder.h.

Member Function Documentation

Append()

template<typename OPTIONS = StringBuilder_Options<>>

template<IUNICODECanUnambiguouslyConvertFrom CHAR_T>

nonvirtual void Stroika::Foundation::Characters::StringBuilder< OPTIONS >::Append

(

span< const CHAR_T >

s

)

Append the given argument characters to this buffer.

argument characters can be given by o span<unicode (or narrow ASCII) characters> o const T* - nul-terminated array of unicode (or narrow ASCII) characters o basic_string<unicode (or narrow ASCII) characters> o basic_string_view<unicode (or narrow ASCII) characters> o String o Character

This function appends as IF the argument was converted to a UNICODE string, and then appended.

operator+=()

template<typename OPTIONS = StringBuilder_Options<>>

template<typename APPEND_ARG_T >
requires (requires (StringBuilder& s, APPEND_ARG_T&& a) { s.Append (forward<APPEND_ARG_T> (a)); })

nonvirtual auto Stroika::Foundation::Characters::StringBuilder< OPTIONS >::operator+=

(

APPEND_ARG_T &&

a

)

-> StringBuilder &

Aliases

Append

operator<<()

template<typename OPTIONS = StringBuilder_Options<>>

template<typename APPEND_ARG_T >
requires (Characters::Private_::IToString<APPEND_ARG_T> or requires (StringBuilder& s, APPEND_ARG_T&& a) { s.Append (forward<APPEND_ARG_T> (a)); })

nonvirtual auto Stroika::Foundation::Characters::StringBuilder< OPTIONS >::operator<<

(

APPEND_ARG_T &&

a

)

-> StringBuilder &

Aliases

Append if that would work, and otherwise alias for Append (ToString(arg)), if that would work;

size()

template<typename OPTIONS >

size_t Stroika::Foundation::Characters::StringBuilder< OPTIONS >::size ( ) const

noexcept

returns number of characters (not bytes, not including any possible NUL-terminator)

Definition at line 206 of file StringBuilder.inl.

empty()

template<typename OPTIONS >

bool Stroika::Foundation::Characters::StringBuilder< OPTIONS >::empty ( ) const

noexcept

Returns true if this is an empty string (aka iff size () == 0);

Definition at line 217 of file StringBuilder.inl.

GetAt()

template<typename OPTIONS >

Character Stroika::Foundation::Characters::StringBuilder< OPTIONS >::GetAt ( size_t  index ) const

noexcept

Note

- this can be very slow if OPTIONS::BufferElementType != char32_t (but if StringBuilder_Options<char32_t> its fast)

Definition at line 223 of file StringBuilder.inl.

SetAt()

template<typename OPTIONS >

void Stroika::Foundation::Characters::StringBuilder< OPTIONS >::SetAt ( Character  item, size_t  index  )

noexcept

Note

- this can be very slow if OPTIONS::BufferElementType != char32_t (but if StringBuilder_Options<char32_t> its fast)

Definition at line 238 of file StringBuilder.inl.

operator[]()

template<typename OPTIONS >

const Character Stroika::Foundation::Characters::StringBuilder< OPTIONS >::operator[] ( size_t  i ) const

noexcept

return (read-only) Character object

Aliases

GetAt (size_t i) const;

Note

this is very inefficient, unless using StringBuilder_Options<char32_t> - in which case its quite fast

Definition at line 257 of file StringBuilder.inl.

InsertAt()

template<typename OPTIONS = StringBuilder_Options<>>

template<Common::IAnyOf< char, Character, String, span< const Character >, span< Character > > T>

nonvirtual void Stroika::Foundation::Characters::StringBuilder< OPTIONS >::InsertAt	(	T	c,
		size_t	at
	)

Mimic the String::InsertAt API, except modify in place.

ShrinkTo()

template<typename OPTIONS >

void Stroika::Foundation::Characters::StringBuilder< OPTIONS >::ShrinkTo ( size_t  sz )

noexcept

Change the size of this object to sz = where sz must be <= size()

Definition at line 271 of file StringBuilder.inl.

As()

template<typename OPTIONS = StringBuilder_Options<>>

template<Common::IAnyOf< String, wstring, u8string, u16string, u32string > RESULT_T>

nonvirtual RESULT_T Stroika::Foundation::Characters::StringBuilder< OPTIONS >::As

(

)

const

Only specifically specialized variants are supported. Convert String losslessly into a o String or o wstring o u8string o u16string o u32string

str()

template<typename OPTIONS >

String Stroika::Foundation::Characters::StringBuilder< OPTIONS >::str

(

)

const

mimic wstringstream method

Definition at line 284 of file StringBuilder.inl.

length()

template<typename OPTIONS >

size_t Stroika::Foundation::Characters::StringBuilder< OPTIONS >::length ( ) const

noexcept

number of characters, not bytes or code-points

Aliases

size ()

Definition at line 348 of file StringBuilder.inl.

data()

template<typename OPTIONS >

auto Stroika::Foundation::Characters::StringBuilder< OPTIONS >::data

(

)

ONLY valid til the next non-const call to StringBuilder. See also GetData (to select a different charType).

Definition at line 353 of file StringBuilder.inl.

GetData()

template<typename OPTIONS = StringBuilder_Options<>>

template<IUNICODECanUnambiguouslyConvertFrom CHAR_T>
requires (not is_const_v<CHAR_T>)

nonvirtual span< const CHAR_T > Stroika::Foundation::Characters::StringBuilder< OPTIONS >::GetData

(

Memory::StackBuffer< CHAR_T > *

probablyIgnoredBuf

)

const

access a span of data located inside the StringBuilder. Return internal pointer, or pointer internal to possiblyUsedBuffer

Note

Lifetime of resulting span is ONLY until the next change to the StackBuffer OR the StringBuilder.

The pointer MIGHT refer to data inside the (possibly resized) StackBuffer, or be internal to the StringBuilder

The point of this queer API is too allow accessing the internal data by pointer, but allow StringBuilder to change its internal representation (not necessarily matching the kind of string being requested).

Note

Caller should ignore the size of possiblyUsedBuffer; its for internal use inside of GetData() - and may not match the size of the resulting string/span. Note also, the span will not in general be NUL-terminated.

Why use this function? You would think the point of StringBuilder was to - well - build a string - right? So why not use the str() API. Well, that allocates memory, which must be freed, and that is not cost free. For some short-lived strings, it CAN be cheaper to just peek at the constructed in memory stack based String already being produced in this StringBuilder.

But this needs to be done in a way with data hiding (so we can change the internal representation of the StringBuilder class as needed) and with respect for the possibility that the string could be large (so break out of any small-string optimizations).

Passing in a reference to the 'StackBuffer' class is a compromise among all these considerations. The only cost is initializing a pointer, and checking that pointer on destruction, if no memory allocation is needed.

Example Usage:

Memory::StackBuffer<wchar_t> probablyIgnoredBuf;
span<const wchar_t> s = sb.GetData (&probablyIgnoredBuf);

Memory::StackBuffer<wchar_t> probablyIgnoredBuf;
out.Write (sb.GetData (&probablyIgnoredBuf));

---

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

• StringBuilder.h
• StringBuilder.inl