Difference between revisions of "GSREAD"

From BeebWiki
Jump to: navigation, search
(GSREAD safety)
m (Slight tweeks.)
 
Line 6: Line 6:
 
|  6502  || align="left" | '''On entry:''' || align="left" | '''On exit:'''
 
|  6502  || align="left" | '''On entry:''' || align="left" | '''On exit:'''
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| Cy || align="left" | undefined || align="left" | 0=Character valid<br>1=End of string reached
+
| Cy || align="left" | undefined || align="left" | CC = Character valid<br>CS = End of string reached
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| A || align="left" | undefined || align="left" | Current character of string; =&0D if end of string reached
+
| A || align="left" | undefined || align="left" | Current character of string, =&0D if end of string reached
 
|- align="center" valign="top"
 
|- align="center" valign="top"
 
| X || align="left" | undefined || align="left" | preserved
 
| X || align="left" | undefined || align="left" | preserved
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| Y || align="left" | Offset of current character || align="left" | Offset of next character
+
| Y || align="left" | Offset of current character&nbsp;&nbsp; || align="left" | Offset of next character
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| ?&F2 || align="left" | LSB of start of array || align="left" | preserved
+
| (&F2),Y || align="left" | the string being parsed || align="left" | (&F2) preserved
|- align="center" valign="top"
 
| ?&F3 || align="left" | MSB of start of array || align="left" | preserved
 
 
|}
 
|}
  
Returns one character at a time from a string found using [[GSINIT]]. The string may be enclosed in double quotes (<tt>"</tt>) in which case spaces in the string are preserved. The string may also contain control codes and high-order characters encoded with an escape sequence.
+
Returns one character at a time from a string found using [[GSINIT]]. The
 +
string may be enclosed in double quotes (<tt>"</tt>) in which case spaces in
 +
the string are preserved. The string may also contain control codes and
 +
high-order characters encoded with an escape sequence.
  
GSREAD parses the character sequence at the position given by (?&F2,?&F3)+Y and scans forward.
+
GSREAD parses the character sequence at the position given by (&F2),Y
 +
and scans forward.
  
If the string began with <tt>"</tt> then a character is returned with Cy=0 unless the closing <tt>"</tt> has been reached; then Cy=1 and A=&0D is returned. [[VDU 13|CR]] encountered before the closing <tt>"</tt> causes error &FD, '''Bad string'''.
+
If the string began with <tt>"</tt> then a character is returned with
 +
Carry Clear unless the closing <tt>"</tt> has been reached, then Carry Set
 +
is returned with A=&0D. [[VDU 13|CR]] encountered before the closing
 +
<tt>&quot;</tt> causes error &FD, '''Bad string'''.
  
Otherwise a character is returned with Cy=0 unless CR, or also space if GSINIT was called with Cy=0, has been reached; then Cy=1 and A=&0D is returned.
+
Otherwise a character is returned with Carry Clear unless it is a CR, or
 +
a space if GSINIT was called with Carry Clear, then Carry Set is returned
 +
with A=&0D.
  
(?&F2,?&F3)+Y is left pointing to the next character unless Cy=1, in which case GSREAD skips any spaces following the end of the string.
+
(&F2),Y is left pointing to the next character unless Carry Set is returned,
 +
in which case GSREAD skips any spaces following the end of the string.
  
While processing a command line, Z=0 on exit from GSINIT indicates that an argument is present. When the first call to GSREAD returns Cy=1, the flag from GSINIT distinguishes between an empty argument and no argument.
+
While processing a command line, GSINIT returning Not Equal indicates that an
 +
argument is present. When the first call to GSREAD returns Carry Set, the flag
 +
from GSINIT distinguishes between an empty argument and no argument.
  
It is safe to call GSREAD at least once following GSINIT. However, after GSREAD returns Cy=1 it must not be called again without an intervening GSINIT; otherwise, overshooting a closing <tt>"</tt> and reaching CR also raises a '''Bad string''' error.
+
It is safe to call GSREAD at least once following GSINIT. However, after
 +
GSREAD returns Carry Set it must not be called again without an intervening
 +
GSINIT, otherwise, overshooting a closing <tt>"</tt> and reaching CR also
 +
raises a '''Bad string''' error.
  
 
;Note
 
;Note
The character returned by [[GSINIT]] is ''not'' necessarily the character returned by the first call to GSREAD.
+
The character returned by [[GSINIT]] is ''not'' necessarily the character
 
+
returned by the first call to GSREAD.
==Calling from BBC BASIC==
 
  
 
==Entry points==
 
==Entry points==

Latest revision as of 13:08, 17 October 2020

Read character from string

Specification

 6502  On entry: On exit:
Cy undefined CC = Character valid
CS = End of string reached
A undefined Current character of string, =&0D if end of string reached
X undefined preserved
Y Offset of current character   Offset of next character
(&F2),Y the string being parsed (&F2) preserved

Returns one character at a time from a string found using GSINIT. The string may be enclosed in double quotes (") in which case spaces in the string are preserved. The string may also contain control codes and high-order characters encoded with an escape sequence.

GSREAD parses the character sequence at the position given by (&F2),Y and scans forward.

If the string began with " then a character is returned with Carry Clear unless the closing " has been reached, then Carry Set is returned with A=&0D. CR encountered before the closing " causes error &FD, Bad string.

Otherwise a character is returned with Carry Clear unless it is a CR, or a space if GSINIT was called with Carry Clear, then Carry Set is returned with A=&0D.

(&F2),Y is left pointing to the next character unless Carry Set is returned, in which case GSREAD skips any spaces following the end of the string.

While processing a command line, GSINIT returning Not Equal indicates that an argument is present. When the first call to GSREAD returns Carry Set, the flag from GSINIT distinguishes between an empty argument and no argument.

It is safe to call GSREAD at least once following GSINIT. However, after GSREAD returns Carry Set it must not be called again without an intervening GSINIT, otherwise, overshooting a closing " and reaching CR also raises a Bad string error.

Note

The character returned by GSINIT is not necessarily the character returned by the first call to GSREAD.

Entry points

  • 6502 Entry Address: &FFC5 (I/O processor only)

Regregex (talk) 18:31, 11 January 2019 (CET)