Mercurial > repo

comparison interps/c-intercal/pit/lib/numio.doc @ 996:859f9b4339e6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
<Gregor> tar xf egobot.tar.xz
author HackBot
date Sun, 09 Dec 2012 19:30:08 +0000
parents
children
comparison
equal deleted inserted replaced
995:6883f5911eb7 996:859f9b4339e6
1 Summary of routines in numio.i:
2
3 (3000) .1 <- character from input
4 (3001) Prints .2 as a character
5 (3010) ,1 <- a string of input from the user, no longer than .1, and
6 excluding the terminating newline.
7 .2 <- the real length of the user input.
8 .3 <- #1 if .2 <= .1 (i.e., no characters were lost).
9 Otherwise, .3 <- #2.
10 (3020) ,1 <- a string of input from the user, no longer than .1,
11 translated (where possible) into indices into ,2
12 .3 <- the real length of the user input.
13 .4 <- #1 if .3 <= .1 and all characters in the input are
14 listed in ,2. Otherwise, .4 <- #2.
15 (3080) .1 <- a 16-bit number from the user
16 (3089) .1 <- a 16-bit number from the user, with an error message if
17 non-digits are encountered
18 (3090) Displays the value in .1
19 (3099) Displays the value in .1 and prints a newline
20 (3180) :1 <- a 32-bit number from the user
21 (3189) :1 <- a 32-bit number from the user, with an error message if
22 non-digits are encountered
23 (3190) Displays the value in :1
24 (3199) Displays the value in :1 and prints a newline
25 (3990) Initializes internal arrays.
26
27 numio.i reserves the use of two arrays - ,3000 and ,3001 - for input
28 and output respectively. Each array has one dimension of one element,
29 and they are used to provide a getchar routine, at (3000), and a
30 putchar routine, (3001). Note that (3001) expects that the character
31 values have already been bit-reversed.
32
33 The arrays are initialized by routine (3990); this should be called
34 before using any other routines in this library.
35
36 Routines (3010) and (3020) provide line input capabilities. The
37 routines write in characters until they see a newline (or
38 end-of-file), and store them in ,1. They are called with .1 being the
39 number of characters to save; any input after that is thrown
40 away. (Already they're better than C's gets()!)
41
42 (3010) returns the actual number of characters that were input in .2,
43 and .3 is set to #2 if characters were lost (i.e., if .2 is longer
44 than .1). I decided to add .3, even though the caller could check for
45 this themselves, as inequal comparisons are a bit painful in INTERCAL.
46 Or, to be accurate, they're more painful than equal comparisons. Note
47 also that if .1 is #0, the routine becomes a press-Enter-to-continue
48 type of function, and ,1 need not actually be defined.
49
50 (3020) is a filtering, or translating, input routine. When called, the
51 array ,2 should contain a set of "approved" characters that are
52 expected to be in the input, and .2 should contain the number of
53 characters in ,2. As input is retrieved, the routine tries to look up
54 each character in ,2. If the character is found, the routine stores in
55 ,1 the index of the character instead. (Otherwise the actual character
56 number is stored, as with (3010).) Upon return, .3 has the number of
57 characters that were input, and .4 is set to #2 if characters were
58 lost OR if any characters in the input were not in the set of approved
59 characters.
60
61 The remaining routines are for doing "wimpmode"-style I/O - or in
62 other words, the C-INTERCAL equivalent of atoi and itoa. (3080) and
63 (3090) translate the ASCII input as a number (yes, a number as in
64 [0-9]*), and (3090) and (3190) do the same for displaying numbers in
65 ASCII. (By the way, the routines can also be made to support EBCDIC:
66 simply replace #3 with #15 on lines 119, 159, and 185.)
67
68 Each routine also has a "niner" variation. For itoa, (3099) and (3190)
69 print a newline at the end of the number. In the case of atoi, (3089)
70 and (3189) make sure that the number ends with a newline. In other
71 words, they ensure there are no other non-numeric characters in the
72 input line. If there are, a typically snide INTERCAL error message is
73 displayed. (The regular versions work like C's atoi in that they
74 return as soon as they see any non-digit.)
75
76 There's not too much to note about these routines. The atoi routines
77 use the shift-and-add trick to avoid multiplying by 10, so they should
78 be pretty efficient (snort). itoa has no such shortcuts, and the
79 routines use modified division routines which also returns the
80 remainder. The 16-bit version is at (2030), and is the familiar one
81 created by Louis Howell, copied from lib2.i. The 32-bit version is at
82 (2530), and is just a copy of the standard library routine without the
83 lines that throw away the remainder at the end.
84
85 Note also that for these routines to work properly, they must be used
86 more or less exclusively in regards to other array I/O. Otherwise, the
87 getchar and putchar subroutines will get out of sync with the
88 Turing-text character loop. If you do want to do other I/O while using
89 these routines, you can use (3000) and (3001) as a getchar and
90 putchar. Or, you can simply re-initialize the ,3000 and/or ,3001
91 values after you are done, by storing in them the bit-reversed ASCII
92 value of the last character that you wrote in and/or read out. For
93 example, if you READ OUT some strings and the last thing to be printed
94 was a newline, then:
95
96 DO ,3001SUB#1 <- #80
97
98 would then allow you to safely call the itoa routines.