A Sliding_String provides methods to manipulate a character stream as if it were a String by backing it with an istream to provide the characters for the String. More...

#include <Sliding_String.hh>

Inheritance diagram for Sliding_String:

[legend]

Collaboration diagram for Sliding_String:

[legend]

List of all members.

Public Types
typedef std::vector < String_Filter * >	Filter_List
	A vector of filters.
typedef unsigned long	Location
	A virtual location in the Sliding_String.
Public Member Functions
char	at (Location location)
	Gets the character at the specified Location in the virual stream.
bool	begins_with (const std::string &pattern, Location location, bool case_sensitive=true)
	Tests if the pattern matches the substring starting at the Location.
Location	end_location () const
	Gets the Location immediately following the last character in the String.
bool	ended () const
	Tests if the end of input has been reached; i\.e\.
void	filter (Index start=0, Index end=String::EOS)
	Applies all of the filters to the current String.
String::Index	index_of (Location location) const
	Gets the Index in the String for the Location in the input stream.
void	insert_filter (String_Filter *filter, Index index=EOS)
	Inserts a String_Filter pointer into the vector of filters that will be applied to the Sliding_String.
bool	is_empty () const
	Tests if there are no more characters at the next Location; the source of characters is effectively empty.
bool	is_end (Location location) const
	Tests if the specified Location is at or beyond the end Location.
Location	location_of (char character, Location location)
	Finds the next Location of the character.
Location	location_of (const std::string &pattern, Location location)
	Finds the next Location of the pattern string.
Location	location_of (Index index) const
	Gets the Location in the character stream of the Index in the String.
String::Index	next_index (Index index)
	Sets the next Location using a String Index value.
String::Index	next_index () const
	Gets the Index in the String of the next Location.
Location	next_location (Location location)
	Sets the next Location to position the String when sliding it forward.
Location	next_location () const
	Gets the current value of the next Location.
String::Index	non_text_limit (Index limit)
	Sets the length of a non-text data sequence that will cause input from the character stream to the the String to stop.
String::Index	non_text_limit () const
	Get the current limit for non-text data input.
Sliding_String &	operator= (const Sliding_String &sliding_string)
Location	read_limit (Location limit)
	Sets the Location where character input is to stop.
Location	read_limit () const
	Gets the current limit where reading characters is to stop; the maximum number of characters to input from the istream.
std::istream &	reader () const
	Gets the istream used as the source of characters.
Sliding_String &	reader (std::istream &reader)
	Sets the istream to use as the source of characters.
bool	reader_source () const
	Tests if the source of characters is an istream.
String::Index	remains (char *buffer=NULL)
	Get the remains of any data read but not appended to the String.
bool	remove_filter (String_Filter *filter=NULL)
	Removes String_Filter pointers from the vector of filters.
String::Index	size_increment () const
	Gets the size increment by which the input buffer will be extended when it is slid forward in the istream's input stream.
String::Index	size_increment (Index amount)
	Sets the size increment by which the String will be extended when it is slid forward in the character stream.
Location	skip_over (const std::string &skip, Location location)
	Skips over a character set in the character stream.
Location	skip_until (const std::string &find, Location location)
	Skips until a member of the character set is found in the character stream.
virtual bool	slide ()
	Slide the string forward by extending it with additional input characters.
	Sliding_String (const std::string &string_source)
	Creates a Sliding_String with a string source of characters.
	Sliding_String (std::istream &reader, Location limit=NO_LIMIT)
	Creates a Sliding_String with the reader as the source of characters up to the specified limit.
	Sliding_String (const Sliding_String &sliding_string)
	Creates a copy of a Sliding_String.
	Sliding_String ()
	Creates a Sliding_String with no character source.
Location	string_location () const
	Gets the current Location of the beginning of the String in the character stream.
bool	string_source () const
	Tests if the source of characters is a string; i.e.
String	substr (Location start, Location length)
	Gets the substring including the length number of characters from the start Location.
