Reserve v0.1.0

Package: Text

Signature

func Reserve(self, additional: uint);

Parameters

Remarks

Ensures the block can hold additional bytes beyond the current Length, so the appends that follow do not reallocate. It is Grow with the bookkeeping done for you — the argument is relative to what is written, not the total.

Capacity only ever grows, so this leaves a builder that is already big enough alone; the capacity that goes unused is handed back by Shrink, not by reserving less.

Reserving may move the block, so a pointer taken from Data beforehand must not be used after.

Example

import Text::StringBuilder;

func Main() -> int {
    var builder = StringBuilder::New();
    builder.Append("Rux");   // Length is 3

    builder.Reserve(100);    // room for 100 more, so at least 103 in all
    builder.Capacity();      // >= 103, and no append below that reallocates

    builder.Free();
    return 0;
}

See also

• StringBuilder — the builder type
• Grow — ask for a total size instead of an increment
• WithCapacity — reserve up front, before anything is written
• Shrink — hand back what went unused