From: <baz...@us...> - 2008-02-26 17:05:59
|
Revision: 8139 http://armagetronad.svn.sourceforge.net/armagetronad/?rev=8139&view=rev Author: bazaarmagetron Date: 2008-02-26 08:51:56 -0800 (Tue, 26 Feb 2008) Log Message: ----------- Manuel Moos: Added overload docs. Modified Paths: -------------- clio/trunk/clio/clio/macros.hpp clio/trunk/clio/doc/about.t2t.in clio/trunk/clio/doc/main.t2t.in clio/trunk/clio/doc/method_overloads.t2t.in clio/trunk/clio/tests/overloads.test/output.txt clio/trunk/clio/tests/overloads.test/overloads.cpp Property Changed: ---------------- clio/trunk/clio/ Property changes on: clio/trunk/clio ___________________________________________________________________ Name: bzr:revision-info - timestamp: 2008-02-26 14:53:01.226000071 +0100 committer: Manuel Moos <z-...@us...> properties: branch-nick: src + timestamp: 2008-02-26 16:22:07.852999926 +0100 committer: Manuel Moos <z-...@us...> properties: branch-nick: src Name: bzr:revision-id:v3-list-QlpoOTFBWSZTWZvbKhsAAAdRgAAQABK6798QIABURMgAAaeoNT1TxT1DQbKaeobXKiyAmlWT7Y5MkdJOtXDtB7w7DOGFBHiOBxaUIu7HQyyQSvxdyRThQkJvbKhs - 4 z-...@us...-20080222202821-mkuiwckx41jof2gj 5 z-...@us...-20080222202957-htiysaaxkiroqd7e 6 z-...@us...-20080222211806-jc50b77qlgn2dp8j 7 z-...@us...-20080222215601-p8y78c77ncvq5eb1 8 z-...@us...-20080222223809-mmh9wh6yzrdm7oa1 9 z-...@us...-20080222232123-uhnuqd9db0p27rkf 10 z-...@us...-20080222232154-k64q4ee9zuq5r2jp 11 z-...@us...-20080222234236-ny0hc8lwybz73rv6 12 z-...@us...-20080223000039-566psft2c96236kw 13 z-...@us...-20080223000530-4mtket15l6oeo1ju 14 z-...@us...-20080223001030-5t86d3u3bidpoq6r 15 z-...@us...-20080223002857-qvx8z72tmsoguku0 16 z-...@us...-20080223004917-abqn3vdfqb1euyzc 17 z-...@us...-20080223010025-h0nul9yntjvutdbq 18 z-...@us...-20080223013357-1nzhrjwjr4g0h7g9 19 z-...@us...-20080223015240-btmt95d1vvlip4gl 20 z-...@us...-20080223124731-dlwuagon76gq2o3g 21 z-...@us...-20080223133015-0hjqyrki59ydwdcv 22 z-...@us...-20080223135113-icwd4g99yev9n0u2 23 z-...@us...-20080223152916-8rm942q1rmjlueca 24 z-...@us...-20080223174524-3lb2wm6tt5nytd4b 25 z-...@us...-20080223174610-gwmr3fn8456rwvmg 26 z-...@us...-20080223183115-ub0hshkf3zfs69ko 27 z-...@us...-20080223185539-cvhsltp2u12d5lgc 28 z-...@us...-20080223211352-km18u9bp9qhufyta 29 z-...@us...-20080223225132-94n2bwt307fujbg4 30 z-...@us...-20080223234541-mqp3d64uyn3no98y 31 z-...@us...-20080223235231-5lshcanhqlkwv36n 32 z-...@us...-20080224001425-n6xziwrp0hh3nz2f 33 z-...@us...-20080224161454-lyyn0grllfn5qx8w 34 z-...@us...-20080224180639-fr6dqfch7kboocs0 35 z-...@us...-20080224181843-8iq9zyjoz4dprm8b 36 z-...@us...-20080224224147-cmxp11hux8yn3jbp 37 z-...@us...-20080224224848-0h65c9bpg637lgar 38 z-...@us...-20080224225219-0arhdm8hw42hptrf 39 z-...@us...-20080225000421-fh9p1qmu32awa41y 40 z-...@us...-20080225000607-bsvlilqbv5ssltr3 41 z-...@us...-20080225003311-fnfdbdvp3p2bw8b4 42 z-...@us...-20080225013618-jrkbe6q8gpdzbj3n 43 z-...@us...-20080225015144-8j759e33zdztmena 44 z-...@us...-20080225022114-1360a7t61rtei61d 45 z-...@us...-20080225023750-vf22upkbeiyoclbc 46 z-...@us...-20080225024308-j2a0nomtfuzfbjf8 47 z-...@us...-20080225100512-ck04wcqo0w3jibyq 48 z-...@us...-20080225103727-f42008yfu3y6q5r5 49 z-...@us...-20080225113757-opine59p0ak9r6h0 50 z-...@us...-20080225115932-akfi8jo7apw0phkk 51 z-...@us...-20080225120844-31fhi28emjcs4ys6 52 z-...@us...-20080225122224-wrmmr1nt5w9106rg 53 z-...@us...-20080225123606-ts2l2h3aivk9pplp 54 z-...@us...-20080225145431-x956npu0w5htu7sa 55 z-...@us...-20080225152517-hejvwwjukez9aemh 56 z-...@us...-20080225154230-rpq3t8xnbu99mx4t 57 z-...@us...-20080225162001-ukwye8clhep133jz 58 z-...@us...-20080225162148-mvmfjwz461o7xvaa 59 z-...@us...-20080225164010-oej2am8f8ysxnu3n 60 z-...@us...-20080225175844-w74is4pxw6zefuou 61 z-...@us...-20080225185644-df7z71i5bh7056tw 62 z-...@us...-20080225231713-lk9zjwf6tlmck94z 63 z-...@us...-20080226004842-kj1448gvijflyn6b 64 z-...@us...-20080226012214-xipk2o8idaj0rzoz 65 z-...@us...-20080226013159-8zq7m6hatobv71x4 66 z-...@us...-20080226110837-nfl4khd9y39rdmir 67 z-...@us...-20080226111231-7fvp5r7eu9flwx7s 68 z-...@us...-20080226121838-20m97dmv5sj8kifs 69 z-...@us...-20080226122134-71pekd0jywe5n39l 70 z-...@us...-20080226122505-1u5cfryv0elid3f2 71 z-...@us...-20080226123432-rzi9qkm2whs3sad6 72 z-...@us...-20080226133113-lyap55resu8kx0gm 73 z-...@us...-20080226133403-riqoo03f2f2a4gfz 74 z-...@us...-20080226134345-0tnwohpjgizklima 75 z-...@us...-20080226135301-1han96uhxd6h20o1 + 4 z-...@us...-20080222202821-mkuiwckx41jof2gj 5 z-...@us...-20080222202957-htiysaaxkiroqd7e 6 z-...@us...-20080222211806-jc50b77qlgn2dp8j 7 z-...@us...-20080222215601-p8y78c77ncvq5eb1 8 z-...@us...-20080222223809-mmh9wh6yzrdm7oa1 9 z-...@us...-20080222232123-uhnuqd9db0p27rkf 10 z-...@us...-20080222232154-k64q4ee9zuq5r2jp 11 z-...@us...-20080222234236-ny0hc8lwybz73rv6 12 z-...@us...-20080223000039-566psft2c96236kw 13 z-...@us...-20080223000530-4mtket15l6oeo1ju 14 z-...@us...-20080223001030-5t86d3u3bidpoq6r 15 z-...@us...-20080223002857-qvx8z72tmsoguku0 16 z-...@us...-20080223004917-abqn3vdfqb1euyzc 17 z-...@us...-20080223010025-h0nul9yntjvutdbq 18 z-...@us...-20080223013357-1nzhrjwjr4g0h7g9 19 z-...@us...-20080223015240-btmt95d1vvlip4gl 20 z-...@us...-20080223124731-dlwuagon76gq2o3g 21 z-...@us...-20080223133015-0hjqyrki59ydwdcv 22 z-...@us...-20080223135113-icwd4g99yev9n0u2 23 z-...@us...-20080223152916-8rm942q1rmjlueca 24 z-...@us...-20080223174524-3lb2wm6tt5nytd4b 25 z-...@us...-20080223174610-gwmr3fn8456rwvmg 26 z-...@us...-20080223183115-ub0hshkf3zfs69ko 27 z-...@us...-20080223185539-cvhsltp2u12d5lgc 28 z-...@us...-20080223211352-km18u9bp9qhufyta 29 z-...@us...-20080223225132-94n2bwt307fujbg4 30 z-...@us...-20080223234541-mqp3d64uyn3no98y 31 z-...@us...-20080223235231-5lshcanhqlkwv36n 32 z-...@us...-20080224001425-n6xziwrp0hh3nz2f 33 z-...@us...-20080224161454-lyyn0grllfn5qx8w 34 z-...@us...-20080224180639-fr6dqfch7kboocs0 35 z-...@us...-20080224181843-8iq9zyjoz4dprm8b 36 z-...@us...-20080224224147-cmxp11hux8yn3jbp 37 z-...@us...-20080224224848-0h65c9bpg637lgar 38 z-...@us...-20080224225219-0arhdm8hw42hptrf 39 z-...@us...-20080225000421-fh9p1qmu32awa41y 40 z-...@us...-20080225000607-bsvlilqbv5ssltr3 41 z-...@us...-20080225003311-fnfdbdvp3p2bw8b4 42 z-...@us...-20080225013618-jrkbe6q8gpdzbj3n 43 z-...@us...-20080225015144-8j759e33zdztmena 44 z-...@us...-20080225022114-1360a7t61rtei61d 45 z-...@us...-20080225023750-vf22upkbeiyoclbc 46 z-...@us...-20080225024308-j2a0nomtfuzfbjf8 47 z-...@us...-20080225100512-ck04wcqo0w3jibyq 48 z-...@us...-20080225103727-f42008yfu3y6q5r5 49 z-...@us...-20080225113757-opine59p0ak9r6h0 50 z-...@us...-20080225115932-akfi8jo7apw0phkk 51 z-...@us...-20080225120844-31fhi28emjcs4ys6 52 z-...@us...-20080225122224-wrmmr1nt5w9106rg 53 z-...@us...-20080225123606-ts2l2h3aivk9pplp 54 z-...@us...-20080225145431-x956npu0w5htu7sa 55 z-...@us...-20080225152517-hejvwwjukez9aemh 56 z-...@us...-20080225154230-rpq3t8xnbu99mx4t 57 z-...@us...-20080225162001-ukwye8clhep133jz 58 z-...@us...-20080225162148-mvmfjwz461o7xvaa 59 z-...@us...-20080225164010-oej2am8f8ysxnu3n 60 z-...@us...-20080225175844-w74is4pxw6zefuou 61 z-...@us...-20080225185644-df7z71i5bh7056tw 62 z-...@us...-20080225231713-lk9zjwf6tlmck94z 63 z-...@us...-20080226004842-kj1448gvijflyn6b 64 z-...@us...-20080226012214-xipk2o8idaj0rzoz 65 z-...@us...-20080226013159-8zq7m6hatobv71x4 66 z-...@us...-20080226110837-nfl4khd9y39rdmir 67 z-...@us...-20080226111231-7fvp5r7eu9flwx7s 68 z-...@us...-20080226121838-20m97dmv5sj8kifs 69 z-...@us...-20080226122134-71pekd0jywe5n39l 70 z-...@us...-20080226122505-1u5cfryv0elid3f2 71 z-...@us...-20080226123432-rzi9qkm2whs3sad6 72 z-...@us...-20080226133113-lyap55resu8kx0gm 73 z-...@us...-20080226133403-riqoo03f2f2a4gfz 74 z-...@us...-20080226134345-0tnwohpjgizklima 75 z-...@us...-20080226135301-1han96uhxd6h20o1 76 z-...@us...-20080226152207-k1x8v7lhaohj7a2t Modified: clio/trunk/clio/clio/macros.hpp =================================================================== --- clio/trunk/clio/clio/macros.hpp 2008-02-26 14:02:41 UTC (rev 8138) +++ clio/trunk/clio/clio/macros.hpp 2008-02-26 16:51:56 UTC (rev 8139) @@ -444,6 +444,8 @@ #define CLIO_OVERLOADED_METHOD( FUNCTION, DISAMBIGUATION ) CLIO_OVERLOADED_METHOD_EX( FUNCTION, DISAMBIGUATION,"" ) +#define CLIO_TEMPLATE_METHOD_EX( FUNCTION, SIGNATURE, DISAMBIGUATION, USERNAME ) clio::RegisterFunction<CLASS>( CLIO_FUNCTION_SIGNATURE_EX( <CLASS>, DISAMBIGUATION, &CLIO_CLASS_TEMPPARM::template FUNCTION CLIO_TEMPLATE_ARGLIST_COMPLETE_SIGNATURE(SIGNATURE), template ), clio::GetFunctionName(#FUNCTION, USERNAME ).c_str() ).SetDebugInfo( __FILE__ ":" CLIO_STRINGIFY(__LINE__) ) + #define CLIO_OVERLOADED_TEMPLATE_METHOD_EX( FUNCTION, SIGNATURE, DISAMBIGUATION, USERNAME ) clio::RegisterOverloadedFunction<CLASS>( CLIO_FUNCTION_SIGNATURE_EX( <CLASS>, DISAMBIGUATION, &CLIO_CLASS_TEMPPARM::template FUNCTION CLIO_TEMPLATE_ARGLIST_COMPLETE_SIGNATURE(SIGNATURE), template ), clio::GetFunctionName(#FUNCTION, USERNAME ).c_str() ).SetDebugInfo( __FILE__ ":" CLIO_STRINGIFY(__LINE__) ) #define CLIO_OVERLOADED_TEMPLATE_METHOD( FUNCTION, SIGNATURE ) CLIO_OVERLOADED_TEMPLATE_METHOD_EX( FUNCTION,SIGNATURE,,"" ) Modified: clio/trunk/clio/doc/about.t2t.in =================================================================== --- clio/trunk/clio/doc/about.t2t.in 2008-02-26 14:02:41 UTC (rev 8138) +++ clio/trunk/clio/doc/about.t2t.in 2008-02-26 16:51:56 UTC (rev 8139) @@ -54,6 +54,7 @@ === Currently Unsupported === +- operators - exceptions - plain, regular C functions (you can have classes adopt them as static member functions, though) Modified: clio/trunk/clio/doc/main.t2t.in =================================================================== --- clio/trunk/clio/doc/main.t2t.in 2008-02-26 14:02:41 UTC (rev 8138) +++ clio/trunk/clio/doc/main.t2t.in 2008-02-26 16:51:56 UTC (rev 8139) @@ -35,12 +35,12 @@ [Argument Conversion argument_conversion.html]: how clio handles function argument conversion +[Template Classes classes_template.html]: template classes + [Method Overloads method_overloads.html]: overloaded member functions [Constructors constructors.html]: custom constructors -[Template Classes classes_template.html]: template classes - [Virtuals virtuals.html]: how to overload virtual C++ member functions from Io [Namespaces and Nesting namespaces.html]: how C++ namespaces and nested classes are handled Modified: clio/trunk/clio/doc/method_overloads.t2t.in =================================================================== --- clio/trunk/clio/doc/method_overloads.t2t.in 2008-02-26 14:02:41 UTC (rev 8138) +++ clio/trunk/clio/doc/method_overloads.t2t.in 2008-02-26 16:51:56 UTC (rev 8139) @@ -1,11 +1,140 @@ -Title +Overloaded Methods @navbar@ -== Chapter 1 == -== Chapter 2 == +=== Wrapping Overloaded Methods === +Trying to make overloaded methods known to clio with the usual +``CLIO_METHOD`` macro will quickly bombard you with error messages, +because clio won't be able to determine from the name alone what +it is you want to have wrapped. Template member functions also +won't work out of the box. One way or another, you'll have to tell +clio the signature of the function you want to make known in Io. +You can do so with the ``CLIO_OVERLOADED_METHOD`` macro or, +easier for template methods, the ``CLIO_OVERLOADED_TEMPLATE_METHOD`` +macro. + +Say your class looks like this: +``` +class Overload +{ +public: + void f(); + int f(int x); + template <class T> void g( T x ); +}; +``` + +You'd wrap this class this way: +``` +CLIO_CLASS( Overload ) +{ + CLIO_OVERLOADED_METHOD( f, (void (Overload::*)()) ); + CLIO_OVERLOADED_METHOD( f, (int (Overload::*)( int )) ); + + // wrap g<int> + CLIO_OVERLOADED_TEMPLATE_METHOD( g, (1,(int)) ); + + // wrap g<float *> + CLIO_OVERLOADED_TEMPLATE_METHOD( g, (1,(float *)) ); +} +``` + +The first argument to ``CLIO_OVERLOADED_METHOD`` is the function name, the +second is the C++ function pointer type in an extra pair of parentheses. +Personally, I always get that one wrong, [this page http://www.parashift.com/c++-faq-lite/pointers-to-members.html#faq-33.5] helps me then. + +The first argument of ``CLIO_OVERLOADED_TEMPLATE_METHOD`` is the function +name, the second is the template argument list to use in clio notation. + +=== Using Overloaded Methods === + +Overloaded methods of the same name will share the same slot in your +Io object, and activating that slot will try select the best +C++ function to use for the given set of arguments. This selection +is done at runtime, of course, requires extra code that is not +needed for non-overloaded methods, and is slow. + +The overload resolution rules are basically those of C++, modified +to the fact that the full type of all arguments is known at +resolution time, and modified to almost always select one function +to call. + +Resolution works like this: +For all the overloaded methods of one name, all arguments are +converted to the types the C++-functions would accept. The worst +conversion quality of any of them and the argument position is noted. +Functions that accept the wrong number of arguments and functions +where one of the conversions fails are thrown away. The rest are +compared according to these criteria: + +- Conversion Quality of the worst conversion. From best to worst, + the conversion qualities are: + - Perfect: best possible match. Type matched as exactly as possible. + - Upcast/Box/Unbox: it was required to cast a class pointer to a + base class pointer, or it was required to box a value into a proxy, + or to unbox a value from a proxy (this roughly corresponds to + following/taking references in C++) + - Conversion: a conversion was required. For example, the function + wants an ``int`` or ``int const &``, but you pass int a ``Clio Char``. + A ``Clio Int`` could be passed verbatim (counting as Upcast + for internal reasons still), but the ``Char`` needs conversion. + - Void: casting to a ``void *`` or ``IoObject *`` was required. + Those are the worst because you can do that with absolutely any + argument. + +- Position of the worst conversion. Functions where the worst conversion + quality happens only on arguments further to the right are preferred, + arbitrarily assuming that function arguments standing on the left are + more important. + +- If conversion/casting was involved, prefer the function that required + less casting steps. Casting steps are counted in the usual "depth first" + way, so every base class + +- Lastly, the quality of the C++ function argument is analyzed. Clio + prefers doubles over floats over integers, and integers with bigger + value range over those with smaller range. Clio does not like references, + hates smart pointers and deeply detests plain pointers. Don't get + it started about ``IoObject`` or even ``void``. For objects, non-const + variants of functions are slightly preferred, for primitives, the const + versions. + + + +And only if two functions fare equally in all these criteria, which pretty +much only can happen if they have identical signatures, clio refuses +to call any function. + +=== Alternatives === + +Instead of letting the functions that are overloaded in C++ share one Io slot +and therefore being overloaded in Io, too, you can use the _EX +family of macros to give each variant a different name: +``` +CLIO_CLASS( Overload ) +{ + CLIO_METHOD_EX( f, (void (Overload::*)()), "f" ); + CLIO_METHOD_EX( f, (int (Overload::*)( int )), "f_int" ); + + // wrap g<int> + CLIO_TEMPLATE_METHOD_EX( g, (1,(int)),, "g_int" ); + + // wrap g<float *> + CLIO_TEMPLATE_METHOD_EX( g, (1,(float *)),, "g_float_ptr" ); +} +``` + +The last argument of both macros is the method name in Io, and the +third argument of ``CLIO_OVERLOADED_TEMPLATE_METHOD_EX`` is the +optional C++ function pointer type. + +Note: you need to use the ``OVERLOADED`` variants of the macros if +several C++ functions should share the same name in Io. The regular +macros don't generate the code required to select the correct +overload. + @navbar@ Modified: clio/trunk/clio/tests/overloads.test/output.txt =================================================================== --- clio/trunk/clio/tests/overloads.test/output.txt 2008-02-26 14:02:41 UTC (rev 8138) +++ clio/trunk/clio/tests/overloads.test/output.txt 2008-02-26 16:51:56 UTC (rev 8139) @@ -20,8 +20,8 @@ h<char> Exception: Too many equally fitting overloads found for passed argument of type 'Clio ConstPrimitiveProxy With(Clio Proxy With(Clio Char)) [clio::ConstPrimitiveProxy<clio::Proxy<char const>>]'. The candidates are: +overloads.cpp:75 : OverloadTest2::g( char const & ) overloads.cpp:74 : OverloadTest2::g( char const & ) -overloads.cpp:73 : OverloadTest2::g( char const & ) (during call of C++ function 'OverloadTest2::g( char const & )') <<<< x f(OverloadTest clone) Modified: clio/trunk/clio/tests/overloads.test/overloads.cpp =================================================================== --- clio/trunk/clio/tests/overloads.test/overloads.cpp 2008-02-26 14:02:41 UTC (rev 8138) +++ clio/trunk/clio/tests/overloads.test/overloads.cpp 2008-02-26 16:51:56 UTC (rev 8139) @@ -69,6 +69,7 @@ CLIO_OVERLOADED_METHOD_EX( template g<float>,, "g" ); CLIO_OVERLOADED_TEMPLATE_METHOD( g, (1,(double)) ); CLIO_OVERLOADED_TEMPLATE_METHOD( g, (1,(double const &)) ); + CLIO_OVERLOADED_TEMPLATE_METHOD_EX( g, (1,(double const &)),, "g" ); CLIO_OVERLOADED_TEMPLATE_METHOD( g, (1,(int const &)) ); CLIO_OVERLOADED_TEMPLATE_METHOD( g, (1,(char const &)) ); CLIO_OVERLOADED_TEMPLATE_METHOD( g, (1,(char const &)) ); @@ -88,7 +89,7 @@ CLIO_METHOD_EX( template h<int>,, "h_int" ); CLIO_METHOD_EX( template h<char>,, "h_char" ); - CLIO_METHOD_EX( template h<float>,, "h_float" ); + CLIO_TEMPLATE_METHOD_EX( h,(1,(float)),, "h_float" ); CLIO_METHOD_EX( template h<std::string>,, "h_string" ); } This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |