com.nexusalpha.utility.io.stream
Class InputStreamParser

java.lang.Object
  extended bycom.nexusalpha.utility.io.stream.InputStreamParser

public class InputStreamParser
extends java.lang.Object

For parsing input streams and feeding the results into output streams, arrays or strings. Author: Tom de Havas
Approval: Chris Best or Ryan Baldwin
Circulation: NAL Only

General Information

Recent Changes

The addition of readPositionStore() and readPositionRestore() methods allow for re-parsing a stream.

The addition of the 'compareAbbreveatedNextByteSequence' provides significant support for situations where byte sequences in an incoming stream can be abbreviated such as an enquiry from and SMS phone. E.g. Roch instead of rochester.

Case insensitivity has now been added. This is off by default but can be switched on and off via two methods. It effects all methods that compare bytes.

getLengthOfRead provides an indication of the number of bytes read so far.

The "match" methods have been depreciated to be replaced by the "compareNext" methods which do the same job but are a little more flexable. They return -1 when no match is found. The "match" methods used to throw an InputStreamParserException. This is now reserved for buffer overflows only.

You can now determine the buffer size in the constructor. It used to be 1024 by default. Pass in 10 to get a buffer of 1024.

There were a couple of methods that broke the naming conventions, these have been renamed.

There are methods to detect an end of stream before it happens, these should now be used rather than allowing an EOFException to be thrown. When match methods

Description

If you have an input stream and need to process the bytes coming in then this class provides the support you need. This class is ideal for extracting data from an input stream. The extracted data can be provided in byte arrays or or fed to any output stream or provided as strings. It can be used simply to extract bytes between two given delemiters, read simple record formats or it can serve to interpret far more complex syntaxes. Often you will be looking for a certain byte sequence or byte or reading to some other byte sequence or byte. Perhaps looking for one of a number of possible byte sequences. Bytes or byte sequences can be passed in as chars or strings making it very simple. This class provides you with an easy to use and very comprehensive set of methods that allow you to intelligently handle an incoming stream. You can use this class to extract data from almost any format you care to mention.

Look at InputStreamParserTests.java to see examples of the use of this class.

No provision is made in this class for going backwards on a stream, there is no 'seek' or push back operation as yet but it is intended to add such facilities at a later date.

