![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to istream.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / man / mana|
Return to istream.3 CVS log | Up to [Research Unix] / researchv10dc / man / mana |
1.1 root 1: . \"ident "%W%"
2: . \"Copyright (c) 1984 AT&T
3: . \"All Rights Reserved
4: . \"THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF AT&T
5: . \"The copyright notice above does not evidence any
6: . \"actual or intended publication of such source code.
7: .TH ISTREAM 3I+ "C++ Stream Library" " "
8: .SH NAME
9: istream \- formatted and unformatted input
10: .SH SYNOPSIS
11: .nf
12: .ft B
13: .ta1i 2i
14: #include <iostream.h>
15:
16: typedef long streamoff, streampos;
17: class ios {
18: public:
19: enum seek_dir { beg, cur, end };
20: enum open_mode { in, out, ate, app } ;
21: // \fIand lots of other stuff ... \fP
22: } ;
23:
24: class istream : ios {
25: public:
26: int gcount();
27: istream& get(char* ptr, int len, char delim='\en');
28: istream& get(unsigned char* ptr,int len, char delim='\en');
29:
30: istream& get(unsigned char& c);
31: istream& get(char& c);
32: istream& get(streambuf&, char delim ='\en');
33: int get();
34: istream& getline(char* ptr, int len, char delim='\en');
35: istream& getline(unsigned char* ptr, int len, char delim='\en');
36: istream& getline(streambuf& sb, int len, char delim='\en');
37: istream& ignore(int len=1,int delim=EOF);
38: int ipfx(int need=0);
39: int peek();
40: istream& putback(char c);
41: istream& read(char* s,int n);
42: istream& read(unsigned char* s,int n);
43: istream& seekg(streampos pos);
44: istream& seekg(streamoff off, seek_dir d);
45: streampos tellg();
46:
47: istream& operator>>(char*);
48: istream& operator>>(unsigned char*);
49: istream& operator>>(unsigned char&);
50: istream& operator>>(char&);
51: istream& operator>>(short&);
52: istream& operator>>(int&);
53: istream& operator>>(long&);
54: istream& operator>>(unsigned short&);
55: istream& operator>>(unsigned int&);
56: istream& operator>>(unsigned long&);
57: istream& operator>>(float&);
58: istream& operator>>(double&);
59: istream& operator>>(streambuf&);
60: istream& operator>>(istream& (*)(istream&));
61: };
62:
63: class istream_withassign {
64: istream_withassign();
65: istream& operator=(istream&);
66: istream& operator=(streambuf*);
67: };
68:
69: extern istream_withassign cin;
70:
71: istream& ws(iostream& i) ;
72: .fi
73: .ft R
74: .SH DESCRIPTION
75: \f(CWistream\fRs support interpretation of characters
76: fetched from an associated \f(CWstreambuf\fR.
77: These are commonly refered to as input operations.
78: .PP
79: Assume that
80: .br
81: \(em \fBins\fR has type \f(CWistream\fR.
82: .br
83: \(em \fBinwa\fR has type \f(CWistream_withassign\fR.
84: .br
85: \(em \fBinsp\fR has type \f(CWistream*\fR.
86: .br
87: \(em \fBc\fR has type \f(CWchar&\fR
88: .br
89: \(em \fBdelim\fR has type \f(CWchar\fR.
90: .br
91: \(em \fBptr\fR has type \f(CWchar*\fR or \f(CWunsigned char*\fR.
92: .br
93: \(em \fBsb\fR has type \f(CWstreambuf&\fR.
94: .br
95: \(em \fBi\fR, \fBlen\fR, \fBd\fR, and \fBneed\fR have type \f(CWint\fR.
96: .br
97: \(em \fBpos\fR is a \f(CWstreampos\fR.
98: .br
99: \(em \fBoff\fR is a \f(CWstreamoff\fR.
100: .br
101: \(em \fBdir\fR is a \f(CWseek_dir\fR.
102: .br
103: \(em \fBmanip\fR is a function with type \f(CWistream& (*)(istream&)\fR.
104: .PP
105: Constructors and assignment:
106: .TP
107: \fBistream(sb)\fR
108: Initializes \fBios\fR state variables and associates stream with
109: buffer \fBsb\fR.
110: \fBistream_withassign()\fR
111: Does no initialization. This allows a file static
112: variable of this type
113: (\fBcin\fR for example) to be used before it is constructed provided
114: it is assigned to first.
115: .TP
116: \fBinswa=sb\fR
117: Associates \fBsb\fR with \fBswa\fR and initializes the entire
118: state of \fBinswa\fR.
119: .TP
120: \fBinswa=ins\fR
121: Associates \fBins->rdbuf()\fR with \fBswa\fR and initializes the entire
122: state of \fBinswa\fR.
123: .PP
124: Input prefix function:
125: .TP
126: \fBins.ipfx(need)
127: If \fBins\fR's error state is non-zero return immediately.
128: If neccessary (and it is non-null) \fBf.tie\fR is flushed.
129: Flushing is neccessary if either \fBneed==0\fR or there
130: are less than \fBneed\fR characters immediately available.
131: If \fBf.skip()\fR is non-zero and \fBneed\fR is zero
132: then leading whitespace characters are
133: extracted from \fBins\fR. Return zero
134: or an error occurs while skipping whitespace.
135: Otherwise it returns non-zero.
136: .PP
137: Formatted input functions:
138: .TP
139: \fBins\fP>>\fPx\fR
140: Calls \fBipfx(0)\fR and if that returns non-zero
141: extracts characters from \fBins\fR and converts them according
142: to the type of \fBx\fR. It stores the converted value in
143: \fBx\fR.
144: Errors are indicated by setting the
145: error state of \fBins\fR. \f(CWfailbit\fR means that characters
146: in \fBins\fR were not a representation of the required type.
147: \f(CWbadbit\fR indicates that attempts to extract characters failed.
148: \fBins\fR is always returned.
149: .RS
150: .PP
151: The details of conversion depend on the values of \fBins\fR's format
152: state variable (see \fIios\fR(3C++)) and the
153: type of \fBx\fR. Except as noted, the extraction operators
154: do not change the value
155: of the format state variables.
156: .TP
157: \f(CWchar*\fR, \f(CWunsigned char*\fR
158: Characters are stored in the array pointed at by \fBx\fR
159: until a whitespace character is found in \fBins\fR.
160: The terminating whitespace
161: is left in \fBins\fR.
162: If \fBins.width()\fR
163: is non-zero it is taken to be the size of the array, and
164: no more than \fBins.width()-1\fR characters are extracted.
165: A terminating
166: null character (0) is always stored (even when nothing else is
167: done because of \fBins\fR's status).
168: \fBins.width()\fR is reset to 0.
169: .TP
170: \f(CWchar&\fR, \f(CWunsigned char&\fR
171: A character is extracted and stored in \fBx\fR.
172: .TP
173: \f(CWshort&\fR, \f(CWunsigned short&\fR, \f(CWint&\fR, \f(CWunsigned int&\fR, \f(CWlong&\fR, \f(CWunsigned long&\fR
174: Characters are extracted and converted to an integral value
175: according to the conversion specified by
176: \fBins.convbase()\fR.
177: The first character may be a sign (\f(CW+\fR or \f(CW-\fR). After that,
178: if \fBins.convbase()\fR
179: is 8, 10, or 16 the conversion is octal, decimal, or hexadecimal respectively.
180: Conversion is terminated by the first "non-digit," which is left
181: in \fBins\fR. Octal digits are the characters '0' to '7'.
182: Decimal
183: digits are the octal digits plus '8' and '9'.
184: Hexadecimal digits
185: are the decimal digits plus the letters 'a' through 'f' (in either
186: upper or lower case).
187: If \fBins.convbase()\fR
188: is 0 then the number is interpreted according to C lexical
189: conventions. That is, if the first characters (after the optional
190: sign) are \f(CW0x\fR or \f(CW0X\fR a hexadecimal conversion
191: is performed
192: on following hexadecimal digits. Otherwise if the first character is a
193: \f(CW0\fR an
194: octal conversion is performed and in all other cases a decimal conversion
195: is performed.
196: \f(CWfailbit\fR is set if there are no
197: digits (not counting the \f(CW0\fR in \f(CW0x\fR or \f(CW0X\fR) during
198: hex conversion) available.
199: .TP
200: \f(CWfloat&\fR, \f(CWdouble&\fR
201: Converts the characters according to C++ syntax for a float or double,
202: and stores the result in \fBx\fR. \f(CWfailbit\fR is set if there are no
203: digits available in \fBins\fR or if it does not begin with a well formed
204: floating point number.
205: .RE
206: .PP
207: The type and name(\f(CWoperator>>\fR) of
208: the extraction operations are chosen
209: to give a convenient syntax for sequences of input operations.
210: The operator overloading of C++ permits
211: extraction functions to be declared for user defined classes.
212: These operations can then be used with the same syntax as the
213: member functions described here.
214: .PP
215: Unformatted input functions, which call \fBipfx(1)\fR and proceed only
216: if it returns non-zero:
217: .TP
218: \fBinsp=&ins.get(ptr,len,delim)\fR
219: Extracts characters and stores them in
220: the byte array beginning at \fBptr\fR
221: and extending for \fBlen\fR bytes.
222: Extraction stops when \fBdelim\fR is encountered
223: (\fBdelim\fR is left in \fBins\fR and not stored),
224: when \fBins\fR has no more characters,
225: or when the array has only one byte left.
226: \fBget\fR always stores a terminating null, even if it doesn't extract
227: any characters from \fBins\fR because of its error status.
228: \f(CWfailbit\fR is set only if \fBget\fR encounters
229: an end of file before it stores any characters.
230: .TP
231: \fBinsp=&ins.get(c)\fR
232: Extracts a single character
233: and stores it in \fBc\fR.
234: .TP
235: \fBinsp=&ins.get(sb,delim)\fB
236: Extracts characters from \fBins.rdbuf()\fR and stores
237: them into \fBsb\fR.
238: It stops if it encounters end of file or if a store into
239: \fBsb\fR
240: fails or
241: if it encounters \fBdelim\fR (which it leaves in \fBins\fR).
242: \f(CWfailbit\fR is set if it stops because the store into \fBsb\fR fails
243: .TP
244: \fBi=ins.get()\fR.
245: Extracts a character and returns it.
246: \fBi\fR is \f(CWEOF\fR if extraction encounters end of file.
247: \f(CWfailbit\fR is never set.
248: .TP
249: \fBinsp=&ins.getline(ptr,len,delim)\fR
250: Does the same thing as \fBins.get(ptr,len,delim)\fR with the exception
251: that it extracts a terminating \fBdelim\fR character from \fBins\fR.
252: In case \fBdelim\fR occurs when exactly \fBlen\fR characters
253: have been extracted, termination is treated as being due to the
254: array being filled, and this \fBdelim\fR is left in \fBins\fR.
255: .TP
256: \fBinsp=&ins.ignore(n,d)\fR
257: Extracts and throws away
258: up to \fBn\fR characters.
259: Extraction stops prematurely if
260: \fBd\fR is extracted or end of file is reached.
261: If \fBd\fR is \f(CWEOF\fR it can never cause termination.
262: .TP
263: \fBinsp=&ins.read(ptr,n)\fR
264: Extracts
265: \fBn\fR
266: characters and stores them in the array beginning at \fBptr\fR
267: If end of file is reached before \fBn\fR characters have been
268: extracted,
269: \fBread\fR
270: stores whatever it can extract and sets \f(CWfailbit\fR.
271: The number of characters extracted can be determined via \fBins.gcount()\fR.
272: .PP
273: Other members are:
274: .TP
275: \fBi=ins.gcount()\fR
276: Returns the number of characters extracted by the last unformatted
277: input function. Formatted input functions may call unformatted
278: input functions and thereby reset this number.
279: .TP
280: \fBi=ins.peek()\fR
281: Begins by calling \fBins.ipfx(1)\fR.
282: If that call returns zero or if \fBins\fR is at end of file,
283: it returns \f(CWEOF\fR.
284: Otherwise it returns (without extracting it) the next character.
285: .TP
286: \fBinsp=&ins.putback(c)\fR
287: Attempts to back up \fBins.rdbuf()\fR.
288: \fBc\fR must be the character before \fBins.rdbuf()\fR's get pointer.
289: (Unless other activity is modifying \fBins.rdbuf()\fR this
290: is the last character extracted from \fBins\fR.)
291: If it is not, the effect is undefined.
292: \fBputback\fR may fail (and set the error state).
293: Although it is a member of \f(CWistream\fR,
294: \fBputback\fR never extracts characters, so
295: it does not call \fBipfx\fR. It will, however, return without
296: doing anything if the error state is non-zero.
297: .TP
298: \fBins>>manip\fR
299: Equivalent to \fBmanip(ins)\fR.
300: Syntactically this looks like an extractor
301: operation, but semantically it does an arbitrary operations
302: rather than converting a sequence of characters and storing the
303: result in \fBmanip\fR.
304: .PP
305: Member functions related to positioning.
306: .TP
307: \fBinsp=&ins.seekg(off,dir)\fR
308: Repositions \fBins.rdbuf()\fR's get pointer.
309: See \fIsbuf.pub\fR(3C++)\fR for a discussion of positioning.
310: .TP
311: \fBinsp=&ins.seekg(pos)\fR
312: Repositions \fBins.rdbuf()\fR's get pointer.
313: See \fIsbuf.pub\fR(3C++)\fR for a discussion of positioning.
314: .TP
315: \fBpos=ins.tellg()\fR
316: The current position of \fBios.rdbuf()\fR's get pointer.
317: See \fIsbuf.pub\fR(3C++)\fR for a discussion of positioning.
318: .PP
319: Manipulator:
320: .TP
321: \fBins>>ws\fR
322: Extracts whitespace characters.
323: .SH CAVEATS
324: .PP
325: There is no overflow detection on conversion of integers. There should
326: be, and overflow should cause the error state to be set.
327: .PP
328: There should be a way to input an arbitrary length string without
329: knowing a maximum size beforehand.
330: .PP
331: .SH SEE ALSO
332: ios(3C++)
333: sbuf.pub(3C++)
334: manip(3C++)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.