Merged revisions 33188-33189,33191-33193,33196,33198,33202-33203,33206,33210,33212,33218-33220,33222,33224-33226,33229-33243,33246,33248-33250,33252,33258-33261,33263,33266,33270,33272-33283,33285,33287-33290,33295-33298,33321,33325-33330,33332-33335,33337-33340,33342,33345,33347,33349-33350,33352-33357,33359-33367,33369-33371,33373,33375-33377,33379-33380,33383-33385,33387-33389,33392-33394,33400-33402,33404-33405,33407-33410,33412-33416,33418-33419,33425-33427,33432,33436-33438,33444,33446 via svnmerge from

https://scummvm.svn.sourceforge.net/svnroot/scummvm/scummvm/trunk

svn-id: r33450

1 files changed, 125 insertions, 6 deletions

diff --git a/common/func.h b/common/func.h
index 95df96123a..1c045b9e5d 100644
--- a/common/func.h
+++ b/common/func.h
@@ -29,12 +29,18 @@
 
 namespace Common {
 
+/**
+ * Generic unary function.
+ */
 template<class Arg, class Result>
 struct UnaryFunction {
 	typedef Arg ArgumenType;
 	typedef Result ResultType;
 };
 
+/**
+ * Generic binary function.
+ */
 template<class Arg1, class Arg2, class Result>
 struct BinaryFunction {
 	typedef Arg1 FirstArgumentType;
@@ -42,16 +48,25 @@ struct BinaryFunction {
 	typedef Result ResultType;
 };
 
+/**
+ * Predicate to check for equallity of two data elements.
+ */
 template<class T>
 struct EqualTo : public BinaryFunction<T, T, bool> {
 	bool operator()(const T &x, const T &y) const { return x == y; }
 };
 
+/**
+ * Predicate to check for x being less than y.
+ */
 template<class T>
 struct Less : public BinaryFunction<T, T, bool> {
 	bool operator()(const T &x, const T &y) const { return x < y; }
 };
 
+/**
+ * Predicate to check for x being greater than y.
+ */
 template<class T>
 struct Greater : public BinaryFunction<T, T, bool> {
 	bool operator()(const T &x, const T &y) const { return x > y; }
@@ -70,6 +85,10 @@ public:
 	}
 };
 
+/**
+ * Transforms a binary function object into an unary function object.
+ * To achieve that the first parameter is bound to the passed value t.
+ */
 template<class Op, class T>
 inline Binder1st<Op> bind1st(const Op &op, const T &t) {
 	return Binder1st<Op>(op, t);
@@ -88,6 +107,10 @@ public:
 	}
 };
 
+/**
+ * Transforms a binary function object into an unary function object.
+ * To achieve that the second parameter is bound to the passed value t.
+ */
 template<class Op, class T>
 inline Binder2nd<Op> bind2nd(const Op &op, const T &t) {
 	return Binder2nd<Op>(op, t);
@@ -119,11 +142,17 @@ public:
 	}
 };
 
+/**
+ * Creates an unary function object from a function pointer.
+ */
 template<class Arg, class Result>
 inline PointerToUnaryFunc<Arg, Result> ptr_fun(Result (*func)(Arg)) {
 	return PointerToUnaryFunc<Arg, Result>(func);
 }
 
+/**
+ * Creates an binary function object from a function pointer.
+ */
 template<class Arg1, class Arg2, class Result>
 inline PointerToBinaryFunc<Arg1, Arg2, Result> ptr_fun(Result (*func)(Arg1, Arg2)) {
 	return PointerToBinaryFunc<Arg1, Arg2, Result>(func);
@@ -143,7 +172,7 @@ public:
 };
 
 template<class Result, class T>
