logo

class

sys::Buf

sys::Obj
  sys::Buf

Buf is used to model a buffer of bytes with random access. Buf is typically backed by a block of memory. Buf provides an InStream and OutStream to read and write into the buffer using a configurable position accessed via Buf.pos and Buf.seek.

When using an InStream, bytes are read starting at pos where pos is advanced after each read. The end of stream is reached when pos reaches size. When using the OutStream, bytes are written starting at pos with pos advanced after each write. If pos is less then size then the existing bytes are rewritten and size is not advanced, otherwise the buffer is automatically grown and size is advanced as bytes are appended. It is common to write bytes into the buffer using the OutStream, then call Buf.flip to prepare the buffer to be used for reading.

Slots

capacity

virtual Int capacity

The number of bytes this buffer can hold without allocating more memory. Capacity is always greater or equal to size. If adding a large number of bytes, it may be more efficient to manually set capacity. See the trim() method to automatically set capacity to size. Throw ArgErr if attempting to set capacity less than size.

charset

Charset charset

Character set for both the OutStream and InStream.

clear

Buf clear()

Read the buffer for a fresh read by reseting the buffer's pos and size to zero. The buffer's capacity remains the same.

eachLine

Void eachLine(|Str| f)

Convenience for in.eachLine

empty

Bool empty()

Return if size() == 0.

equals

override Bool equals(Obj that)

Two Bufs are equal if they have string of bytes.

flip

virtual Buf flip()

Flip a buffer from write-mode to read-mode. This method sets total size to current position, and position to 0. Return this.

fromBase64

static Buf fromBase64(Str s)

Decode the specified Base64 string into its binary contents as defined by MIME RFC 2045. Any characters which are not included in the Base64 character set are safely ignored.

Example:

Buf.make.print("Fan").toBase64  -> "RmFu"
Buf.fromBase64("RmFu").readAllStr -> "Fan"
fromHex

static Buf fromHex(Str s)

Decode the specified hexadecimal string into its binary contents. Any characters which are not included in the set "0-9, a-f, A-F" are ignored as long as they appear between bytes (hi and lo nibbles must be contiguous).

Example:

Buf.make.print("\r\n").toHex   -> "0d0a"
Buf.fromHex("0d0a").readAllStr -> "\r\n"
get

virtual Int get(Int index)

Get the byte at the specified absolute index. A negative index may be used to access from the end of the buffer. For example get(-1) is translated into get(size()-1). This method accesses the buffer absolutely independent of current position. The get method is accessed via the [] shortcut operator. Throw IndexErr if index out of range.

hash

override Int hash()

Return hash code based on string of bytes.

in

InStream in()

Get the InStream which reads from this buffer. This method always returns the same instance.

make

new make(Int capacity := def)

Make a byte buffer with the initial given capacity.

more

virtual Bool more()

Return if more bytes are available to read: remaining() > 0.

out

OutStream out()

Get the OutStream which writes to this buffer. This method always returns the same instance.

peek

Int peek()

Convenience for in.peek

peekChar

Int peekChar()

Convenience for in.peekChar

pos

virtual Int pos()

Return the current position for the next read or write. The position is always between 0 and size(). If pos is less then size then future writes will rewrite the existing bytes without growing size.

print

Buf print(Obj s)

Convenience for out.print Return this.

printLine

Buf printLine(Obj obj := def)

Convenience for out.printLine Return this.

read

Int read()

Convenience for in.read

readAllBuf

Buf readAllBuf()

Convenience for in.readAllBuf

readAllLines

Str[] readAllLines()

Convenience for in.readAllLines

readAllStr

Str readAllStr(Bool normalizeNewlines := def)

Convenience for in.readAllStr

readBool

Bool readBool()

Convenience for in.readBool

readBuf

Int readBuf(Buf buf, Int n)

Convenience for in.readBuf

readBufFully

Buf readBufFully(Buf buf, Int n)

Convenience for in.readBufFully

readChar

Int readChar()

Convenience for in.readChar

readF4

Float readF4()

Convenience for in.readF4

readF8

Float readF8()

Convenience for in.readF8

readLine

Str readLine(Int max := def)

Convenience for in.readLine

readObj

Obj readObj()

Convenience for in.readObj

readS1

Int readS1()

Convenience for in.readS1

readS2

Int readS2()

Convenience for in.readS2

readS4

Int readS4()

