|  | reflex::Input Class Reference updated Fri Dec 9 2016 |

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Classes | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
reflex::Input Class Reference

Input character sequence class for unified access to sources of input. More...

`#include <input.h>`

## Classes
struct | Const
| Common constants. More...

## Public Member Functions
| Input (const Input &input)
| Copy constructor (with intended "move semantics" as internal state is shared, should not rely on using the rhs after copying). More...
| Input (void)
| Construct empty input character sequence. More...
| Input (const char *cstring)
| Construct input character sequence from a NUL-terminated string. More...
| Input (const std::string &string)
| Construct input character sequence from a std::string. More...
| Input (const std::string *string)
| Construct input character sequence from a pointer to a std::string. More...
| Input (const wchar_t *wstring)
| Construct input character sequence from a NUL-terminated wide character string. More...
| Input (const std::wstring &wstring)
| Construct input character sequence from a std::wstring. More...
| Input (const std::wstring *wstring)
| Construct input character sequence from a pointer to a std::wstring. More...
| Input (FILE *file)
| Construct input character sequence from an open FILE* file descriptor, supports UTF-8 conversion from UTF-16 and UTF-32, use stdin if file == NULL. More...
| Input (std::istream &istream)
| Construct input character sequence from a std::istream. More...
| Input (std::istream *istream)
| Construct input character sequence from a pointer to a std::istream, use stdin if istream == NULL. More...
| operator const char * ()
| Cast this Input object to string. More...
| operator const wchar_t * ()
| Cast this Input object to wide character string. More...
| operator FILE * ()
| Cast this Input object to file descriptor FILE*. More...
| operator std::istream * ()
| Cast this Input object to std::istream*. More...
const char * | cstring (void)
| Get the remaining string of this Input object. More...
const wchar_t * | wstring (void)
| Get the remaining wide character string of this Input object. More...
FILE * | file (void)
| Get the FILE* of this Input object. More...
std::istream * | istream (void)
| Get the std::istream of this Input object. More...
size_t | size (void)
| Get the size of the input character sequence in number of ASCII/UTF-8 bytes (zero if size is not determinable from a `FILE*` or `std::istream` source). More...
bool | good (void)
bool | eof (void)
size_t | get (char *s, size_t n)
void | file_encoding (short enc)
| Set encoding for `FILE*` input to Const::plain, Const::utf16be, Const::utf16le, Const::utf32be, or Const::utf32le. File encodings are automatically detected by the presence of a UTF BOM in the file. This function may be used when a BOM is not present and file encoding is known or to override the BOM. More...
short | file_encoding (void) const

## Protected Member Functions
void | init (void)
| Initialize the state after (re)setting the input source. More...
void | file_init (void)
| Implements init() on a FILE*. More...
size_t | file_get (char *s, size_t n)
| Implements get() on a FILE*. More...
void | file_size (void)
| Implements size() on a FILE*. More...
bool | file_good (void)
| Implements good()operation on a FILE*. More...
bool | file_eof (void)
| Implements eof() on a FILE*. More...

## Protected Attributes
const char * | cstring_
| NUL-terminated char string input (when non-null) More...
const wchar_t * | wstring_
| NUL-terminated wide string input (when non-null) More...
FILE * | file_
| FILE* input (when non-null) More...
std::istream * | istream_
| stream input (when non-null) More...
size_t | size_
| size of the input in bytes, when known More...
char | utf8_ [8]
| UTF-8 conversion buffer. More...
unsigned short | uidx_
| index in utf8_[] or >= 8 when unused More...
unsigned short | utfx_
| 0 = ASCII/UTF-8, 1 = UTF-16 BE, 2 = UTF-16 LE, 3 = UTF-32 BE, 4 = UTF-32 LE More...

## Detailed Description

Input character sequence class for unified access to sources of input.

## Description

The Input class unifies access to a source of input of a character sequence as follows:

- An Input object is instantiated and (re)assigned a (new) source input: either a `char*` string, a `wchar_t*` wide string, a `std::string`, a `std::wstring`, a `FILE*` descriptor, or a `std::istream` object.
- When assigned a wide string source as input, the wide character content is automatically converted to an UTF-8 character sequence when reading with get().
- When assigned a `FILE*` source as input, the file is checked for the presence of a UTF-8 or a UTF-16 BOM (Byte Order Mark). A UTF-8 BOM is ignored and will not appear on the input character stream (and size is adjusted by 3 bytes). A UTF-16 BOM is intepreted, resulting in the conversion of the file content automatically to an UTF-8 character sequence when reading the file with get(). Also, size() gives the content size in the number of UTF-8 bytes.
- An input object can be reassigned a new source of input for reading at any time.
- An input object obeys move semantics. That is, after assigning an input object to another, the former can no longer be used to read input. This prevents adding the overhead and complexity of file and stream duplication.
- `size_t Input::get(char *buf, size_t len);` reads source input and fills `buf` with up to `len` bytes, returning the number of bytes read or zero when a stream or file is bad or when EOF is reached.
- `size_t Input::size(void);` returns the number of ASCII/UTF-8 bytes available to read from the source input or zero (zero is also returned when the size is not determinable). Use this function only before reading input with get(). Wide character strings and UTF-16 `FILE*` content is counted as the total number of UTF-8 bytes that will be produced by get(). The size of a `std::istream` cannot be determined.
- `bool Input::good(void);` returns true if the input is readable and a non-empty sequence of characters is available to get. Returns false on EOF or if an error condition is present.
- `bool Input::eof(void);` returns true if the input reached EOF. Note that good() == ! eof() for string source input only, since files and streams may have error conditions that prevent reading. That is, for files and streams eof() implies good() == false, but not vice versa. Thus, an error is diagnosed when the condition good() == false && eof() == false holds. Note that get(buf, len) == 0 && len > 0 implies good() == false.