-class ConstMemFunc0 : public UnaryFunction<T*, Result> {
+class ConstMemFunc0 : public UnaryFunction<T *, Result> {
 private:
 	Result (T::*_func)() const;
 public:
@@ -156,7 +185,7 @@ public:
 };
 
 template<class Result, class Arg, class T>
-class MemFunc1 : public BinaryFunction<T*, Arg, Result> {
+class MemFunc1 : public BinaryFunction<T *, Arg, Result> {
 private:
 	Result (T::*_func)(Arg);
 public:
@@ -169,7 +198,7 @@ public:
 };
 
 template<class Result, class Arg, class T>
-class ConstMemFunc1 : public BinaryFunction<T*, Arg, Result> {
+class ConstMemFunc1 : public BinaryFunction<T *, Arg, Result> {
 private:
 	Result (T::*_func)(Arg) const;
 public:
@@ -181,21 +210,43 @@ public:
 	}
 };
 
+/**
+ * Creates a unary function object from a class member function pointer.
+ * The parameter passed to the function object is the 'this' pointer to
+ * be used for the function call.
+ */
 template<class Result, class T>
 inline MemFunc0<Result, T> mem_fun(Result (T::*f)()) {
 	return MemFunc0<Result, T>(f);
 }
 
+/**
+ * Creates a unary function object from a class member function pointer.
+ * The parameter passed to the function object is the 'this' pointer to
+ * be used for the function call.
+ */
 template<class Result, class T>
 inline ConstMemFunc0<Result, T> mem_fun(Result (T::*f)() const) {
 	return ConstMemFunc0<Result, T>(f);
 }
 
+/**
+ * Creates a binary function object from a class member function pointer.
+ * The first parameter passed to the function object is the 'this' pointer to
+ * be used for the function call.
+ * The second one is the parameter passed to the member function.
+ */
 template<class Result, class Arg, class T>
 inline MemFunc1<Result, Arg, T> mem_fun(Result (T::*f)(Arg)) {
 	return MemFunc1<Result, Arg, T>(f);
 }
 
+/**
+ * Creates a binary function object from a class member function pointer.
+ * The first parameter passed to the function object is the 'this' pointer to
+ * be used for the function call.
+ * The second one is the parameter passed to the member function.
+ */
 template<class Result, class Arg, class T>
 inline ConstMemFunc1<Result, Arg, T> mem_fun(Result (T::*f)(Arg) const) {
 	return ConstMemFunc1<Result, Arg, T>(f);
@@ -203,6 +254,11 @@ inline ConstMemFunc1<Result, Arg, T> mem_fun(Result (T::*f)(Arg) const) {
 
 // functor code
 
+/**
+ * Generic functor object for function objects without parameters.
+ *
+ * @see Functor1
+ */
 template<class Res>
 struct Functor0 {
 	virtual ~Functor0() {}
@@ -211,6 +267,18 @@ struct Functor0 {
 	virtual Res operator()() const = 0;
 };
 
+/**
+ * Functor object for a class member function without parameter.
+ *
+ * Example creation:
+ *
+ * Foo bar;
+ * Functor0Men<void, Foo> myFunctor(&bar, &Foo::myFunc);
+ *
+ * Example usage:
+ *
+ * myFunctor();
+ */
 template<class Res, class T>
 class Functor0Mem : public Functor0<Res> {
 public:
@@ -218,7 +286,7 @@ public:
 
 	Functor0Mem(T *t, const FuncType &func) : _t(t), _func(func) {}
 
-	bool isValid() const { return _func != 0; }
+	bool isValid() const { return _func != 0 && _t != 0; }
 	Res operator()() const {
 		return (_t->*_func)();
 	}
@@ -227,6 +295,38 @@ private:
 	const FuncType _func;
 };
 
+/**
+ * Generic functor object for unary function objects.
+ *
+ * A typical usage for an unary function object is for executing opcodes
+ * in a script interpreter. To achieve that one can create an Common::Array
+ * object with 'Functor1<Arg, Res> *' as type. Now after the right engine version
+ * has been determined and the opcode table to use is found one could easily
+ * add the opcode implementations like this:
+ *
+ * Common::Array<Functor1<ScriptState, void> *> opcodeTable;
+ * opcodeTable[0] = new Functor1Mem<ScriptState, void, MyEngine_v1>(&myEngine, &MyEngine_v1::o1_foo);
+ * opcodeTable[1] = new Functor1Mem<ScriptState, void, MyEngine_v2>(&myEngine, &MyEngine_v2::o2_foo);
+ * // unimplemented/unused opcode
+ * opcodeTable[2] = 0;
+ * etc.
+ *
+ * This makes it easy to add member functions of different classes as
+ * opcode functions to the function table. Since with the generic
+ * Functor1<ScriptState, void> object the only requirement for an
+ * function to be used is 'ScriptState' as argument and 'void' as return
+ * value.
+ *
+ * Now for calling the opcodes one has simple to do:
+ * if (opcodeTable[opcodeNum] && opcodeTable[opcodeNum]->isValid())
+ *     (*opcodeTable[opcodeNum])(scriptState);
+ * else
+ *     warning("Unimplemented opcode %d", opcodeNum);
+ *
+ * If you want to see an real world example check the kyra engine.
+ * Files: engines/kyra/script.cpp and .h and engine/kyra/script_*.cpp
+ * are interesting for that matter.
+ */
 template<class Arg, class Res>
 struct Functor1 : public Common::UnaryFunction<Arg, Res> {
 	virtual ~Functor1() {}
@@ -235,6 +335,13 @@ struct Functor1 : public Common::UnaryFunction<Arg, Res> {
 	virtual Res operator()(Arg) const = 0;
 };
 
+/**
+ * Functor object for an unary class member function.
+ * Usage is like with Functor0Mem. The resulting functor object
+ * will take one parameter though.
+ *
+ * @see Functor0Men
+ */
 template<class Arg, class Res, class T>
 class Functor1Mem : public Functor1<Arg, Res> {
 public:
@@ -242,7 +349,7 @@ public:
 
 	Functor1Mem(T *t, const FuncType &func) : _t(t), _func(func) {}
 
-	bool isValid() const { return _func != 0; }
+	bool isValid() const { return _func != 0 && _t != 0; }
 	Res operator()(Arg v1) const {
 		return (_t->*_func)(v1);
 	}
@@ -251,6 +358,11 @@ private:
 	const FuncType _func;
 };
 
+/**
+ * Generic functor object for binary function objects.
+ *
+ * @see Functor1
+ */
 template<class Arg1, class Arg2, class Res>
 struct Functor2 : public Common::BinaryFunction<Arg1, Arg2, Res> {
 	virtual ~Functor2() {}
@@ -259,6 +371,13 @@ struct Functor2 : public Common::BinaryFunction<Arg1, Arg2, Res> {
 	virtual Res operator()(Arg1, Arg2) const = 0;
 };
 
+/**
+ * Functor object for a binary class member function.
+ * Usage is like with Functor0Mem. The resulting functor object
+ * will take two parameter though.
+ *
+ * @see Functor0Men
+ */
 template<class Arg1, class Arg2, class Res, class T>
 class Functor2Mem : public Functor2<Arg1, Arg2, Res> {
 public:
@@ -266,7 +385,7 @@ public:
 
 	Functor2Mem(T *t, const FuncType &func) : _t(t), _func(func) {}
 
-	bool isValid() const { return _func != 0; }
+	bool isValid() const { return _func != 0 && _t != 0; }
 	Res operator()(Arg1 v1, Arg2 v2) const {
 		return (_t->*_func)(v1, v2);
 	}