DataInputStream

advances the bit position to the specified alignment.

Note that the bitAlignment1b argument is 1-based.

Passing 0 as the argument is a usage error.

Passing 1 as the argument performs no alignment, as any bit position is 1-bit aligned.

For any other value, the bit position (1-based) is advanced to the next multiple of that argument value.

False is returned if there are insufficient available bits to achieve the alignment.

Debugging flag. If set then performance may be reduced, but historic and upcoming data may be viewed using the pastData and futureData methods.

This should be set at the beginning of execution. If it is set after data has been accessed then IllegalStateException is thrown.

As characters are iterated, the underlying bit position changes.

This does not construct a new iterator, it provides access to iterator behavior of the DataInputStream. In other words, there is no separate state of the iterator from the DataInputStream.

If any of the characteristics of the stream are changed (such as encoding, or bit order), then the iterator begins decoding characters using that new information immediately.

If next() is called after hasNext() has returned false, or when hasNext() would return false, then an IllegalStateException is thrown.

The behavior if characteristics are changed between a call to hasNext() and the subsequent call to next() is unspecified, but such usage is an error. If detected an unspecified RuntimeException will be thrown. However, the implementation may not check for this condition for performance reasons.

If encodingErrorPolicy is 'error', and a malformed character representation is encountered in the data then both hasNext() and next() on this iterator will throw CharacterCodingException.

Note that this is an exception to the way other methods of this API work in that an exception is thrown. It is generally expected that character decode errors are rare/exceptional situations.

If encodingErrorPolicy is 'replace' then hasNext() will only return false once the end of the available data has been reached. The next() method may return a Unicode replacement character as a replacement for an actual decode error, or if the encoding is a Unicode encoding, then a unicode replacement character may actually exist in the data stream. It is not possible to distinguish these two situations using this API when encodingErrorPolicy is 'replace'.

If insufficient bits are available to decode a character, then this is treated as a malformed character, per above.

