format: formatted string interpolation

Functions
template<class Arg , class... Args>
size_t	c4::format (substr buf, csubstr fmt, Arg const &a, Args const &...more)
	using a format string, serialize the arguments into the given fixed-size buffer. More...
template<class... Args>
substr	c4::format_sub (substr buf, csubstr fmt, Args const &...args)
	like c4::format() but return a substr instead of a size More...
template<class CharOwningContainer , class... Args>
void	c4::formatrs (CharOwningContainer *cont, csubstr fmt, Args const &...args)
	format+resize: like c4::format(), but receives a container, and resizes it as needed to contain the result. More...
template<class CharOwningContainer , class... Args>
CharOwningContainer	c4::formatrs (csubstr fmt, Args const &...args)
	format+resize: like c4::format(), but create a new container with the result. More...
template<class CharOwningContainer , class... Args>
csubstr	c4::formatrs_append (CharOwningContainer *cont, csubstr fmt, Args const &...args)
	format+resize+append: like format(), but receives a container, and appends the arguments, resizing the container as needed to contain the result. More...

Detailed Description

Function Documentation

format()

template<class Arg , class... Args>

size_t c4::format	(	substr	buf,
		csubstr	fmt,
		Arg const &	a,
		Args const &...	more
	)

using a format string, serialize the arguments into the given fixed-size buffer.

The buffer size is strictly respected: no writes will occur beyond its end. In the format string, each argument is marked with a compact curly-bracket pair: {}. Arguments beyond the last curly bracket pair are silently ignored. For example:

c4::format(buf, "the {} drank {} {}", "partier", 5, "beers"); // the partier drank 5 beers
c4::format(buf, "the {} drank {} {}", "programmer", 6, "coffees"); // the programmer drank 6 coffees

Returns

the number of characters needed to write into the buffer.

See also

c4::formatrs() if instead of a fixed-size buffer, a resizeable container is desired

c4::unformat() for the inverse function

c4::cat() if no format or separator is needed

c4::catsep() if no format is needed, but a separator must be used

Definition at line 806 of file format.hpp.

{
    size_t pos = fmt.find("{}"); // @todo use _find_fmt()
    if(C4_UNLIKELY(pos == csubstr::npos))
        return to_chars(buf, fmt);
    size_t num = to_chars(buf, fmt.sub(0, pos));
    size_t out = num;
    buf  = buf.len >= num ? buf.sub(num) : substr{};
    num  = to_chars(buf, a);
    out += num;
    buf  = buf.len >= num ? buf.sub(num) : substr{};
    num  = format(buf, fmt.sub(pos + 2), more...);
    out += num;
    return out;
}

References c4::yml::npos, and c4::to_chars().

Referenced by c4::format_sub(), c4::formatrs(), c4::formatrs_append(), sample::sample_formatting(), and sample::to_chars().

format_sub()

template<class... Args>

substr c4::format_sub	(	substr	buf,
		csubstr	fmt,
		Args const &...	args
	)

like c4::format() but return a substr instead of a size

See also

c4::format()

c4::catsep(). uncatsep() is the inverse of catsep().

Definition at line 826 of file format.hpp.

{
    size_t sz = c4::format(buf, fmt, args...);
    C4_CHECK(sz <= buf.len);
    return {buf.str, sz <= buf.len ? sz : buf.len};
}

References c4::format().

Referenced by sample::sample_formatting().

formatrs() [1/2]

template<class CharOwningContainer , class... Args>

void c4::formatrs ( CharOwningContainer *  cont, csubstr  fmt, Args const &...  args  )

inline

format+resize: like c4::format(), but receives a container, and resizes it as needed to contain the result.

The container is overwritten. To append to the container use the append overload.

See also

c4::format()

Definition at line 995 of file format.hpp.

{
retry:
    substr buf = to_substr(*cont);
    size_t ret = format(buf, fmt, args...);
    cont->resize(ret);
    if(ret > buf.len)
        goto retry;
}

References c4::format(), and c4::to_substr().

Referenced by c4::formatrs(), and sample::sample_formatting().

formatrs() [2/2]

template<class CharOwningContainer , class... Args>

CharOwningContainer c4::formatrs ( csubstr  fmt, Args const &...  args  )

inline

format+resize: like c4::format(), but create a new container with the result.

Returns

the requested container

Definition at line 1011 of file format.hpp.

{
    CharOwningContainer cont;
    formatrs(&cont, fmt, args...);
    return cont;
}

References c4::formatrs().

formatrs_append()

template<class CharOwningContainer , class... Args>

csubstr c4::formatrs_append ( CharOwningContainer *  cont, csubstr  fmt, Args const &...  args  )

inline

format+resize+append: like format(), but receives a container, and appends the arguments, resizing the container as needed to contain the result.

The buffer is appended to.

Returns

the region newly appended to the original container

Definition at line 1025 of file format.hpp.

{
    const size_t pos = cont->size();
retry:
    substr buf = to_substr(*cont).sub(pos);
    size_t ret = format(buf, fmt, args...);
    cont->resize(pos + ret);
    if(ret > buf.len)
        goto retry;
    return to_csubstr(*cont).range(pos, cont->size());
}

References c4::format(), c4::to_csubstr(), and c4::to_substr().

Referenced by sample::sample_formatting().