GRID CARTOGRAPHER 4
Shortcuts

GCBuffer

2019-04-13

A set of functions to create and manage general purpose in-memory data buffers. Buffers can be used to cache data when reading from or writing to disk to improve performance.

Create

GCBuffer.Create(): int

Create a new empty buffer and return a handle to it. Returns the handle or 0 (zero) if there was a failure (too many buffers, internal error, etc.)

Destroy

GCBuffer.Destroy( handle: int ): void

Destroy a buffer referenced by the given handle. The handle is internally marked as invalid and cannot be used for future operations.

Fill

GCBuffer.Fill( handle: int, data: int, count: int ): int

Write a single 8-bit value data, count times into the buffer referenced by handle. If handle is invalid the function will return GCERR_INVARG. Otherwise GCOK.

Length

GCBuffer.Length( handle: int ): int

Return the size in bytes of the data in the buffer referenced by handle. If the handle is invalid the function returns GCERR_INVARG.

Prepare

GCBuffer.Prepare( handle: int, size: int ): void

Prepare the buffer referenced by handle to receive size bytes of data. This is an optimization function that affects the storage used to hold the data, not the data itself.

When data is written to a buffer it automatically expands into space provided by the 'backing storage'. When this storage is full, a larger block of memory is allocated to allow for extra data to be added. This expansion involves copying the current data to the new location which may reduce performance. Prepare instructs the buffer to expand, in advance, reducing the amount of unnecessary copying steps.

If the size given is less than the amount of data already in the buffer, the call will do nothing and no error will be generated.

Print

GCBuffer.Print( handle: int, message: string|int|float ): int

Write a string, integer or float value as plain ASCII text to the buffer. Returns GCOK on success and automatically advances the read/write cursor to the end of the message. If the handle is invalid it returns GCERR_INVARG.

Peek8

GCBuffer.Peek8( handle: int ): int|null

Read an unsigned 8-bit binary value from the file buffer at the current cursor position. The cursor position is not updated after this call. If the handle is invalid, or there is insufficient data in the buffer, returns null.

Peek16

GCBuffer.Peek16( handle: int ): int|null

Read an unsigned 16-bit binary value from the file buffer at the current cursor position. The cursor position is not updated after this call. If the handle is invalid, or there is insufficient data in the buffer, returns null.

Read8

GCBuffer.Read8( handle: int ): int|null

Read an unsigned 8-bit binary value from the file buffer at the current cursor position and then advance the cursor forward by one byte. If the handle is invalid, or there is insufficient data in the buffer, returns null.

Read16LE

GCBuffer.Read16LE( handle: int ): int|null

Read an unsigned little-endian 16-bit binary value from the file buffer at the current cursor position and then advance the cursor forward by two bytes. If the handle is invalid, or there is insufficient data in the buffer, returns null.

Read16BE

GCBuffer.Read16BE( handle: int ): int|null

Read an unsigned big-endian 16-bit binary value from the file buffer at the current cursor position and then advance the cursor forward by two bytes. If the handle is invalid, or there is insufficient data in the buffer, returns null.

Read32LE

GCBuffer.Read32LE( handle: int ): int|null

Read an unsigned little-endian 32-bit value from the file buffer at the current cursor position. If the handle is invalid, or there is insufficient data in the buffer, returns null.

Read32BE

GCBuffer.Read32BE( handle: int ): int|null

Read an unsigned big-endian 32-bit value from the file buffer at the current cursor position. If the handle is invalid, or there is insufficient data in the buffer, returns null.

Reset

GCBuffer.Reset( handle: int ): void

Reset the contents of the buffer referenced by handle to 0 (zero) length. Also resets the read/write cursor to 0 (zero). This call will preserve the backing storage allocated so future writes to the buffer will be a faster.

Seek

GCBuffer.Seek( handle: int, where: int ): int

Change the position of the read/write cursor to the byte offset specified by where. If the handle is invalid the function returns GCERR_INVARG.

If the position is beyond the start or end of the data in the buffer, the cursor will be set to the first or last position respectively and the function will return GCERR_EOF. Otherwise the cursor is updated normally and the function returns GCOK.

Where

GCBuffer.Where( handle: int ): int

Return the position of the read/write cursor for the buffer referenced by handle. If the handle is invalid the function will return GCERR_INVARG.

WriteBool

GCBuffer.WriteBool( handle: int, data: int|bool ): int

Write a Boolean to the given buffer as 8-bit value 0 or 1. If the data parameter is an integer a 1 will be written for any value not equal to 0 (zero). If handle is invalid the function will return GCERR_INVARG. Otherwise GCOK.

Write8

GCBuffer.Write8( handle: int, data: int ): int

Write an unsigned 8-bit binary value (1 byte) to the given buffer at the read/write cursor (the data parameter is converted to an unsigned integer and then the bottom 8 bits are used). If handle is invalid the function will return GCERR_INVARG. Otherwise GCOK.

Write16

GCBuffer.Write16( handle: int, data: int ): int

Write an unsigned 16-bit binary value (2 bytes) to the given buffer at the read/write cursor (the data parameter is converted to an unsigned integer and then the bottom 16 bits are used). If handle is invalid the function will return GCERR_INVARG. Otherwise GCOK.

Write32

GCBuffer.Write32( handle: int, data: int ): int

Write a 32-bit binary value (4 bytes) to the given buffer at the read/write cursor. If handle is invalid the function will return GCERR_INVARG. Otherwise GCOK.

WriteString

GCBuffer.WriteString( handle: int, data: string ): int

Write a string of character bytes followed by a 0 (zero) 'terminator' to the given buffer at the write cursor. If handle is invalid the function will return GCERR_INVARG. Otherwise GCOK.