ScopeBuffer

ScopeBuffer encapsulates using a local array as a temporary buffer. It is initialized with the local array that should be large enough for most uses. If the need exceeds the size, ScopeBuffer will resize it using malloc() and friends.

ScopeBuffer cannot contain more than (uint.max-16)/2 elements.

ScopeBuffer is an OutputRange.

Since ScopeBuffer potentially stores elements of type T in malloc'd memory, those elements are not scanned when the GC collects. This can cause memory corruption. Do not use ScopeBuffer when elements of type T point to the GC heap.

@system

struct ScopeBuffer (

alias realloc = .realloc

) if (

isAssignable!T &&

!hasElaborateDestructor!T

!hasElaborateCopyConstructor!T

!hasElaborateAssign!T

) {

this(T[] buf);

void free();

void put(T c);

void put(CT[] s);

T[] opSlice(size_t lower, size_t upper);

inout(T)[] opSlice();

T opIndex(size_t i);

size_t length [@property getter];

size_t length [@property setter];

}

Constructors

this this(T[] buf): Initialize with buf to use as scratch buffer space.

Members

Functions

free void free(): Releases any memory used. This will invalidate any references returned by the [] operator. A destructor is not used, because that would make it not POD (Plain Old Data) and it could not be placed in registers.
opIndex T opIndex(size_t i)
opSlice T[] opSlice(size_t lower, size_t upper)
inout(T)[] opSlice(): Retrieve a slice into the result.
put void put(T c): Append element c to the buffer. This member function makes ScopeBuffer an OutputRange.
put void put(CT[] s): Append array s to the buffer.

Properties

length size_t length [@property getter]
length size_t length [@property setter]: Used to shrink the length of the buffer, typically to 0 so the buffer can be reused. Cannot be used to extend the length of the buffer.

Examples

1 import core.stdc.stdio;
2 import std.internal.scopebuffer;
3 void main()
4 {
5     char[2] buf = void;
6     auto textbuf = ScopeBuffer!char(buf);
7     scope(exit) textbuf.free(); // necessary for cleanup
8 
9     // Put characters and strings into textbuf, verify they got there
10     textbuf.put('a');
11     textbuf.put('x');
12     textbuf.put("abc");
13     assert(textbuf.length == 5);
14     assert(textbuf[1..3] == "xa");
15     assert(textbuf[3] == 'b');
16 
17     // Can shrink it
18     textbuf.length = 3;
19     assert(textbuf[0..textbuf.length] == "axa");
20     assert(textbuf[textbuf.length - 1] == 'a');
21     assert(textbuf[1..3] == "xa");
22 
23     textbuf.put('z');
24     assert(textbuf[] == "axaz");
25 
26     // Can shrink it to 0 size, and reuse same memory
27     textbuf.length = 0;
28 }

It is invalid to access ScopeBuffer's contents when ScopeBuffer goes out of scope. Hence, copying the contents are necessary to keep them around:

1 import std.internal.scopebuffer;
2 string cat(string s1, string s2)
3 {
4     char[10] tmpbuf = void;
5     auto textbuf = ScopeBuffer!char(tmpbuf);
6     scope(exit) textbuf.free();
7     textbuf.put(s1);
8     textbuf.put(s2);
9     textbuf.put("even more");
10     return textbuf[].idup;
11 }

ScopeBuffer is intended for high performance usages in @system and @trusted code. It is designed to fit into two 64 bit registers, again for high performance use. If used incorrectly, memory leaks and corruption can result. Be sure to use scope(exit) textbuf.free(); for proper cleanup, and do not refer to a ScopeBuffer instance's contents after ScopeBuffer.free() has been called.

The realloc parameter defaults to C's realloc(). Another can be supplied to override it.

ScopeBuffer instances may be copied, as in:

textbuf = doSomething(textbuf, args);

which can be very efficent, but these must be regarded as a move rather than a copy. Additionally, the code between passing and returning the instance must not throw exceptions, otherwise when ScopeBuffer.free() is called, memory may get corrupted.