## Example

The following example shows how to read a character sequence in blocks from a `std::ifstream`:

std::ifstream ifs;
ifs.open("input.h", std::ifstream::in);
reflex::Input input(ifs);
char buf[1024];
size_t len;
while ((len = input.get(buf, sizeof(buf))) > 0)
fwrite(buf, 1, len, stdout);
if (!input.eof())
std::cerr << "An IO error occurred" << std::endl;
ifs.close();

## Example

The following example shows how to buffer the entire content of a file:

reflex::Input input(fopen("input.h", "r"));
if (!input.file())
abort();
size_t len = input.size();
char *buf = new char[len];
input.get(buf, len);
if (!input.eof())
std::cerr << "An IO error occurred" << std::endl;
fwrite(buf, 1, len, stdout);
delete[] buf;
fclose(input.file());

Files with UTF-16 content are converted to UTF-8 by get(buf, len), where size() gives the total number of UTF-8 bytes that will be produced by get(buf, len).

## Example

The following example shows how to read a character sequence in blocks from a file:

reflex::Input input(fopen("input.h", "r"));
char buf[1024];
size_t len;
while ((len = input.get(buf, sizeof(buf))) > 0)
fwrite(buf, 1, len, stdout);
fclose(input);

## Example

The following example shows how to echo characters one by one from stdin (reading input from a tty):

reflex::Input input(stdin);
char c;
while (input.get(&c, 1))
fputc(c, stdout);

## Example

The following example shows how to read a character sequence in blocks from a wide character string while converting it to UTF-8:

reflex::Input input(L"Copyright ©"); // © is unicode U+00A9 and UTF-8 C2 A9
char buf[8];
size_t len;
while ((len = input.get(buf, sizeof(buf))) > 0)
fwrite(buf, 1, len, stdout);

## Example

The following example shows how to convert a wide character string to UTF-8:

reflex::Input input(L"Copyright ©"); // © is unicode U+00A9 and UTF-8 C2 A9
size_t len = input.size(); // size of UTF-8 string
char *buf = new char[len];
input.get(buf, len);
fwrite(buf, 1, len, stdout);

## Example

The following example shows how to switch source inputs while reading input byte by byte (use a buffer as shown in other examples to improve efficiency):

reflex::Input input = "Hello";
std::string message;
char c;
while (input.get(&c, 1))
message.append(c);
input = L" world! To ∞ and beyond."; // switch input to a wide string
while (input.get(&c, 1))
message.append(c);

## Constructor & Destructor Documentation

reflex::Input::Input | ( | const Input & | input | ) |
| inline

Copy constructor (with intended "move semantics" as internal state is shared, should not rely on using the rhs after copying).

Parameters

  input | an Input object to share state with (undefined behavior results from using both objects at the same time)

reflex::Input::Input | ( | void |  | ) |
| inline

Construct empty input character sequence.

reflex::Input::Input | ( | const char * | cstring | ) |
| inline

Construct input character sequence from a NUL-terminated string.

Parameters

  cstring | NUL-terminated char* string

reflex::Input::Input | ( | const std::string & | string | ) |
| inline

Construct input character sequence from a std::string.

Parameters

  string | input string

reflex::Input::Input | ( | const std::string * | string | ) |
| inline

Construct input character sequence from a pointer to a std::string.

Parameters

  string | input string

reflex::Input::Input | ( | const wchar_t * | wstring | ) |
| inline

Construct input character sequence from a NUL-terminated wide character string.

Parameters

  wstring | NUL-terminated wchar_t* input string

reflex::Input::Input | ( | const std::wstring & | wstring | ) |
| inline

Construct input character sequence from a std::wstring.

Parameters

  wstring | input wide string

reflex::Input::Input | ( | const std::wstring * | wstring | ) |
| inline

Construct input character sequence from a pointer to a std::wstring.

Parameters

  wstring | input wide string

reflex::Input::Input | ( | FILE * | file | ) |
| inline

Construct input character sequence from an open FILE* file descriptor, supports UTF-8 conversion from UTF-16 and UTF-32, use stdin if file == NULL.

Parameters

  file | input file

reflex::Input::Input | ( | std::istream & | istream | ) |
| inline

Construct input character sequence from a std::istream.

Parameters

  istream | input stream

reflex::Input::Input | ( | std::istream * | istream | ) |
| inline