String	substring (Location start, Location end)
	Gets the substring including the characters from the start Location up to, but not including, the end Location in the character stream.
Location	total_read () const
	Gets the total number of characters read so far.
virtual	~Sliding_String ()
	Deletes the current Data_Buffer before destroying the object.
Static Public Member Functions
static bool	is_text (char character)
	Tests if a character is considered to be text.
Static Public Attributes
static const String::Index	DEFAULT_NON_TEXT_LIMIT
	The default limit on non-text data.
static const Location	DEFAULT_READ_LIMIT
	The default limit on the number of characters to read.
static const String::Index	DEFAULT_SIZE_INCREMENT
	The default String extension increment.
static const char *const	ID
	Class identification.
static const char	INVALID_CHARACTER
	A character that should not occur in any valid string.
static const Location	NO_LIMIT
	The value when no limit is to be applied, or no location was found.
Protected Member Functions
void	data_buffer_size (Index size)
	Reallocate the Data_Buffer with a new size.
bool	data_ingest ()
	Ingest the contents of the Data_Buffer into the String.
Protected Attributes
String::Index	Data_Amount
	The number of valid data bytes in the Data_Buffer.
char *	Data_Buffer
	Input Data Buffer.
String::Index	Data_Buffer_Size
	The size of the Data_Buffer (bytes).
Location	Next_Location
	Location of the next statement.
String::Index	Non_Text_Count
	The number of sequential non-text characters last read.
String::Index	Non_Text_Limit
	The number of non-text chars that will end data input.
Location	Read_Limit
	The maximum amount (bytes) to read from the input stream.
std::istream *	Reader
	An istream source of characters.
String::Index	Size_Increment
	The amount to read when sliding the String forward.
Location	String_Location
	Location of the first character in the buffer.
Location	Total_Read
	The total amount read.

Detailed Description

A Sliding_String provides methods to manipulate a character stream as if it were a String by backing it with an istream to provide the characters for the String.

The intended use is to consume the character stream, in a semi-sequential manner, processing statements as they are encountered by moving along the stream from statement to statement. A statement is composed of a contiguous sequence of characters of variable length.

The character stream may be sourced from an istream or a string. A string source is a convenience that allows a string to be used transparently in the same context where an istream might also be used, but instead a "pre-read" source of characters is provided directly (a istringstream could also be used).

For an istream source the character stream is read into a String that may slide along the stream: the end of the String may be extended by reading increments of more characters from the stream, and the beginning of the String may have characters removed ("consumed"). The stream's character contents are referenced by virtual Location values that act as indexes into the entire character stream; the first character of the stream is at Location 0. The String is automatically extended to contain characters from any Location available in the input stream.

To avoid a large number of read operations on the input stream, the String is always extended by a specified size_increment. In addition, a read_limit may be specified to force input termination at any Location in the character stream. Input may also be terminated when a threshold of non-text bytes (a specified sequential limit) occurs in the stream, as would typically be found after the initial label area of an image file.

When statements from the character stream have been processed and are no longer needed the next_location is updated. That part of the character stream in the String before the next_location is considered to be disposable so that the next time the String needs to be extended to a new stream Location the portion of the String containing characters from before the next_location are deleted, which slides the String forward. Thus instead of simply extending indefinitely, the String is reused by moving the contents to cover the section of the character stream being processed and removing contents no longer needed. In this way character streams of indefinite length may be processed using a relatively small String size.

Modifications may be made to the contents of the String using any of the String/string methods. When the String needs to be extended, because a reference is made to a Location beyond the end of the current String contents, input characters are always appended to the end of the existing String contents regardless of changes that have been made that might have altered the number of characters it contains. However, the next_location will not change unless specifically updated by the user, and all characters before the next_location will be deleted whenever the String contents are slid forward, so characters before the next_location should be considered consumed. Thus the Sliding_String effectively offers String access to all characters obtained from the istream at the next_location and extending on. If the next_location is never moved forward (it can be moved backwards, but not before the current string_location) then all characters from the istream are always available (this is always the case for a string source of characters), but sliding the String forward past consumed statements is what provides efficient use of String storage for indefinately long input streams.