Features

  • Highly orthogonal method set.
  • Methods optimised for both complex and simple cases.

  • Typical Applications

  • Extracting data from a communication stream or redirecting it
  • Extracting string between given delemiters e.g. [connect 2400]
  • Extracting a value for a given field e.g. [User]="Jimbo Bimbo"
  • Recieving data from radio transmissions where a stream of data might be interupted
  • Redirecting streams to appropriate handlers based on content
  • Simple extraction of data send between given bytes or byte sequences
  • Directing action to be taken based on recieved byte sequences
  • Simple reading of comma seperated variable files
  • Reading most formats of file or data stream

  • Functionality

    parse.ignoreUntilByte() parse.ignoreUntilByteSequence() parse.ignoreWhileByte() parse.ignoreWhileNotByte() parse.compareNextByte() parse.compareNextByteSequence() parse.compareAbbreviatedNextByteSequence() parse.takeUntilByte() parse.takeUntilByteSequence() parse.takeUntilEndOfStream() parse.takeWhileByte() parse.takeWhileNotByte() parse.takeLength() parse.ignoreLength() parse.stringUntilByte() parse.stringUntilByteSequence() parse.stringWhileByte() parse.stringWhileNotByte() parse.stringLength() parse.readByte()

    Primary methods can be divided into 'Take', 'Ignore' and 'Compare' methods. All the 'take' methods are mirrored by 'string' methods that do the same thing but rather then putting the results into an array or a stream. The results are returned as a string.

  • 'Take' methods, take bytes while or until a contition is met, putting them into the given array or stream.
  • 'String' methods, take bytes while or until a contition is met, returning them as a string.
  • 'Ignore' methods, ignore/skip bytes while or until a condition is met.
  • 'Compare' methods, skip bytes provided they match one of a number of given byte sequences or byte sets.
  • The conditions to be met are typically those below but readers should look at the comments for each method to fully appreciate what that method can do.

    Byte sequences or single bytes can be passed in as strings and chars if prefered, in all the conditions below. It is often more useful that way.

  • 'UntilByteSequence' will read or ignore bytes until (up to) one of a number of given byte sequences. The recognised byte sequence is discarded.
  • 'UntilByte' will read or ignore bytes until (up to) one of a number of given byte values.
  • 'UntilEndOfStream' will read bytes until end of file. There is no ignoreUntilEndOfStream
  • 'WhileByte' will read or ignore bytes while they are one of a number of given byte values.
  • 'WhileNotByte' will read or ignore bytes while they are NOT one of a number of given byte values.
  • 'Length' will read or ignore some length of bytes
  • NOTE: Where a number of possible bytes or byte sequences are passed into a method in an array for matching or as part of the 'Until' condition then the index of the one used is returned. The index returned can be used in the original array to find the byte or byte sequence or can be used in a switch statement. -1 is returned if no match was found.

    NOTE: All 'Until' methods dispose of the byte or sequence when they find it e.g. takeUntilByte will return having thrown away the byte it was able to match.

    Protocol

    Once the constructor has been called and a input stream reference passed in then any other method may be called at any point. The constructor also takes a parameter powerOfTwoBufferSize this will allow the parser to have a buffer of size 2 to the power of the number passed in. Thus if you pass in 8 you will get a buffer of 256. You should not do anything that would return a string larger then 255 characters on any string method. Also you must not look for any byte sequence longer than 255 characters or the buffer will overflow. If you need a bigger buffer, pass in a bigger number! Three exceptions can be thrown. InputStreamParserException - This is thrown when there is an irrecoverable error in the operation of the Input Stream Parser. Usually a buffer overflow. EOFException - This is thrown by this class when an end of stream is reached unexpectedly normally the compareNextEndOfStream methode can be used to avoid this. IOException - is passed straight through. There is currently no provision for any kind of time out. The user must therfore time out on their own thread if they are concerned about this.


    Reliability


    Testing

    See the test class.

    Internal Failure Effects

    There are no known internal falures.

    External Failure Immunity

    Supplying incorrect parameter values will usually lead to an exception sooner or later. Direct accessing the stream passed into InputStreamParser WILL cause problems. InputStreamParser has its own internal buffer so you will lose characters by bypassing it. Also EndOfStream on the stream is not necessarily the same as EndOfStream on the InputStreamParser. This is of corse to the buffering of characters.

  • where an array is passed in, in a take method, if it does not contain sufficient space an exception will be thrown.
  • where an sequence was not found or matched an exception will be thrown.

  • Application


    Warnings

    If you mess with the input stream outside of this object it may cause problems, as the object may buffer bytes read from the stream, from time to time. These bytes will be read in when the next method is called and will disrupt the stream.

    If you are expecting one of say 6000 possible byte sequences held in a database, it would not be a good idea to create an array of these and pass them into one of this classes methods. Although it could be done, ask yourself whether you could not, with the addition of a delemiter, read the sequence until the delemiter and then allow the database to do the comparison work.

    Be aware that the 'UntilByteSequence' and 'UntilByte' will throw away the terminating sequence or terminating byte when they find it. If you want to do 'UntilByte' but preserve the terminating byte in the stream then use a 'WhileNot' method instead. When a 'WhileNot' method finds a terminating byte it leaves it in the stream.

    When using this on top of an InputStream you may need to provide some sort of timeout or it can wait forever.

    If you have a couple of sequences you are looking for then the methods will always look through trying to match the sequences provided in the order they were provided. e.g. 'CATERPILLAR' 'CAT' will return which ever is first in the UntilByteSequence array when the word 'CATERPILLER' is in the stream.


    Efficiency

    Currently this class has not been optimised for efficiency. Where you pass in a single terminating sequence it simply puts it into the first eliment of an array of terminating sequences and calls the method that handles multiple terminating sequences. This is not a huge overhead and will be improved in the future.

    Application Examples


    Reading CSV, HTTP and XML files

    An example of XML, HTTP and CSV parsing is given in 'InputStreamParserTests.java' There is also a file of test data for it to read.


    Constructor Summary
    InputStreamParser(java.io.InputStream stream, int powerOfTwoBufferSize)
              Constructor
     
    Method Summary
     int[] compareAbbreviatedNextByteSequence(byte[][] matchSequence, byte[] abbreviators, boolean ClearMatch)
               
     int[] compareAbbreviatedNextByteSequence(byte[] matchSequence, byte[] abbreviators, boolean ClearMatch)
              See first method of this name for comments
     int[] compareAbbreviatedNextByteSequence(java.lang.String[] matchSequence, java.lang.String abbreviators, boolean ClearMatch)
              See first method of this name for comments
     int[] compareAbbreviatedNextByteSequence(java.lang.String matchSequence, java.lang.String abbreviators, boolean ClearMatch)
              Looks ahead into the stream to see if the first bytes in the stream can be identified as an abbreviation for or full match for one of the given byte sequences.
     int compareNextByte(byte[] matchByte, boolean ClearMatch)
              See first method of this name for comments
     int compareNextByte(byte compareNextByte, boolean ClearMatch)
              See first method of this name for comments
     int compareNextByte(char compareNextByte, boolean ClearMatch)
              Looks ahead into the stream to see if the first byte in the stream will match one of the given bytes or a single given byte.
     int compareNextByte(java.lang.String compareNextByte, boolean ClearMatch)
              See first method of this name for comments
     int compareNextByteSequence(byte[][] matchSequence, boolean ClearMatch)
               
     int compareNextByteSequence(byte[] compareNextByteSequence, boolean ClearMatch)
              See first method of this name for comments
     int compareNextByteSequence(java.lang.String[] compareNextByteSequence, boolean ClearMatch)
              See first method of this name for comments
     int compareNextByteSequence(java.lang.String compareNextByteSequence, boolean ClearMatch)
              Looks ahead into the stream to see if the first bytes in the stream will match one of the given byte sequences or a single given byte sequence.
     boolean compareNextEndOfStream()
              Looks ahead into the stream to see if we are at the end of the stream.
     int getReadLength()
              This method will return the number of bytes that have been read.
     int getTakenLength()
              Where one of the 'take' methods of this class has been called, this method will return the number of bytes that were taken.
     int getWhichByteOrSequence()
              Where 'match' or 'until' methods were called.
     void ignoreLength(int ignoreLength)
              Ignores the given number bytes from a stream.
     int ignoreUntilByte(byte untilByte)
              See first method of this name for comments
     int ignoreUntilByte(byte[] untilByte)
              See first method of this name for comments
     int ignoreUntilByte(char untilByte)
              Ignores bytes from a stream until a certain byte is found.
     int ignoreUntilByte(java.lang.String untilByte)
              See first method of this name for comments
     int ignoreUntilByteSequence(byte[] untilByteSequence)
              See first method of this name for comments
     int ignoreUntilByteSequence(byte[][] untilByteSequence)
              See first method of this name for comments
     int ignoreUntilByteSequence(java.lang.String untilByteSequence)
              Ignores bytes from a stream until a certain byte sequence is found.
     int ignoreUntilByteSequence(java.lang.String[] untilByteSequence)
              See first method of this name for comments
     void ignoreWhileByte(byte whileByte)
              See first method of this name for comments
     void ignoreWhileByte(byte[] whileByte)
              See first method of this name for comments
     void ignoreWhileByte(char whileByte)
              Ignores bytes from a stream while its bytes are one of a set of given bytes.
     void ignoreWhileByte(java.lang.String whileByte)
              See first method of this name for comments
     int ignoreWhileNotByte(byte whileNotByte)
              See first method of this name for comments
     int ignoreWhileNotByte(byte[] whileNotByte)
              See first method of this name for comments
     int ignoreWhileNotByte(char whileNotByte)
              Ignores bytes from a stream while its bytes are NOT one of a set of given bytes.
     int ignoreWhileNotByte(java.lang.String whileNotByte)
              See first method of this name for comments
     int matchByte(byte matchByte)
              Deprecated. calls to this method should be replaced with calls to compareNextByteSequence( matchByteSequence, true );
     int matchByte(byte[] matchByte)
              Deprecated. calls to this method should be replaced with calls to compareNextByte( matchByte, true );
     int matchByte(char matchByte)
              Deprecated. calls to this method should be replaced with calls to compareNextByte( matchByte, true );
     int matchByte(java.lang.String matchByte)
              Deprecated. calls to this method should be replaced with calls to compareNextByteSequence( matchByteSequence, true );
     int matchByteSequence(byte[] matchByteSequence)
              Deprecated. calls to this method should be replaced with calls to compareNextByteSequence( matchByteSequence, true );
     int matchByteSequence(byte[][] matchByteSequence)
              Deprecated. calls to this method should be replaced with calls to compareNextByteSequence( matchByteSequence, true );
     int matchByteSequence(java.lang.String matchByteSequence)
              Deprecated. calls to this method should be replaced with calls to compareNextByteSequence( matchByteSequence, true );
     int matchByteSequence(java.lang.String[] matchByteSequence)
              Deprecated. calls to this method should be replaced with calls to compareNextByteSequence( matchByteSequence, true );
     int readByte()
              Reads one byte.
     void readPositionRestore(int stackPointerReference)
              This method goes with the readPositionStore() method and the comments for that method should explain this method.
     int readPositionStore()
              Each time this method is called the current position is stored and data is buffered from that position onwards.
     void setCaseInsensitive()
              All methods called after a call to this method are case insensitive
     void setCaseSensitive()
              All methods called after a call to this method are case sensitive which is the default
     java.lang.String stringLength(int takeLength)
              Takes the given number bytes from a stream.
     java.lang.String stringUntilByte(byte untilByte)
              See first method of this name for comments
     java.lang.String stringUntilByte(byte[] untilByte)
              See first method of this name for comments
     java.lang.String stringUntilByte(char untilByte)
              Takes bytes from a stream until a certain byte is found.
     java.lang.String stringUntilByte(java.lang.String untilByte)
              See first method of this name for comments
     java.lang.String stringUntilByteSequence(byte[] untilByteSequence)
              See first method of this name for comments
     java.lang.String stringUntilByteSequence(byte[][] untilByteSequence)
              See first method of this name for comments
     java.lang.String stringUntilByteSequence(java.lang.String untilByteSequence)
              Takes bytes from a stream until a certain byte sequence is found.
     java.lang.String stringUntilByteSequence(java.lang.String[] untilByteSequence)
              See first method of this name for comments
     java.lang.String stringUntilEndOfStream()
              Takes bytes from a stream until the end of stream is reached.
     java.lang.String stringWhileByte(byte whileByte)
              See first method of this name for comments
     java.lang.String stringWhileByte(byte[] whileByte)
              See first method of this name for comments
     java.lang.String stringWhileByte(char whileByte)
              Takes bytes from a stream while its bytes are one of a set of given bytes.
     java.lang.String stringWhileByte(java.lang.String whileByte)
              See first method of this name for comments
     java.lang.String stringWhileNotByte(byte whileNotByte)
              See first method of this name for comments
     java.lang.String stringWhileNotByte(byte[] whileNotByte)
              See first method of this name for comments
     java.lang.String stringWhileNotByte(char whileNotByte)
              Takes bytes from a stream while its bytes are NOT one of a set of given bytes.
     java.lang.String stringWhileNotByte(java.lang.String whileNotByte)
              See first method of this name for comments
     void takeLength(byte[] take, int takeLength)
              Takes the given number bytes from a stream.
     void takeLength(java.io.OutputStream take, int takeLength)
              See first method of this name for comments
     int takeUntilByte(byte[] take, byte untilByte)
              See first method of this name for comments
     int takeUntilByte(byte[] take, byte[] untilByte)
              See first method of this name for comments
     int takeUntilByte(byte[] take, char untilByte)
              Takes bytes from a stream until a certain byte is found.
     int takeUntilByte(byte[] take, java.lang.String untilByte)
              See first method of this name for comments
     int takeUntilByte(java.io.OutputStream take, byte untilByte)
              See first method of this name for comments
     int takeUntilByte(java.io.OutputStream take, byte[] untilByte)
              See first method of this name for comments
     int takeUntilByte(java.io.OutputStream take, char untilByte)
              See first method of this name for comments
     int takeUntilByte(java.io.OutputStream take, java.lang.String untilByte)
              See first method of this name for comments
     int takeUntilByteSequence(byte[] take, byte[] untilByteSequence)
              See first method of this name for comments
     int takeUntilByteSequence(byte[] take, byte[][] untilByteSequence)
              See first method of this name for comments
     int takeUntilByteSequence(byte[] take, java.lang.String untilByteSequence)
              Takes bytes from a stream until a certain byte sequence is found.
     int takeUntilByteSequence(byte[] take, java.lang.String[] untilByteSequence)
              See first method of this name for comments
     int takeUntilByteSequence(java.io.OutputStream take, byte[] untilByteSequence)
              See first method of this name for comments
     int takeUntilByteSequence(java.io.OutputStream take, byte[][] untilByteSequence)
              See first method of this name for comments
     int takeUntilByteSequence(java.io.OutputStream take, java.lang.String untilByteSequence)
              See first method of this name for comments
     int takeUntilByteSequence(java.io.OutputStream take, java.lang.String[] untilByteSequence)
              See first method of this name for comments
     int takeUntilEndOfStream(byte[] take)
              Takes bytes from a stream until the end of stream is reached.
     int takeUntilEndOfStream(java.io.OutputStream take)
              See first method of this name for comments
     int takeWhileByte(byte[] take, byte whileByte)
              See first method of this name for comments
     int takeWhileByte(byte[] take, byte[] whileByte)
              See first method of this name for comments
     int takeWhileByte(byte[] take, char whileByte)
              Takes bytes from a stream while its bytes are one of a set of given bytes.
     int takeWhileByte(byte[] take, java.lang.String whileByte)
              See first method of this name for comments
     int takeWhileByte(java.io.OutputStream take, byte whileByte)
              See first method of this name for comments
     int takeWhileByte(java.io.OutputStream take, byte[] whileByte)
              See first method of this name for comments
     int takeWhileByte(java.io.OutputStream take, char whileByte)
              See first method of this name for comments
     int takeWhileByte(java.io.OutputStream take, java.lang.String whileByte)
              See first method of this name for comments
     int takeWhileNotByte(byte[] take, byte whileNotByte)
              See first method of this name for comments
     int takeWhileNotByte(byte[] take, byte[] whileNotByte)
              See first method of this name for comments
     int takeWhileNotByte(byte[] take, char whileNotByte)
              Takes bytes from a stream while its bytes are NOT one of a set of given bytes.
     int takeWhileNotByte(byte[] take, java.lang.String whileNotByte)
              See first method of this name for comments
     int takeWhileNotByte(java.io.OutputStream take, byte whileNotByte)
              See first method of this name for comments
     int takeWhileNotByte(java.io.OutputStream take, byte[] whileNotByte)
              See first method of this name for comments
     int takeWhileNotByte(java.io.OutputStream take, char whileNotByte)
              See first method of this name for comments
     int takeWhileNotByte(java.io.OutputStream take, java.lang.String whileNotByte)
              See first method of this name for comments
     
    Methods inherited from class java.lang.Object
    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     

    Constructor Detail

    InputStreamParser

    public InputStreamParser(java.io.InputStream stream,
                             int powerOfTwoBufferSize)
    Constructor

    Parameters:
    stream - - the input stream to be read from. You should not access this stream directly at any time as the InputStreamParser has its own buffering which you would short cut, thus loosing characters.
    powerOfTwoBufferSize - Sets the buffer in the InputStreamParser to be two to the power of the value passed in. e.g. 8 gives a buffer size of 256, 10 gives 1024 etc. 1024 is normally plenty. You can use up to the buffer size minus one. You can overflow the buffer by using a 'string' method of this class to return a string that is bigger then the buffer size minus one. And you can overflow the buffer by passing in a byte seqence that is bigger then the buffer size minus one. Doing either will throw an InputStreamParserException. 1< bytes where powerOfTwoBufferSize is a number given to the
    Method Detail

    getTakenLength

    public int getTakenLength()
    Where one of the 'take' methods of this class has been called, this method will return the number of bytes that were taken.

    Returns:
    number of bytes taken in last 'take' method call

    getReadLength

    public int getReadLength()
    This method will return the number of bytes that have been read.

    Returns:
    number of bytes taken in last 'take' method call

    getWhichByteOrSequence

    public int getWhichByteOrSequence()
    Where 'match' or 'until' methods were called. This method gives the index of the found byte or byte sequence in the array that was passed in.

    Returns:
    Index in the array of the byte or byte sequence that lead the last method to terminate. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte sequence was found.

    setCaseInsensitive

    public void setCaseInsensitive()
    All methods called after a call to this method are case insensitive


    setCaseSensitive

    public void setCaseSensitive()
    All methods called after a call to this method are case sensitive which is the default


    stringUntilByteSequence

    public java.lang.String stringUntilByteSequence(java.lang.String untilByteSequence)
                                             throws java.io.EOFException,
                                                    java.io.IOException,
                                                    InputStreamParserException
    Takes bytes from a stream until a certain byte sequence is found. Looks for a single byte sequence or one of a number of possible byte sequences as termination markers. Throw away the found termination marker. The 'stringUntil' method family is identical to the 'takeUntil' family but returns a string as opposed to the number of characters read in.

    Parameters:
    untilByteSequence - if untilByteSequence is an array of arrays then each sub-array inputs one of the possible terminating byte sequences. if untilByteSequence is an array then it inputs the single terminating byte sequence. if untilByteSequence is an array of strings then each string inputs one of the possible terminating byte sequences. if untilByteSequence is an array then it inputs the single terminating byte sequence.
    Returns:
    the string taken. (Note: Lenght limitation! See 'InputStreamParserException') Where a number of terminating sequences were passed in, a call to getWhichByteOrSequence() returns the index in the array of the one that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte sequence was found. A call to getTakenLength() will return the number of characters taken.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - is thrown if a terminating byte sequence or returned string was longer than 1< bytes where powerOfTwoBufferSize is a number given to the constructor.

    stringUntilByteSequence

    public java.lang.String stringUntilByteSequence(java.lang.String[] untilByteSequence)
                                             throws java.io.EOFException,
                                                    java.io.IOException,
                                                    InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringUntilByteSequence

    public java.lang.String stringUntilByteSequence(byte[] untilByteSequence)
                                             throws java.io.EOFException,
                                                    java.io.IOException,
                                                    InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringUntilByteSequence

    public java.lang.String stringUntilByteSequence(byte[][] untilByteSequence)
                                             throws java.io.EOFException,
                                                    java.io.IOException,
                                                    InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByteSequence

    public int takeUntilByteSequence(byte[] take,
                                     java.lang.String untilByteSequence)
                              throws java.io.EOFException,
                                     java.io.IOException,
                                     InputStreamParserException
    Takes bytes from a stream until a certain byte sequence is found. Looks for a single byte sequence or one of a number of possible byte sequences as termination markers. Throws away the found termination marker. The bytes are passed into the array or stream.

    Parameters:
    take - A byte array or an OutputStream in which to take the bytes.
    untilByteSequence - if untilByteSequence is an array of arrays then each sub-array inputs one of the possible terminating byte sequences. if untilByteSequence is an array then it inputs the single terminating byte sequence. if untilByteSequence is an array of strings then each string inputs one of the possible terminating byte sequences. if untilByteSequence is a string then it inputs the single terminating byte sequence.
    Returns:
    the number of taken bytes. Where a number of terminating sequences were passed in, a call to getWhichByteOrSequence() returns the index in the array of the one that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. A call to getTakenLength() will return the number of characters taken.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - is thrown if a terminating byte sequence was longer than 1< bytes where powerOfTwoBufferSize is a number given to the constructor.

    takeUntilByteSequence

    public int takeUntilByteSequence(byte[] take,
                                     java.lang.String[] untilByteSequence)
                              throws java.io.EOFException,
                                     java.io.IOException,
                                     InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByteSequence

    public int takeUntilByteSequence(byte[] take,
                                     byte[] untilByteSequence)
                              throws java.io.EOFException,
                                     java.io.IOException,
                                     InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByteSequence

    public int takeUntilByteSequence(byte[] take,
                                     byte[][] untilByteSequence)
                              throws java.io.EOFException,
                                     java.io.IOException,
                                     InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByteSequence

    public int takeUntilByteSequence(java.io.OutputStream take,
                                     java.lang.String untilByteSequence)
                              throws java.io.EOFException,
                                     java.io.IOException,
                                     InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByteSequence

    public int takeUntilByteSequence(java.io.OutputStream take,
                                     java.lang.String[] untilByteSequence)
                              throws java.io.EOFException,
                                     java.io.IOException,
                                     InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByteSequence

    public int takeUntilByteSequence(java.io.OutputStream take,
                                     byte[] untilByteSequence)
                              throws java.io.EOFException,
                                     java.io.IOException,
                                     InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByteSequence

    public int takeUntilByteSequence(java.io.OutputStream take,
                                     byte[][] untilByteSequence)
                              throws java.io.EOFException,
                                     java.io.IOException,
                                     InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringUntilByte

    public java.lang.String stringUntilByte(char untilByte)
                                     throws java.io.EOFException,
                                            java.io.IOException,
                                            InputStreamParserException
    Takes bytes from a stream until a certain byte is found. Looks for a single byte or one of a number of possible bytes as termination markers. Throws away the found termination marker. The 'stringUntil' method family is identical to the 'takeUntil' family but returns a string as opposed to the number of characters read in.

    Parameters:
    untilByte - if untilByte is an array of bytes then each byte is one of the possible terminating bytes. if untilByte is a byte then it inputs the single terminating byte. if untilByteSequence is a string then each character is one of the possible terminating bytes. if untilByteSequence is a character then it inputs the single terminating byte.
    Returns:
    the string taken. (Note: Lenght limitation! See 'InputStreamParserException') Where a number of terminating bytes were passed in, a call to getWhichByteOrSequence() returns the index in the array of the byte that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte was found. A call to getTakenLength() will return the number of characters taken.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - is thrown if a returned string was longer than 1< bytes where powerOfTwoBufferSize is a number given to the constructor.

    stringUntilByte

    public java.lang.String stringUntilByte(java.lang.String untilByte)
                                     throws java.io.EOFException,
                                            java.io.IOException,
                                            InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringUntilByte

    public java.lang.String stringUntilByte(byte untilByte)
                                     throws java.io.EOFException,
                                            java.io.IOException,
                                            InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringUntilByte

    public java.lang.String stringUntilByte(byte[] untilByte)
                                     throws java.io.EOFException,
                                            java.io.IOException,
                                            InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByte

    public int takeUntilByte(byte[] take,
                             char untilByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    Takes bytes from a stream until a certain byte is found. Looks for a single byte or one of a number of possible bytes as termination markers. Throws away the found termination marker. The bytes are passed into the array or stream.

    Parameters:
    take - A byte array or an OutputStream in which to take the bytes.
    untilByte - if untilByte is an array of bytes then each byte is one of the possible terminating bytes. if untilByte is a byte then it inputs the single terminating byte. if untilByteSequence is a string then each character is one of the possible terminating bytes. if untilByteSequence is a character then it inputs the single terminating byte.
    Returns:
    the number of taken bytes. Where a number of terminating bytes were passed in, a call to getWhichByteOrSequence() returns the index in the array of the byte that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte was found. A call to getTakenLength() will return the number of characters taken.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.

    takeUntilByte

    public int takeUntilByte(byte[] take,
                             java.lang.String untilByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByte

    public int takeUntilByte(byte[] take,
                             byte untilByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByte

    public int takeUntilByte(byte[] take,
                             byte[] untilByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByte

    public int takeUntilByte(java.io.OutputStream take,
                             char untilByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByte

    public int takeUntilByte(java.io.OutputStream take,
                             java.lang.String untilByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByte

    public int takeUntilByte(java.io.OutputStream take,
                             byte untilByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeUntilByte

    public int takeUntilByte(java.io.OutputStream take,
                             byte[] untilByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringUntilEndOfStream

    public java.lang.String stringUntilEndOfStream()
                                            throws java.io.EOFException,
                                                   java.io.IOException,
                                                   InputStreamParserException
    Takes bytes from a stream until the end of stream is reached. The bytes are passed into the array or stream. The 'stringUntil' method family is identical to the 'takeUntil' family but returns a string as opposed to the number of characters read in.

    Returns:
    the string taken. (Note: Lenght limitation! See 'InputStreamParserException') A call to getTakenLength() will return the number of characters taken.
    Throws:
    java.io.IOException - is passed through.
    InputStreamParserException - is thrown if a returned string was longer than 1< bytes where powerOfTwoBufferSize is a number given to the constructor.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.
    java.io.EOFException

    takeUntilEndOfStream

    public int takeUntilEndOfStream(byte[] take)
                             throws java.io.EOFException,
                                    java.io.IOException,
                                    InputStreamParserException
    Takes bytes from a stream until the end of stream is reached. The bytes are passed into the array or stream.

    Parameters:
    take - A byte array or an OutputStream in which to take the bytes.
    Returns:
    the number of taken bytes. A call to getTakenLength() will return the number of characters taken.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - although this exception is indicated as being thrown. This call will not throw it.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.

    takeUntilEndOfStream

    public int takeUntilEndOfStream(java.io.OutputStream take)
                             throws java.io.EOFException,
                                    java.io.IOException,
                                    InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreUntilByteSequence

    public int ignoreUntilByteSequence(java.lang.String untilByteSequence)
                                throws java.io.EOFException,
                                       java.io.IOException,
                                       InputStreamParserException
    Ignores bytes from a stream until a certain byte sequence is found. Looks for a single byte sequence or one of a number of possible byte sequences as termination markers. Throws away the found termination marker. The ignored bytes are discarded.

    Parameters:
    untilByteSequence -

    ~ if untilByteSequence is an array of arrays then each sub-array inputs one of the possible terminating byte sequences.

    ~ if untilByteSequence is an array then it inputs the single terminating byte sequence.

    ~ if untilByteSequence is an array of strings then each string inputs one of the possible terminating byte sequences.

    ~ if untilByteSequence is a string then it inputs the single terminating byte sequence.

    Returns:
    the index in the array of the one that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. Where a number of terminating sequences were passed in, a call to getWhichByteOrSequence() returns the index in the array of the one that lead to the termination. This can be used to drive a switch statement. Indexes start at 0.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - is thrown if a terminating byte sequence was longer than 1< bytes where powerOfTwoBufferSize is a number given to the constructor.

    ignoreUntilByteSequence

    public int ignoreUntilByteSequence(java.lang.String[] untilByteSequence)
                                throws java.io.EOFException,
                                       java.io.IOException,
                                       InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreUntilByteSequence

    public int ignoreUntilByteSequence(byte[] untilByteSequence)
                                throws java.io.EOFException,
                                       java.io.IOException,
                                       InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreUntilByteSequence

    public int ignoreUntilByteSequence(byte[][] untilByteSequence)
                                throws java.io.EOFException,
                                       java.io.IOException,
                                       InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreUntilByte

    public int ignoreUntilByte(char untilByte)
                        throws java.io.EOFException,
                               java.io.IOException,
                               InputStreamParserException
    Ignores bytes from a stream until a certain byte is found. Looks for a single byte or one of a number of possible bytes as termination markers. Throws away the found termination marker. The ignored bytes are discarded.

    Parameters:
    untilByte - if untilByte is an array of bytes then each byte is one of the possible terminating bytes. if untilByte is a byte then it inputs the single terminating byte. if untilByteSequence is a string then each character is one of the possible terminating bytes. if untilByteSequence is a character then it inputs the single terminating byte.
    Returns:
    the index in the array of the byte that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte was found. Where a number of terminating bytes were passed in, a call to getWhichByteOrSequence() returns the index in the array of the byte that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte was found.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.

    ignoreUntilByte

    public int ignoreUntilByte(java.lang.String untilByte)
                        throws java.io.EOFException,
                               java.io.IOException,
                               InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreUntilByte

    public int ignoreUntilByte(byte untilByte)
                        throws java.io.EOFException,
                               java.io.IOException,
                               InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreUntilByte

    public int ignoreUntilByte(byte[] untilByte)
                        throws java.io.EOFException,
                               java.io.IOException,
                               InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringWhileNotByte

    public java.lang.String stringWhileNotByte(char whileNotByte)
                                        throws java.io.EOFException,
                                               java.io.IOException,
                                               InputStreamParserException
    Takes bytes from a stream while its bytes are NOT one of a set of given bytes. Checks for a single byte or one of a number of possible bytes in the stream. The 'stringWhileNotByte' method family is identical to the 'takeWhileNotByte' family but returns a string as opposed to the number of characters read in.

    Parameters:
    whileNotByte -

    ~ if whileNotByte is an array of bytes then each byte is one of the disallowed bytes.

    ~ if whileNotByte is a byte then it inputs the single disallowed byte.

    ~ if whileNotByte is a string then each character is one of the disallowed bytes.

    ~ if whileNotByte is a character then it inputs the single disallowed byte.

    Returns:
    the string taken. (Note: Length limitation! See 'InputStreamParserException') Where a number of disallowed bytes were passed in, a call to getWhichByteOrSequence() returns the index in the array of the byte that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte was found. A call to getTakenLength() will return the number of characters taken.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - is thrown if a returned string was longer than 1< bytes where powerOfTwoBufferSize is a number given to the constructor.

    stringWhileNotByte

    public java.lang.String stringWhileNotByte(java.lang.String whileNotByte)
                                        throws java.io.EOFException,
                                               java.io.IOException,
                                               InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringWhileNotByte

    public java.lang.String stringWhileNotByte(byte whileNotByte)
                                        throws java.io.EOFException,
                                               java.io.IOException,
                                               InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringWhileNotByte

    public java.lang.String stringWhileNotByte(byte[] whileNotByte)
                                        throws java.io.EOFException,
                                               java.io.IOException,
                                               InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileNotByte

    public int takeWhileNotByte(byte[] take,
                                char whileNotByte)
                         throws java.io.EOFException,
                                java.io.IOException,
                                InputStreamParserException
    Takes bytes from a stream while its bytes are NOT one of a set of given bytes. Checks for a single byte or one of a number of possible bytes in the stream. The bytes are passed into the array or stream.

    Parameters:
    whileNotByte -

    ~ if whileNotByte is an array of bytes then each byte is one of the disallowed bytes.

    ~ if whileNotByte is a byte then it inputs the single disallowed byte.

    ~ if whileNotByte is a string then each character is one of the disallowed bytes.

    ~ if whileNotByte is a character then it inputs the single disallowed byte.

    Returns:
    the number of taken bytes. Where a number of disallowed bytes were passed in, a call to getWhichByteOrSequence() returns the index in the array of the byte that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte was found. A call to getTakenLength() will return the number of characters taken.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.

    takeWhileNotByte

    public int takeWhileNotByte(byte[] take,
                                java.lang.String whileNotByte)
                         throws java.io.EOFException,
                                java.io.IOException,
                                InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileNotByte

    public int takeWhileNotByte(byte[] take,
                                byte whileNotByte)
                         throws java.io.EOFException,
                                java.io.IOException,
                                InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileNotByte

    public int takeWhileNotByte(byte[] take,
                                byte[] whileNotByte)
                         throws java.io.EOFException,
                                java.io.IOException,
                                InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileNotByte

    public int takeWhileNotByte(java.io.OutputStream take,
                                char whileNotByte)
                         throws java.io.EOFException,
                                java.io.IOException,
                                InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileNotByte

    public int takeWhileNotByte(java.io.OutputStream take,
                                java.lang.String whileNotByte)
                         throws java.io.EOFException,
                                java.io.IOException,
                                InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileNotByte

    public int takeWhileNotByte(java.io.OutputStream take,
                                byte whileNotByte)
                         throws java.io.EOFException,
                                java.io.IOException,
                                InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileNotByte

    public int takeWhileNotByte(java.io.OutputStream take,
                                byte[] whileNotByte)
                         throws java.io.EOFException,
                                java.io.IOException,
                                InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringWhileByte

    public java.lang.String stringWhileByte(char whileByte)
                                     throws java.io.EOFException,
                                            java.io.IOException,
                                            InputStreamParserException
    Takes bytes from a stream while its bytes are one of a set of given bytes. Checks for a single byte or one of a number of possible bytes in the stream. The 'stringWhileByte' method family is identical to the 'takeWhileByte' family but returns a string as opposed to the number of characters read in.

    Parameters:
    whileByte -

    ~ if whileByte is an array of bytes then each byte is one of the allowed bytes.

    ~ if whileByte is a byte then it inputs the single allowed byte.

    ~ if whileByte is a string then each character is one of the allowed bytes.

    ~ if whileByte is a character then it inputs the single disallowed byte.

    Returns:
    the string taken. (Note: Lenght limitation! See 'InputStreamParserException') A call to getTakenLength() will return the number of characters taken.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - is thrown if a returned string was longer than 1< bytes where powerOfTwoBufferSize is a number given to the constructor.

    stringWhileByte

    public java.lang.String stringWhileByte(java.lang.String whileByte)
                                     throws java.io.EOFException,
                                            java.io.IOException,
                                            InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringWhileByte

    public java.lang.String stringWhileByte(byte whileByte)
                                     throws java.io.EOFException,
                                            java.io.IOException,
                                            InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringWhileByte

    public java.lang.String stringWhileByte(byte[] whileByte)
                                     throws java.io.EOFException,
                                            java.io.IOException,
                                            InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileByte

    public int takeWhileByte(byte[] take,
                             char whileByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    Takes bytes from a stream while its bytes are one of a set of given bytes. Checks for a single byte or one of a number of possible bytes in the stream. The bytes are passed into the array or stream.

    Parameters:
    whileByte -

    ~ if whileByte is an array of bytes then each byte is one of the allowed bytes.

    ~ if whileByte is a byte then it inputs the single allowed byte.

    ~ if whileByte is a string then each character is one of the allowed bytes.

    ~ if whileByte is a character then it inputs the single allowed byte.

    Returns:
    the number of taken bytes. A call to getTakenLength() will return the number of characters taken.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.

    takeWhileByte

    public int takeWhileByte(byte[] take,
                             java.lang.String whileByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileByte

    public int takeWhileByte(byte[] take,
                             byte whileByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileByte

    public int takeWhileByte(byte[] take,
                             byte[] whileByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileByte

    public int takeWhileByte(java.io.OutputStream take,
                             char whileByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileByte

    public int takeWhileByte(java.io.OutputStream take,
                             java.lang.String whileByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileByte

    public int takeWhileByte(java.io.OutputStream take,
                             byte whileByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    takeWhileByte

    public int takeWhileByte(java.io.OutputStream take,
                             byte[] whileByte)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreWhileByte

    public void ignoreWhileByte(char whileByte)
                         throws java.io.EOFException,
                                java.io.IOException,
                                InputStreamParserException
    Ignores bytes from a stream while its bytes are one of a set of given bytes. Checks for a single byte or one of a number of possible bytes in the stream. The ignored bytes are discarded.

    Parameters:
    whileByte -

    ~ if whileByte is an array of bytes then each byte is one of the allowed bytes.

    ~ if whileByte is a byte then it inputs the single allowed byte.

    ~ if whileByte is a string then each character is one of the allowed bytes.

    ~ if whileByte is a character then it inputs the single allowed byte.

    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.

    ignoreWhileByte

    public void ignoreWhileByte(java.lang.String whileByte)
                         throws java.io.EOFException,
                                java.io.IOException,
                                InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreWhileByte

    public void ignoreWhileByte(byte whileByte)
                         throws java.io.EOFException,
                                java.io.IOException,
                                InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreWhileByte

    public void ignoreWhileByte(byte[] whileByte)
                         throws java.io.EOFException,
                                java.io.IOException,
                                InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreWhileNotByte

    public int ignoreWhileNotByte(char whileNotByte)
                           throws java.io.EOFException,
                                  java.io.IOException,
                                  InputStreamParserException
    Ignores bytes from a stream while its bytes are NOT one of a set of given bytes. Checks for a single byte or one of a number of possible bytes in the stream. The ignored bytes are discarded.

    Parameters:
    whileNotByte -

    ~ if whileNotByte is an array of bytes then each byte is one of the disallowed bytes.

    ~ if whileNotByte is a byte then it inputs the single disallowed byte.

    ~ if whileNotByte is a string then each character is one of the disallowed bytes.

    ~ if whileNotByte is a character then it inputs the single disallowed byte.

    Returns:
    the index in the array of the byte that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte was found. Where a number of disallowed bytes were passed in, a call to getWhichByteOrSequence() returns the index in the array of the byte that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte was found.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.

    ignoreWhileNotByte

    public int ignoreWhileNotByte(java.lang.String whileNotByte)
                           throws java.io.EOFException,
                                  java.io.IOException,
                                  InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreWhileNotByte

    public int ignoreWhileNotByte(byte whileNotByte)
                           throws java.io.EOFException,
                                  java.io.IOException,
                                  InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreWhileNotByte

    public int ignoreWhileNotByte(byte[] whileNotByte)
                           throws java.io.EOFException,
                                  java.io.IOException,
                                  InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    stringLength

    public java.lang.String stringLength(int takeLength)
                                  throws java.io.EOFException,
                                         java.io.IOException,
                                         InputStreamParserException
    Takes the given number bytes from a stream. The bytes are passed into the array or stream. The 'stringLength' method is identical to 'takeLength' but returns a string as opposed to the number of characters read in.

    Parameters:
    takeLength - The number of bytes to take
    Returns:
    the string taken.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - is thrown if a returned string was longer than 1< bytes where powerOfTwoBufferSize is a number given to the constructor.

    takeLength

    public void takeLength(byte[] take,
                           int takeLength)
                    throws java.io.EOFException,
                           java.io.IOException,
                           InputStreamParserException
    Takes the given number bytes from a stream. The bytes are passed into the array or stream.

    Parameters:
    takeLength - The number of bytes to take
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.

    takeLength

    public void takeLength(java.io.OutputStream take,
                           int takeLength)
                    throws java.io.EOFException,
                           java.io.IOException,
                           InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    ignoreLength

    public void ignoreLength(int ignoreLength)
                      throws java.io.EOFException,
                             java.io.IOException,
                             InputStreamParserException
    Ignores the given number bytes from a stream.

    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.

    matchByteSequence

    public int matchByteSequence(java.lang.String matchByteSequence)
                          throws java.io.EOFException,
                                 java.io.IOException,
                                 InputStreamParserException
    Deprecated. calls to this method should be replaced with calls to compareNextByteSequence( matchByteSequence, true );

    Matches a stream, at the point it is at, to one of a number of possible byte sequences or a single byte sequence. Throws away the matched byte sequence if found.

    Parameters:
    matchByteSequence -

    ~ if matchByteSequence is an array of arrays then each sub-array inputs one of the possible matching byte sequences.

    ~ if matchByteSequence is an array then it inputs the single matching byte sequence.

    ~ if matchByteSequence is an array of strings then each string inputs one of the possible matching byte sequences.

    ~ if matchByteSequence is a string then it inputs the single matching byte sequence.

    Returns:
    the index in the array of the one that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte sequence was found. Where a number of terminating sequences were passed in, a call to getWhichByteOrSequence() returns the index in the array of the one that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte sequence was found.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - although this exception is indicated as being thrown. This call will not throw it.
    InputStreamParserException - is thrown if a terminating byte sequence was longer than 1< bytes where powerOfTwoBufferSize is a number given to the constructor.

    matchByteSequence

    public int matchByteSequence(java.lang.String[] matchByteSequence)
                          throws java.io.EOFException,
                                 java.io.IOException,
                                 InputStreamParserException
    Deprecated. calls to this method should be replaced with calls to compareNextByteSequence( matchByteSequence, true );

    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    matchByteSequence

    public int matchByteSequence(byte[] matchByteSequence)
                          throws java.io.EOFException,
                                 java.io.IOException,
                                 InputStreamParserException
    Deprecated. calls to this method should be replaced with calls to compareNextByteSequence( matchByteSequence, true );

    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    matchByteSequence

    public int matchByteSequence(byte[][] matchByteSequence)
                          throws java.io.EOFException,
                                 java.io.IOException,
                                 InputStreamParserException
    Deprecated. calls to this method should be replaced with calls to compareNextByteSequence( matchByteSequence, true );

    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    matchByte

    public int matchByte(char matchByte)
                  throws java.io.EOFException,
                         java.io.IOException,
                         InputStreamParserException
    Deprecated. calls to this method should be replaced with calls to compareNextByte( matchByte, true );

    Matches a stream, at the point it is at, to one of a number of possible bytes or a single byte. Throws away the matched byte if found.

    Parameters:
    matchByte -

    ~ if matchByte is an array of bytes then each byte is one of the possible match bytes.

    ~ if matchByte is a single byte then it is the single match byte.

    ~ if matchByte is a string then each character is one of the possible match bytes.

    ~ if matchByte is a single character then it is the single match byte.

    Returns:
    the index in the array of the one that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte sequence was found. Where a number of terminating sequences were passed in, a call to getWhichByteOrSequence() returns the index in the array of the one that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte sequence was found.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - although this exception is indicated as being thrown. This call will not throw it.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.

    matchByte

    public int matchByte(java.lang.String matchByte)
                  throws java.io.EOFException,
                         java.io.IOException,
                         InputStreamParserException
    Deprecated. calls to this method should be replaced with calls to compareNextByteSequence( matchByteSequence, true );

    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    matchByte

    public int matchByte(byte matchByte)
                  throws java.io.EOFException,
                         java.io.IOException,
                         InputStreamParserException
    Deprecated. calls to this method should be replaced with calls to compareNextByteSequence( matchByteSequence, true );

    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    matchByte

    public int matchByte(byte[] matchByte)
                  throws java.io.EOFException,
                         java.io.IOException,
                         InputStreamParserException
    Deprecated. calls to this method should be replaced with calls to compareNextByte( matchByte, true );

    Matches a stream, at the point it is at, to one of a number of possible bytes. Throws away the matched byte if found.

    Parameters:
    matchByte - each byte is one of the possible match bytes.
    Returns:
    the index in the array of the byte that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte sequence was found. A call to getWhichByteOrSequence() returns the index in the array of the one that lead to the termination. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no terminating byte was found.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - although this exception is indicated as being thrown. This call will not throw it.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.

    compareNextEndOfStream

    public boolean compareNextEndOfStream()
                                   throws java.io.IOException,
                                          InputStreamParserException
    Looks ahead into the stream to see if we are at the end of the stream. Unlike most EOS functions, it is not necessary to read off the end of stream before this method returns true. Reading off the end of stream will throw an exception.

    Returns:
    true if the next read would throw an EOSexception
    Throws:
    java.io.IOException - is passed through.
    InputStreamParserException - although this exception is indicated as being thrown. This call will not throw it.

    compareNextByteSequence

    public int compareNextByteSequence(java.lang.String compareNextByteSequence,
                                       boolean ClearMatch)
                                throws java.io.EOFException,
                                       java.io.IOException,
                                       InputStreamParserException
    Looks ahead into the stream to see if the first bytes in the stream will match one of the given byte sequences or a single given byte sequence. Removes the bytes if ClearMatch is true.

    Parameters:
    compareNextByteSequence -

    ~ if compareNextByteSequence is an array of arrays then each sub-array inputs one of the possible byte sequences to compare.

    ~ if compareNextByteSequence is an array then it inputs the single byte sequence to compare.

    ~ if compareNextByteSequence is an array of strings then each string inputs one of the possible byte sequences to compare.

    ~ if compareNextByteSequence is a string then it inputs the single byte sequence to compare.

    ClearMatch - if true then any matched bytes will be removed from the stream. Otherwise they are preserved.
    Returns:
    the index of the byte sequence sub-array in matchByteSequence. if matchByteSequence is a single array then 0. If no match was found then -1 is returned.
    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    compareNextByteSequence

    public int compareNextByteSequence(java.lang.String[] compareNextByteSequence,
                                       boolean ClearMatch)
                                throws java.io.EOFException,
                                       java.io.IOException,
                                       InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    compareNextByteSequence

    public int compareNextByteSequence(byte[] compareNextByteSequence,
                                       boolean ClearMatch)
                                throws java.io.EOFException,
                                       java.io.IOException,
                                       InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    compareNextByteSequence

    public int compareNextByteSequence(byte[][] matchSequence,
                                       boolean ClearMatch)
                                throws java.io.EOFException,
                                       java.io.IOException,
                                       InputStreamParserException
    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    compareNextByte

    public int compareNextByte(char compareNextByte,
                               boolean ClearMatch)
                        throws java.io.EOFException,
                               java.io.IOException,
                               InputStreamParserException
    Looks ahead into the stream to see if the first byte in the stream will match one of the given bytes or a single given byte. Removes the byte if ClearMatch is true.

    Parameters:
    compareNextByte -

    ~ if compareNextByte is an array then each sub-array inputs one of the possible bytes to compare.

    ~ if compareNextByte is a single byte then it inputs the single byte to compare.

    ~ if compareNextByteSequence is a string then each character inputs one of the possible bytes to compare.

    ~ if compareNextByte is a char then it inputs the single byte to compare.

    ClearMatch - if true then any matched byte will be removed from the stream. Otherwise it is preserved.
    Returns:
    the index of the byte in the matchByteByte array. if matchByteByte is a single byte 0. If no match was found then -1 is returned.
    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    compareNextByte

    public int compareNextByte(java.lang.String compareNextByte,
                               boolean ClearMatch)
                        throws java.io.EOFException,
                               java.io.IOException,
                               InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    compareNextByte

    public int compareNextByte(byte compareNextByte,
                               boolean ClearMatch)
                        throws java.io.EOFException,
                               java.io.IOException,
                               InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    compareNextByte

    public int compareNextByte(byte[] matchByte,
                               boolean ClearMatch)
                        throws java.io.EOFException,
                               java.io.IOException,
                               InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    compareAbbreviatedNextByteSequence

    public int[] compareAbbreviatedNextByteSequence(java.lang.String matchSequence,
                                                    java.lang.String abbreviators,
                                                    boolean ClearMatch)
                                             throws java.io.EOFException,
                                                    java.io.IOException,
                                                    InputStreamParserException
    Looks ahead into the stream to see if the first bytes in the stream can be identified as an abbreviation for or full match for one of the given byte sequences. Removes the bytes from the stream if ClearMatch is true. An abbreviated byte sequence must match up to the point of where an abbreviation byte is found. For example 'Inc.' in the stream, would be accepted as an abbreviation for 'Incorporated' if full stop was defined as an abbreviator in the array of abbreviators passed into the method. Space can also be defined as an abbreviator so that 'Inc ' would be accepted. Where space is one of the abbreviators then end of stream is also considered as an abbreviator. So if the last three characters in the stream were 'Inc' then it would be accepted.

    Parameters:
    matchSequence -

    ~ if matchSequence is an array of arrays then each sub-array inputs one of the possible byte sequences to identify.

    ~ if matchSequence is an array then it inputs the single byte sequence to identify.

    ~ if matchSequence is an array of strings then each string inputs one of the possible byte sequences to identify.

    ~ if matchSequence is a string then it inputs the single byte sequence to identify.

    abbreviators - bytes that are considered to be valid abbreviaton characters in the stream.
    ClearMatch - if true then any matched bytes will be removed from the stream. Otherwise they are preserved.
    Returns:
    the indexes of the byte sequence sub-arrays in matchSequence that are possable matches for the abbreviation in the stream. See below to look at what happens when a full match is found. A call to getWhichByteOrSequence() returns the index in the array of any full match if there is one. This can be used to drive a switch statement. Indexes start at 0. -1 is returned if no fully matching byte sequence was found. A call to getTakenLength() will return the number of characters taken.
    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    compareAbbreviatedNextByteSequence

    public int[] compareAbbreviatedNextByteSequence(java.lang.String[] matchSequence,
                                                    java.lang.String abbreviators,
                                                    boolean ClearMatch)
                                             throws java.io.EOFException,
                                                    java.io.IOException,
                                                    InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    compareAbbreviatedNextByteSequence

    public int[] compareAbbreviatedNextByteSequence(byte[] matchSequence,
                                                    byte[] abbreviators,
                                                    boolean ClearMatch)
                                             throws java.io.EOFException,
                                                    java.io.IOException,
                                                    InputStreamParserException
    See first method of this name for comments

    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    compareAbbreviatedNextByteSequence

    public int[] compareAbbreviatedNextByteSequence(byte[][] matchSequence,
                                                    byte[] abbreviators,
                                                    boolean ClearMatch)
                                             throws java.io.EOFException,
                                                    java.io.IOException,
                                                    InputStreamParserException
    Throws:
    java.io.EOFException
    java.io.IOException
    InputStreamParserException

    readByte

    public int readByte()
                 throws java.io.EOFException,
                        java.io.IOException
    Reads one byte.

    Returns:
    The byte read.
    Throws:
    java.io.IOException - is passed through.
    java.io.EOFException - is thrown if an unexpected end of stream is reached. Use compareNextEndOfStream() to avoid this.

    readPositionStore

    public int readPositionStore()
                          throws InputStreamParserException
    Each time this method is called the current position is stored and data is buffered from that position onwards. The readPositionRestore() method allows you to go back to a previously stored position. The positions are stored on a stack and so calls to store and restore can be nested. The stack is limited to 256 entries and an exception will be thrown if this is exceeded. Each call to store returns an integer that must be used as the parameter to the corresponding restore method. This integer holds an index into the stack. This means that you can restor to a specific stored position. When you restore then all positions stored after the position you restore to, will be lost and there entries on the stack effectively cleared. Thus you must never attempt to restore forwards of the current position! When you call restore with 0 as a parameter the stack will be cleared and the buffering will cease but the position will stay where it is. Note that 0 is never returned from the store method. IMPORTANT: As soon as a position is stored then data from that point on is held in the InputStreamParser buffer which can overflow. So never use a call to store without a corresponding call to restore. e.g. if you have code which branches on error conditions etc you must restore appropriatly.

    Returns:
    stackPointerReference as passed into from readPositionRestore( )
    Throws:
    InputStreamParserException

    readPositionRestore

    public void readPositionRestore(int stackPointerReference)
                             throws InputStreamParserException
    This method goes with the readPositionStore() method and the comments for that method should explain this method.

    Parameters:
    stackPointerReference - as returned from readPositionStore( )
    Throws:
    InputStreamParserException