(Note: This iterator replaces the use of scala Reader[Char] in the low levels of the I/O system. Reader[Char] can still be used, by encapsulating this iterator to create the chars. However, the only need for scala Reader[Char] was due to use of the scala combinator RegexParsers functionality, which is replaced by the lookingAt method above. The DFA stuff doesn't actually need a Reader[Char]. It would be happy with this iterator.)

The bit limit is Nope if there is no imposed limit other than end of data.

The bitLimit1b is the value of the first bitPos1b beyond the end of the data. Valid bit positions are less than, but not equal to, the bit limit.

If bitLimit0b is defined, then there IS that much data available at least.

Discards a mark. Old marks must be discarded when there is no possibility that a reset(...) to them will be needed. This reclaims any storage needed by the mark. (Think of it as popping the stack of marks back to, and including the supplied mark.)

Any mark newer than the supplied argument mark is also discarded.

Marks must be discarded because otherwise stack locations may grow slowly over time, but without limit (memory leak).

Fill a charBuffer with characters.

Returns the number of chars delivered. Nope if end of data stream.

The bit position is advanced to immediately after the representation of the delivered characters.

Set the position and limit of the char buffer if you want to retrieve only a small number of characters. For example, a single character can be retrieved if the char buffer has only one character remaining.

If the encodingErrorPolicy is 'error' and at least 1 character has been delivered into the char buffer, then this will return successfully, as if it stopped immediately before encountering a decoding error. If, however, zero characters have been delivered into the char buffer, then a decoding error will throw a CharacterCodingException or will be replaced by a Unicode replacement character.

Note that this is an exception to the way other methods of this API work in that an exception is thrown. It is generally expected that character decode errors are rare/exceptional situations.

If the encodingErrorPolicy is 'replace' then the result may contain Unicode replacement characters. The bit position is advanced to after the representation of all the characters, including after the non-decodable data bits that result in Unicode replacement character(s).

Note that the characters may be any width in bits including a variable width (such as for utf-8 which has from 1 to 4 bytes per character).

Retrieving text limited by size in bits or bytes can be achieved by setting the bitLimit to a position N bytes (or bits) greater than the current position, then calling this method with a charBuffer having sufficient capacity that the char buffer available size will not be reached before the bitLimit. Having performed the read, the bitLimit can then be restored to its prior value. See the withBitLengthLimit method.

In theory at least, this method can be used to do some parsing without ever allocating a string. E.g., checking for a specifc delimiter character. The pattern match can occur directly against the charbuffer to determine if the text matches the literal nil syntax. If so we set the nilled flag in the infoset element and never create a string.

The char buffer is not 'flipped' by this method. To read the characters that are placed into the char buffer by this method using relative getter calls the caller of this method must flip the char buffer.

When characters are not made up of complete bytes, but fragments of a byte, then when data ends in the middle of a byte, a character can be decoded from the partial-final byte, if enough bits are available from the prior byte and the partial final byte.

Implementation Note: a specialized 4-bit encoding which maps 4 bits to 0-9A-F can be used to treat packed decimal representations like text strings.

Float and Double

These are constructed per the currently set BinaryFloatRep.

Throws NotEnoughDataException if there are not 32 bits or 64 bits (respectively) available. Consider first calling isDefinedForLength before calling this in order to avoid the possibility of a throw.

Returns a byte array containing the bits between the current bit position and that position plus bitLengthFrom1.

The byte array result is constructed using the currently set bit order and byte order. The returned byte array is always in most significant bit first bit order and little endian byte ordr.

If the data stream does not have bitLengthFrom1 remaining bits, NotEnoughDataException is thrown. Calls should be preceded by calls to isDefinedForLength to check if sufficient bits are available. Alternatively one can catch the exception, but that is likely less performant.

Usage: The smallest value of bitLengthFrom1 is 1.

If the bitLengthFrom1 is not a multiple of 8, the final byte will be padded with zeros to make a full byte.

Constructs a big integer from the data. The current bit order and byte order are used.

The result will be negative if the most significant bit is set.

If the data stream does not have bitLengthFrom1 remaining bits, NotEnoughDataException is thrown. Calls should be preceded by calls to isDefinedForLength to check if sufficient bits are available. Alternatively one can catch the exception, but that is likely less performant.

If the bitLength is 1, then the value returned will be 1 or 0 depending on the bit value. That is, if there is only 1 bit, it is treated as non-negative.

Usage: The smallest value of bitLengthFrom1 is 1.

It is recommended that getSignedLong be used for any bit length 64 or less, as that method does not require a heap allocated object to represent the value.

Similar, but returns a negative value if the most-significant bit of the data is 1. That is, the most significant bit is treated as a twos-complement sign bit for the data.

If the bitLength is 1, then the value returned will be 1 or 0 depending on the bit value. That is, if there is only 1 bit, it is treated as non-negative.

If the bit length is 2 or greater, then the most significant bit will be interpreted as a sign bit for a twos-complement representation. (A 2-bit signed integer can represent the four values 1, 0, -1, -2 as bits 01, 00, 11, 10 respectively)

Usage: The maximum number of bits is 64.

If the data stream does not have bitLengthFrom1To64 remaining bits, NotEnoughDataException is thrown. Calls should be preceded by calls to isDefinedForLength to check if sufficient bits are available. Alternatively one can catch the exception, but that is likely less performant.

Returns One(string) if any (up to nChars) are available, Nope otherwise.

Throws a CharacterCodingException if the encoding error policy is 'error' and a decode error is detected within nChars.

Returns One(string) if nChars are available, Nope otherwise.

Throws a CharacterCodingException if the encoding error policy is 'error' and a decode error is detected within nChars.

Constructs a big integer from the data. The current bit order and byte order are used.

The result will never be negative.

If the data stream does not have bitLengthFrom1 remaining bits, NotEnoughDataException is thrown. Calls should be preceded by calls to isDefinedForLength to check if sufficient bits are available. Alternatively one can catch the exception, but that is likely less performant.

Usage: The smallest value of bitLengthFrom1 is 1.

It is recommended that getUnsignedLong be used for any bit length 64 or less, as that method does not require a heap allocated object to represent the value.

Returns a long integer containing the bits between the current bit position and that position plus the bitLength.

The long integer result is constructed using the currently set bit order and byte order. The returned value is always non-negative.

This call is expected to be used for extracting data for all unsigned integer types up to UnsignedLong with 64 bits length. Calling code converts into Byte, Short, or Int types if smaller size integers are required.

Usage: The bitLength must be between 1 and 64 inclusive.

If the data stream does not have bitLengthFrom1To64 remaining bits, NotEnoughDataException is thrown. Calls should be preceded by calls to isDefinedForLength to check if sufficient bits are available. Alternatively one can catch the exception, but that is likely less performant.

For assertion checking really. Optimizations should remove the need for most alignment operations. This can be used in assertions that check that this is working properly.

Note that the bitAlignment1b argument is 1-based.

Passing 0 as the argument is a usage error.

Passing 1 as the argument performs no alignment, as any bit position is 1-bit aligned.

Determines whether the input stream has this much more data.

Does not advance the position

Matches a regex Matcher against a prefix of the data stream.

Advances the stream to the bit position following the match.

If there is no match, the bit position is unchanged.

The matcher will be reset, possibly multiple times during this operation.

After this method returns, the matcher's hitEnd and requireEnd methods are interpreted relative to the end of the available data. See the definition of available data above.

Result is false if there is no match.

If the encodingErrorPolicy is 'error' then an attempt to match that encounters data which causes a decoding error will throw a CharacterCodingException.

Note that this is an exception to the way other methods of this API work in that an exception is thrown. It is generally expected that character decode errors are rare/exceptional situations.

Implementation Note: pre-buffering of data cannot cause these CharacterCodingExceptions. It is only when the pattern match actually must consume another character that the error is thrown.

This implementation will take advantage of the behavior of fillCharBuffer in that the matcher will consume data from a char buffer and see if a match can succeed completely before a decode error occurs. The match will only try to consume more if the matcher does not yet know if the match will succeed or fail, or the match could be longer if more data was available. So it is only when a match tries to consume more that it will encounter the decode error.

If the encodingErrorPolicy is 'replace' then the matching may encounter Unicode replacement characters, and these may be incorporated into a successful match. This has strong performance implications in that regular expressions like ".*" will match an unlimited length in the data stream. In the presence of backtracking this can result in large parts of the data stream being decoded multiple times.

A tuneable limit maximumRegexMatchLengthInCharacters can be set to limit the maximum size of a match. If this tunable maximum is hit, or an implementation specific absolute maximum is hit, then after return of this method the matcher will have the hitEnd and requireEnd values as if the end of the data stream had been reached.

This API does not use a CharBuffer because there is no way to avoid allocation of strings by the underlying Matcher and regular expression API upon which this is built.

Returns a mark value. It saves the current state of the input stream such that it can be restored by calling reset(mark).

The state includes the bit position, the bit limit, and all the other parts of the state for which there are setters.

Multiple calls to mark will create distinct mark values.

The requestorID argument is a string for debugging pool-management bugs. It identifies the code that is requesting the mark/reset. If resets are not done then at end of execution the non-reset requestorIDs are issued in an abort.

Implementation Note: A mark is probably just an integer offset into an array that is treated like a stack (top of stack at higher index value locations of the array). So marking and resetting does not need to imply allocating structures, though it could be implemented that way.

In other words marking and resetting do not imply allocation of objects.

Access to historic (past data) and upcoming data for purposes of display in a trace or debugger.

If areDebugging is false, these throw IllegalStateException

Returns number of bits remaining (if a limit is defined). Nope if not defined.

Resets the current state of the input stream to the position it had when the mark was created. All marks taken later than the mark argument are implicitly discarded. The mark passed as an argument is also discarded by this operation.

If the bit position has advanced from the mark far enough to exceed implementation defined maximum extent, or a tunable limit on the maximum extent, then the mark is referred to as an invalid mark. A call to reset to an invalid mark causes an IOException to be thrown.

Sets the bit limit to an absolute value and returns true. Returns false if the new bit limit is beyond the existing bit limit range.

Allow tuning of these thresholds and starting values. These could, in principle, be tuned differently for different elements, thereby keeping limits small when the schema component can be determined to only require small space, but enabling larger limits/starting values when a component has larger needs.

These could be cached on, say, the ElementRuntimeData object for each element, or some other kind of dynamic cache.

Advances the bit position by nBits. If nBits aren't available this returns false. Otherwise it returns true.

Skips N characters and returns true, adjusting the bitPos0b based on parsing them. Returns false if there is not enough data to skip all N characters.

Called once after each parse operation to verify final invariants for the implementation.

Use to perform checks such as that data structures held in pools are all returned before end of parse.

The byte position excludes any partial byte. So if the bit position is not on a byte boundary, then the byte position is as if the bit position was rounded down to the next byte boundary.

These are convenience methods only.

Convenience methods that temporarily set and (reliably) restore the bitLimit. The argument gives the limit length. Note this is a length, not a bit position.

This is added to the current bit position to get the limiting bit position which is then set as the bitLimit when the body is evaluated. On return the bit limit is restored to its prior value.

The return value is false if the new bit limit is beyond the existing bit limit range. Otherwise the return value is true.

The prior value is restored even if an Error/Exception is thrown. (ie., via a try-finally)

These are intended for use implementing specified-length types (simple or complex).

Note that length limits in lengthUnits Characters are not implemented this way. See fillCharBuffer(cb) method.