diff --git a/src/rt/aApply.d b/src/rt/aApply.d index bea441f550..5d5ddb3474 100644 --- a/src/rt/aApply.d +++ b/src/rt/aApply.d @@ -1,7 +1,5 @@ /** - * This code handles decoding UTF strings for foreach loops. There are 6 - * combinations of conversions between char, wchar, and dchar, and 2 of each - * of those. + * This code handles decoding UTF strings for foreach loops. * * Copyright: Copyright Digital Mars 2004 - 2010. * License: $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0). @@ -15,9 +13,64 @@ import core.internal.utf : decode, toUTF8; /**********************************************/ /* 1 argument versions */ -// dg is D, but _aApplycd() is C -extern (D) alias int delegate(void *) dg_t; +/** +Delegate type corresponding to transformed loop body + +The parameter is a pointer to the current `char`, `wchar` or `dchar` + +Returns: non-zero when a `break` statement is hit +*/ +extern (D) alias dg_t = int delegate(void* c); + +// Note: dg is extern(D), but _aApplycd() is extern(C) + +/** +Loop over a string while changing the UTF encoding + +There are 6 combinations of conversions between `char`, `wchar`, and `dchar`, +and 2 of each of those. + +The naming convention is as follows: + +_aApply{c,d,w}{c,d,w}{1,2} +The first letter corresponds to the input string encoding, and the second letter corresponds to the target character type. + +- c = `char` +- w = `wchar` +- d = `dchar` + +The `1` variant only produces the character, the `2` variant also produces a loop index. + +Examples: +--- +void main() +{ + string str; + wtring wstr; + dstring dstr; + + foreach (dchar c; str) {} + // _aApplycd1 + + foreach (wchar c; dstr) {} + // _aApplydw1 + + foreach (i, wchar c; str) {} + // _aApplycw2 + + foreach (wchar w; wstr) {} + // no conversion +} +--- + +Params: + aa = input string + dg = foreach body transformed into a delegate, similar to `opApply` + +Returns: + non-zero when the loop was exited through a `break` +*/ extern (C) int _aApplycd1(in char[] aa, dg_t dg) { int result; @@ -78,8 +131,7 @@ unittest assert(i == 4); } -/*****************************/ - +/// ditto extern (C) int _aApplywd1(in wchar[] aa, dg_t dg) { int result; @@ -140,8 +192,7 @@ unittest assert(i == 4); } -/*****************************/ - +/// ditto extern (C) int _aApplycw1(in char[] aa, dg_t dg) { int result; @@ -215,8 +266,7 @@ unittest assert(i == 5); } -/*****************************/ - +/// ditto extern (C) int _aApplywc1(in wchar[] aa, dg_t dg) { int result; @@ -296,8 +346,7 @@ unittest assert(i == 9); } -/*****************************/ - +/// ditto extern (C) int _aApplydc1(in dchar[] aa, dg_t dg) { int result; @@ -373,8 +422,7 @@ unittest assert(i == 9); } -/*****************************/ - +/// ditto extern (C) int _aApplydw1(in dchar[] aa, dg_t dg) { int result; @@ -446,9 +494,20 @@ unittest /****************************************************************************/ /* 2 argument versions */ -// dg is D, but _aApplycd2() is C -extern (D) alias int delegate(void *, void *) dg2_t; +/** +Delegate type corresponding to transformed loop body + +Parameters are pointers to a `size_t` loop index, and the current `char`, `wchar` or `dchar`. +Returns: non-zero when a `break` statement is hit +*/ +extern (D) alias dg2_t = int delegate(void* i, void* c); + +// Note: dg is extern(D), but _aApplycd2() is extern(C) + +/** +Variants of _aApplyXXX that include a loop index. +*/ extern (C) int _aApplycd2(in char[] aa, dg2_t dg) { int result; @@ -516,8 +575,7 @@ unittest assert(i == 4); } -/*****************************/ - +/// ditto extern (C) int _aApplywd2(in wchar[] aa, dg2_t dg) { int result; @@ -585,8 +643,7 @@ unittest assert(i == 4); } -/*****************************/ - +/// ditto extern (C) int _aApplycw2(in char[] aa, dg2_t dg) { int result; @@ -665,8 +722,7 @@ unittest assert(i == 5); } -/*****************************/ - +/// ditto extern (C) int _aApplywc2(in wchar[] aa, dg2_t dg) { int result; @@ -751,8 +807,7 @@ unittest assert(i == 9); } -/*****************************/ - +/// ditto extern (C) int _aApplydc2(in dchar[] aa, dg2_t dg) { int result; @@ -832,8 +887,7 @@ unittest assert(i == 9); } -/*****************************/ - +/// ditto extern (C) int _aApplydw2(in dchar[] aa, dg2_t dg) { int result; diff --git a/src/rt/aApplyR.d b/src/rt/aApplyR.d index 7f19fa8152..ce3bb9eaf7 100644 --- a/src/rt/aApplyR.d +++ b/src/rt/aApplyR.d @@ -1,7 +1,5 @@ /** - * This code handles decoding UTF strings for foreach_reverse loops. There are - * 6 combinations of conversions between char, wchar, and dchar, and 2 of each - * of those. + * This code handles decoding UTF strings for `foreach_reverse` loops. * * Copyright: Copyright Digital Mars 2004 - 2010. * License: $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0). @@ -15,9 +13,27 @@ import core.internal.utf; /**********************************************/ /* 1 argument versions */ -// dg is D, but _aApplyRcd() is C -extern (D) alias int delegate(void *) dg_t; +// Note: dg is extern(D), but _aApplyRcd() is extern(C) +/** +Delegate type corresponding to transformed loop body + +The parameter is a pointer to the current `char`, `wchar` or `dchar` + +Returns: non-zero when a `break` statement is hit +*/ +extern (D) alias dg_t = int delegate(void* c); + +/** +Same as `_aApplyXXX` functions, but for `foreach_reverse` + +Params: + aa = input string + dg = foreach body transformed into a delegate, similar to `opApply` + +Returns: + non-zero when the loop was exited through a `break` +*/ extern (C) int _aApplyRcd1(in char[] aa, dg_t dg) { int result; @@ -90,8 +106,7 @@ unittest assert(i == 4); } -/*****************************/ - +/// ditto extern (C) int _aApplyRwd1(in wchar[] aa, dg_t dg) { int result; @@ -154,8 +169,7 @@ unittest assert(i == 4); } -/*****************************/ - +/// ditto extern (C) int _aApplyRcw1(in char[] aa, dg_t dg) { int result; @@ -241,8 +255,7 @@ unittest assert(i == 5); } -/*****************************/ - +/// ditto extern (C) int _aApplyRwc1(in wchar[] aa, dg_t dg) { int result; @@ -326,8 +339,7 @@ unittest assert(i == 9); } -/*****************************/ - +/// ditto extern (C) int _aApplyRdc1(in dchar[] aa, dg_t dg) { int result; @@ -405,8 +417,7 @@ unittest assert(i == 9); } -/*****************************/ - +/// ditto extern (C) int _aApplyRdw1(in dchar[] aa, dg_t dg) { int result; @@ -477,9 +488,20 @@ unittest /****************************************************************************/ /* 2 argument versions */ -// dg is D, but _aApplyRcd2() is C -extern (D) alias int delegate(void *, void *) dg2_t; +/** +Delegate type corresponding to transformed loop body + +Parameters are pointers to a `size_t` loop index, and the current `char`, `wchar` or `dchar`. +Returns: non-zero when a `break` statement is hit +*/ +extern (D) alias dg2_t = int delegate(void* i, void* c); + +// Note: dg is extern(D), but _aApplyRcd2() is extern(C) + +/** +Variants of _aApplyRXXX that include a loop index. +*/ extern (C) int _aApplyRcd2(in char[] aa, dg2_t dg) { int result; size_t i; @@ -555,8 +577,7 @@ unittest assert(i == 4); } -/*****************************/ - +/// ditto extern (C) int _aApplyRwd2(in wchar[] aa, dg2_t dg) { int result; @@ -621,8 +642,7 @@ unittest assert(i == 4); } -/*****************************/ - +/// ditto extern (C) int _aApplyRcw2(in char[] aa, dg2_t dg) { int result; @@ -710,8 +730,7 @@ unittest assert(i == 5); } -/*****************************/ - +/// ditto extern (C) int _aApplyRwc2(in wchar[] aa, dg2_t dg) { int result; @@ -797,8 +816,7 @@ unittest assert(i == 9); } -/*****************************/ - +/// ditto extern (C) int _aApplyRdc2(in dchar[] aa, dg2_t dg) { int result; @@ -877,8 +895,7 @@ unittest assert(i == 9); } -/*****************************/ - +/// ditto extern (C) int _aApplyRdw2(in dchar[] aa, dg2_t dg) { int result;