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

#include <iostream>
#include <iomanip>

#include <stdhdrs.h>
#include <strbuf.h>

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

    sb.Set( "xyz" );

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

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

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

Executing the preceding code produces the following output:

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