Skip to content
This repository was archived by the owner on Oct 12, 2022. It is now read-only.

Commit f2277d3

Browse files
dkorpeldlang-bot
dkorpel
authored and
dlang-bot
committed
Issue 23212 - Improve documentation of rt/aApply
1 parent 412a2e6 commit f2277d3

File tree

2 files changed

+125
-54
lines changed

2 files changed

+125
-54
lines changed

‎src/rt/aApply.d‎

Lines changed: 81 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
/**
2-
* This code handles decoding UTF strings for foreach loops. There are 6
3-
* combinations of conversions between char, wchar, and dchar, and 2 of each
4-
* of those.
2+
* This code handles decoding UTF strings for foreach loops.
53
*
64
* Copyright: Copyright Digital Mars 2004 - 2010.
75
* License: $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0).
@@ -15,9 +13,64 @@ import core.internal.utf : decode, toUTF8;
1513
/**********************************************/
1614
/* 1 argument versions */
1715

18-
// dg is D, but _aApplycd() is C
19-
extern (D) alias int delegate(void *) dg_t;
16+
/**
17+
Delegate type corresponding to transformed loop body
18+
19+
The parameter is a pointer to the current `char`, `wchar` or `dchar`
20+
21+
Returns: non-zero when a `break` statement is hit
22+
*/
23+
extern (D) alias dg_t = int delegate(void* c);
24+
25+
// Note: dg is extern(D), but _aApplycd() is extern(C)
26+
27+
/**
28+
Loop over a string while changing the UTF encoding
29+
30+
There are 6 combinations of conversions between `char`, `wchar`, and `dchar`,
31+
and 2 of each of those.
32+
33+
The naming convention is as follows:
34+
35+
_aApply{c,d,w}{c,d,w}{1,2}
2036
37+
The first letter corresponds to the input string encoding, and the second letter corresponds to the target character type.
38+
39+
- c = `char`
40+
- w = `wchar`
41+
- d = `dchar`
42+
43+
The `1` variant only produces the character, the `2` variant also produces a loop index.
44+
45+
Examples:
46+
---
47+
void main()
48+
{
49+
string str;
50+
wtring wstr;
51+
dstring dstr;
52+
53+
foreach (dchar c; str) {}
54+
// _aApplycd1
55+
56+
foreach (wchar c; dstr) {}
57+
// _aApplydw1
58+
59+
foreach (i, wchar c; str) {}
60+
// _aApplycw2
61+
62+
foreach (wchar w; wstr) {}
63+
// no conversion
64+
}
65+
---
66+
67+
Params:
68+
aa = input string
69+
dg = foreach body transformed into a delegate, similar to `opApply`
70+
71+
Returns:
72+
non-zero when the loop was exited through a `break`
73+
*/
2174
extern (C) int _aApplycd1(in char[] aa, dg_t dg)
2275
{
2376
int result;
@@ -78,8 +131,7 @@ unittest
78131
assert(i == 4);
79132
}
80133

81-
/*****************************/
82-
134+
/// ditto
83135
extern (C) int _aApplywd1(in wchar[] aa, dg_t dg)
84136
{
85137
int result;
@@ -140,8 +192,7 @@ unittest
140192
assert(i == 4);
141193
}
142194

143-
/*****************************/
144-
195+
/// ditto
145196
extern (C) int _aApplycw1(in char[] aa, dg_t dg)
146197
{
147198
int result;
@@ -215,8 +266,7 @@ unittest
215266
assert(i == 5);
216267
}
217268

218-
/*****************************/
219-
269+
/// ditto
220270
extern (C) int _aApplywc1(in wchar[] aa, dg_t dg)
221271
{
222272
int result;
@@ -296,8 +346,7 @@ unittest
296346
assert(i == 9);
297347
}
298348

