.. oe:namespace:: OEPlatform



.. meta::
   :keywords: oeistream, istream


.. _OEPlatform_oeistream:

.. oe:class:: oeistream

   .. oe:api::


      class oeistream : public oestream

   This class represents `oeistream`.

   Defines the platform independent interface and implementation for a
   generic input data stream class.

   The following methods are publicly inherited from :ref:`oestream <OEPlatform_oestream>`:
   

   ============================================================= ============================================================ ============================================================
   :oe:meth:`operator bool<OEPlatform::oestream::operator bool>` :oe:meth:`rewind<OEPlatform::oestream::rewind>`              :oe:meth:`tell<OEPlatform::oestream::tell>`                 
   :oe:meth:`eof<OEPlatform::oestream::eof>`                     :oe:meth:`seek<OEPlatform::oestream::seek>`                                                                              
   :oe:meth:`length<OEPlatform::oestream::length>`               :oe:meth:`size<OEPlatform::oestream::size>`                                                                              
   ============================================================= ============================================================ ============================================================


   The following classes derive from this class:
    * :ref:`oeifstream <OEPlatform_oeifstream>`
    * :ref:`oeigzstream <OEPlatform_oeigzstream>`
    * :ref:`oeisstream <OEPlatform_oeisstream>`
    * :ref:`oeistdstream <OEPlatform_oeistdstream>`
    * :ref:`oeiwrapperstream <OEPlatform_oeiwrapperstream>`
    * :ref:`oeprogressstream <OESystem_oeprogressstream>`
   
   .. oe:method:: Constructors

      .. oe:language:: c++ java csharp

         .. oe:api::

            oeistream()

      .. oe:language:: python

         .. oe:api:: python

            oeistream() -> oeistream

      Creates an instance of an
      :ref:`oeistream <OEPlatform_oeistream>`. This class is designed to
      provide an interface and some functionality; however, this
      class does not define a data source and therefore instances
      of this class have no independent functionality.

   .. oe:method:: operator>>
      :language: c++


      .. oe:api::

         oeistream &operator>>(oestream &(_f)(oestream &))
         oeistream &operator>>(oeistream &(_f)(oeistream &))

      Use of these operators executes the specified function ('f') on
      the stream in question. In order for proper compilation and
      execution, the specified function must be prototyped according
      to the API shown above.

      .. oe:api::

         oeistream &operator>>(oeostream &)

      Sends all of the remaining input on the stream to the specified 
      :ref:`oeostream <OEPlatform_oeostream>`.

      .. oe:api::

         oeistream &operator>>(int &)
         oeistream &operator>>(bool &)
         oeistream &operator>>(long &)
         oeistream &operator>>(char &)
         oeistream &operator>>(float &)
         oeistream &operator>>(short &)
         oeistream &operator>>(double &)
         oeistream &operator>>(std::string &)
         oeistream &operator>>(signed char &)
         oeistream &operator>>(unsigned int &)
         oeistream &operator>>(unsigned long &)
         oeistream &operator>>(unsigned char &)
         oeistream &operator>>(unsigned short &)

      These operators read the next whitespace-delimited token on the
      input stream, converts it into the appropriate data type, and
      stores that value in the specified parameter. The use of these
      operators on non-text streams is undefined.

   .. oe:method:: close

      .. oe:language:: c++ java csharp

         .. oe:api::

            void close()

      .. oe:language:: python

         .. oe:api:: python

            close() -> None

      Closes the input stream. All future attempts to read from this
      stream will fail until it is opened again with new input.

   .. oe:method:: get

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool get(char& c)
            bool get(signed char& c)
            bool get(unsigned char& c)

      .. oe:language:: python

         .. oe:api:: python

            get(c: str) -> bool
            get(str: signed) -> bool

      Gets the next byte off of the stream and assigns its value to the
      parameter 'c'. Returns whether or not the byte read equals EOF.

   .. oe:method:: getbyte

      .. oe:language:: c++ java csharp

         .. oe:api::

            int getbyte()

      .. oe:language:: python

         .. oe:api:: python

            getbyte() -> int

      Returns the next byte off of the stream.

   .. oe:method:: getline

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool getline(std::string& sbuffer)
            bool getline(char* buffer, oesize_t max)
            bool getline(signed char* buffer, oesize_t max)
            bool getline(std::string& sbuffer, oesize_t max)
            bool getline(unsigned char* buffer, oesize_t max)

      .. oe:language:: python

         .. oe:api:: python

            getline(sbuffer: str) -> bool
            getline(sbuffer: str, max: oesize_t) -> bool

      Retrieves the next text line from the stream and directly copies
      its contents into the 'buffer' parameter. The newline character is
      not copied with the rest of the contents, though a null
      terminator, '\0', is placed at the end of the contents. The 'max' parameter
      specifies the maximum size of the memory passed in as the
      'buffer' argument. If a newline character is not found within
      'max - 1' characters, only the specified number of characters will be copied
      into the buffer and all the remaining characters in the stream
      before the next newline character will be discarded.

   .. oe:method:: gettoken

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool gettoken(char* buffer, oesize_t max)
            bool gettoken(signed char* buffer, oesize_t max)
            bool gettoken(std::string& sbuffer, oesize_t max)
            bool gettoken(unsigned char* buffer, oesize_t max)

      .. oe:language:: python

         .. oe:api:: python

            gettoken(sbuffer: str, max: oesize_t) -> bool

      Retrieves the next whitespace delimited token from the stream and
      directly copies its contents into the 'buffer' parameter. This
      function discards the whitespace characters read when searching for
      the next token. The 'max' parameter specifies the maximum number of
      characters allowed per token. If a whitespace character is not
      found within the specified number of characters, only the specified
      number of characters will be copied into the buffer and all the
      remaining characters in the stream before the next whitespace
      character will be discarded.



   .. oe:method:: open

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool open(const char* name)
            bool open(const std::string& name)
            bool open(unsigned char* buffer, oesize_t len)

      .. oe:language:: python

         .. oe:api:: python

            open(name: str) -> bool
            open(buffer: str, len: oesize_t) -> bool

      Opens the input stream with data from the specified
      sources. Passing a 'name' parameter will result in invocation of a
      protected virtual method to appropriate handle the specified input
      source. Passing a pointer to a character buffer along with the
      buffer's size will result in the stream wrapping the 'buffer' and
      using that as the stream data source. Returns whether or not data
      can now be read from the stream.



   .. oe:method:: peekbyte

      .. oe:language:: c++ java csharp

         .. oe:api::

            int peekbyte()

      .. oe:language:: python

         .. oe:api:: python

            peekbyte() -> int

      Returns the value of the next byte without removing that byte from
      the input stream. Returns ``-1`` if the stream is not valid.

   .. oe:method:: read

      .. oe:language:: c++ java csharp

         .. oe:api::

            oesize_t read(std::string& sbuffer)
            oesize_t read(char* buffer, oesize_t len)
            oesize_t read(signed char* buffer, oesize_t len)
            oesize_t read(std::string& sbuffer, oesize_t len)
            oesize_t read(unsigned char* buffer, oesize_t len)

      .. oe:language:: python

         .. oe:api:: python

            read(sbuffer: str) -> oesize_t

      Reads the next len number of bytes off of the stream, stores them
      in the specified 'buffer' and returns the number of bytes actually
      read. It is the user's responsibility when using any of the three
      ``char *`` versions to make sure that the specified 'buffer' has been
      properly allocated and has enough room to store len bytes. This
      function does not add a NULL terminator to the end of the
      buffer.

      The version that takes a ``std::string`` without a size will
      read the entire contents of the stream into the string, or until
      ``std::bad_alloc`` is thrown when the system runs out of
      memory. 

   .. oe:method:: skip

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool skip(oefpos_t len)

      .. oe:language:: python

         .. oe:api:: python

            skip(len: oefpos_t) -> bool

      Discards the next number of bytes specified by 'len' in the
      stream. Returns whether or not there are any bytes left in the
      stream.



   .. oe:method:: skipbyte

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool skipbyte()

      .. oe:language:: python

         .. oe:api:: python

            skipbyte() -> bool

      Discards the next byte in the stream. Returns whether or not there
      are any bytes left in the stream.

   .. oe:method:: skipline

      .. oe:language:: c++ java csharp

         .. oe:api::

            bool skipline()

      .. oe:language:: python

         .. oe:api:: python

            skipline() -> bool

      Discards the next text line in the stream. Returns whether or not
      there are any bytes left in the stream.

