cat: concatenate arguments to string

Functions
template<class Arg, class... Args>
size_t	c4::cat (substr buf, Arg const &a, Args const &...more)
	serialize the arguments, concatenating them to the given fixed-size buffer.
template<class... Args>
substr	c4::cat_sub (substr buf, Args const &...args)
	like c4::cat() but return a substr instead of a size
template<class CharOwningContainer, class... Args>
void	c4::catrs (CharOwningContainer *cont, Args const &...args)
	cat+resize: like c4::cat(), but receives a container, and resizes it as needed to contain the result.
template<class CharOwningContainer, class... Args>
CharOwningContainer	c4::catrs (Args const &...args)
	cat+resize: like c4::cat(), but creates and returns a new container sized as needed to contain the result.
template<class CharOwningContainer, class... Args>
csubstr	c4::catrs_append (CharOwningContainer *cont, Args const &...args)
	cat+resize+append: like c4::cat(), but receives a container, and appends to it instead of overwriting it.

Detailed Description

Function Documentation

cat()

template<class Arg, class... Args>

size_t c4::cat	(	substr	buf,
		Arg const &	a,
		Args const &...	more )

serialize the arguments, concatenating them to the given fixed-size buffer.

The buffer size is strictly respected: no writes will occur beyond its end.

Returns

the number of characters needed to write all the arguments into the buffer.

See also

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

c4::uncat() for the inverse function

c4::catsep() if a separator between each argument is to be used

c4::format() if a format string is desired

Note

The arguments to format are restricted (legal because they are rvalues). This may require a workaround when arguments of type char[]/const char[] are passed repeatedly to the function. For example,

const char str[] = "Hi! ";
cat(buf, str, str, str); // compile error: 'passing argument 2 to ‘restrict’-qualified parameter aliases with arguments 3, 4'

It is possible to work around the problem by suppressing -Wrestrict or by using the decayed type char* or const char*, or even wrapping the argument in a csubstr():

const char str[] = "Hi! ";
csubstr ss = to_csubstr(str);
cat(buf, ss, ss, ss); // ok! compiles cleanly

Definition at line 649 of file format.hpp.

{
    size_t num = to_chars(buf, a);
    buf  = buf.len >= num ? buf.sub(num) : substr{};
    num += cat(buf, more...);
    return num;
}

Referenced by cat(), cat_sub(), catrs(), catrs_append(), and sample_formatting().

cat_sub()

template<class... Args>

substr c4::cat_sub	(	substr	buf,
		Args const &...	args )

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

Definition at line 659 of file format.hpp.

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

Referenced by sample_formatting().

catrs() [1/2]

template<class CharOwningContainer, class... Args>

void c4::catrs ( CharOwningContainer * cont, Args const &... args )

inline

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

The container is overwritten. To append to it, use c4::catrs_append().

See also

c4::cat()

c4::catrs_append()

Note

The arguments to format are restricted (legal because they are rvalues). This may require a workaround when arguments of type char[]/const char[] are passed repeatedly to the function. For example,

const char str[] = "Hi! ";
cat(buf, str, str, str); // compile error: 'passing argument 2 to ‘restrict’-qualified parameter aliases with arguments 3, 4'

It is possible to work around the problem by suppressing -Wrestrict or by using the decayed type char* or const char*, or even wrapping the argument in a csubstr():

const char str[] = "Hi! ";
csubstr ss = to_csubstr(str);
cat(buf, ss, ss, ss); // ok! compiles cleanly

Definition at line 1040 of file format.hpp.

{
    cont->resize(cont->capacity()); // improve the odds of fitting in the original buffer
retry:
    substr buf = to_substr(*cont);
    size_t ret = cat(buf, args...);
    cont->resize(ret);
    if(ret > buf.len)
        goto retry;
}

Referenced by catrs(), and sample_formatting().

catrs() [2/2]

template<class CharOwningContainer, class... Args>

CharOwningContainer c4::catrs ( Args const &... args )

inline

cat+resize: like c4::cat(), but creates and returns a new container sized as needed to contain the result.

See also

c4::cat()

Note

The arguments to format are restricted (legal because they are rvalues). This may require a workaround when arguments of type char[]/const char[] are passed repeatedly to the function. For example,

const char str[] = "Hi! ";
cat(buf, str, str, str); // compile error: 'passing argument 2 to ‘restrict’-qualified parameter aliases with arguments 3, 4'

It is possible to work around the problem by suppressing -Wrestrict or by using the decayed type char* or const char*, or even wrapping the argument in a csubstr():

const char str[] = "Hi! ";
csubstr ss = to_csubstr(str);
cat(buf, ss, ss, ss); // ok! compiles cleanly

Definition at line 1075 of file format.hpp.

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

catrs_append()

template<class CharOwningContainer, class... Args>

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

inline

cat+resize+append: like c4::cat(), but receives a container, and appends to it instead of overwriting it.

The container is resized as needed to contain the result.

Returns

the region newly appended to the original container

See also

c4::cat()

c4::catrs()

Note

The arguments to format are restricted (legal because they are rvalues). This may require a workaround when arguments of type char[]/const char[] are passed repeatedly to the function. For example,

const char str[] = "Hi! ";
cat(buf, str, str, str); // compile error: 'passing argument 2 to ‘restrict’-qualified parameter aliases with arguments 3, 4'

It is possible to work around the problem by suppressing -Wrestrict or by using the decayed type char* or const char*, or even wrapping the argument in a csubstr():

const char str[] = "Hi! ";
csubstr ss = to_csubstr(str);
cat(buf, ss, ss, ss); // ok! compiles cleanly

Definition at line 1109 of file format.hpp.

{
    const size_t pos = cont->size();
    cont->resize(cont->capacity()); // improve the odds of fitting in the original buffer
retry:
    substr buf = to_substr(*cont).sub(pos);
    size_t ret = cat(buf, args...);
    cont->resize(pos + ret);
    if(ret > buf.len)
        goto retry;
    return to_csubstr(*cont).range(pos, cont->size());
}

Referenced by sample_formatting().