What's the purpose of this function that does nearly nothing?

Question

I'm currently reading the code of RapidJSON, and I don't understand this bit of code:

//! Reserve n characters for writing to a stream.
template<typename Stream>
inline void PutReserve(Stream& stream, size_t count) {
    (void)stream;
    (void)count;
}

//! Put N copies of a character to a stream.
template<typename Stream, typename Ch>
inline void PutN(Stream& stream, Ch c, size_t n) {
    PutReserve(stream, n);// I think this function does nothing
    for (size_t i = 0; i < n; i++)
        PutUnsafe(stream, c);
}

Can anyone explain the purpose of 'PutReserve' for me?

It could also be there to have a common interface. There is a `PutReserve` in [here](https://github.com/Tencent/rapidjson/blob/7e68aa0a21b7800ec98133cb106e49bd6536e25c/include/rapidjson/stringbuffer.h) that actually does something so this could be a function that "does nothing if not implemented for that stream type function" — NathanOliver, Jan 07 '19 at 13:57
In some cases, functions that do nothing are meant to have "no-operation" functionality. Sometimes the function name is `noop`. This is needed in cases where you need to provide a function callback to something, but you don't necessarily have anything to do. So juts give it a function that does nothing. — Lansana Camara, Jan 07 '19 at 13:59
Note `PutN` is a template which needs some functionality called `PutReserve`. By default it does noting, but there can be specialization of `PutReserve` template which it does something useful and is such case `PutN` will use alternative version. — Marek R, Jan 07 '19 at 14:08

Max Langhof · Accepted Answer · 2019-01-07T17:59:02.040

7

This code allows others to specialize PutReserve for their own stream types. This gives other forms of streams the option to act on the information passed here - in this case, that count characters are about to be inserted into the stream.

You are correct that the repository has no such specialization right now, thus nothing will ever happen from this code alone. However, if this is intended as an option for extension by users (or future extension within the library), it still has a purpose. And if it remains unspecialized, the compiler will of course see that the function does nothing and completely optimize it away.

In practice, a user that wants to use this library with his MyStream type would specialize the function like this:

template<> void PutReserve(MyStream& stream, size_t count) {
  // ...user code
}

Note however that the C++ standard library is going to eliminate all forms of function template specialization (in namespace std) in a future C++ version, replacing them by functor classes as "customization points". See this question for the rationale.

edited Jan 07 '19 at 17:59

answered Jan 07 '19 at 14:09

Max Langhof

23,383
5
39
72

Maybe you can explain a bit how this specialization is done, with a simple explanation and example of ADL with a custom stream type – KABoissonneault Jan 07 '19 at 14:13
thank you,does **the compiler will of course see that the function does nothing and completely optimize it away** can be relied on in production code? – maidamai Jan 07 '19 at 14:18
@maidamai Yes. If you do optimized builds, of course. – Max Langhof Jan 07 '19 at 14:18
This is a bit misleading because C++20 will not eliminate *overloading*, which can also be used to provide template customization points. However, such an overload cannot be in or under `namespace std` i.e. needs to be ADL-friendly. `swap`, `begin`, `end`, and some others are explicitly mentioned as customization points in this manner. The change mostly forbids (IMO) weird things like providing an explicit specialization of `std::sort`. Weird, among other things, because it only works with the exact types of iterators and e.g. comparison function. – Arne Vogel Jan 07 '19 at 17:54
1

@ArneVogel I clarified that part a bit. Yes, there are more customization points, but I meant to specifically talk about specializing `std` function templates. – Max Langhof Jan 07 '19 at 18:00

What's the purpose of this function that does nearly nothing?

1 Answers1