Forward declaration of inline functions

Question

I have a header file that is going to contain a large amount (30+) of inline functions.

Rather than having the reader scroll or search for the definition (implementation) of the inline function, I would like to have a forward declaration section that states the function declaration with comments describing the function. This section would allow the reader to find out how to use a function or to look for a function without having to scroll down to the implementation.

Also, I would like the readers to get in the habit of using functions without having to see their implementations.

What is the syntax for a forward declaration of a stand-alone function?

{This applies to C99 and C++}

FYI, I am using IAR Workbench C compiler set to use C99.

Solution 1

No differently than a non-inline function:

void func();       // "forward" declaration

// ...

inline void func() // definition
{
    // impl
}

Typically the pattern used to "hide" the definitions from the library consumer is to put the declarations in one header (a.h) and the definitions in a second header (a_def.h), then have the former #include the latter (inclusion guards omitted for brevity):

// a.h
void func();
#include "a_def.h"

// a_def.h
inline void func()
{
    // impl
}

The library consumer would simply #include <a.h>.

Solution 2

You don't need to "forward declare" it (a term that is usually only applied to types, since we usually define them in the same place that we first declare them).

Just declare it, like normal:

#include <iostream>

void foo();            // Declaration

inline void foo() {    // Defining declaration
   std::cout << "!";
}

// ---------------------------------------------

int main() {
   foo();              // Output: foo()
}

Live demo.

Comments

[Thomas Matthews]

Perhaps I wasn't clear in my question, is there any issues with using a forward declaration for an inline function?

[Lightness Races in Orbit]

@ThomasMatthews: You asked for the syntax. But my answer also already covers your new question. And as it also says, don't call it "forward declaration".

[Kerrek SB]

There is actually no term "forward declaration" in C++ at all. It's just "declaration".

[Lightness Races in Orbit]

How come I get no votes, whereas an answer posted later gets 5? :(

[Lightness Races in Orbit]

@KerrekSB: The title of standard chapter 27.3 disagrees with you (and with whoever upvoted your incorrect comment). To save you looking it up, it's called "forward declarations", and it lists the forward declarations in iostreams. Hope that helps.

[Kerrek SB]

@LightnessRacesinOrbit: Citing <utility> for the forward declaration doesn't count! :-) OK, more seriously: Are chapter titles normative? Anyway, I'll have to have a word with that standard... I don't like being disagreed with :-)

[Lightness Races in Orbit]

@KerrekSB: There's also 9.1/2: "[..] A declaration consisting solely of class-key identifier; is either a redeclaration of the name in the current scope or a forward declaration of the identifier as a class name. It introduces the class name into the current scope. [..]" Now that's normative.

[Fabian]

How are the definitions hidden if they are only one file away? Is there any difference if I have the definitions in the same file below the declarations?

[ildjarn]

@Fabian : "Hide" is in quotes for a reason. ;-] No, there's no difference at all.

[a3f]

This is not correct for C99. Using a non-inline declaration together with an inline definition will emit an externally visible symbol in each translation unit where the header is included causing linking to fail with a duplicate symbol error.

[ildjarn]

@a3f : Well noted; this answer is for C++. (And this is why tagging multiple languages on a question is silly.)