back to Table of Contents

SeekBuf (function)

This function sets the current buffer (cursor) position for the specified buffer using the given placement characteristics. This position is used as starting point for most buffer operations, which in any way read, write, copy or search data. The result of this function is the old position in the buffer, or negative if an error occurs. The mode is used to specify the relative start position, the displacement is added to that position and may be positive or negative. Eg. 20 from current is a position 20 bytes forward from current, -20 is 20 bytes back from current. You'll get an error, if you try to seek beyond the lower or upper bounds of the buffer.

SYNTAX:

oldPos& = SeekBuf& (buf$(), displace&, mode%)

INPUTS:

buf$() (STRING array)

• This is the array of any existing and initialized buffer, for which you wanna set the new position.

displace& (LONG)

• This is any value which is added to the start position (origin) designated by the given seek mode, it may be negative, zero or positive.

mode% (INTEGER)

• This is the desired seek mode, which designates the origin for the new position, it may be a regular seek mode as listed below (see also stringbuffer.bi) or the ID number of any set marker, which its position shall be used as origin.

RESULT:

oldPos& (LONG)

• On success (positive value) this is the old buffer position.
• On failure (negative value) it is any of the error numbers defined in the stringbuffer.bi file (see also Common-Info), the old position remains unchanged in this case.

SEEK MODES:

SBM_PosRestore

• If you know the exact position, then this is the easiest mode, it will set any absolute position given in the displacement argument (valid values range from 1 to GetBufLen() + 1).

SBM_BufStart

• Set a position relative to the buffer start (ie. 1 + displacement).

SBM_BufCurrent

• Set a position relative to the current position (ie. GetBufPos() + displacement).

SBM_BufEnd

• Set a position relative to the buffer end (ie. (GetBufLen() + 1) + displacement).

SBM_LineStart

• Set a position relative to the start of the current line, which the actual cursor is on.
  • Start of line = first char of the line.
  • Ie. the set position is 1st char of line + displacement.

SBM_LineEnd

• Set a position relative to the end of the current line, which the actual cursor is on.
  • End of line = last char of the line + 1 (ie. the cursor is on the actual line break char, CHR$(13) for Windows or CHR$(10) for Linux/MacOSX).
  • Ie. the set position is current line's line break char + displacement.

any Marker ID

• Set a position relative to the marker position (ie. GetBufMark() + displacement).
  • If the displacement is zero, then this is equal to GotoBufMark().

back to Table of Contents