Return to istream.3 CVS log

Up to [Research Unix] / researchv10dc / man / mana

Annotation of researchv10dc/man/mana/istream.3, revision 1.1

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.