Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

C/C++ API Documentation | 2025.2

# StrBuf::Alloc( int )

Allocate an additional specified number of bytes to a `StrBuf`. The string pointed to by the `StrBuf`'s `buffer` is logically extended.

Virtual? | No |
Class | `StrBuf` |
Arguments | `int len` | number of bytes to be allocated
Returns | `char *` | pointer to the first additional byte allocated

## Notes

The `length` of the `StrBuf` is incremented by the `len` argument.

If the memory for the `StrBuf`'s `buffer` is not large enough, enough new memory is allocated to contiguously contain the extended string. If new memory is allocated, the old memory is freed. (All `StrBuf` member functions with the potential to increase the length of a `StrBuf` manage memory this way.)

A call to `Alloc()` might change the string pointed to by the `StrBuf`'s `buffer`; do not rely on pointer arithmetic to determine the new pointer, because the call to `Alloc()` might have moved the buffer location.

## Example

Copy

    #include &lt;iostream&gt;
    #include &lt;iomanip&gt;

    #include &lt;stdhdrs.h&gt;
    #include &lt;strbuf.h&gt;

    int main( int argc, char **argv )
    {
        StrBuf sb;
        char *p;

        sb.Set( "xyz" );

        cout &lt;&lt; "sb.Text() prior to sb.Alloc( 70 ) returns ";
        cout &lt;&lt; "\"" &lt;&lt; sb.Text() &lt;&lt; "\"\n";
        cout &lt;&lt; "(int)sb.Text() prior to sb.Alloc( 70 ) returns 0x" &lt;&lt; hex;
        cout &lt;&lt; setw( 8 ) &lt;&lt; setfill( '0' ) &lt;&lt; (int)sb.Text() &lt;&lt; dec &lt;&lt; "\n";
        cout &lt;&lt; "sb.Length() prior to sb.Alloc( 70 ) returns ";
        cout &lt;&lt; sb.Length() &lt;&lt; "\n\n";

        p = sb.Alloc( 70 );   // allocate in StrBuf

        cout &lt;&lt; "sb.Text() after sb.Alloc( 70 ) returns (first three bytes) ";
        cout &lt;&lt; "\"" &lt;&lt; setw( 3 ) &lt;&lt; sb.Text() &lt;&lt; "\"\n";
        cout &lt;&lt; "(int)sb.Text() after sb.Alloc( 70 ) returns 0x" &lt;&lt; hex;
        cout &lt;&lt; setw( 8 ) &lt;&lt; setfill( '0' ) &lt;&lt; (int)sb.Text() &lt;&lt; dec &lt;&lt; "\n";
        cout &lt;&lt; "(int)sb.Alloc( 70 ) returned 0x" &lt;&lt; hex;
        cout &lt;&lt; setw( 8 ) &lt;&lt; setfill( '0' ) &lt;&lt; (int)p &lt;&lt; dec &lt;&lt; "\n";
        cout &lt;&lt; "sb.Length() after sb.Alloc( 70 ) returns ";
        cout &lt;&lt; sb.Length() &lt;&lt; "\n";
    }

Executing the preceding code produces the following output:

Copy

    sb.Text() prior to sb.Alloc( 70 ) returns "xyz"
    (int)sb.Text() prior to sb.Alloc( 70 ) returns 0x0804a9a0
    sb.Length() prior to sb.Alloc( 70 ) returns 3

    sb.Text() after sb.Alloc( 70 ) returns (first three bytes) "xyz"
    (int)sb.Text() after sb.Alloc( 70 ) returns 0x0804a9b0
    (int)sb.Alloc( 70 ) returned 0x0804a9b3
    sb.Length() after sb.Alloc( 70 ) returns 73

Your search for returned results