ADDVEC - replace a vector by a new, larger one.

Alternate Entry Name: ADD.VE

Usage:

B:
   vector = addvec( vector [,addlen [,oldlen] ]);

/* C users use realloc */

Where:

vector

is a pointer to a block of storage, as returned by the B library function GETVEC.

addlen

is the amount of extra memory you want to "add" to the end of "vector". If only one argument is given, this defaults to one (so that the length of "vector" is increased by one word).

oldlen

is the length of the old block of storage pointed to by "vector". If this argument is omitted, the value in the upper half of "vector" is used. (This is because ADDVEC itself returns the length of the new vector in the upper half of the vector pointer it returns.)

Description:

ADDVEC, whose name is somewhat misleading, "adds" a total of "addlen" words to the length of a given vector. It does this by calling GETVEC to allocate a new larger vector, copying the old vector into the new, and then calling RLSEVEC to release the old vector's memory.

Note that if you have pointers into the old vector, it is extremely unwise to call ADDVEC unless you are prepared to reset your pointers to the proper locations in the new vector.

The value which ADDVEC returns is a word whose lower half is a pointer to the location of the new vector, and whose upper half contains the allocated length of the new vector. Thus if you make a number of calls to ADDVEC to grow the same vector, you need only specify "oldlen" once; on subsequent calls, the "oldlen" value will be contained in the vector pointer itself.

Since ADDVEC calls RLSEVEC, using ADDVEC to increase the length of auto vectors or externally declared "static" vectors will probably lead to disaster.

See Also:

expl b lib getvec

Copyright © 1996, Thinkage Ltd.