Note: Those Sliding_String methods which search forward for character patterns will extend the String to the end of input if the pattern is not found. To avoid unnecessarily large String extensions the read_limit can be set to some location downstream that the application considers to be beyond where the pattern could reasonably be found.

When the character source is a string, nothing is ever read. Nevertheless, the contents of the String may still be appended with additional characters and the next_location may still be moved forward. When buffer manipulation methods attempt to extend the String, it will still be slid forward by deleting characters before the next_location. In this case virtual Location values may be thought of as the number of charaters consumed (slid over) plus the number of characters in the String.

A special feature of the Sliding_String is its ability to apply filters to the data used to extend the string. Filtering objects that implement the String_Filter interface may be inserted in any order and selectively removed. All currently registered filters will be applied automatically to the new data after each slide. N.B.: Filtering will only be applied when the source of characters is an istream.

See also:: String; String_Filter

Author:: Bradford Castalia

Version:: 1.18

Member Typedef Documentation

typedef unsigned long Location

A virtual location in the Sliding_String.

typedef std::vector<String_Filter*> Filter_List

A vector of filters.

Constructor & Destructor Documentation

Sliding_String ( )

Creates a Sliding_String with no character source.

See also:: reader(std::istream&)

Sliding_String	(	std::istream &	reader,
		Location	limit = `NO_LIMIT`
	)

Creates a Sliding_String with the reader as the source of characters up to the specified limit.

Parameters:

reader	The istream to use as the source of input.
limit	The maximum number of character bytes to read.

See also:: read_limit(Location)

Sliding_String ( const std::string & string_source ) [explicit]

Creates a Sliding_String with a string source of characters.

Parameters:

string_source The string to use as the source of input.

Sliding_String ( const Sliding_String & sliding_string )

Creates a copy of a Sliding_String.

State is preserved, including a copy of the current String and the contents of the internal Data_Buffer, and the Reader is shared.

virtual ~Sliding_String ( ) [virtual]

Deletes the current Data_Buffer before destroying the object.

Member Function Documentation

Sliding_String& operator= ( const Sliding_String & sliding_string )

Sliding_String& reader ( std::istream & reader )

Sets the istream to use as the source of characters.

Changing the istream in mid stream may have unexpected side effects. Any data still being held in the internal buffer pending further processing before transfer to the String will be dropped. The total_read will not be reset by a change of istream; i.e. a single virtual character input stream is seen.

Parameters:

reader The reader to associate with this object. If it is the same as the current reader then no change is made (the current Data_Buffer is not emptied).

Returns:: This Sliding_String.

std::istream& reader ( ) const [inline]

Gets the istream used as the source of characters.

Returns:: The istream associated with this object; will be NULL if the object currently has no istream (e.g. it was created with a string character source).

See also:: reader(std::istream&)

References Sliding_String::Reader.

bool reader_source ( ) const [inline]

Tests if the source of characters is an istream.

Returns:: true if the source of characters is an istream.

References Sliding_String::Reader.

bool string_source ( ) const [inline]

Tests if the source of characters is a string; i.e.

there is no istream.

Returns:: true if the source of characters is a string.

References Sliding_String::Reader.

Referenced by Sliding_String::ended().

Location location_of ( Index index ) const [inline]

Gets the Location in the character stream of the Index in the String.

Location values must be used when accessing the contents of the virtual String using Sliding_String methods.

Location values are virtual with respect to the entire character input stream. Location 0 corresponds to the first character that was placed in the virtual String. If the number of characters in the String is only changed when it is slid forward, then Location values are relative to all characters in the input stream. However, since the number of characters in the String may be changed by String/string methods, Location values are actually relative to all characters that the buffer has slid over (been consumed) plus the current contents of the buffer; i.e. the virtual character stream. Changing the contents of the String may change the Location of characters in the String, and the effective Location of characters yet to be read into the String: Location values are relative to the current Location of the first character in the String.

