Restore - Learn To Code - PlayBASIC Documentation

Restore

Restore Position / SearchString$

Parameters:

Position / SearchString$ = Data position (0 = first value), SearchString$ = String to restore Data Pointer to

Returns: NONE

      Restore sets the internal data pointer position, where any following ReadData() commands will begin reading the data from that point onwards.

      Restore supports three main methods to locate where in the data you would like to set the data pointer.

      1) The first and most traditional method is via Label. The label can be located any where within your program and providing the Restore statement and the label in question are located within the same scope, PlayBASIC will work out where in the data heap this label is for you. Using a label is fine in most situations, but there's a few down sides. Namely, you can't easily dynamically choose a label your program is running and it can be awkward when scopes are involved.

      2) The second method is by Integer. If you give the restore command any integer value, it'll take that value as the new absolute data pointer. If the value is illegal (outside of the current data range) the Data Pointer will be reset to zero. You can read the current data pointer value by using the getdatapointer function

      3) The third method is by String. If you pass Restore a string, it's behavior changes to search mode. The command will search the data heap (from the top) looking for the first occurrence of that exact string. If the string is not found, the data pointer is not changed. You can use the FindData function to do this manually if you like.

      Once the data pointer has been changed any following ReadData, ReadData# and ReadData$ calls will start reading from the newly restored position.

FACTS:

      * Unlike many BASIC dialects, PlayBASIC's RESTORE command can be set dynamically, either by an absolute position / label or via using a search string.

      * The current data poisition ranges between 0 to GetDataQuantity() -1

      * See ProgramLayout to learn more about labels, in particluar about Label scope, which can impact Restores ability to find a label if you use Restore inside functions.

Mini Tutorial #1:

Restore the data pointer to a Label

; Set the Data pointer to this label
  Restore StartReadingDataHere


; Read and display the data at this position
  Print ReadData$()


; Display the Screen and wait for the user to press a key
  Sync
  WaitKey

  Data "This is the First line of Data"

StartReadingDataHere:

  Data "This is the Second line of Data"

This example would output.

  This is the Second Line of Data

Mini Tutorial #2:

This example uses both dyanmic positioning and string searching move the internal data pointer

; read the first data value
  Print ReadData()

; Restore data position to 3
  Restore 3

; read the fourth and fifth data value
  Print ReadData()
  Print ReadData()

; Restore to the string "Play"
  Restore "Play"

; Read data from "Play"
  Print ReadData$()
  Print ReadData$()


; embedded data
  Data 0,1,2,3,4,5,6
  Data 7,8,9, "Not here", "Play", "Basic"

; Display the Screen and wait for the user to press a key
  Sync
  WaitKey

This example would output.

  0
  3
  4
  Play
  Basic


Related Info:	Data \| FindData \| GetDataPointer \| GetDataQuantity \| GetDataType \| ReadData \| ReadData# \| ReadData$ :