Construct input character sequence from a pointer to a std::istream, use stdin if istream == NULL.

Parameters

  istream | input stream

## Member Function Documentation

const char* reflex::Input::cstring | ( | void |  | ) |
| inline

Get the remaining string of this Input object.

Returns
  remaining unbuffered part of the NUL-terminated string or NULL.

bool reflex::Input::eof | ( | void |  | ) |
| inline

Check if input reached EOF.

Returns
  true if input is at EOF and no characters are available.

FILE* reflex::Input::file | ( | void |  | ) |
| inline

Get the FILE* of this Input object.

Returns
  pointer to current file descriptor or NULL.

void reflex::Input::file_encoding | ( | short | enc | ) |
| inline

Set encoding for `FILE*` input to Const::plain, Const::utf16be, Const::utf16le, Const::utf32be, or Const::utf32le. File encodings are automatically detected by the presence of a UTF BOM in the file. This function may be used when a BOM is not present and file encoding is known or to override the BOM.

Parameters

  enc | Const::plain, Const::utf16be, Const::utf16le, Const::utf32be, or Const::utf32le

short reflex::Input::file_encoding | ( | void |  | ) | const
| inline

Get encoding of the current `FILE*` input, Const::plain, Const::utf16be, Const::utf16le, Const::utf32be, or Const::utf32le.

Returns
  Const::plain, Const::utf16be, Const::utf16le, Const::utf32be, or Const::utf32le.

bool reflex::Input::file_eof | ( | void |  | ) |
| inline protected

Implements eof() on a FILE*.

size_t reflex::Input::file_get | ( | char * | s,
|  | size_t | n
| ) |  |
| protected

Implements get() on a FILE*.

Parameters

  s | points to the string buffer to fill with input
  n | size of buffer pointed to by s

bool reflex::Input::file_good | ( | void |  | ) |
| inline protected

Implements good()operation on a FILE*.

void reflex::Input::file_init | ( | void |  | ) |
| protected

Implements init() on a FILE*.

void reflex::Input::file_size | ( | void |  | ) |
| protected

Implements size() on a FILE*.

size_t reflex::Input::get | ( | char * | s,
|  | size_t | n
| ) |  |
| inline

Copy subsequent character sequence data into buffer.

Returns
  the nonzero number of (less or equal to n) 8-bit characters added to buffer s from the current input, or zero when EOF.

Parameters

  s | points to the string buffer to fill with input
  n | size of buffer pointed to by s

bool reflex::Input::good | ( | void |  | ) |
| inline

Check if input is available.

Returns
  true if a non-empty sequence of characters is available to get.

void reflex::Input::init | ( | void |  | ) |
| inline protected

Initialize the state after (re)setting the input source.

std::istream* reflex::Input::istream | ( | void |  | ) |
| inline

Get the std::istream of this Input object.

Returns
  pointer to current std::istream or NULL.

reflex::Input::operator const char * | ( |  | ) |
| inline

Cast this Input object to string.

Returns
  remaining unbuffered part of the NUL-terminated string or NULL.

reflex::Input::operator const wchar_t * | ( |  | ) |
| inline

Cast this Input object to wide character string.

Returns
  remaining unbuffered part of the NUL-terminated wide character string or NULL.

reflex::Input::operator FILE * | ( |  | ) |
| inline

Cast this Input object to file descriptor FILE*.

Returns
  pointer to current file descriptor or NULL.

reflex::Input::operator std::istream * | ( |  | ) |
| inline

Cast this Input object to std::istream*.

Returns
  pointer to current std::istream or NULL.

size_t reflex::Input::size | ( | void |  | ) |
| inline

Get the size of the input character sequence in number of ASCII/UTF-8 bytes (zero if size is not determinable from a `FILE*` or `std::istream` source).

Returns
  the nonzero number of ASCII/UTF-8 bytes available to read, or zero when source is empty or if size is not determinable.

Warning
  This function SHOULD NOT be used after get().

const wchar_t* reflex::Input::wstring | ( | void |  | ) |
| inline

Get the remaining wide character string of this Input object.

Returns
  remaining unbuffered part of the NUL-terminated wide character string or NULL.

## Member Data Documentation

const char* reflex::Input::cstring_
| protected

NUL-terminated char string input (when non-null)

FILE* reflex::Input::file_
| protected

FILE* input (when non-null)

std::istream* reflex::Input::istream_
| protected

stream input (when non-null)

size_t reflex::Input::size_
| protected

size of the input in bytes, when known

unsigned short reflex::Input::uidx_
| protected

index in utf8_[] or >= 8 when unused

char reflex::Input::utf8_[8]
| protected

UTF-8 conversion buffer.

unsigned short reflex::Input::utfx_
| protected

0 = ASCII/UTF-8, 1 = UTF-16 BE, 2 = UTF-16 LE, 3 = UTF-32 BE, 4 = UTF-32 LE

const wchar_t* reflex::Input::wstring_
| protected

NUL-terminated wide string input (when non-null)

The documentation for this class was generated from the following file:

- input.h