Parameters:

index A String Index value.

Returns:: The corresponding character stream Location. The location of the special index value EOS is NO_LIMIT.

References String::EOS, Sliding_String::NO_LIMIT, and Sliding_String::String_Location.

Referenced by Sliding_String::next_index().

String::Index index_of ( Location location ) const [inline]

Gets the Index in the String for the Location in the input stream.

Index values are relative to the current contents of the String; Index 0 corresponds to the character currently at the beginning of the String. Index values must be used when using String methods.

Note: Location values are long; Index values are int.

Parameters:

location A Location in the input stream.

Returns:: The corresponding buffer Index relative to the current Location of the beginning of the buffer in the input stream. The location of the special location value NO_LIMIT is EOS.

References String::EOS, Sliding_String::NO_LIMIT, and Sliding_String::String_Location.

Referenced by Sliding_String::next_index().

Location string_location ( ) const [inline]

Gets the current Location of the beginning of the String in the character stream.

Returns:: The Location of the first character in the String.

References Sliding_String::String_Location.

Location next_location ( Location location )

Sets the next Location to position the String when sliding it forward.

If the Location is beyond the end of the current String contents the String is slid forward to include the Location, if possible.

Parameters:

location The next Location to use for the beginning of the String when the String is slid forward.

Returns:: The new value of the next Location. The only case where this will be different from the specified Location is when the end of input has been reached before the specified Location could be reached; in which case the return value is the final end Location.

Exceptions:

out_of_range If the Location is before the beginning of the String.

See also:: slide(); end_location()

Location next_location ( ) const [inline]

Gets the current value of the next Location.

Returns:: The current value of the next Location.

See also:: next_location(Location)

References Sliding_String::Next_Location.

Referenced by Sliding_String::next_index().

String::Index next_index ( Index index ) [inline]

Sets the next Location using a String Index value.

Parameters:

index The String Index value for the next Location.

Returns:: The Index value of the new next Location.

See also:: next_location(Location)

References Sliding_String::index_of(), Sliding_String::location_of(), and Sliding_String::next_location().

String::Index next_index ( ) const [inline]

Gets the Index in the String of the next Location.

Returns:: The Index in the String of the next Location.

See also:: next_location()

References Sliding_String::Next_Location, and Sliding_String::String_Location.

Location end_location ( ) const [inline]

Gets the Location immediately following the last character in the String.

Returns:: The Location immediately following the last character in the String.

References Sliding_String::String_Location.

Referenced by Sliding_String::is_empty(), and Sliding_String::is_end().

Location read_limit ( Location limit )

Sets the Location where character input is to stop.

This is the maximum number of characters to read from the reader.

If the limit is 0, then input stops immediately. Use the value NO_LIMIT to allow for unlimited input. Initially the read limit is set to the DEFAULT_READ_LIMIT.

Note: The read limit is reset to the total number of characters read if an istream encounters the end of the input stream.

Note: The read limit will have no effect when the character source is a string. In this case nothing is ever read so the read limit is identical to the string size.

Note: When the threshold for sequential non-text data has been reached while sliding the buffer, then the read limit is automatically set to the number of characters read before the non-text sequence. Once this condition has been encountered, the read limit can not be changed without first resetting the non_text_limit threshold up to a higher value.

This class was designed for use with the PVL Parser (which is a subclass) for processing PVL syntax statements. For example, the read limit sets the maximum initial amount of a file to read when parsing an image file label. Without a recognizable end-of-label marker it is quite possible for non-label file data to be interpreted as PVL statements. Thus it is advisable to set a reasonable limit on the amount of file data to read. It is typical for a PVL label to contain as one of its parameters the size of the label. This suggests a strategy of using a reasonably small limit (enough to ensure that the label size parameter, usually near the start of the PVL statements, will be read), finding this parameter, rewinding the file, and ingesting the PVL statements again using the parameter value as the limiting value. A less "intelligent" (but likely to be easier) approach is to use the default limit and simply check the validity of parameters, since applications are likely to know what parameters are valid for them.

Parameters:

limit The Location where character input is to stop.

Returns:: The previous limit.

See also:: non_text_limit(Index)

Location read_limit ( ) const [inline]

Gets the current limit where reading characters is to stop; the maximum number of characters to input from the istream.

This will be NO_LIMIT if there is no limit to the number of characters to read from the character stream.

Returns:: The current read limit.

See also:: read_limit(Location)

References Sliding_String::Read_Limit.

Location total_read ( ) const [inline]

Gets the total number of characters read so far.

This value is the actual number of characters input from the istream regardless of any subsequent use of the data.

Returns:: The total number of characters read.

References Sliding_String::Total_Read.

bool ended ( ) const [inline]

Tests if the end of input has been reached; i\.e\.

if there are any more characters to be read.

The end of input occurs when the read limit has been reached. When the input source is a string, then it has always ended (i.e. there is nothing to read).

Returns:: true if the character source has ended.

See also:: read_limit(Location)

References Sliding_String::NO_LIMIT, Sliding_String::Read_Limit, Sliding_String::string_source(), and Sliding_String::Total_Read.

Referenced by Sliding_String::is_empty().

bool is_empty ( ) const [inline]

Tests if there are no more characters at the next Location; the source of characters is effectively empty.

There will be no more characters at the next Location if the input has ended and the next Location is at, or beyond, the end Location.

Returns:: true if there are no more characters available.

See also:: next_location(); ended(); end_location()

References Sliding_String::end_location(), Sliding_String::ended(), and Sliding_String::Next_Location.

bool is_end ( Location location ) const [inline]

Tests if the specified Location is at or beyond the end Location.

N.B.: Unlike ended, is_end only indicates that the Location is beyond the current String contents. There may still be more characters available.

Parameters:

location The Location to test.

Returns:: true if the Location is at or beyond the end_location.

See also:: end_location()

References Sliding_String::end_location().

String::Index size_increment ( Index amount )

Sets the size increment by which the String will be extended when it is slid forward in the character stream.

If the amount is less than or equal to 0, then the DEFAULT_SIZE_INCREMENT will be applied. If the amount is less than or equal to the non_text_limit threshold, then it will be increased by that amount. If the current internal buffer array contains more pending input data that the size increment, then it will be set to the amount of data being held. If the new size increment is different from the length of the current internal buffer, then a new buffer will be allocated and any pending input data in the old buffer will be copied into it.

Parameters:

amount The new size increment.

Returns:: The previous size_increment.

See also:: non_text_limit(Index)

String::Index size_increment ( ) const [inline]

Gets the size increment by which the input buffer will be extended when it is slid forward in the istream's input stream.

Returns:: The current size increment.

See also:: size_increment(Index)

References Sliding_String::Size_Increment.

String::Index non_text_limit ( Index limit )

Sets the length of a non-text data sequence that will cause input from the character stream to the the String to stop.

Text characters are recognized by the is_text method; characters that fail this test are non-text.

Since this class is managing a String, it is assumed that non-text data from the input should not be transferred into the buffer; i.e. the data are not valid String characters. However, to allow for possible input filter requirements (e.g. binary record size values), a sequence of non-text data less than the limit is allowed into the String. When a sequence of non-text data in the input stream reaches the limit the read_limit is set to the amount read up to, but not including, the sequence of non-text data. A limit of 0 has the same effect as a limit of 1; i.e. no non-text data are acceptable. Checking for non-text data is disabled by specifing NO_LIMIT; i.e. any non-text data is acceptable.

Note: No sequence of non-text data as long as the limit amount is allowed into the String; shorter sequences are allowed to pass. And since the read_limit is set to the Location in the input stream immediately preceeding a limiting non-text sequence, the String will not be slid forward beyond this Location. However, the non_text_limit may subsequently be increased and the read_limit lifted (in that order; the read_limit can not be changed while a non_text_limit block is in effect) to allow further processing of the input stream (data read from the istream but not transferred to the String is never lost). Nevertheless, any non-text data sequence outstanding will remain in effect and will be included in counting the length of the next non-text sequence; the non-text sequence length is only reset to 0 when a text character is seen in the input stream.

Warning: The non_text_limit may affect the operation of an input filter. The input filter provided with this class requires a non_text_limit of a least 4.

Parameters:

limit The maximum allowed sequence of non-text input data.

Returns:: The previous non-text limit.

See also:: is_text(char); read_limit(Location)

String::Index non_text_limit ( ) const [inline]

Get the current limit for non-text data input.

Returns:: The non-text data limit.

See also:: non_text_limit(Index)

References Sliding_String::Non_Text_Limit.

static bool is_text ( char character ) [inline, static]

Tests if a character is considered to be text.

Text is evaluated against the ASCII code set and includes all printable characters - values from 0x20 (' ') to 0x7E ('~') inclusive - plus the usual format control characters - HT, LF, VT, FF, and CR (0x9 to 0xD inclusive).

Parameters:

character The character to be tested.

Returns:: true if the character is text; false otherwise.

char at ( Location location )

Gets the character at the specified Location in the virual stream.

The current contents of the character buffer will be automatically slid forward to the specified Location.

Parameters:

location The Location from which to get a character.

Returns:: The char found at the location. If the location is invalid for any reason then the INVALID_CHARACTER is returned.

String substring	(	Location	start,
		Location	end
	)

Gets the substring including the characters from the start Location up to, but not including, the end Location in the character stream.

The current contents of the String will be automatically slid forward to include the specified Locations. If the substring extends beyond the end of input Location, then that portion up to the end of input will be returned. If both start and end Locations are beyond the end of input, then an empty String will be returned.

Parameters:

start	The Location of the first character of the substring.
end	The Location of end of the substring (the Location immediately following the last character in the substring).

Returns:: The String from the start Location, inclusive, to the end Location, exclusive.

String substr	(	Location	start,
		Location	length
	)

Gets the substring including the length number of characters from the start Location.

The current contents of the String will be automatically slid forward to include the specified substring. If the substring extends beyond the end of input Location, then that portion up to the end of input will be returned. If both start and end Locations are beyond the end of input, then an empty String will be returned.

Parameters:

start	The Location of the first character of the substring.
length	The length of the substring.

Returns:: The String from the start Location for length characters.

Location skip_over	(	const std::string &	skip,
		Location	location
	)

Skips over a character set in the character stream.

Starting at the specified Location find the Location of the next character that is not in the skip string. The skip string is not a pattern; i.e. a character in the character stream that matches any character in the skip string is skipped during the search. The return Location will be for a character that does not occur in the skip string.

The String will be slid forward until a non-skip character is found. N.B.: The String will be extended to include all available input if all characters from the beginning Location on are in the skip String.

Parameters:

skip	The string containing characters to be skipped.
location	The Location from which to start the search.

Returns:: The Location of the next character not in the skip string. This will be NO_LIMIT if the end of input data is reached (i.e. all characters from the start Location on are in the skip string).

Location skip_until	(	const std::string &	find,
		Location	location
	)

Skips until a member of the character set is found in the character stream.

Starting at the specified Location find the Location of the next character that is in the find string. The find string is not a pattern; i.e. a character in the string that matches any character in the find string satisfies the search. The return Location will be for a character that occurs in the find string.

The character buffer will be slid forward until a find character is found. N.B.: The character buffer will be extended to include all available input if all characters from the beginning Location on are not in the find string.

Parameters:

find	The string containing characters to be found.
location	The Location from which to start the search.

Returns:: The Location of the next character also in the find string. If the end of input data is reached (i.e. all characters from the start Location on are not in the find string), then NO_LIMIT is returned.

Location location_of	(	const std::string &	pattern,
		Location	location
	)

Finds the next Location of the pattern string.

Starting at the specified Location find the Location of the next occurance of the substring that matches the pattern string.

The character buffer will be slid forward until the pattern substring is found. N.B.: The character buffer will be extended to include all available input if the pattern can not be found.

Parameters:

pattern	The string to be found.
location	The Location from which to start the search.

Returns:: The Location of the beginning of the pattern substring. If the end of input data is reached without finding the pattern string, then NO_LIMIT is returned.

Location location_of	(	char	character,
		Location	location
	)

Finds the next Location of the character.

Starting at the specified Location find the next Location of the specified character.

The String will be slid forward until the specified character is found. N.B.: The String will be extended to include all available input if the character can not be found.

Parameters:

character	The character to be found.
location	The Location from which to start the search.

Returns:: The Location of the next occurance of the character. If the end of input data is reached without finding the character, then NO_LIMIT is returned.

bool begins_with	(	const std::string &	pattern,
		Location	location,
		bool	case_sensitive = `true`
	)

Tests if the pattern matches the substring starting at the Location.

The String will be slid forward as needed to include a substring starting at the specified Location that is as long as the pattern String.

Parameters:

pattern	The string to compare against the substring.
location	The location of the substring to compare.
case_sensitive	Case sensitive match?

Returns:: true if the substring equals the pattern string; false otherwise.

virtual bool slide ( ) [virtual]

Slide the string forward by extending it with additional input characters.

The procedure to slide the buffer has several steps:

Slide the buffer forward.: If the next_location is beyond the string_location then the consumed contents of the buffer - i.e. from the beginning up to, but not including, the next_index - are deleted.
Check for end of input.: The end of input occurs when the end of the istream's data stream has been reached, or the amount of input has reached the read_limit. When this object was constructed from a string the end of input has been reached by definition. When the end of input has been reached the buffer can not be slid so the method returns false.
Determine how much to slide the buffer forward.: The buffer will be extended by the lesser of the amount of free space in the internal character array or the amount from the current total_read up to the read_limit. Of course, if there is no read limit then the former is always used. The internal character array, where characters read from the istream are stored for checking before being transferred to the object's buffer, has a length of size_increment. However, during each read cycle less than the entire character array contents may be transferred to the buffer; the remainder is carried over in the array where new input data is added in the next read cycle. Thus the buffer will be extended by no more than size_increment characters.
Read characters.: Characters are read from the istream into an internal character array. Here they may be scanned for non-text data before being appended to the object's character buffer.
Check for non-text data.: Characters read into the internal storage array may be scanned for a sequence of non-text data of the current maximum length. This check is only done if the non_text_limit length is non-negative. Counting of sequential non-text data is continuous across buffer extensions and is only reset to zero when a text character is found. If a non-text sequence of non_text_limit length is found, then only the data preceeding the sequence is appended to the object's character buffer and the read_limit is reset to the corresponding position in the data stream. Shorter sequences of non-text data at the end of scanned input are also omitted from the transfer to the buffer, against the possibility of more non-text data from the next read, but the read_limit is not changed. Data not transferred to the buffer is retained in the internal array where it is added to in the next read cycle.
Transfer characters to the buffer.: The data in the character array, from the beginning up to but not including any trailing non-text data (if non-text data checking is enabled), is appended to the object's character buffer.
Filter the new characters.: If input filtering is enabled, the filter method is invoked on the new characters.

N.B.: Altering the istream's input position in the character stream may have have unpredictable consequences. The impact on the operation of the filter_string method in particular could be fatal. Without input filtering, however, it is quite possible to move the istream's input position (e.g. by read, ignore or seekg operations) to suit application needs. It is important to keep in mind that any such alterations will go undetected, and the value of the total_read and source stream Locations will continue to indicate the amount of data actually read and consumed from a virtually sequential input stream.

Returns:: true if more input is available; false if the end of input was reached.

Exceptions:

std::ios_base::failure If the read method of the istream failed.

See also:: next_location(Location); string_location(); next_index(); ended(); read_limit(Location); total_read(); size_increment(Index); is_text(char); non_text_limit(Index); filter(Index, Index)

String::Index remains ( char * buffer = NULL )

Get the remains of any data read but not appended to the String.

This data will be the currently outstanding non-text data sequence read from the input stream. It will never be longer than Non-Text_Limit bytes.

When a Non_Text_Limit sequence of non-text data is encountered in the input stream, thus ending input, an attempt is made to reposition the input stream back to the first non-text datum. However, limitations of the input stream may prevent all or part of this push back. This method may be used by the application to retieve the remaining non-text data.

The data may be transferred to a specified char buffer, but it it is not removed from the internal buffer.

Parameters:

buffer A pointer to char storage. This storage must be large enough to hold all the remaining data, which will never be more than Non_Text_Limit bytes. If this argument is not present, no data is transferred.

Returns:: The number of remaining data bytes. This will be the number of bytes transferred if a buffer is specified.

void data_buffer_size ( Index size ) [protected]

Reallocate the Data_Buffer with a new size.

Parameters:

size	The new buffer size.

bool data_ingest ( ) [protected]

Ingest the contents of the Data_Buffer into the String.

void insert_filter	(	String_Filter *	filter,
		Index	index = `EOS`
	)

Inserts a String_Filter pointer into the vector of filters that will be applied to the Sliding_String.

A String_Filter is an abstract class that provides an interface used to filter the String contents during each slide forward.

Parameters:

filter	A String_Filter pointer.
index	The vector element location for the filter. Index 0 is the first filter, index -1 is the last filter. If the index is beyond the end of the list, the filter will be added to the end of the list. The default is to add the filter at the end of the list.

See also:: String_Filter

bool remove_filter ( String_Filter * filter = NULL )

Removes String_Filter pointers from the vector of filters.

Parameters:

filter A pointer to the filter to be removed. If the pointer is NULL (the default) all filters are removed.

Returns:: true if one or more filters were removed; false otherwise.

void filter	(	Index	start = `0`,
		Index	end = `String::EOS`
	)

Applies all of the filters to the current String.

Member Data Documentation

const char* const ID [static]

Class identification.

Reimplemented from String.

const Location NO_LIMIT [static]

The value when no limit is to be applied, or no location was found.

Referenced by Sliding_String::ended(), Sliding_String::index_of(), and Sliding_String::location_of().

const Location DEFAULT_READ_LIMIT [static]

The default limit on the number of characters to read.

const String::Index DEFAULT_SIZE_INCREMENT [static]

The default String extension increment.

const String::Index DEFAULT_NON_TEXT_LIMIT [static]

The default limit on non-text data.

const char INVALID_CHARACTER [static]

A character that should not occur in any valid string.

std::istream* Reader [protected]

An istream source of characters.

This will remain NULL if the source is a string.

Referenced by Sliding_String::reader(), Sliding_String::reader_source(), and Sliding_String::string_source().

char* Data_Buffer [protected]

Input Data Buffer.

The Data_Buffer holds the raw data input from the Reader. The data bytes are scanned for non-text data before being appended to the String base class.

String::Index Data_Buffer_Size [protected]

The size of the Data_Buffer (bytes).

String::Index Data_Amount [protected]

The number of valid data bytes in the Data_Buffer.

String::Index Size_Increment [protected]

The amount to read when sliding the String forward.

Referenced by Sliding_String::size_increment().

Location String_Location [protected]

Location of the first character in the buffer.

Referenced by Sliding_String::end_location(), Sliding_String::index_of(), Sliding_String::location_of(), Sliding_String::next_index(), and Sliding_String::string_location().