Convenience for in.readS4

readS8

Int readS8()

Convenience for in.readS8

readStrToken

Str readStrToken(Int max := def, |Int -> Bool| c := def)

Convenience for in.readStrToken

readU1

Int readU1()

Convenience for in.readU1

readU2

Int readU2()

Convenience for in.readU2

readU4

Int readU4()

Convenience for in.readU4

readUtf

Str readUtf()

Convenience for in.readUtf

remaining

virtual Int remaining()

Return the remaining number of bytes to read: size-pos.

seek

virtual Buf seek(Int pos)

Set the current position to the specified byte offset. A negative index may be used to access from the end of the buffer. For example seek(-1) is translated into seek(size-1). Return this.

set

virtual Buf set(Int index, Int byte)

Set is used to overwrite the byte at the specified the index. A negative index may be used to access an index from the end of the buffer. The set method is accessed via the []= shortcut operator. Return this. Throw IndexErr if index is out of range.

size

virtual Int size

Return the total number of bytes in the buffer. If the size is set greater than capacity then the buffer's capacity is automatically grown, otherwise capacity remains the same. Setting size does not actually change any bytes in the buffer.

slice

virtual Buf slice(Range range)

Return a new buffer containing the bytes in the specified absolute range. Negative indexes may be used to access from the end of the buf. This method accesses the buffer absolutely independent of current position. This method is accessed via the [] operator. Throw IndexErr if range illegal.

Examples:

buf := Buf.make
buf.write(0xaa).write(0xbb).write(0xcc).write(0xdd)
buf[0..2]   -> 0x[aabbcc]
buf[3..3]   -> 0x[dd]
buf[-2..-1] -> 0x[ccdd]
buf[0...2]  -> 0x[aabb]
buf[1..-2]  -> 0x[bbcc]
toBase64

Str toBase64()

Encode the buffer contents from 0 to size to a Base64 string as defined by MIME RFC 2045. No line breaks are added.

Example:

Buf.make.print("Fan").toBase64  -> "RmFu"
Buf.fromBase64("RmFu").readAllStr -> "Fan"
toDigest

Buf toDigest(Str algorithm)

Apply the specified message digest algorthm to this buffer's contents from 0 to size and return the resulting hash. Digests are secure one-way hash functions which input an arbitrary sized buffer and return a fixed sized buffer. Common algorithms include: "MD5", "SHA-1", and "SHA-256"; the full list supported is platform dependent. On the Java VM, the algorithm maps to those avaialble via the java.security.MessageDigest API. Throw ArgErr if the algorithm is not available.

Example:

Buf.make.print("password").print("salt").toDigest("MD5").toHex
 ->  "b305cadbb3bce54f3aa59c64fec00dea"
toHex

Str toHex()

Encode the buffer contents from 0 to size into a hexadecimal string.

Example:

Buf.make.print("\r\n").toHex   -> "0d0a"
Buf.fromHex("0d0a").readAllStr -> "\r\n"
toStr

override Str toStr()

Return hex string of bytes.

trim

Buf trim()

Trim the capacity such that the underlying storage is optimized for the current size. Return this.

unread

Buf unread(Int b)

Convenience for in.unread Return this.

unreadChar

Buf unreadChar(Int b)

Convenience for in.unreadChar Return this.

write

Buf write(Int byte)

Convenience for out.write Return this.

writeBool

Buf writeBool(Bool b)

Convenience for out.writeBool Return this.

writeBuf

Buf writeBuf(Buf buf, Int n := def)

Convenience for out.writeBuf Return this.

writeChar

Buf writeChar(Int char)

Convenience for out.writeChar Return this.

writeChars

Buf writeChars(Str str, Int off := def, Int len := def)

Convenience for out.writeChars Return this.

writeF4

Buf writeF4(Float r)

Convenience for out.writeF4 Return this.

writeF8

Buf writeF8(Float r)

Convenience for out.writeF8 Return this.

writeI2

Buf writeI2(Int n)

Convenience for out.writeI2 Return this.

writeI4

Buf writeI4(Int n)

Convenience for out.writeI4 Return this.

writeI8

Buf writeI8(Int n)

Convenience for out.writeI8 Return this.

writeObj

Buf writeObj(Obj obj, Str:Obj options := def)

Convenience for out.writeObj Return this.

writeUtf

Buf writeUtf(Str s)

Convenience for out.writeUtf Return this.