Skip to content

Commit

Permalink
Merge pull request #692 from nazriel/runnable-examples
Browse files Browse the repository at this point in the history 
Runnable examples - std.array, std.base64, std.concurreny
  • Loading branch information
@andralex
andralex committed Jul 16, 2012
2 parents 4f8c154 + dc408e6 commit acc8c7d
Show file tree
Hide file tree
Showing 3 changed files with 130 additions and 24 deletions.
49 changes: 48 additions & 1 deletion std/array.d
View file
Expand Up @@ -26,10 +26,13 @@ a special case in an overload.
Example:
$(D_RUN_CODE
$(ARGS
----
auto a = array([1, 2, 3, 4, 5][]);
assert(a == [ 1, 2, 3, 4, 5 ]);
----
), $(ARGS), $(ARGS), $(ARGS import std.array;))
*/
ForeachType!Range[] array(Range)(Range r)
if (isIterable!Range && !isNarrowString!Range)
Expand Down Expand Up @@ -207,6 +210,8 @@ array. In this case sizes may be specified for any number of dimensions from 1
to the number in $(D T).
Examples:
$(D_RUN_CODE
$(ARGS
---
double[] arr = uninitializedArray!(double[])(100);
assert(arr.length == 100);
Expand All @@ -215,6 +220,7 @@ double[][] matrix = uninitializedArray!(double[][])(42, 31);
assert(matrix.length == 42);
assert(matrix[0].length == 31);
---
), $(ARGS), $(ARGS), $(ARGS import std.array;))
*/
auto uninitializedArray(T, I...)(I sizes)
if(allSatisfy!(isIntegral, I))
Expand Down Expand Up @@ -293,11 +299,14 @@ the first argument using the dot notation, $(D array.empty) is
equivalent to $(D empty(array)).
Example:
$(D_RUN_CODE
$(ARGS
----
auto a = [ 1, 2, 3 ];
assert(!a.empty);
assert(a[3 .. $].empty);
----
), $(ARGS), $(ARGS), $(ARGS import std.array;))
*/

@property bool empty(T)(in T[] a) @safe pure nothrow
Expand All @@ -320,11 +329,14 @@ equivalent to $(D save(array)). The function does not duplicate the
content of the array, it simply returns its argument.
Example:
$(D_RUN_CODE
$(ARGS
----
auto a = [ 1, 2, 3 ];
auto b = a.save;
assert(b is a);
----
), $(ARGS), $(ARGS), $(ARGS import std.array;))
*/

@property T[] save(T)(T[] a) @safe pure nothrow
Expand All @@ -341,11 +353,14 @@ $(D popFront) automaticaly advances to the next $(GLOSSARY code
point).
Example:
$(D_RUN_CODE
$(ARGS
----
int[] a = [ 1, 2, 3 ];
a.popFront();
assert(a == [ 2, 3 ]);
----
), $(ARGS), $(ARGS), $(ARGS import std.array;))
*/

void popFront(A)(ref A a)
Expand Down Expand Up @@ -408,11 +423,14 @@ popFront) automaticaly eliminates the last $(GLOSSARY code point).
Example:
$(D_RUN_CODE
$(ARGS
----
int[] a = [ 1, 2, 3 ];
a.popBack();
assert(a == [ 1, 2 ]);
----
), $(ARGS), $(ARGS), $(ARGS import std.array;))
*/

void popBack(A)(ref A a)
Expand Down Expand Up @@ -475,10 +493,13 @@ dchar).
Example:
$(D_RUN_CODE
$(ARGS
----
int[] a = [ 1, 2, 3 ];
assert(a.front == 1);
----
), $(ARGS), $(ARGS), $(ARGS import std.array;))
*/
@property ref T front(T)(T[] a)
if (!isNarrowString!(T[]) && !is(T[] == void[]))
Expand Down Expand Up @@ -516,10 +537,13 @@ back) automaticaly returns the last $(GLOSSARY code point) as a $(D
dchar).
Example:
$(D_RUN_CODE
$(ARGS
----
int[] a = [ 1, 2, 3 ];
assert(a.back == 3);
----
), $(ARGS), $(ARGS), $(ARGS import std.array;))
*/
@property ref T back(T)(T[] a) if (!isNarrowString!(T[]))
{
Expand Down Expand Up @@ -557,6 +581,8 @@ values referred by them. If $(D r1) and $(D r2) have an overlapping
slice, returns that slice. Otherwise, returns the null slice.
Example:
$(D_RUN_CODE
$(ARGS
----
int[] a = [ 10, 11, 12, 13, 14 ];
int[] b = a[1 .. 3];
Expand All @@ -565,6 +591,7 @@ b = b.dup;
// overlap disappears even though the content is the same
assert(overlap(a, b).empty);
----
), $(ARGS), $(ARGS), $(ARGS import std.array;))
*/
inout(T)[] overlap(T)(inout(T)[] r1, inout(T)[] r2) @trusted pure nothrow
{
Expand Down Expand Up @@ -616,12 +643,15 @@ it's commented out.
must be an input range or a single item) inserted at position $(D pos).
Examples:
$(D_RUN_CODE
$(ARGS
--------------------
int[] a = [ 1, 2, 3, 4 ];
auto b = a.insert(2, [ 1, 2 ]);
assert(a == [ 1, 2, 3, 4 ]);
assert(b == [ 1, 2, 1, 2, 3, 4 ]);
--------------------
), $(ARGS), $(ARGS), $(ARGS import std.array;))
+/
T[] insert(T, Range)(T[] array, size_t pos, Range stuff)
if(isInputRange!Range &&
Expand Down Expand Up @@ -718,13 +748,16 @@ unittest
implicitly convertible items) in $(D array) at position $(D pos).
Example:
$(D_RUN_CODE
$(ARGS
---
int[] a = [ 1, 2, 3, 4 ];
a.insertInPlace(2, [ 1, 2 ]);
assert(a == [ 1, 2, 1, 2, 3, 4 ]);
a.insertInPlace(3, 10u, 11);
assert(a == [ 1, 2, 1, 10, 11, 2, 3, 4]);
---
), $(ARGS), $(ARGS), $(ARGS import std.array;))
+/
void insertInPlace(T, Range)(ref T[] array, size_t pos, Range stuff)
if(isInputRange!Range &&
Expand Down Expand Up @@ -1078,11 +1111,13 @@ unittest
Splits a string by whitespace.
Example:
$(D_RUN_CODE
$(ARGS
----
auto a = " a bcd ef gh ";
assert(equal(splitter(a), ["", "a", "bcd", "ef", "gh"][]));
----
), $(ARGS), $(ARGS), $(ARGS import std.array, std.algorithm: equal;))
*/
auto splitter(C)(C[] s)
if(isSomeString!(C[]))
Expand Down Expand Up @@ -1176,13 +1211,16 @@ unittest
$(D sep) as the separator if present.
Examples:
$(D_RUN_CODE
$(ARGS
--------------------
assert(join(["hello", "silly", "world"], " ") == "hello silly world");
assert(join(["hello", "silly", "world"]) == "hellosillyworld");
assert(join([[1, 2, 3], [4, 5]], [72, 73]) == [1, 2, 3, 72, 73, 4, 5]);
assert(join([[1, 2, 3], [4, 5]]) == [1, 2, 3, 4, 5]);
--------------------
), $(ARGS), $(ARGS), $(ARGS import std.array;))
+/
ElementEncodingType!(ElementType!RoR)[] join(RoR, R)(RoR ror, R sep)
if(isInputRange!RoR &&
Expand Down Expand Up @@ -1555,12 +1593,15 @@ until then, it's commented out.
array without changing the contents of $(D subject).
Examples:
$(D_RUN_CODE
$(ARGS
--------------------
auto a = [ 1, 2, 3, 4 ];
auto b = a.replace(1, 3, [ 9, 9, 9 ]);
assert(a == [ 1, 2, 3, 4 ]);
assert(b == [ 1, 9, 9, 9, 4 ]);
--------------------
), $(ARGS), $(ARGS), $(ARGS import std.array;))
+/
T[] replace(T, Range)(T[] subject, size_t from, size_t to, Range stuff)
if(isInputRange!Range &&
Expand Down Expand Up @@ -1651,11 +1692,14 @@ unittest
shrinks the array as needed.
Example:
$(D_RUN_CODE
$(ARGS
---
int[] a = [ 1, 2, 3, 4 ];
a.replaceInPlace(1, 3, [ 9, 9, 9 ]);
assert(a == [ 1, 9, 9, 9, 4 ]);
---
), $(ARGS), $(ARGS), $(ARGS import std.array;))
+/
void replaceInPlace(T, Range)(ref T[] array, size_t from, size_t to, Range stuff)
if(isDynamicArray!Range &&
Expand Down Expand Up @@ -1877,6 +1921,8 @@ recommended over $(D a ~= data) when appending many elements because it is more
efficient.
Example:
$(D_RUN_CODE
$(ARGS
----
auto app = appender!string();
string b = "abcdefg";
Expand All @@ -1889,6 +1935,7 @@ app2.put(3);
app2.put([ 4, 5, 6 ]);
assert(app2.data == [ 1, 2, 3, 4, 5, 6 ]);
----
), $(ARGS), $(ARGS), $(ARGS import std.array;))
*/
struct Appender(A : T[], T)
{
Expand Down
84 changes: 62 additions & 22 deletions std/base64.d
View file
Expand Up @@ -6,23 +6,40 @@
* Implemented according to $(WEB tools.ietf.org/html/rfc4648,
* RFC 4648 - The Base16, Base32, and Base64 Data Encodings).
*
* Example:
* -----
* ubyte[] data = [0x14, 0xfb, 0x9c, 0x03, 0xd9, 0x7e];
* Base64.encode(data); //-> "FPucA9l+"
* Base64.decode("FPucA9l+"); //-> [0x14, 0xfb, 0x9c, 0x03, 0xd9, 0x7e]
* Example:
* $(D_RUN_CODE
* $(ARGS
* -----
*ubyte[] data = [0x14, 0xfb, 0x9c, 0x03, 0xd9, 0x7e];
*
*const(char)[] encoded = Base64.encode(data);
*assert(encoded == "FPucA9l+");
*
*ubyte[] decoded = Base64.decode("FPucA9l+");
*assert(decoded == [0x14, 0xfb, 0x9c, 0x03, 0xd9, 0x7e]);
* -----
* ), $(ARGS), $(ARGS), $(ARGS import std.base64;))
* Support Range interface using Encoder / Decoder.
*
* Example:
* $(D_RUN_CODE
* $(ARGS
* -----
* // Create MIME Base64 with CRLF, per line 76.
* foreach (encoded; Base64.encoder(f.byChunk(57))) {
* mime64.put(encoded);
* mime64.put("\r\n");
* }
*File f = File("./text.txt", "r");
*scope(exit) f.close();
*
*Appender!string mime64 = appender!string;
*
*foreach (encoded; Base64.encoder(f.byChunk(57)))
*{
* mime64.put(encoded);
* mime64.put("\r\n");
*}
*
*writeln(mime64.data);
* -----
*), $(ARGS), $(ARGS), $(ARGS import std.base64, std.array, std.stdio: File, writeln;))
*
* Copyright: Masahiro Nakagawa 2010-.
* License: $(WEB boost.org/LICENSE_1_0.txt, Boost License 1.0).
Expand Down Expand Up @@ -655,22 +672,36 @@ template Base64Impl(char Map62th, char Map63th, char Padding = '=')
* Default $(D Encoder) encodes chunk data.
*
* Example:
*$(D_RUN_CODE
*$(ARGS
* -----
* foreach (encoded; Base64.encoder(f.byLine())) {
* ... use encoded line ...
* }
*File f = File("text.txt", "r");
*scope(exit) f.close();
*
*uint line = 0;
*foreach (encoded; Base64.encoder(f.byLine()))
*{
* writeln(++line, ". ", encoded);
*}
* -----
*), $(ARGS), $(ARGS), $(ARGS import std.base64, std.stdio: File, writeln;))
*
* In addition, You can use $(D Encoder) that returns encoded single character.
* This $(D Encoder) performs Range-based and lazy encoding.
*
* Example:
*$(D_RUN_CODE
*$(ARGS
* -----
*ubyte[] data = cast(ubyte[]) "0123456789";
*
* // The ElementType of data is not aggregation type
* foreach (encoded; Base64.encoder(data)) {
* ... use encoded character ...
* }
*foreach (encoded; Base64.encoder(data))
*{
* writeln(encoded);
*}
* -----
*), $(ARGS), $(ARGS), $(ARGS import std.base64, std.stdio: writeln;))
*
* Params:
* range = an $(D InputRange) to iterate.
Expand Down Expand Up @@ -1318,22 +1349,31 @@ template Base64Impl(char Map62th, char Map63th, char Padding = '=')
* Default $(D Decoder) decodes chunk data.
*
* Example:
*$(D_RUN_CODE
*$(ARGS
* -----
* foreach (decoded; Base64.decoder(f.byLine())) {
* ... use decoded line ...
* }
*foreach (decoded; Base64.decoder(stdin.byLine()))
*{
* writeln(decoded);
*}
* -----
*), $(ARGS FPucA9l+), $(ARGS), $(ARGS import std.base64, std.stdio;))
*
* In addition, You can use $(D Decoder) that returns decoded single character.
* This $(D Decoder) performs Range-based and lazy decoding.
*
* Example:
*$(D_RUN_CODE
*$(ARGS
* -----
* auto encoded = Base64.encoder(cast(ubyte[])"0123456789");
* foreach (n; map!q{a - '0'}(Base64.decoder(encoded))) {
* ... do something with n ...
* }
*auto encoded = Base64.encoder(cast(ubyte[])"0123456789");
*foreach (n; map!q{a - '0'}(Base64.decoder(encoded)))
*{
* writeln(n);
*}
* -----
*), $(ARGS), $(ARGS), $(ARGS import std.base64, std.stdio: writeln;
*import std.algorithm: map;))
*
* NOTE:
* If you use $(D ByChunk), chunk-size should be the multiple of 4.
Expand Down

0 comments on commit acc8c7d

Please sign in to comment.