ByteStream

open class ByteStream : StreamBase, @unchecked Sendable

Abstract base class for byte streams.

  • Immutable empty byte stream, for which readByte will always return -1.

    Declaration

    Swift

    public static let empty: ByteStream

  • Immutable empty byte stream (representing the case where there is no stream available), for which readByte will always return -1.

    See also

    empty.

    Declaration

    Swift

    public static let none: ByteStream

  • Default initializer.

    Declaration

    Swift

    override public init()

  • On platforms where the binary type is a mutable array, enable an optimization where the buffer used for the default implementation of readBinary (which calls readByte in a loop) can reuse and return the internal buffer’s internal array (across multiple readBinary calls). If enabling this optimization, be aware that multiple readBinary calls can return the same array. Currently applicable only to C# and Java, and otherwise ignored.

    Declaration

    Swift

    open func allowReadBinaryToReuseBufferInternalArray()

  • Assuming this stream is a UTF-8 byte stream, map it to a character stream (of UTF-16 code units).

    Declaration

    Swift

    open func asText() -> CharStream

    Return Value

    New character stream, which reads from this UTF-8 byte stream and converts to UTF-16 code units.

  • Does this stream support undoRead?

    See also

    withUndo.

    Declaration

    Swift

    open var canUndo: Bool { get }

  • Close this stream. Automatically calls flush before closing. This function can be safely called if the stream is already closed.

    Declaration

    Swift

    override open func close() throws

  • Copy all remaining data until the end of this stream into a target stream, then close this stream. Also propagate the entityTag and mediaType of this stream into the target stream.

    Declaration

    Swift

    open func copyTo(target: ByteStream, closeTarget: Bool = true) throws

    Parameters

    target

    Output stream.
    closeTarget

    Close target stream? (defaults to true)

  • Copy all remaining data until the end of the stream into a file, then close this stream.

    Declaration

    Swift

    open func copyToFile(_ file: String) throws

    Parameters

    file

    Output file name.

  • Data type with a DataType.code of DataType.BYTE_STREAM.

    Declaration

    Swift

    override open var dataType: DataType { get }

  • Declaration

    Swift

    open class func fileWriter(file: String) throws -> ByteStream

    Parameters

    file

    Output file name.

    Return Value

    A stream that will write the contents of a data file.

  • Declaration

    Swift

    open class func fromBinary(data: Data, offset: Int = (0 as Int), length: Int = (2147483647 as Int)) -> ByteStream

    Parameters

    data

    Source data.
    offset

    Starting offset (zero-based).
    length

    Maximum number of bytes to read.

    Return Value

    A new stream for reading from a binary value.

  • Declaration

    Swift

    open class func fromFile(_ file: String) throws -> ByteStream

    Parameters

    file

    Input file name.

    Return Value

    A stream that will read the contents of a data file.

  • Declaration

    Swift

    open class func fromStream(_ stream: StreamBase) -> ByteStream

    Parameters

    stream

    Underlying stream.

    Return Value

    stream (if stream is a ByteStream) or ByteStream.fromText(stream) (if stream is a CharStream).

  • Declaration

    Swift

    open class func fromText(stream: CharStream) -> ByteStream

    Parameters

    stream

    Underlying character stream.

    Return Value

    A new UTF-8 byte stream which reads from an underlying UTF-16 character stream.

  • Read all remaining data until the end of the stream, then close this stream. Caution: this function loads all stream content into memory at once. Consider reading a chunk-at-a-time in a loop, using readBinary.

    Declaration

    Swift

    open func readAndClose() throws -> Data

    Return Value

    The remaining data.

  • Read up to length bytes from this stream (may read less, even if the end of stream is not reached).

    Declaration

    Swift

    open func readBinary(length: Int = (20000 as Int)) throws -> Data?

    Parameters

    length

    Maximum number of bytes to read (must be greater than zero). Defaults to 20,000.

    Return Value

    Binary value with at most length bytes, or nil if there is no remaining data in the stream.

  • Read a single byte from this stream.

    Declaration

    Swift

    open func readByte() throws -> Int

    Return Value

    Unsigned integer equivalent of the byte read, or -1 at end of stream.

  • Declaration

    Swift

    open class func toBuffer(_ buffer: ByteBuffer) -> ByteStream

    Parameters

    buffer

    Buffer to be written to.

    Return Value

    A new byte stream which writes to a provided buffer.

  • Convert this data value to a string. If the dataType is defined by XML Schema Part 2: Datatypes, then the corresponding lexical format is used. JSON format is used for structured values (arrays and objects).

    Declaration

    Swift

    override open func toString() -> String

    Return Value

    Lexical representation of this data value.

  • Data type code of the wrapped value, equivalent to dataType.code.

    Declaration

    Swift

    override open var typeCode: Int { get }

  • Undo read of one byte.

    Throws

    DataStreamException if undo is not supported by this stream.

    Declaration

    Swift

    open func undoRead(_ value: Int) throws

    Parameters

    value

    Byte value that was previously read by the caller and is to be made available to read again.

  • Fluent API to set the mediaType for this stream.

    Declaration

    Swift

    open func withType(_ type: String?) -> ByteStream

    Parameters

    type

    Media type.

    Return Value

    This stream.

  • See also

    canUndo.

    Declaration

    Swift

    open func withUndo() throws -> ByteStream

    Return Value

    A wrapper (if needed) of this stream supporting undoRead, or this stream if it already supports undoRead.

  • Write to this stream the portion of data from the specified offset with the specified length.

    Declaration

    Swift

    open func writeBinary(data: Data) throws

    Parameters

    data

    Source data.

  • Write a single byte to this stream.

    Declaration

    Swift

    open func writeByte(_ value: Int) throws

    Parameters

    value

    Byte value to be written.