How to deprecate a function?

 Windows API  No Responses »
Aug 042008
 

Well what is deprecation? It’s just a way to tell the user that a better/safer function is available for a function which he is using!

For e.g. strcpy.

If you use strcpy in VC8 we’ll get a warning saying that it’s deprecated, instead use strcpy_s which is the secure version of this API.

So the question is how to deprecate a function using VC++ compiler. There are two options in VC++…

  1. Using __declspec(deprecated)
  2. Using #pragma deprecated

Using __declspec(deprecated) compiler directive.

// Helper #defines for deprecation compiler directive
#define deprecate __declspec(deprecated)
#define deprecate_msg(message) __declspec(deprecated(message))

First version is just plain, just produces default compiler warnings, while second version prints out a custom message along with the normal deprecation message.

// Deprecate a function
void deprecate OldFunction() {}

// Deprecate a class/struct
class deprecate OldClass {};

// This time with custom message //

// Deprecate a function, also tell the user that a better option exists
void
deprecate_msg( "******OldFunction is deprecated, start using NewFunction******" )
OldFunction()
{}
// Deprecate a class/struct, also tell the user that a better option exists
class
deprecate_msg( "******OldClass is deprecated, start using NewClass******" )
OldClass
{};

The output that I get looks like this

\consolegunieapig\consolegunieapig.cpp(144) : warning C4996: ‘OldFunction’ was declared deprecated
1> \consolegunieapig\consolegunieapig\consolegunieapig.cpp(124) : see declaration of ‘OldFunction’
1>        Message: ‘******OldFunction is deprecated, start using NewFunction******’
1>\consolegunieapig\consolegunieapig\consolegunieapig.cpp(145) : warning C4996: ‘OldClass’ was declared deprecated
1>\consolegunieapig\consolegunieapig\consolegunieapig.cpp(128) : see declaration of ‘OldClass’
1>        Message: ‘******OldClass is deprecated, start using NewClass******’

Using #pragma deprecated

Another option to deprecate a class/struct/function is to use the #pragma deprecated compiler directive.

The main difference is that using __declspec(deprecated) we can selective deprecate functions but with #pragma deprecated every function with that particular name is marked as deprecated. With #pragma deprecated you can even deprecate a macro.

This is how we use #pragma deprecated

void OldFunction() {}
void OldFunction( int i ) {}
class OldClass {};

// Note that both versions of OldFunction will be marked as deprecated.
#pragma deprecated(OldFunction,OldClass);