1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Boost: bind.hpp documentation</title>
</head>
<body bgcolor="White" style="margin-left: 5%; margin-right: 5%;">
<table border="0" width="100%">
<tr>
<td width="277">
<img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86">
</td>
<td align="center">
<h1>bind.hpp</h1>
</td>
</tr>
<tr>
<td colspan="2" height="64"> </td>
</tr>
</table>
<h2>Contents</h2>
<h3 style="margin-left: 20pt;"><a href="#Purpose">Purpose</a></h3>
<h4 style="margin-left: 40pt;"><a href="#with_functions">Using bind with functions and function pointers</a></h4>
<h4 style="margin-left: 40pt;"><a href="#with_function_objects">Using bind with function objects</a></h4>
<h4 style="margin-left: 40pt;"><a href="#with_member_functions">Using bind with member function pointers</a></h4>
<h4 style="margin-left: 40pt;"><a href="#nested_binds">Using nested binds for function composition</a></h4>
<h3 style="margin-left: 20pt;"><a href="#Examples">Examples</a></h3>
<h4 style="margin-left: 40pt;"><a href="#with_algorithms">Using bind with standard algorithms</a></h4>
<h4 style="margin-left: 40pt;"><a href="#with_boost_function">Using bind with Boost.Function</a></h4>
<h3 style="margin-left: 20pt;"><a href="#Limitations">Limitations</a></h3>
<h3 style="margin-left: 20pt;"><a href="#FAQ">Frequently Asked Questions</a></h3>
<h4 style="margin-left: 40pt;"><a href="#Q_doesnt_compile">Why doesn't this compile?</a></h4>
<h4 style="margin-left: 40pt;"><a href="#Q_does_compile">Why does this compile? It should not.</a></h4>
<h4 style="margin-left: 40pt;"><a href="#Q_forms">What is the difference between bind(f, ...) and bind<R>(f, ...)?</a></h4>
<h4 style="margin-left: 40pt;"><a href="#Q_win32_api">Does <b>bind</b> work with Windows API functions?</a></h4>
<h4 style="margin-left: 40pt;"><a href="#Q_com">Does <b>bind</b> work with COM methods?</a></h4>
<h4 style="margin-left: 40pt;"><a href="#Q_mac">Does <b>bind</b> work with Mac toolbox functions?</a></h4>
<h4 style="margin-left: 40pt;"><a href="#Q_auto_stdcall">Why doesn't <b>bind</b> automatically recognize nonstandard functions?</a></h4>
<h3 style="margin-left: 20pt;"><a href="#Troubleshooting">Troubleshooting</a></h3>
<h4 style="margin-left: 40pt;"><a href="#err_num_args">Incorrect number of arguments</a></h4>
<h4 style="margin-left: 40pt;"><a href="#err_signature">The function object cannot be called with the specified arguments</a></h4>
<h4 style="margin-left: 40pt;"><a href="#err_arg_access">Accessing an argument that does not exist</a></h4>
<h4 style="margin-left: 40pt;"><a href="#err_short_form">Inappropriate use of bind(f, ...)</a></h4>
<h4 style="margin-left: 40pt;"><a href="#err_long_form">Inappropriate use of bind<R>(f, ...)</a></h4>
<h4 style="margin-left: 40pt;"><a href="#err_nonstd">Binding a nonstandard function</a></h4>
<h4 style="margin-left: 40pt;"><a href="#err_const_arg"><b>const</b> in signatures</a></h4>
<h4 style="margin-left: 40pt;"><a href="#err_msvc_using">MSVC specific: using boost::bind;</a></h4>
<h4 style="margin-left: 40pt;"><a href="#err_msvc_class_template">MSVC specific: class templates shadow function templates</a></h4>
<h4 style="margin-left: 40pt;"><a href="#err_msvc_ellipsis">MSVC specific: ... in signatures treated as type</a></h4>
<h3 style="margin-left: 20pt;"><a href="#Interface">Interface</a></h3>
<h4 style="margin-left: 40pt;"><a href="#Synopsis">Synopsis</a></h4>
<h4 style="margin-left: 40pt;"><a href="#CommonRequirements">Common requirements</a></h4>
<h4 style="margin-left: 40pt;"><a href="#CommonDefinitions">Common definitions</a></h4>
<h4 style="margin-left: 40pt;"><a href="#bind">bind</a></h4>
<h3 style="margin-left: 20pt;"><a href="#Implementation">Implementation</a></h3>
<h4 style="margin-left: 40pt;"><a href="#Files">Files</a></h4>
<h4 style="margin-left: 40pt;"><a href="#Dependencies">Dependencies</a></h4>
<h4 style="margin-left: 40pt;"><a href="#NumberOfArguments">Number of Arguments</a></h4>
<h4 style="margin-left: 40pt;"><a href="#stdcall">"__stdcall" and "pascal" Support</a></h4>
<h4 style="margin-left: 40pt;"><a href="#BOOST_BIND">Using the BOOST_BIND macro</a></h4>
<h4 style="margin-left: 40pt;"><a href="#visit_each"><b>visit_each</b> support</a></h4>
<h3 style="margin-left: 20pt;"><a href="#Acknowledgements">Acknowledgements</a></h3>
<h2><a name="Purpose">Purpose</a></h2>
<p>
<b>boost::bind</b> is a generalization of the standard functions
<b>std::bind1st</b> and <b>std::bind2nd</b>. It supports arbitrary function
objects, functions, function pointers, and member function pointers, and is able
to bind any argument to a specific value or route input arguments into arbitrary
positions. <b>bind</b> does not place any requirements on the function object;
in particular, it does not need the <b>result_type</b>,
<b>first_argument_type</b> and <b>second_argument_type</b> standard typedefs.
</p>
<h3><a name="with_functions">Using bind with functions and function pointers</a></h3>
<p>
Given these definitions:
</p>
<pre>
int f(int a, int b)
{
return a + b;
}
int g(int a, int b, int c)
{
return a + b + c;
}
</pre>
<p>
<tt>bind(f, 1, 2)</tt> will produce a "nullary" function object that
takes no arguments and returns <tt>f(1, 2)</tt>. Similarly,
<tt>bind(g, 1, 2, 3)()</tt> is equivalent to <tt>g(1, 2, 3)</tt>.
</p>
<p>
It is possible to selectively bind only some of the arguments.
<tt>bind(f, _1, 5)(x)</tt> is equivalent to <tt>f(x, 5)</tt>; here
<b>_1</b> is a placeholder argument that means "substitute with the first
input argument."
<p>
For comparison, here is the same operation expressed with the standard
library primitives:
</p>
<pre>
std::bind2nd(std::ptr_fun(f), 5)(x);
</pre>
<p>
<b>bind</b> covers the functionality of <b>std::bind1st</b> as well:
</p>
<pre>
std::bind1st(std::ptr_fun(f), 5)(x); // f(5, x)
bind(f, 5, _1)(x); // f(5, x)
</pre>
<p>
<b>bind</b> can handle functions with more than two arguments, and its
argument substitution mechanism is more general:
</p>
<pre>
bind(f, _2, _1)(x, y); // f(y, x)
bind(g, _1, 9, _1)(x); // g(x, 9, x)
bind(g, _3, _3, _3)(x, y, z); // g(z, z, z)
bind(g, _1, _1, _1)(x, y, z); // g(x, x, x)
</pre>
<p>
Note that, in the last example, the function object produced by
<tt>bind(g, _1, _1, _1)</tt> does not contain references to any arguments
beyond the first, but it can still be used with more than one argument.
Any extra arguments are silently ignored, just like the first and the second
argument are ignored in the third example.
</p>
<p>
The arguments that <b>bind</b> takes are copied and held internally by
the returned function object. For example, in the following code:
</p>
<pre>
int i = 5;
bind(f, i, _1);
</pre>
<p>
a copy of the value of <b>i</b> is stored into the function object.
<a href="ref.html">boost::ref</a> and <a href="ref.html">boost::cref</a>
can be used to make the function object store a reference to an object,
rather than a copy:
</p>
<pre>
int i = 5;
bind(f, ref(i), _1);
</pre>
<h3><a name="with_function_objects">Using bind with function objects</a></h3>
<p>
<b>bind</b> is not limited to functions; it accepts arbitrary function objects.
In the general case, the return type of the generated function object's
<b>operator()</b> has to be specified explicitly (without a <b>typeof</b>
operator the return type cannot be inferred):
</p>
<pre>
struct F
{
int operator()(int a, int b) { return a - b; }
bool operator()(long a, long b) { return a == b; }
};
F f;
int x = 104;
bind<int>(f, _1, _1)(x); // f(x, x), i.e. zero
</pre>
<p>
When the function object exposes a nested type named <b>result_type</b>,
the explicit return type can be omitted:
</p>
<pre>
int x = 8;
bind(std::less<int>(), _1, 9)(x); // x < 9
</pre>
<p>
[Note: the ability to omit the return type is not available on all compilers.]
</p>
<h3><a name="with_member_functions">Using bind with member function pointers</a></h3>
<p>
Pointers to member functions are not function objects, because they do not
support <tt>operator()</tt>. For convenience, <b>bind</b> accepts member function
pointers as its first argument, and the behavior is as if
<a href="mem_fn.html">boost::mem_fn</a> has been used to convert the member
function pointer into a function object. In other words, the expression
</p>
<pre>
bind(&X::f, <i>args</i>)
</pre>
<p>
is equivalent to
</p>
<pre>
bind<R>(<a href="mem_fn.html">mem_fn</a>(&X::f), <i>args</i>)
</pre>
<p>
where <b>R</b> is the return type of <b>X::f</b>.
</p>
<p>
[Note: <b>mem_fn</b> creates
function objects that are able to accept a pointer, a reference, or a smart
pointer to an object as its first argument; for additional information, see
the <b>mem_fn</b> <a href="mem_fn.html">documentation</a>.]
</p>
<p>
Example:
</p>
<pre>
struct X
{
bool f(int a);
};
X x;
shared_ptr<X> p(new X);
int i = 5;
bind(&X::f, ref(x), _1)(i); // x.f(i)
bind(&X::f, &x, _1)(i); // (&x)->f(i)
bind(&X::f, x, _1)(i); // (<i>internal copy of x</i>).f(i)
bind(&X::f, p, _1)(i); // (<i>internal copy of p</i>)->f(i)
</pre>
<p>
The last two examples are interesting in that they produce "self-contained"
function objects. <tt>bind(&X::f, x, _1)</tt> stores a copy of <b>x</b>.
<tt>bind(&X::f, p, _1)</tt> stores a copy of <b>p</b>, and since <b>p</b>
is a
<a href="../smart_ptr/shared_ptr.htm">boost::shared_ptr</a>,
the function object retains a reference to its instance of <b>X</b> and will
remain valid even when <b>p</b> goes out of scope or is <b>reset()</b>.
</p>
<h3><a name="nested_binds">Using nested binds for function composition</a></h3>
<p>
Some of the arguments passed to <b>bind</b> may be nested <b>bind</b> expressions
themselves:
</p>
<pre>
bind(f, bind(g, _1))(x); // f(g(x))
</pre>
<p>
The nested subexpressions are evaluated when the function object is called. This
feature of <b>bind</b> can be used to perform function composition.
</p>
<p>
See <a href="bind_as_compose.cpp">bind_as_compose.cpp</a> for an example that
demonstrates how to use <b>bind</b> to achieve similar functionality to
<a href="../compose/index.htm">Boost.Compose</a>.
</p>
<p>
Note that the <b>first</b> argument - the bound function object - is an
exception to the nesting rules. A nested <b>bind</b> expression passed
to <b>bind</b> as a first argument is <b>not</b> treated differently from
any other function object:
</p>
<pre>
int x = 4;
template<class F> void test(F f)
{
bind(f, 5)(x);
}
int g(int, int);
int main()
{
test(bind(g, _1, 8)); // g(5, 8) and not g(x, 8)(5)
}
</pre>
<h2><a name="Examples">Examples</a></h2>
<h3><a name="with_algorithms">Using bind with standard algorithms</a></h3>
<pre>
class image;
class animation
{
public:
void advance(int ms);
bool inactive() const;
void render(image & target) const;
};
std::vector<animation> anims;
template<class C, class P> void erase_if(C & c, P pred)
{
c.erase(std::remove_if(c.begin(), c.end(), pred), c.end());
}
void update(int ms)
{
std::for_each(anims.begin(), anims.end(), boost::bind(&animation::advance, _1, ms));
erase_if(anims, boost::mem_fn(&animation::inactive));
}
void render(image & target)
{
std::for_each(anims.begin(), anims.end(), boost::bind(&animation::render, _1, boost::ref(target)));
}
</pre>
<h3><a name="with_boost_function">Using bind with Boost.Function</a></h3>
<pre>
class button
{
public:
<a href="../function/index.html">boost::function</a><void> onClick;
};
class player
{
public:
void play();
void stop();
};
button playButton, stopButton;
player thePlayer;
void connect()
{
playButton.onClick = boost::bind(&player::play, &thePlayer);
stopButton.onClick = boost::bind(&player::stop, &thePlayer);
}
</pre>
<h3><a name="Limitations">Limitations</a></h3>
<p>
The function objects generated by <b>bind</b> take their arguments by
reference and cannot, therefore, accept non-const temporaries or literal
constants. This is an inherent limitation of the C++ language, known as the
"forwarding function problem."
</p>
<p>
The library uses signatures of the form
</p>
<pre>
template<class T> void f(T & t);
</pre>
<p>
to accept arguments of arbitrary types and pass them on unmodified. As noted,
this does not work with non-const r-values.
</p>
<p>
An oft-proposed "solution" to this problem is to add an overload:
</p>
<pre>
template<class T> void f(T & t);
template<class T> void f(T const & t);
</pre>
<p>
Unfortunately, this (a) requires providing 512 overloads for nine arguments
and (b) does not actually work for const arguments, both l- and r-values,
since the two templates produce the exact same signature and cannot be
partially ordered.
</p>
<p>
[Note: this is a dark corner of the language, and the
<a href="http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/cwg_active.html#214">
corresponding issue</a> has not been resolved yet.]
</p>
<h2><a name="FAQ">Frequently Asked Questions</a></h2>
<h3><a name="Q_doesnt_compile">Why doesn't this compile?</a></h3>
<p>
See the <a href="#Troubleshooting">dedicated Troubleshooting section</a>.
</p>
<h3><a name="Q_does_compile">Why does this compile? It should not.</a></h3>
<p>
Probably because you used the general bind<R>(f, ...) syntax, thereby
instructing <b>bind</b> to not "inspect" <b>f</b> to detect arity
and return type errors.
</p>
<h3><a name="Q_forms">What is the difference between bind(f, ...) and bind<R>(f, ...)?</a></h3>
<p>
The first form instructs <b>bind</b> to inspect the type of <b>f</b> in order
to determine its arity (number of arguments) and return type. Arity errors
will be detected at "bind time". This syntax, of course, places some
requirements on <b>f</b>. It must be a function, function pointer, member
function pointer, or a function object that defines a nested type named
<b>result_type</b>; in short, it must be something that <b>bind</b> can
recognize.
</p>
<p>
The second form instructs <b>bind</b> to <b>not</b> attempt to recognize the
type of <b>f</b>. It is generally used with function objects that do not, or
cannot, expose <b>result_type</b>, but it can also be used with nonstandard
functions. For example, the current implementation does not automatically
recognize variable-argument functions like <b>printf</b>, so you will have to
use <tt>bind<int>(printf, ...)</tt>.
</p>
<p>
Another important factor to consider is that compilers without partial template
specialization or function template partial ordering support cannot handle the
first form when <b>f</b> is a function object, and in most cases will not handle
the second form when <b>f</b> is a function (pointer) or a member function pointer.
</p>
<h3><a name="Q_win32_api">Does <b>bind</b> work with Windows API functions?</a></h3>
<p>
Yes, if you <a href="#stdcall">#define BOOST_BIND_ENABLE_STDCALL</a>.
An alternative is to treat the function as a
<a href="#with_function_objects">generic function object</a> and use the
bind<R>(f, ...) syntax.
</p>
<h3><a name="Q_com">Does <b>bind</b> work with COM methods?</a></h3>
<p>
Yes, if you <a href="#stdcall">#define BOOST_MEM_FN_ENABLE_STDCALL</a>.
</p>
<h3><a name="Q_mac">Does <b>bind</b> work with Mac toolbox functions?</a></h3>
<p>
Yes, if you <a href="#stdcall">#define BOOST_BIND_ENABLE_PASCAL</a>.
An alternative is to treat the function as a
<a href="#with_function_objects">generic function object</a> and use the
bind<R>(f, ...) syntax.
</p>
<h3><a name="Q_auto_stdcall">Why doesn't <b>bind</b> automatically recognize nonstandard functions?</a></h3>
<p>
Non-portable extensions, in general, should default to off to prevent vendor
lock-in. Had the <a href="#stdcall">appropriate macros</a> been defined
automatically, you could
have accidentally taken advantage of them without realizing that your code is,
perhaps, no longer portable. In addition, some compilers have the option to
make <b>__stdcall</b> their default calling convention, in which case no
separate support would be necessary.
</p>
<h2><a name="Troubleshooting">Troubleshooting</a></h2>
<h3><a name="err_num_args">Incorrect number of arguments</a></h3>
<p>
In a bind(f, a1, a2, ..., aN) expression, the function object <b>f</b> must
be able to take exactly <b>N</b> arguments. This error is normally detected
at "bind time"; in other words, the compilation error is reported
on the line where bind() is invoked:
</p>
<pre>
int f(int, int);
int main()
{
boost::bind(f, 1); // error, f takes two arguments
boost::bind(f, 1, 2); // OK
}
</pre>
<p>
A common variation of this error is to forget that member functions have an
implicit "this" argument:
</p>
<pre>
struct X
{
int f(int);
}
int main()
{
boost::bind(&X::f, 1); // error, X::f takes two arguments
boost::bind(&X::f, <b>_1</b>, 1); // OK
}
</pre>
<h3><a name="err_signature">The function object cannot be called with the specified arguments</a></h3>
<p>
As in normal function calls, the function object that is bound must be
compatible with the argument list. The incompatibility will usually be
detected by the compiler at "call time" and the result is
typically an error in <b>bind.hpp</b> on a line that looks like:
</p>
<pre>
return f(a[a1_], a[a2_]);
</pre>
<p>
An example of this kind of error:
</p>
<pre>
int f(int);
int main()
{
boost::bind(f, "incompatible"); // OK so far, no call
boost::bind(f, "incompatible")(); // error, "incompatible" is not an int
boost::bind(f, _1); // OK
boost::bind(f, _1)("incompatible"); // error, "incompatible" is not an int
}
</pre>
<h3><a name="err_arg_access">Accessing an argument that does not exist</a></h3>
<p>
The placeholder <b>_N</b> selects the argument at position <b>N</b> from the
argument list passed at "call time." Naturally, it is an error to
attempt to access beyond the end of this list:
</p>
<pre>
int f(int);
int main()
{
boost::bind(f, _1); // OK
boost::bind(f, _1)(); // error, there is no argument number 1
}
</pre>
<p>
The error is usually reported in <b>bind.hpp</b>, at a line similar to:
</p>
<pre>
return f(a[a1_]);
</pre>
<p>
When emulating <b>std::bind1st(f, a)</b>, a common mistake of this category
is to type <b>bind(f, a, _2)</b> instead of the correct <b>bind(f, a, _1)</b>.
</p>
<h3><a name="err_short_form">Inappropriate use of bind(f, ...)</a></h3>
<p>
The bind(f, a1, a2, ..., aN) <a href="#Q_forms">form</a> causes automatic
recognition of the type of <b>f</b>. It will not work with arbitrary
function objects; <b>f</b> must be a function or a member function pointer.
</p>
<p>
It is possible to use this form with function objects that define
<b>result_type</b>, but <b>only on compilers</b> that support partial
specialization and partial ordering. In particular, MSVC up to version 7.0
does not support this syntax for function objects.
</p>
<h3><a name="err_long_form">Inappropriate use of bind<R>(f, ...)</a></h3>
<p>
The bind<R>(f, a1, a2, ..., aN) <a href="#Q_forms">form</a> supports
arbitrary function objects.
</p>
<p>
It is possible (but not recommended) to use this form with functions or
member function pointers, but <b>only on compilers</b> that support partial
ordering. In particular, MSVC up to version 7.0 does not fully support this
syntax for functions and member function pointers.
</p>
<h3><a name="err_nonstd">Binding a nonstandard function</a></h3>
<p>
(to be written)
</p>
<h3><a name="err_const_arg"><b>const</b> in signatures</a></h3>
<p>
Some compilers, including MSVC 6.0 and Borland C++ 5.5.1, have problems
with the top-level <b>const</b> in function signatures:
</p>
<pre>
int f(int const);
int main()
{
boost::bind(f, 1); // error
}
</pre>
<p>
Workaround: remove the <b>const</b> qualifier from the argument.
</p>
<h3><a name="err_msvc_using">MSVC specific: using boost::bind;</a></h3>
<p>
On MSVC (up to version 7.0), when <b>boost::bind</b> is brought into scope
with an using declaration:
</p>
<pre>
using boost::bind;
</pre>
<p>
the syntax <b>bind<R>(...)</b> does not work. Workaround: either use the
qualified name, <b>boost::bind</b>, or use an using directive instead:
</p>
<pre>
using namespace boost;
</pre>
<h3><a name="err_msvc_class_template">MSVC specific: class templates shadow function templates</a></h3>
<p>
On MSVC (up to version 7.0), a nested class template named <b>bind</b> will
shadow the function template <b>boost::bind</b>, breaking the
<b>bind<R>(...)</b> syntax. Unfortunately, some libraries contain nested
class templates named <b>bind</b> (ironically, such code is often an MSVC
specific workaround.) You may try to patch the library in question or contact
its author/maintainer. The other option is use the
<a href="#BOOST_BIND">BOOST_BIND</a> macro to rename <b>bind</b>.
</p>
<h3><a name="err_msvc_ellipsis">MSVC specific: ... in signatures treated as type</a></h3>
<p>
MSVC (up to version 7.0) treats the ellipsis in a variable argument function
(such as <b>std::printf</b>) as a type. Therefore, it will accept the
(incorrect in the current implementation) form:
</p>
<pre>
bind(printf, "%s\n", _1);
</pre>
<p>
and will reject the correct version:
</p>
<pre>
bind<int>(printf, "%s\n", _1);
</pre>
<h2><a name="Interface">Interface</a></h2>
<h3><a name="Synopsis">Synopsis</a></h3>
<pre>
namespace boost
{
// no arguments
template<class R, class F> <i>implementation-defined-1</i> <a href="#bind_1">bind</a>(F f);
template<class F> <i>implementation-defined-1-1</i> <a href="#bind_1_1">bind</a>(F f);
template<class R> <i>implementation-defined-2</i> <a href="#bind_2">bind</a>(R (*f) ());
// one argument
template<class R, class F, class A1> <i>implementation-defined-3</i> <a href="#bind_3">bind</a>(F f, A1 a1);
template<class F, class A1> <i>implementation-defined-3-1</i> <a href="#bind_3_1">bind</a>(F f, A1 a1);
template<class R, class B1, class A1> <i>implementation-defined-4</i> <a href="#bind_4">bind</a>(R (*f) (B1), A1 a1);
template<class R, class T, class A1> <i>implementation-defined-5</i> <a href="#bind_5">bind</a>(R (T::*f) (), A1 a1);
template<class R, class T, class A1> <i>implementation-defined-6</i> <a href="#bind_6">bind</a>(R (T::*f) () const, A1 a1);
// two arguments
template<class R, class F, class A1, class A2> <i>implementation-defined-7</i> <a href="#bind_7">bind</a>(F f, A1 a1, A2 a2);
template<class F, class A1, class A2> <i>implementation-defined-7-1</i> <a href="#bind_7_1">bind</a>(F f, A1 a1, A2 a2);
template<class R, class B1, class B2, class A1, class A2> <i>implementation-defined-8</i> <a href="#bind_8">bind</a>(R (*f) (B1, B2), A1 a1, A2 a2);
template<class R, class T, class B1, class A1, class A2> <i>implementation-defined-9</i> <a href="#bind_9">bind</a>(R (T::*f) (B1), A1 a1, A2 a2);
template<class R, class T, class B1, class A1, class A2> <i>implementation-defined-10</i> <a href="#bind_10">bind</a>(R (T::*f) (B1) const, A1 a1, A2 a2);
// implementation defined number of additional overloads for more arguments
}
namespace
{
<i>implementation-defined-placeholder-type-1</i> _1;
<i>implementation-defined-placeholder-type-2</i> _2;
<i>implementation-defined-placeholder-type-3</i> _3;
// implementation defined number of additional placeholder definitions
}
</pre>
<h3><a name="CommonRequirements">Common requirements</a></h3>
<p>
All <tt><i>implementation-defined-N</i></tt> types returned by <b>bind</b> are
<b>CopyConstructible</b>. <tt><i>implementation-defined-N</i>::result_type</tt> is defined as
the return type of <tt><i>implementation-defined-N</i>::operator()</tt>.
</p>
<p>
All <tt><i>implementation-defined-placeholder-N</i></tt> types are
<b>CopyConstructible</b>. Their copy constructors do not throw exceptions.
</p>
<h3><a name="CommonDefinitions">Common definitions</a></h3>
<p>
The function µ(x, v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>), where m is a nonnegative integer, is defined as:
</p>
<ul>
<li><tt>x.get()</tt>, when <tt>x</tt> is of type
<tt><a href="ref.html">boost::reference_wrapper</a><T></tt> for some type <tt>T</tt>;</li>
<li>v<sub>k</sub>, when <tt>x</tt> is (a copy of) the placeholder _k for some positive integer k;</li>
<li><tt>x(v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>)</tt>
when <tt>x</tt> is (a copy of) a function object returned by <b>bind</b>;</li>
<li><tt>x</tt> otherwise.</li>
</ul>
<h3><a name="bind">bind</a></h3>
<h4><a name="bind_1">template<class R, class F> <i>implementation-defined-1</i> bind(F f)</a></h4>
<p>
<b>Returns:</b> a function object <i>λ</i> such that the expression
<tt>λ(v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>()</tt>,
implicitly converted to <b>R</b>.
</p>
<p>
<b>Throws:</b> Nothing unless the copy constructor of <b>F</b> throws an exception.
</p>
<h4><a name="bind_1_1">template<class F> <i>implementation-defined-1-1</i> bind(F f)</a></h4>
<p>
<b>Effects:</b> equivalent to <tt>bind<typename F::result_type, F>(f);</tt>
</p>
<h4><a name="bind_2">template<class R> <i>implementation-defined-2</i> bind(R (*f) ())</a></h4>
<p>
<b>Returns:</b> a function object <i>λ</i> such that the expression
<tt>λ(v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to <tt><b>f</b>()</tt>.
</p>
<p>
<b>Throws:</b> Nothing.
</p>
<h4><a name="bind_3">template<class R, class F, class A1> <i>implementation-defined-3</i> bind(F f, A1 a1)</a></h4>
<p>
<b>Returns:</b> a function object <i>λ</i> such that the expression
<tt>λ(v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to
<tt><b>f</b>(µ(<b>a1</b>, v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>))</tt>,
implicitly converted to <b>R</b>.
</p>
<p>
<b>Throws:</b> Nothing unless the copy constructors of <b>F</b> or <b>A1</b> throw an exception.
</p>
<h4><a name="bind_3_1">template<class F, class A1> <i>implementation-defined-3-1</i> bind(F f, A1 a1)</a></h4>
<p>
<b>Effects:</b> equivalent to <tt>bind<typename F::result_type, F, A1>(f, a1);</tt>
</p>
<h4><a name="bind_4">template<class R, class B1, class A1> <i>implementation-defined-4</i> bind(R (*f) (B1), A1 a1)</a></h4>
<p>
<b>Returns:</b> a function object <i>λ</i> such that the expression
<tt>λ(v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to
<tt><b>f</b>(µ(<b>a1</b>, v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>))</tt>.
</p>
<p>
<b>Throws:</b> Nothing unless the copy constructor of <b>A1</b> throws an exception.
</p>
<h4><a name="bind_5">template<class R, class T, class A1> <i>implementation-defined-5</i> bind(R (T::*f) (), A1 a1)</a></h4>
<p>
<b>Effects:</b> equivalent to <tt>bind<R>(<a href="mem_fn.html">boost::mem_fn</a>(f), a1);</tt>
</p>
<h4><a name="bind_6">template<class R, class T, class A1> <i>implementation-defined-6</i> bind(R (T::*f) () const, A1 a1)</a></h4>
<p>
<b>Effects:</b> equivalent to <tt>bind<R>(<a href="mem_fn.html">boost::mem_fn</a>(f), a1);</tt>
</p>
<h4><a name="bind_7">template<class R, class F, class A1, class A2> <i>implementation-defined-7</i> bind(F f, A1 a1, A2 a2)</a></h4>
<p>
<b>Returns:</b> a function object <i>λ</i> such that the expression
<tt>λ(v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to
<tt><b>f</b>(µ(<b>a1</b>, v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>), µ(<b>a2</b>, v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>))</tt>,
implicitly converted to <b>R</b>.
</p>
<p>
<b>Throws:</b> Nothing unless the copy constructors of <b>F</b>, <b>A1</b> or <b>A2</b> throw an exception.
</p>
<h4><a name="bind_7_1">template<class F, class A1, class A2> <i>implementation-defined-7-1</i> bind(F f, A1 a1, A2 a2)</a></h4>
<p>
<b>Effects:</b> equivalent to <tt>bind<typename F::result_type, F, A1, A2>(f, a1, a2);</tt>
</p>
<h4><a name="bind_8">template<class R, class B1, class B2, class A1, class A2> <i>implementation-defined-8</i> bind(R (*f) (B1, B2), A1 a1, A2 a2)</a></h4>
<p>
<b>Returns:</b> a function object <i>λ</i> such that the expression
<tt>λ(v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>)</tt> is equivalent to
<tt><b>f</b>(µ(<b>a1</b>, v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>), µ(<b>a2</b>, v<sub>1</sub>, v<sub>2</sub>, ..., v<sub>m</sub>))</tt>.
</p>
<p>
<b>Throws:</b> Nothing unless the copy constructors of <b>A1</b> or <b>A2</b> throw an exception.
</p>
<h4><a name="bind_9">template<class R, class T, class B1, class A1, class A2> <i>implementation-defined-9</i> bind(R (T::*f) (B1), A1 a1, A2 a2)</a></h4>
<p>
<b>Effects:</b> equivalent to <tt>bind<R>(<a href="mem_fn.html">boost::mem_fn</a>(f), a1, a2);</tt>
</p>
<h4><a name="bind_10">template<class R, class T, class B1, class A1, class A2> <i>implementation-defined-10</i> bind(R (T::*f) (B1) const, A1 a1, A2 a2)</a></h4>
<p>
<b>Effects:</b> equivalent to <tt>bind<R>(<a href="mem_fn.html">boost::mem_fn</a>(f), a1, a2);</tt>
</p>
<h2><a name="Implementation">Implementation</a></h2>
<h3><a name="Files">Files</a></h3>
<ul>
<li><a href="../../boost/bind.hpp">boost/bind.hpp</a> (main header)</li>
<li><a href="../../boost/bind/bind_cc.hpp">boost/bind/bind_cc.hpp</a> (used by bind.hpp, do not include directly)
<li><a href="../../boost/bind/bind_mf_cc.hpp">boost/bind/bind_mf_cc.hpp</a> (used by bind.hpp, do not include directly)
<li><a href="../../boost/bind/bind_template.hpp">boost/bind/bind_template.hpp</a> (used by bind.hpp, do not include directly)
<li><a href="bind_test.cpp">libs/bind/bind_test.cpp</a> (test)</li>
<li><a href="bind_as_compose.cpp">libs/bind/bind_as_compose.cpp</a> (function composition example)</li>
<li><a href="bind_visitor.cpp">libs/bind/bind_visitor.cpp</a> (visitor example)</li>
<li><a href="bind_stdcall_test.cpp">libs/bind/bind_stdcall_test.cpp</a> (test with __stdcall functions)</li>
<li><a href="bind_stdcall_mf_test.cpp">libs/bind/bind_stdcall_mf_test.cpp</a> (test with __stdcall member functions)</li>
</ul>
<h3><a name="Dependencies">Dependencies</a></h3>
<ul>
<li><a href="../config/config.htm">Boost.Config</a>
<li><a href="ref.html">boost/ref.hpp</a>
<li><a href="mem_fn.html">boost/mem_fn.hpp</a>
</ul>
<h3><a name="NumberOfArguments">Number of Arguments</a></h3>
<p>
This implementation supports function objects with up to nine arguments.
This is an implementation detail, not an inherent limitation of the
design.
</p>
<h3><a name="stdcall">"__stdcall" and "pascal" Support</a></h3>
<p>
Some platforms allow several types of (member) functions that differ by their
<b>calling convention</b> (the rules by which the function is invoked: how
are arguments passed, how is the return value handled, and who cleans up the
stack - if any.)
</p>
<p>
For example, Windows API functions and COM interface member functions use a
calling convention known as <b>__stdcall</b>. Mac toolbox functions use a
<b>pascal</b> calling convention.
</p>
<p>
To use <b>bind</b> with <b>__stdcall</b> functions, <b>#define</b> the macro
<b>BOOST_BIND_ENABLE_STDCALL</b> before including <b><boost/bind.hpp></b>.
</p>
<p>
To use <b>bind</b> with <b>__stdcall</b> <b>member</b> functions, <b>#define</b> the
macro <b>BOOST_MEM_FN_ENABLE_STDCALL</b> before including <b><boost/bind.hpp></b>.
</p>
<p>
To use <b>bind</b> with <b>pascal</b> functions, <b>#define</b> the macro
<b>BOOST_BIND_ENABLE_PASCAL</b> before including <b><boost/bind.hpp></b>.
</p>
<p>
[Note: this is a non-portable extension. It is not part of the interface.]
</p>
<p>
[Note: Some compilers provide only minimal support for the <b>__stdcall</b> keyword.]
</p>
<h3><a name="BOOST_BIND">Using the BOOST_BIND macro</a></h3>
<p>
A <a href="#err_msvc_class_template">bug in MSVC (up to version 7.0)</a>
causes <b>boost::bind</b> to be incompatible
with libraries that contain nested class templates named <b>bind</b>. To work
around this problem, <b>#define</b> the macro <b>BOOST_BIND</b> to something
other than <b>bind</b> (before the inclusion of <b><boost/bind.hpp></b>)
and use this identifier throughout your code wherever you'd normally use
<b>bind</b>.
</p>
<p style="color: Red;">
[Note: BOOST_BIND is not a general renaming mechanism. It is not part of the
interface, and is not guaranteed to work on other compilers, or persist between
library versions. In short, don't use it unless you absolutely have to.]
</p>
<h3><a name="visit_each"><b>visit_each</b> support</a></h3>
<p>
Function objects returned by <b>bind</b> support the experimental and
undocumented, as of yet, <b>visit_each</b> enumeration interface.
</p>
<p>
See <a href="bind_visitor.cpp">bind_visitor.cpp</a> for an example.
</p>
<h2><a name="Acknowledgements">Acknowledgements</a></h2>
<p>
Earlier efforts that have influenced the library design:
</p>
<ul>
<li>The <a href="http://staff.cs.utu.fi/BL/">Binder Library</a>
by Jaakko Järvi;
<li>The <a href="http://lambda.cs.utu.fi/">Lambda Library</a>
by Jaakko Järvi and Gary Powell (the successor to the Binder Library);
<li><a href="http://matfys.lth.se/~petter/src/more/stlext/index.html">
Extensions to the STL</a> by Petter Urkedal.
</ul>
<p>
Doug Gregor suggested that a visitor mechanism would allow <b>bind</b> to
interoperate with a signal/slot library.
</p>
<p>
John Maddock fixed a MSVC-specific conflict between <b>bind</b> and the
<a href="../type_traits/index.htm">type traits library</a>.
</p>
<p>
Numerous improvements were suggested during the formal review period by
Ross Smith, Richard Crossley, Jens Maurer, Ed Brey, and others. Review manager
was Darin Adler.
</p>
<p>
The precise semantics of <b>bind</b> were refined in discussions with Jaakko Järvi.
</p>
<p>
Dave Abrahams fixed a MSVC-specific conflict between <b>bind</b> and the
<a href="../utility\iterator_adaptors.htm">iterator adaptors library</a>.
</p>
<p>
Dave Abrahams modified <b>bind</b> and <b>mem_fn</b> to support void returns
on deficient compilers.
</p>
<p>
Mac Murrett contributed the "pascal" support enabled by
BOOST_BIND_ENABLE_PASCAL.
</p>
<p><br><br><br><small>Copyright © 2001 by Peter Dimov and Multi Media
Ltd. Permission to copy, use, modify, sell and distribute this document is
granted provided this copyright notice appears in all copies. This document
is provided "as is" without express or implied warranty, and with
no claim as to its suitability for any purpose.</small></p>
</body>
</html>
|
