The base class for input streams. This class cannot be instantiated.
More...
#include "nn/nlib/InputStream.h"
|
errno_t | GetErrorValue () const noexcept |
| Gets the error value. More...
|
|
size_t | Pos () const noexcept |
| Returns the current position in the stream. More...
|
|
uint64_t | Pos64 () const noexcept |
| Returns the current position in the stream as a 64-bit value. More...
|
|
bool | IsEos () noexcept |
| Returns true if the stream is finished being read through to the end. If the stream has not been read through to the end, or if an error occurs, the function returns false . More...
|
|
int | Read () noexcept |
| Reads one byte of data from the stream. More...
|
|
int | Peek () noexcept |
| Reads the next byte without consuming the stream. More...
|
|
size_t | Skip (size_t nbytes) noexcept |
| Skips over the number of bytes specified by nbytes. More...
|
|
size_t | Read (void *ptr, size_t nbytes) noexcept |
| Reads the number of bytes of data specified by nbytes into the memory region specified by ptr. More...
|
|
template<size_t N> |
size_t | Read (nlib_byte_t(&buf)[N]) noexcept |
| A template overload of the above function.
|
|
bool | Close () noexcept |
| Closes the stream. Returns true if successful. More...
|
|
bool | Mark (size_t readlimit) noexcept |
| This function provides settings that allow you to return to the current load position using GoBackToMark() . More...
|
|
bool | GoBackToMark () noexcept |
| This function allows you to return to the load position that the last Mark() has been executed at. More...
|
|
bool | IsMarkSupported () const noexcept |
| This function returns true if this stream supports Mark() and GoBackToMark() .
|
|
| operator bool () const |
| Returns true if the object has been initialized and an error has not occurred inside, or returns false if an error has occurred inside.
|
|
|
constexpr | InputStream () noexcept |
| Instantiates the object with default parameters (default constructor). This function is called from the derived class.
|
|
virtual | ~InputStream () noexcept |
| Destructor. This function is called from the derived class.
|
|
The base class for input streams. This class cannot be instantiated.
- Description
- It is the base class for input streams with a synchronous and sequential access interface. The place into which the data is read is defined by the derived class.
- To read data one byte at a time, use code like the following.
int c;
while ((c = is.Read()) >= 0) {
}
}
- To prepare a buffer and read a collection of a certain number of bytes, use code like the following.
uint8_t* buf = ... N bytes of memory ...;
size n = is.Read(buf, N);
}
- To read UTF-8 text data, use a
TextReader
object. Normalize newlines and check for UTF-8, and then convert it into UTF-32 and pass it to the user. TextReader r;
int c;
while ((c = is.Read()) >= 0) {
}
}
Information for Implementing Derived Classes
- The specifications of the
InputStream
class may change without notice. You can lower your risk by implementing derived classes independently whenever possible. However, if necessary, you can define derived classes by overriding the following virtual function.
- size_t FillBuffer_(void* p, size_t nbytes)
- p is the pointer to the data to set, and nbytes is the size. The function is called when the user attempts to read data but there is no data inside the
InputStream
internal buffer. The p parameter holds the pointer to the internal buffer or to a user-specified buffer.
- The value that is returned is the amount of data that was actually set. It is a value equal to or less than nbytes. The function only returns
0
if there was an error or if it was the end of the data. The function must block if the data is not available yet.
- In the case of errors, deal with them as shown in the examples below.
-
If there is no compatible device (for example, the handle is invalid), set
EBADF
and return 0
.
-
If there is a confirmed failure while reading, set an error (for example,
EIO
) and return 0
.
- Note that 0 needs to be returned when an error has occurred, even if data has been partially read.
- Attention
- On and after the 2018-05-08 version, when
nullptr, 0
was passed as the argument, you need to call ResetBuffer()
to set the internal buffer for InputStream
before setting the data.
- bool Close_()
- Closes internal handles and the like. No matter how you implement this function, you must free all associated resources that are being held internally. Also be careful not to call the
Close_
function from the base class destructor.
- In the case of errors, deal with them as shown in the examples below.
-
If there is no compatible device (for example, the handle is invalid), set
EBADF
and return false
.
-
If the process fails during closing, set some error (for example,
EIO
) and return false
.
- Note that even if an error occurs, you must make sure that the handle and other internal resources are freed.
- void* GetWorkBuffer_(size_t* nbytes)
- Attention
- This function was deleted on the 2018-05-08 version and no longer provided.
Notes About the Configuration of InputStream
- When you read data with the
InputStream
class, the data is invariably cached in a buffer. The purpose of this cache is not to collect the read operations from a device, but rather to limit the calls to virtual functions.
- When designing
InputSrteam
, using an interface class as listed below as the base class makes the design simple. This approach, however, is impractical because calling data on a byte basis causes significant overhead of the virtual functions.
Definition at line 29 of file InputStream.h.
◆ Close()
nn::nlib::InputStream::Close |
( |
| ) |
|
|
noexcept |
Closes the stream. Returns true
if successful.
- Returns
- Returns
true
when successful.
- Description
- If the function returns
false
, a process failed. Even if a process failed, you do not need to close again.
◆ GetErrorValue()
nn::nlib::InputStream::GetErrorValue |
( |
| ) |
const |
|
inlinenoexcept |
Gets the error value.
- Returns
- Returns the error value.
- Description
- Any value other than
0
indicates an error. The error values generally depend on the implementation.
Definition at line 57 of file InputStream.h.
◆ GoBackToMark()
nn::nlib::InputStream::GoBackToMark |
( |
| ) |
|
|
noexcept |
This function allows you to return to the load position that the last Mark()
has been executed at.
- Returns
- Returns
true
if the execution could return to the marked load position.
- Description
- You can return to the marked load position if calling this function at a position within
readlimit
bytes from the position that Mark()
was called at.
- Under any of the following conditions,
false
is returned.
-
When this stream provides no support for
Mark()
or GoBackToMark()
. In this case, an ENOTSUP
error is set on the stream.
-
When executing this function after reading data longer than readlimit bytes. In this case, an
ERANGE
error is set on the stream.
◆ IsEos()
nn::nlib::InputStream::IsEos |
( |
| ) |
|
|
inlinenoexcept |
Returns true
if the stream is finished being read through to the end. If the stream has not been read through to the end, or if an error occurs, the function returns false
.
- Returns
- Returns
true
if the end of the stream has been reached.
Definition at line 61 of file InputStream.h.
◆ Mark()
nn::nlib::InputStream::Mark |
( |
size_t |
readlimit | ) |
|
|
noexcept |
This function provides settings that allow you to return to the current load position using GoBackToMark()
.
- Parameters
-
[in] | readlimit | The maximum number of bytes allowed to be read before executing GoBackToMark() |
- Returns
- Returns
true
on success.
- Description
- Executing
GoBackToMark()
allows you to read data of readlimit bytes again at the current position on the stream. For readlimit, specify the maximum number of bytes that can be read before calling GoBackToMark()
. If repeatedly executing Mark()
, only the result from the last execution is effective. In addition, the value for readlimit should be equal to or smaller than 1024.
- Under any of the following conditions,
false
is returned.
-
When this stream provides no support for
Mark()
or GoBackToMark()
. In this case, an ENOTSUP
error is set on the stream.
-
When the readlimit value is larger than 1024. In this case, an
EINVAL
error is set on the stream.
-
When any other error caused by I/O has occurred. In this case, an
EIO
error is set on the stream.
◆ Peek()
nn::nlib::InputStream::Peek |
( |
| ) |
|
|
inlinenoexcept |
Reads the next byte without consuming the stream.
- Returns
- Returns the read data, or
-1
.
- Description
- Returns the data that was read. If the function fails or the stream is finished being read through to the end, the function returns
-1
.
Definition at line 77 of file InputStream.h.
◆ Pos()
nn::nlib::InputStream::Pos |
( |
| ) |
const |
|
inlinenoexcept |
Returns the current position in the stream.
- Returns
- The current position in the stream (the number of bytes that have been read).
- Description
- Note that if you use this member function after the stream has been closed, it does not get a correct value.
Definition at line 59 of file InputStream.h.
◆ Pos64()
nn::nlib::InputStream::Pos64 |
( |
| ) |
const |
|
inlinenoexcept |
Returns the current position in the stream as a 64-bit value.
- Returns
- The current position in the stream (the number of bytes that have been read).
Definition at line 60 of file InputStream.h.
◆ Read() [1/2]
nn::nlib::InputStream::Read |
( |
| ) |
|
|
inlinenoexcept |
Reads one byte of data from the stream.
- Returns
- Returns the read data, or
-1
.
- Description
- Returns the data that was read. If the function fails or the stream is finished being read through to the end, the function returns
-1
.
- Consequently, if
-1
is read, you must determine whether an error occurred or the end of the stream was reached. c = is.Read();
if (c < 0) {
} else {
}
}
Definition at line 69 of file InputStream.h.
◆ Read() [2/2]
nn::nlib::InputStream::Read |
( |
void * |
ptr, |
|
|
size_t |
nbytes |
|
) |
| |
|
inlinenoexcept |
Reads the number of bytes of data specified by nbytes into the memory region specified by ptr.
- Parameters
-
[in,out] | ptr | The location in memory used to store the read data. |
[in] | nbytes | The number of bytes to be read. |
- Returns
- Returns the number of bytes actually read.
- Description
- If the number of bytes read is specified as
0
, either there was an error or the stream is over. The stream might also be over if some other value smaller than nbytes is returned.
Definition at line 86 of file InputStream.h.
◆ SetBuffer()
nn::nlib::InputStream::SetBuffer |
( |
void * |
p, |
|
|
size_t |
nbytes, |
|
|
bool |
is_mark_supported, |
|
|
bool |
is_buf_readonly |
|
) |
| |
|
inlineprotectednoexcept |
Sets the buffer held by InputStream
.
- Parameters
-
[in] | p | Pointer to the buffer. |
[in] | nbytes | Buffer size. |
[in] | is_mark_supported | True if is_mark_supported Mark() is supported. |
[in] | is_buf_readonly | True if overwriting the is_buf_readonly buffer is not permitted. |
Definition at line 116 of file InputStream.h.
◆ SetError()
nn::nlib::InputStream::SetError |
( |
errno_t |
e | ) |
const |
|
inlineprotectednoexcept |
Sets an error to InputStream
.
- Parameters
-
- Description
- If a non-zero error has been set already, that error value is not overwritten.
Definition at line 131 of file InputStream.h.
◆ Skip()
nn::nlib::InputStream::Skip |
( |
size_t |
nbytes | ) |
|
|
noexcept |
Skips over the number of bytes specified by nbytes.
- Parameters
-
[in] | nbytes | The number of bytes to skip. |
- Returns
- Returns the number of bytes actually skipped.
- Description
- Skipping data can be more efficient than reading and discarding data using the
Read
function.
The documentation for this class was generated from the following files: