In some situations a pointer to a zero terminated string is required.  As
strings in QB64 usually do not have a zero byte at its end, and also QB64
may shift the strings at any time on its internal heap, the use of VARPTR
and/or _OFFSET to obtain a pointer for such purposes is not adequate.

The FUNCTION CreateGPMString& will create a zero terminated copy of the
given string in GP Memory and return a pointer to that copied string:

    mstr& = CreateGPMString&("sample.string")

After this call mstr& will hold the pointer to a zero terminated copy of
"sample.string" created in the GP Memory region.  CreateGPMString& will
automatically allocate the required memory (inclusive the zero termination
byte), then writing the given string to the reserved memory and write the
termination byte.  As the memory allocation may fail due to lack of free
memory, this routine may return a zero result.  You must check for this
condition before using the returned pointer.

If the creation of the string was successful, then the pointer remains valid
until the string is explicitly disposed using the SUB DisposeGPMString as
shown in the following example:

    DisposeGPMString mstr&

This call will simply free all the occupied memory used by the string, the
given pointer is invalid after the call and should not longer be used.

The FUNCTION AlignGPMSize& is mostly used internally by the GPM system to
round up memory allocation sizes to a multiple of the minimum supported
block size (currently 8 bytes).  Here some examples:

    size& = AlignGPMSize&(7) 'results into 8
    size& = AlignGPMSize&(8) 'remains 8
    size& = AlignGPMSize&(9) 'results into 16

There is normally no need for you to use this function, as the GPM system
will make sure everything is well aligned internally.

To fill all bytes of a given memory block with a specific value, you may
use the SUB FillGPMem as shown in the following example:

    FillGPMem addr&, 1000&, ASC("*")

This call would fill 1000 bytes, starting at addr&, with the ASCII value
which represents the "*" character.  FillGPMem will fill the given number
of bytes in the target memory region with the specified byte value.  The
pointer to the target region can be aligned on an arbitrary address boundary.
FillGPMem will attempt to fill the memory as efficiently as it can according
to the alignment of the memory region, and the number of bytes it has to
fill.  The algorithm is optimized for filling large blocks of memory which
can result in unnecessary overhead if used to fill very small blocks.

If you need to compare two memory regions (eg. verifying two buffers against
each other), then you may use the FUNCTION CompareGPMem& for that purpose.

    diff& = CompareGPMem&(sAddr&, cAddr&, 1000&, gpmF_Unsigned&)

Here you would compare 1000 bytes of the contents of the source data region
sAddr& with the respective contents of the compare data region cAddr& using
unsigned math for comparing.  Well, CompareGPMem& will compare the given
memory regions, which may both be aligned on arbitrary addresses, and will
return either zero, if the two regions match exactly or a state value which
contains the position of the first found difference and additional information
whether the source byte was less than the compared byte or vice versa.  Because
of the less than / greater than information provided by the result, this
function need to know which comparing math (signed/unsigned) it shall use.
This is, because in signed math bytes with its MSB set are in general less
than bytes with a cleared MSB, but in unsigned math it's the opposite case.

For memory block copies, the SUB CopyGPMem can be used.  The following
sample shows how to use it:

    CopyGPMem sAddr&, dAddr&, 1000&

The call above will copy 1000 bytes from the source region sAddr& to the
destination region dAddr&.  CopyGPMem copies the specified number of bytes
from the source data region to the destination data region.  The pointers
to the regions can be aligned on arbitrary address boundaries.  CopyGPMem
will attempt to copy the memory as efficiently as it can according to the
alignment of the memory blocks, and the amount of data it has to transfer.
The algorithm is optimized for copying large blocks of memory which can
cause unnecessary overhead if used to transfer very small blocks of memory.

    Overlap Copies Are Supported.
    -----------------------------
    The SUB CopyGPMem does explicitly support copying between
    regions that overlap.

                                                      Back to GPM Functions