Defining a Preprocessor Macro

Question

I'm relatively new to C++ and I'm taking a class on it. Our class was assigned a lab and my teacher has said that the lab write-up is a bit hard to understand; however, he did not make any changes to the lab write-up. So, I came across this part of the lab:

Defining a Preprocessor Macro

Long-standing convention capitalizes macro names, and this macro name must be TRACE_FUNC. The macro has a single parameter, a symbol that will be replaced by a function name when you apply the macro to the code. The start of the macro looks like this:

#define TRACE_FUNC( symbol )  replacement-text`

and the preprocessor will substitute the replacement text everywhere that the TRACE_FUNC( sym ) string exists in the source code, AND feed the symbol into that replacement.

NOTE: the #define statement must be all on a single, logical line. To keep the length manageable, you can escape the newline character with a backslash at the end of the line; that will keep the preprocessor happy while allowing you to span a definition across multiple lines.

For this exercise, the replacement text must be a complete statement, including the terminating semi-colon.

The replacement text must be an output statement that prints the symbol followed by the text () called. and a newline to standard output. You can copy and modify one of the output statements from the warning.cpp source file.

warning.cpp is just a file we're using and TRACE_FUNC is being placed in a header file.

So, I read this a couple times and I'm not 100% sure what it's asking. Looking at it one way, it seems like it's asking me to create a macro called TRACE_FUNC. If you look at it another way, it's asking me to use the macro TRACE_FUNC. All of that is fine, but I don't know how to use TRACE_FUNC at all, I can't find any documentation on it anywhere and I don't know how to create a macro. When I asked for help, my teacher just kind of said. words and not ones that were very helpful because it was a very winding, confusing answer with no explanation of what TRACE_FUNC actually is.

Basically, all that my teacher said was that the symbol within TRACE_FUNC needs to be the name of one of the functions in the source code. As an example, say we had a function foo() within warning, then the symbol is supposed to be foo() (or foo, I'm not sure of that, either), from his explanation. Also, in the replacement text, apparently the name itself will be replaced if I put # in front of the symbol. I thought that supposed to denote preprocessor directives. Why am I supposed to be using it here?

Anyway, doing what my teacher says pretty much does nothing. Neither this line

#define TRACE_FUNC( foo() ) #foo() called. ;

nor this line

#define TRACE_FUNC( foo ) #foo () called. ;

replace any text, which I'm pretty sure is the operation of the #define directive. So I must be applying what my teacher said in the wrong way, but I don't really know why it's wrong or how to fix it.

So, my question. Is TRACE_FUNC actually a macro and if so, is there any documentation on it that I can read? Or am I supposed to be creating TRACE_FUNC and if so, how exactly am I supposed to do that?

Answer 1

Wow, what utter rubbish! You're supposed to be learning C++ right, not intricacies of the preprocessor.

Here's what you are supposed to be doing, though why is anyone's guess.

#define TRACE_FUNC(sym) std::cout << #sym << "() called\n"

void foo()
{
  TRACE_FUNC(foo);
  ...
}

I'm assuming that there are examples from warning.cpp that use std::cout if not then you'll have to adapt the above to whatever you find in warning.cpp.

The idea is that each function starts with a use of the TRACE_FUNC macro, so you can trace the execution of your code. Why the professor thinks this is a good idea for newbies is beyond me. Even if it were a good idea, that you are expected to figure out the details for yourself is even stupider.

I could improve the macro above but that would probably confuse even more so I won't. For now I would just do what the professor says but ignore it. Hopefully he'll get onto stuff that's worth learning later.