How to deprecate function when return type changes c++

Question

What strategies are there for deprecating functions when their return type needs to change? For example, I have:

BadObject foo(int); // Old function: BadObject is being removed. 
Object    foo(int); // New function. 

Object and BadObject are very different internally, and swapping their return types will break code for current users of my library. I'm aiming to avoid that.

I can mark BadObject foo(int) deprecated, and give users time to change affected code.
However, I can't overload foo based on return-type. foo is very well named, and it doesn't need to take extra parameters. How can I add the new function to my library whilst maintaining the old version, at least for a while?

What's the strategy to deprecate the old function without breaking too much dependant code, while providing users the time to migrate to the new version? Ideally I'd keep the current function name and parameter list, because it's named quite well now. It feels like this should be a reasonably common problem: what's a decent way to solve it?

Answer 1

Although the solution will force you to change your function names, but it'll be a compromise between your old users and your new ones.

So - rename the old foo into deprecatedFoo and your new foo into foo2 (or anything you want). Then, in the header file you include with your library, you can simply:

#define deprecatedFoo foo

and inside the function itself do:

#warning ("This function is deprecated. Use 'foo2' or change the #define in LINE in file HEADER.")

Users of the old versions won't have to change their code, and will be issued a warning, and the new users will probably listen and change the #define in order to use the new foo.

In the next version you'll just delete the old foo and the define.