C++ FAQ Celebrating Twenty-One Years of the C++ FAQ!!!
(Click here for a personal note from Marshall Cline.)
Section 10:
10.1 What's the deal with constructors?
10.2 Is there any difference between List x; and List x();?
10.3 Can one constructor of a class call another constructor of the same class to initialize the this object? Updated!
10.4 Is the default constructor for Fred always Fred::Fred()?
10.5 Which constructor gets called when I create an array of Fred objects?
10.6 Should my constructors use "initialization lists" or "assignment"?
10.7 Should you use the this pointer in the constructor?
10.8 What is the "Named Constructor Idiom"?
10.9 Does return-by-value mean extra copies and extra overhead?
10.10 Does the compiler optimize returning a local variable by value?
10.11 Why can't I initialize my static member data in my constructor's initialization list?
10.12 Why are classes with static data members getting linker errors?
10.13 Can I add = initializer; to the declaration of a class-scope static const data member?
10.14 What's the "static initialization order fiasco"?
10.15 How do I prevent the "static initialization order fiasco"?
10.16 Why doesn't the construct-on-first-use idiom use a static object instead of a static pointer?
10.17 How do I prevent the "static initialization order fiasco" for my static data members?
10.18 Do I need to worry about the "static initialization order fiasco" for variables of built-in/intrinsic types?
10.19 How can I handle a constructor that fails?
10.20 What is the "Named Parameter Idiom"?
10.21 Why am I getting an error after declaring a Foo object via Foo x(Bar())?
10.22 What is the purpose of the explicit keyword?
[10.20] What is the "Named Parameter Idiom"?

It's a fairly useful way to exploit method chaining.

The fundamental problem solved by the Named Parameter Idiom is that C++ only supports positional parameters. For example, a caller of a function isn't allowed to say, "Here's the value for formal parameter xyz, and this other thing is the value for formal parameter pqr." All you can do in C++ (and C and Java) is say, "Here's the first parameter, here's the second parameter, etc." The alternative, called named parameters and implemented in the language Ada, is especially useful if a function takes a large number of mostly default-able parameters.

Over the years people have cooked up lots of workarounds for the lack of named parameters in C and C++. One of these involves burying the parameter values in a string parameter then parsing this string at run-time. This is what's done in the second parameter of fopen(), for example. Another workaround is to combine all the boolean parameters in a bit-map, then the caller or's a bunch of bit-shifted constants together to produce the actual parameter. This is what's done in the second parameter of open(), for example. These approaches work, but the following technique produces caller-code that's more obvious, easier to write, easier to read, and is generally more elegant.

The idea, called the Named Parameter Idiom, is to change the function's parameters to methods of a newly created class, where all these methods return *this by reference. Then you simply rename the main function into a parameterless "do-it" method on that class.

We'll work an example to make the previous paragraph easier to understand.

The example will be for the "open a file" concept. Let's say that concept logically requires a parameter for the file's name, and optionally allows parameters for whether the file should be opened read-only vs. read-write vs. write-only, whether or not the file should be created if it doesn't already exist, whether the writing location should be at the end ("append") or the beginning ("overwrite"), the block-size if the file is to be created, whether the I/O is buffered or non-buffered, the buffer-size, whether it is to be shared vs. exclusive access, and probably a few others. If we implemented this concept using a normal function with positional parameters, the caller code would be very difficult to read: there'd be as many as 8 positional parameters, and the caller would probably make a lot of mistakes. So instead we use the Named Parameter Idiom.

Before we go through the implementation, here's what the caller code might look like, assuming you are willing to accept all the function's default parameters:

File f = OpenFile("foo.txt");
That's the easy case. Now here's what it might look like if you want to change a bunch of the parameters.
File f = OpenFile("foo.txt")
           .readonly()
           .createIfNotExist()
           .appendWhenWriting()
           .blockSize(1024)
           .unbuffered()
           .exclusiveAccess();
Notice how the "parameters", if it's fair to call them that, are in random order (they're not positional) and they all have names. So the programmer doesn't have to remember the order of the parameters, and the names are (hopefully) obvious.

So here's how to implement it: first we create a class (OpenFile) that houses all the parameter values as private data members. The required parameters (in this case, the only required parameter is the file's name) is implemented as a normal, positional parameter on OpenFile's constructor, but that constructor doesn't actually open the file. Then all the optional parameters (readonly vs. readwrite, etc.) become methods. These methods (e.g., readonly(), blockSize(unsigned), etc.) return a reference to their this object so the method calls can be chained.

class File;

class OpenFile {
public:
  OpenFile(std::string const& filename);
    // sets all the default values for each data member
  OpenFile& readonly();  // changes readonly_ to true
  OpenFile& readwrite(); // changes readonly_ to false
  OpenFile& createIfNotExist();
  OpenFile& blockSize(unsigned nbytes);
  ...
private:
  friend class File;
  std::string filename_;
  bool readonly_;          // defaults to false [for example]
  bool createIfNotExist_;  // defaults to false [for example]
  ...
  unsigned blockSize_;     // defaults to 4096 [for example]
  ...
};

inline OpenFile::OpenFile(std::string const& filename)
  : filename_         (filename)
  , readonly_         (false)
  , createIfNotExist_ (false)
  , blockSize_        (4096u)
{ }

inline OpenFile& OpenFile::readonly()
{ readonly_ = true; return *this; }

inline OpenFile& OpenFile::readwrite()
{ readonly_ = false; return *this; }

inline OpenFile& OpenFile::createIfNotExist()
{ createIfNotExist_ = true; return *this; }

inline OpenFile& OpenFile::blockSize(unsigned nbytes)
{ blockSize_ = nbytes; return *this; }
The only other thing to do is make the constructor for class File to take an OpenFile object:
class File {
public:
  File(OpenFile const& params);
  ...
};
This constructor gets the actual parameters from the OpenFile object, then actually opens the file:
File::File(OpenFile const& params)
{
  ...
}
Note that OpenFile declares File as its friend, that way OpenFile doesn't need a bunch of (otherwise useless) public: get methods.

Since each member function in the chain returns a reference, there is no copying of objects and the chain is highly efficient. Furthermore, if the various member functions are inline, the generated object code will probably be on par with C-style code that sets various members of a struct. Of course if the member functions are not inline, there may be a slight increase in code size and a slight decrease in performance (but only if the construction occurs on the critical path of a CPU-bound program; this is a can of worms I'll try to avoid opening; read the C++ FAQs book for a rather thorough discussion of the issues), so it may, in this case, be a tradeoff for making the code more reliable.