'+---------------+---------------------------------------------------+
'| ###### ###### |     .--. .         .-.                            |
'| ##  ## ##   # |     |   )|        (   ) o                         |
'| ##  ##  ##    |     |--' |--. .-.  `-.  .  .-...--.--. .-.        |
'| ######   ##   |     |  \ |  |(   )(   ) | (   ||  |  |(   )       |
'| ##      ##    |     '   `'  `-`-'  `-'-' `-`-`|'  '  `-`-'`-      |
'| ##     ##   # |                            ._.'                   |
'| ##     ###### | Sources & Documents placed under the MIT License. |
'+---------------+---------------------------------------------------+
'|                                                                   |
'| === BufferSupport.bm ===                                          |
'|                                                                   |
'| == This include file is part of the GuiTools Framework Project.   |
'| == It provides the SUBs and FUNCTIONs of the String Buffer API.   |
'|                                                                   |
'+-------------------------------------------------------------------+
'| Done by RhoSigma, R.Heyder, provided AS IS, use at your own risk. |
'| Find me in the QB64 Forum or mail to support@rhosigma-cw.net for  |
'| any questions or suggestions. Thanx for your interest in my work. |
'+-------------------------------------------------------------------+

The Stringbuffer System

You may use it for simple file buffering or as general purpose storage. You can read and write data, search data (fwd/rev), copy & paste data blocks and use bookmarks. The buffer system supports Windows as well as Linux/MacOSX line endings and can convert one to the other.

Table of Contents

GENERAL

• Common Info
  • informations about common inputs and results

INIT, LOAD & SAVE BUFFERS

• InitBuf
  • init a new string array to be usable as string buffer
• FileToBuf
  • load an entire file into a buffer (init is implied)
• BufToFile
  • write the current buffer contents into a new file
• CopyBuf
  • create an exact clone of any buffer (init is implied)
• BufInsertFile
  • insert an entire file into any buffer at its current position
• BufInsertBuf
  • insert the entire buffer contents into another buffer at its current position

READ & WRITE DATA

• ReadBufLine$
  • read a line from any buffer (SB-Synonym for LINE INPUT)
• WriteBufLine
  • write a line into any buffer (SB-Synonym for PRINT #file,...)
• DeleteBufLine
  • delete a line from any buffer
• ReadBufRawData$
  • read any amount of raw bytes from any buffer (SB-Synonym for GET #file,...)
• WriteBufRawData
  • write any amount of raw bytes into any buffer (SB-Synonym for PUT #file,...)
• DeleteBufRawData
  • delete any amount of raw bytes from any buffer
• GetBufMemData
  • read data from any buffer into the specified _MEM block
• PutBufMemData
  • write data from the specified _MEM block into any buffer

SET & RECALL BOOKMARKS

• FreeBufMarkID
  • get next unused marker ID (mimics FREEFILE for bookmarks)
• SetBufMark
  • set a bookmark at the current buffer (cursor) position
• RemoveBufMark
  • free (unset) any bookmark, its ID becomes available for reuse
• GetBufMark
  • return any bookmark's current (byte) position in the buffer
• GotoBufMark
  • make any marked position becoming the current buffer position

SEARCH DATA

• FreeBufFindID
  • get next unused find data ID (mimics FREEFILE for search criteria)
• SetBufFind
  • define the search criteria for any find data
• RemoveBufFind
  • free (delete) any find data, its ID becomes available for reuse
• FindBufFwd & FindBufRev
  • search for any defined criteria in forward or reverse direction
  • may search a regular data string or any number of delimiter chars

COPY & PASTE DATA

• CopyBufBlock
  • copy a data block from any buffer to the clipboard
• CutBufBlock
  • copy a data block from any buffer to the clipboard and delete the data from the buffer
• PasteBufBlock
  • paste a data block from the clipboard into any buffer
  • insert at current buffer position or replace a selected block in the buffer

POSITION CONTROL

• SeekBuf
  • set the current buffer (cursor) position according to the given placement characteristics
• GetBufPos
  • return the current buffer (cursor) position in any buffer
• GetBufLen
  • return the current data size stored in any buffer
• EndOfBuf
  • return the current "End Of Buffer" condition (SB-Synonym for EOF)

EOL CONVERSION

• BufEolSeq$
  • return the current "End Of Line" (line break) char sequence in any buffer
• ConvBufToNativeEol & ConvBufToLnxMacEol & ConvBufToWinEol
  • switch any buffer to another line endings mode and convert the current buffer contents