Python-style kwargs in C++

When dealing with functions that have lots of optional parameters, or at least for which resonable defaults are readily available, it's often a bit of a frustration in C++. Generally defaults are specified during a function as in:

double BinarySearch(std::function<double(double> fn,
                    int max_depth = 16, double epsilon = 1e-9,
                    double lower_bound = 0, double upper_bound = 100);

And then if we call BinarySearch with only one parameter then the call will use the default values for the rest. But what if I want to specify custom bound, but use the defaults for the other parameters? Admittedly, this is a contrived example since bounds are less likely to be optional then the others, and we could reorder them better going from most-likely-to-be-specified to least, but it's easy to see how something more flexible would be desirable.

Consider then the following two code snippets. Which is more readable?

First snippet:

double solution = BinarySearch(fn, 0, 100);

Second snippet:

double solution = BinarySearch(fn, lower_bound = 0, upper_bound = 100);

I really like the way that optional arguments work in python with kwargs. I'd love to have that same kind of functionality in C++. kwargs.h implements one mechanism of achieving this.

How does it work

kwargs takes advantage of variadic templates in C++ to build up a single data structure which contains all of the optional parameters (I'll call this a "parameter pack"). Each optional parameter of type T is stored in a structure of type Arg<tag,T> where tag is a unique numeric identifier associated with a particular optional argument key.

The parameter pack data structure derives from Arg<tag,T> for each (tag,T) pair that shows up in the list of optional arguments.

Overloading of the equals (=) operator gives us an opportunity for building the (tag,T) pairs within the parameter list of the function call.

Examples

Example 1

Source

#include <iostream>
#include "kwargs/kwargs.h"

// these are tags which will uniquely identify the arguments in a parameter
// pack
enum Keys {
  c_tag,
  d_tag
};

// global symbols used as keys in list of kwargs
kw::Key<c_tag> c_key;
kw::Key<d_tag> d_key;

// a function taking kwargs parameter pack
template <typename... Args>
void foo(int a, int b, Args... kwargs) {
  // first, we construct the parameter pack from the parameter pack
  kw::ParamPack<Args...> params(kwargs...);

  std::cout << "foo:\n--------"
            << "\na: " << a
            << "\nb: " << b
  // We can attempt to retrieve a key while providing a default fallback value.
  // If c_key is in kwargs then this will return the value associated with
  // that key, and will have the correct type. Note that the type of the default
  // parameter in this case is const char*.
            << "\nc: " << kw::Get(params,c_key,"null");
  // We can also do stuff conditionally based on whether or not arg exists in
  // the param pack. We still need to provide a default value, since we need to
  // know the return type of the Get function when the key is not in kwargs.
  // In this case, the default value wont ever be used at runtime.
  if( kw::ContainsTag<c_tag,Args...>::result ) {
    std::cout << "\nd: " << kw::Get(params,d_key,0);
  }

  std::cout << "\n\n";
}

int main( int argc, char** argv )
{
  foo(1, 2);
  foo(1, 2, c_key=3);
  foo(1, 2, c_key=3, d_key=4);
  foo(1, 2, d_key=4);
}

Output

foo:
--------
a: 1
b: 2
c: null

foo:
--------
a: 1
b: 2
c: 3
d: 0

foo:
--------
a: 1
b: 2
c: 3
d: 4

foo:
--------
a: 1
b: 2
c: null

Example 2

Source

#include <iostream>
#include "kwargs/kwargs.h"

// Tags are just numeric constants that allow us to gerate a unique type for
// all of our keys. We can use enums, as in the previous example, or we can
// can use straight up literals. Though the enums are a lot more readable.
kw::Key<1> c_key;

// We can utilize namespaces to keep our tag names from clobbering each other.
namespace test {

enum Tags {
  c_tag,
  d_tag
};

kw::Key<c_tag> c_key;
kw::Key<d_tag> d_key;

}  // namespace test

template <typename... Args>
void foo(int a, int b, Args... kwargs) {
  kw::ParamPack<Args...> params(kwargs...);

  std::cout << "foo:\n-------"
            << "\na: " << a
            << "\nb: " << b
            // If we want to retrieve a parameter by it's tag value, and not
            // it's key name, we can do that to, but this is pretty low-level.
            << "\nc: " << kw::Get<0>(params,"null")
            // Generally, using the key name is more readable.
            << "\nd: " << kw::Get(params,test::d_key,"null")
            << "\n\n";
}

int main( int argc, char** argv )
{
  foo(1, 2);
  // foo() unpacks paremeter tagged with "0" so we can use any kw::Key<0> to
  // assign it.
  foo(1, 2, kw::Key<0>() = 3);
  // Generally speaking, using a declared Key is more readable though, and
  // more in the spirit of python-like kwargs.
  foo(1, 2, test::c_key = 3);
  // Unfortunately this opens up the avenue for abuse by using keys other than
  // the intended key. For instance we can use c_key from the root namespace,
  // which in fact packs the parameter with Key<1>, not Key<0> which is what
  // would be packed with test::c_key... So we need to be careful and use
  // the right keys.
  foo(1, 2, c_key = 3);
}

Output

foo:
-------
a: 1
b: 2
c: null
d: null

foo:
-------
a: 1
b: 2
c: 3
d: null

foo:
-------
a: 1
b: 2
c: 3
d: null

foo:
-------
a: 1
b: 2
c: null
d: 3

Example 3

Source

#include <iostream>
#include "kwargs/kwargs.h"

enum Keys {
  c_tag,
  d_tag
};

kw::Key<c_tag> c_key;
kw::Key<d_tag> d_key;

// This is a dummy class which just prints to cout whenever it is c'tor-ed or
// d'tor-ed to demonstrate the amount of copying that may happen
class Test {
 public:
  Test(const Test& other) { Construct(); }
  Test() { Construct(); }

  ~Test() {
    std::cout << "Destroyed object " << obj_id_ << "\n";
  }

  int GetId() const { return obj_id_; }

 private:
  void Construct() {
    obj_id_ = n_objs_++;
    std::cout << "Created object " << obj_id_ << "\n";
  }
  int obj_id_;
  static int n_objs_;
};

int Test::n_objs_ = 0;

// when we print a test object, print it's ID
std::ostream& operator<<( std::ostream& out, const Test& test ){
  out << test.GetId();
  return out;
}

// when we print a test object pointer, print the object's id
std::ostream& operator<<( std::ostream& out, const Test* test ){
  out << "*" << test->GetId();
  return out;
}

template <typename... Args>
void foo(int a, int b, Args... kwargs) {
  kw::ParamPack<Args...> params(kwargs...);

  std::cout << "foo:\n----"
            << "\na: " << a
            << "\nb: " << b
            << "\ne: " << kw::Get(params,c_key,"null")
            << "\nf: " << kw::Get(params,d_key,"null")
            << "\n\n";
}

int main( int argc, char** argv )
{
  // Note that 5 test objects are created. The object that shows up in foo()
  // is in fact the 4th copy of the original object!
  foo(1, 2, c_key=Test());

  // We can avoid unnecessary copies by forcing the parameter to be passed
  // by const ref. In this case, only one Test object is actually made.
  foo(1, 2, d_key=kw::ConstRef(Test()));

  Test test_obj;
  // We can use ConstRef on non-temporaries too. No additional object's are
  // created, and foo() see's a reference to test_obj itself.
  foo(1, 2, d_key=kw::ConstRef(test_obj));

  // For non-temporaries, we can use non-const ref as well. Again no additional
  // object's are created, and foo() see's a reference to test_obj itself.
  foo(1, 2, d_key=kw::Ref(test_obj));

  // Though, in general, if foo() needs to modify the object it may be better
  // to pass a pointer. In this case foo() get's a non-const pointer to
  // test_obj.
  foo(1, 2, d_key=&test_obj);
}

Output

Created object 0
Created object 1
Created object 2
Destroyed object 1
Created object 3
Created object 4
Destroyed object 3
Created object 5
foo:
----
a: 1
b: 2
e: 5
f: null

Destroyed object 5
Destroyed object 4
Destroyed object 2
Destroyed object 0
Created object 6
foo:
----
a: 1
b: 2
e: null
f: 6

Destroyed object 6
Created object 7
foo:
----
a: 1
b: 2
e: null
f: 7

foo:
----
a: 1
b: 2
e: null
f: 7

foo:
----
a: 1
b: 2
e: null
f: *7

Destroyed object 7