299-
/*****************************/
300-
349+
/// ditto
301350
extern (C) int _aApplydc1(in dchar[] aa, dg_t dg)
302351
{
303352
int result;
@@ -373,8 +422,7 @@ unittest
373422
assert(i == 9);
374423
}
375424

376-
/*****************************/
377-
425+
/// ditto
378426
extern (C) int _aApplydw1(in dchar[] aa, dg_t dg)
379427
{
380428
int result;
@@ -446,9 +494,20 @@ unittest
446494
/****************************************************************************/
447495
/* 2 argument versions */
448496

449-
// dg is D, but _aApplycd2() is C
450-
extern (D) alias int delegate(void *, void *) dg2_t;
497+
/**
498+
Delegate type corresponding to transformed loop body
499+
500+
Parameters are pointers to a `size_t` loop index, and the current `char`, `wchar` or `dchar`.
451501
502+
Returns: non-zero when a `break` statement is hit
503+
*/
504+
extern (D) alias dg2_t = int delegate(void* i, void* c);
505+
506+
// Note: dg is extern(D), but _aApplycd2() is extern(C)
507+
508+
/**
509+
Variants of _aApplyXXX that include a loop index.
510+
*/
452511
extern (C) int _aApplycd2(in char[] aa, dg2_t dg)
453512
{
454513
int result;
@@ -516,8 +575,7 @@ unittest
516575
assert(i == 4);
517576
}
518577

519-
/*****************************/
520-
578+
/// ditto
521579
extern (C) int _aApplywd2(in wchar[] aa, dg2_t dg)
522580
{
523581
int result;
@@ -585,8 +643,7 @@ unittest
585643
assert(i == 4);
586644
}
587645

588-
/*****************************/
589-
646+
/// ditto
590647
extern (C) int _aApplycw2(in char[] aa, dg2_t dg)
591648
{
592649
int result;
@@ -665,8 +722,7 @@ unittest
665722
assert(i == 5);
666723
}
667724

668-
/*****************************/
669-
725+
/// ditto
670726
extern (C) int _aApplywc2(in wchar[] aa, dg2_t dg)
671727
{
672728
int result;
@@ -751,8 +807,7 @@ unittest
751807
assert(i == 9);
752808
}
753809

754-
/*****************************/
755-
810+
/// ditto
756811
extern (C) int _aApplydc2(in dchar[] aa, dg2_t dg)
757812
{
758813
int result;
@@ -832,8 +887,7 @@ unittest
832887
assert(i == 9);
833888
}
834889

835-
/*****************************/
836-
890+
/// ditto
837891
extern (C) int _aApplydw2(in dchar[] aa, dg2_t dg)
838892
{ int result;
839893

‎src/rt/aApplyR.d‎

Lines changed: 44 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
/**
2-
* This code handles decoding UTF strings for foreach_reverse loops. There are
3-
* 6 combinations of conversions between char, wchar, and dchar, and 2 of each
4-
* of those.
2+
* This code handles decoding UTF strings for `foreach_reverse` loops.
53
*
64
* Copyright: Copyright Digital Mars 2004 - 2010.
75
* License: $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0).
@@ -15,9 +13,27 @@ import core.internal.utf;
1513
/**********************************************/
1614
/* 1 argument versions */
1715

18-
// dg is D, but _aApplyRcd() is C
19-
extern (D) alias int delegate(void *) dg_t;
16+
// Note: dg is extern(D), but _aApplyRcd() is extern(C)
2017

18+
/**
19+
Delegate type corresponding to transformed loop body
20+
21+
The parameter is a pointer to the current `char`, `wchar` or `dchar`
22+
23+
Returns: non-zero when a `break` statement is hit
24+
*/
25+
extern (D) alias dg_t = int delegate(void* c);
26+
27+
/**
28+
Same as `_aApplyXXX` functions, but for `foreach_reverse`
29+
30+
Params:
31+
aa = input string
32+
dg = foreach body transformed into a delegate, similar to `opApply`
33+
34+
Returns:
35+
non-zero when the loop was exited through a `break`
36+
*/
2137
extern (C) int _aApplyRcd1(in char[] aa, dg_t dg)
2238
{ int result;
2339

@@ -90,8 +106,7 @@ unittest
90106
assert(i == 4);
91107
}
92108

93-
/*****************************/
94-
109+
/// ditto
95110
extern (C) int _aApplyRwd1(in wchar[] aa, dg_t dg)
96111
{ int result;
97112

@@ -154,8 +169,7 @@ unittest
154169
assert(i == 4);
155170
}
156171

157-
/*****************************/
158-
172+
/// ditto
159173
extern (C) int _aApplyRcw1(in char[] aa, dg_t dg)
160174
{ int result;
161175

@@ -241,8 +255,7 @@ unittest
241255
assert(i == 5);
242256
}
243257

244-
/*****************************/
245-
258+
/// ditto
246259
extern (C) int _aApplyRwc1(in wchar[] aa, dg_t dg)
247260
{ int result;
248261

@@ -326,8 +339,7 @@ unittest
326339
assert(i == 9);
327340
}
328341

329-
/*****************************/
330-
342+
/// ditto
331343
extern (C) int _aApplyRdc1(in dchar[] aa, dg_t dg)
332344
{ int result;
333345

@@ -405,8 +417,7 @@ unittest
405417
assert(i == 9);
406418
}
407419

408-
/*****************************/
409-
420+
/// ditto
410421
extern (C) int _aApplyRdw1(in dchar[] aa, dg_t dg)
411422
{ int result;
412423

@@ -477,9 +488,20 @@ unittest
477488
/****************************************************************************/
478489
/* 2 argument versions */
479490

480-
// dg is D, but _aApplyRcd2() is C
481-
extern (D) alias int delegate(void *, void *) dg2_t;
491+
/**
492+
Delegate type corresponding to transformed loop body
493+
494+
Parameters are pointers to a `size_t` loop index, and the current `char`, `wchar` or `dchar`.
482495
496+
Returns: non-zero when a `break` statement is hit
497+
*/
498+
extern (D) alias dg2_t = int delegate(void* i, void* c);
499+
500+
// Note: dg is extern(D), but _aApplyRcd2() is extern(C)
501+
502+
/**
503+
Variants of _aApplyRXXX that include a loop index.
504+
*/
483505
extern (C) int _aApplyRcd2(in char[] aa, dg2_t dg)
484506
{ int result;
485507
size_t i;
@@ -555,8 +577,7 @@ unittest
555577
assert(i == 4);
556578
}
557579

558-
/*****************************/
559-
580+
/// ditto
560581
extern (C) int _aApplyRwd2(in wchar[] aa, dg2_t dg)
561582
{ int result;
562583

@@ -621,8 +642,7 @@ unittest
621642
assert(i == 4);
622643
}
623644

624-
/*****************************/
625-
645+
/// ditto
626646
extern (C) int _aApplyRcw2(in char[] aa, dg2_t dg)
627647
{ int result;
628648

@@ -710,8 +730,7 @@ unittest
710730
assert(i == 5);
711731
}
712732

713-
/*****************************/
714-
733+
/// ditto
715734
extern (C) int _aApplyRwc2(in wchar[] aa, dg2_t dg)
716735
{ int result;
717736

@@ -797,8 +816,7 @@ unittest
797816
assert(i == 9);
798817
}
799818

800-
/*****************************/
801-
819+
/// ditto
802820
extern (C) int _aApplyRdc2(in dchar[] aa, dg2_t dg)
803821
{ int result;
804822

@@ -877,8 +895,7 @@ unittest
877895
assert(i == 9);
878896
}
879897

880-
/*****************************/
881-
898+
/// ditto
882899
extern (C) int _aApplyRdw2(in dchar[] aa, dg2_t dg)
883900
{ int result;
884901

0 commit comments

Comments
 (0)