C++ bindings for cgul_stream_reader
More...
#include <cgul_stream_reader_cxx.h>
Public Types | |
| typedef cgul_stream_reader__decode_t | decode_t |
Static Public Member Functions | |
| static void | decode_utf8 (cgul_exception_t *cex, unsigned char *block_encoded, size_t size_encoded, size_t *index_encoded, cgul_wchar_t *block_decoded, size_t size_decoded, size_t *count_decoded) |
| static void | decode_ascii (cgul_exception_t *cex, unsigned char *block_encoded, size_t size_encoded, size_t *index_encoded, cgul_wchar_t *block_decoded, size_t size_decoded, size_t *count_decoded) |
Detailed Description
This class provides the C++ bindings for C cgul_stream_reader objects. The main purpose of this class is to convert the C-style function calls and exception handling in cgul_stream_reader into C++-style function calls and exception handling.
Member Typedef Documentation
§ decode_t
Type definition for decoding characters from blocks of bytes.
- See also
- cgul_stream_reader__decode_t
Constructor & Destructor Documentation
§ cgul_stream_reader_cxx() [1/3]
|
inline |
Create a new cgul_stream_reader_cxx instance that by default uses cgul_stream_reader__decode_utf8 to decode blocks of UTF-8 encoded bytes into a stream of UTF-32 characters. After this method returns, add_block_reader() should be called and set_decoder() may be called before calling read(). The client is responsible for deleting the pointer returned. If an error occurs, an exception is thrown.
References cgul_stream_reader__new().
Referenced by set_obj().
§ cgul_stream_reader_cxx() [2/3]
|
inline |
Create a new cgul_stream_reader_cxx instance that by default uses cgul_stream_reader__decode_utf8 to decode blocks of UTF-8 encoded bytes from the block reader br into a stream of UTF-32 characters. After this method returns, set_decoder() may be called before calling read(). This class does not take ownership of the block reader br so the client is responsible for deleting it when this class is no longer using it. The client is responsible for deleting the pointer returned. If an error occurs, an exception is thrown.
- Parameters
-
[in] br block reader to add
References cgul_block_reader_cxx::as_block_reader(), and cgul_stream_reader__new_from_block_reader().
§ cgul_stream_reader_cxx() [3/3]
|
inline |
Create a new cgul_stream_reader_cxx instance that by default uses cgul_stream_reader__decode_utf8 to decode blocks of UTF-8 encoded bytes from the block reader br into a stream of UTF-32 characters. After this method returns, set_decoder() may be called before calling read(). This class does not take ownership of the block reader br so the client is responsible for deleting it when this class is no longer using it. The client is responsible for deleting the pointer returned. If an error occurs, an exception is thrown.
- Parameters
-
[in] br block reader to add
References cgul_stream_reader__new_from_block_reader().
§ ~cgul_stream_reader_cxx()
|
inlinevirtual |
This method deletes the instance freeing all internally allocated resources. Clients must not attempt to use the instance after this method returns.
References cgul_stream_reader__delete().
Member Function Documentation
§ decode_utf8()
|
inlinestatic |
Simple wrapper for cgul_stream_reader__decode_utf8().
References cgul_stream_reader__decode_utf8().
§ decode_ascii()
|
inlinestatic |
Simple wrapper for cgul_stream_reader__decode_ascii().
References cgul_stream_reader__decode_ascii().
§ reset()
|
inlinevirtual |
Reset the instance so it can be used with a new set of block readers. This clears the end of file (EOF) file, resets the line and column numbers to 1, and clears the queue of block readers.
References cgul_stream_reader__reset().
§ read()
|
inlinevirtual |
Read the next encoded character from the stream and return the result as *next_char provided next_char is not NULL. This methods advances the character stream. If successful, 1 is returned. If the end of file is reached, 0 is returned and *next_char is set to CGUL_WCHAR__NUL. If an error occurs, 0 is returned, *next_char is set to CGUL_WCHAR__NUL, and an exception is thrown.
- Parameters
-
[out] next_char next character
- Returns
- whether the read completed successfully
References cgul_stream_reader__read().
§ eof()
|
inlinevirtual |
Return whether the end of file (EOF) has been reached. Calling reset() with clear the EOF flag. Putting a character back will also clear the EOF flag.
- Returns
- whether the end of file has been reached
References cgul_stream_reader__eof().
§ get_line_and_column_tracking()
|
inlinevirtual |
Return whether line and column number tracking is enabled. By default, line and column number tracking is enabled.
- Returns
- whether line and column number tracking is enabled
References cgul_stream_reader__get_line_and_column_tracking().
§ set_line_and_column_tracking()
|
inlinevirtual |
Set whether line and column number tracking is enabled. By default, line and column number tracking is enabled. Disabling line and column number tracking results in about a 10% performance increase.
- Parameters
-
[in] is_tracking_enabled whether line and column number tracking is enabled
References cgul_stream_reader__set_line_and_column_tracking().
§ get_line_number_current()
|
inlinevirtual |
Return the line number for the current character (i.e., the character that will be returned by the next read()). The line number is 1-based (i.e., the first line is assigned the number 1).
- Note
- If line and column number tracking has been disabled,
0is returned. (See see cgul_stream_reader__set_line_and_column_tracking().)
- Returns
- current line number
References cgul_stream_reader__get_line_number_current().
§ get_column_number_current()
|
inlinevirtual |
Return the column number for the current character (i.e., the character that will be returned by the next read()). The column number is 1-based (i.e., the first column is assigned the number 1).
Even though the column number is 1-based, it is possible for this method to return 0. This indicates that putback() was called with an EOL character which moved the cursor backward to the end of the previous line. Unfortunately, there is no good way to know the number of columns in the previous line, and because the return value is an unsigned size_t, the column numbers cannot be made negative without causing other problems. To this end, this class latches the column number to 0 when retreating past an EOL character. It stays latched until the stream advances past an EOL character.
- Note
- If line and column number tracking has been disabled,
0is returned. (See see cgul_stream_reader__set_line_and_column_tracking().)
- Returns
- current column number or
0
References cgul_stream_reader__get_column_number_current().
§ get_line_number_previous()
|
inlinevirtual |
Return the line number for the previous character (i.e., the character that was returned by the previous call to read()). The line number is 1-based (i.e., the first line is assigned the number 1). If 0 is returned, it means the first character has not yet been read.
In the unlike case that the column number is latched (see comments for get_column_number_previous()), it is more likely that the previous character is on the same line as the current character so the current line is returned.
- Note
- If line and column number tracking has been disabled,
0is returned. (See see cgul_stream_reader__set_line_and_column_tracking().)
- Returns
- current line number
References cgul_stream_reader__get_line_number_previous().
§ get_column_number_previous()
|
inlinevirtual |
Return the column number for the previous character (i.e., the character that was returned by the previous call to cgul_stream_reader__read()) or 0 if no character has been read yet. The column number is 1-based (i.e., the first column is assigned the number 1).
Even though the column number is 1-based, it is possible for this method to return 0. This indicates that the first character has not yet been read or that cgul_stream_read__putback() was called with an EOL character which moved the cursor backward to the end of the previous line. In the latter case, unfortunately there is no good way to know the number of columns in the previous line, and because the return value is an unsigned size_t, the column numbers cannot be made negative without causing other problems. To this end, there is an internal stack of line widths to fill in this missing information, but the stack is limited in size. When the stack is empty, this class latches the column number to 0 when retreating past an EOL character. It stays latched until the stream advances past an EOL character. As a practical matter, this should rarely if ever happen.
- Note
- If line and column number tracking has been disabled,
0is returned. (See see cgul_stream_reader__set_line_and_column_tracking().)
- Returns
- current column number or
0
References cgul_stream_reader__get_column_number_previous().
§ get_normalize_eol()
|
inlinevirtual |
Return whether end-of-line (EOL) character sequences are normalized. If normalization is enabled, "\r" and "\r\n" sequences are normalized to "\n". All other characters pass though without replacement.
- Returns
- whether EOLs are normalized
References cgul_stream_reader__get_normalize_eol().
§ set_normalize_eol()
|
inlinevirtual |
Set whether end-of-line character sequences are normalized. If normalization is enabled, "\r" and "\r\n" sequences are normalized to "\n". All other characters passed though without replacement.
- Parameters
-
[in] normalize whether to normalize EOLs
References cgul_stream_reader__set_normalize_eol().
§ add_block_reader() [1/2]
|
inlinevirtual |
Add the block reader br to the queue of block readers. The block reader must end on an encoded character boundary (i.e., encoded characters must not span across block readers). Characters are streamed from the front block reader on the queue. When end of file is reach for the front block reader, it is removed from the queue, and characters are then streamed from the next block reader in the queue. Once a block reader is added to the queue, it should not be modified externally. If an error occurs, an exception is thrown.
- Parameters
-
[in] br block reader to add
- See also
- cgul_block_reader
- cgul_block_reader_file
- cgul_block_reader_memory
References cgul_block_reader_cxx::as_block_reader(), and cgul_stream_reader__add_block_reader().
§ add_block_reader() [2/2]
|
inlinevirtual |
Set the block reader to br. If br is NULL, the current block reader will no longer be used allowing the client to delete the block reader immediately. Also if br is NULL, the line and column numbers will be reset to indicate the start of a new input stream. This method should be called whenever a new file has been loaded into the block reader so this class will know to discard the unused portion of the final block that it read from the old file.
- Parameters
-
[in] br block reader to add
- See also
- cgul_block_reader
- cgul_block_reader_file
- cgul_block_reader_memory
References cgul_stream_reader__add_block_reader().
§ get_block_size()
|
inlinevirtual |
Return the size of the block used to read from the block reader.
- Returns
- size of block used to read from the block reader
References cgul_stream_reader__get_block_size().
§ set_block_size()
|
inlinevirtual |
Set the block size block_size used to read from the block reader. If a block reader has been added, the block size can only be increased. If the block size is not large enough to decode any character in the input stream, the decoder will throw an exception when read(), peek(), or accept() (or related methods) is called. If successful, 1 is returned; otherwise, 0 is returned. If an error occurs, 0 is returned, and an exception is thrown.
- Parameters
-
[in] block_size block size
- Returns
- whether the block size was set
References cgul_stream_reader__set_block_size().
§ get_decoder()
|
inlinevirtual |
Return the decoder used to decode characters from the block reader.
- Returns
- decoder
- See also
- cgul_stream_reader__decode_t
References cgul_stream_reader__get_decoder().
§ set_decoder()
|
inlinevirtual |
Set the decoder decoder used to decode characters from the block reader.
- Parameters
-
[in] decoder decoder
- See also
- cgul_stream_reader__decode_t
References cgul_stream_reader__set_decoder().
§ get_presentation_name()
|
inlinevirtual |
Return the presentation name for the stream reader. If a presentation name has been explicitly set using set_presentation_name(), it is returned. If no presentation name has been explicitly set and only one block reader has been added, the presentation name for the block reader is returned (and should not be cached by the client). If no presentation name has been explicitly set and more than one block reader has been added, "MULTIPART" is returned. If no block reader has been set, an exception is thrown.
- Returns
- presentation name
References cgul_stream_reader__get_presentation_name().
§ set_presentation_name()
|
inlinevirtual |
Set the presentation name for the stream reader. If an error occurs, an exception is thrown.
- Parameters
-
[in] presentation_name presentation name
References cgul_stream_reader__set_presentation_name().
§ get_obj()
|
inlinevirtual |
Get the underlying cgul_stream_reader object.
- Returns
- underlying object
§ take_obj()
|
inlinevirtual |
Take the underlying cgul_stream_reader object. This means the underlying object will not be deleted when the wrapper goes out of scope. Also, because you have taken the underlying object, no other methods should be called on this wrapper's instance. Lastly, after taking the underlying object, it is the caller's responsibility to delete the underlying object by calling delete().
- Returns
- underlying object
§ set_obj()
|
inlinevirtual |
Set the new underlying object to rhs. This causes the old underlying object to be deleted which invalidates any outstanding pointers to or iterators for the old underlying object.
This instance takes ownership of rhs which means rhs will be automatically deleted when the C++ wrapper is deleted. To prevent automatic deletion of rhs, call take_obj() when the C++ wrapper is no longer needed.
- Parameters
-
[in] rhs right-hand side
References cgul_stream_reader__delete(), and cgul_stream_reader_cxx().
The documentation for this class was generated from the following file:
