class sys::Buf

sys::Obj
  sys::Buf

Source

Buf is used to model a block of bytes with random access. Buf is typically backed by a block of memory, but can also be backed by a file:

Buf.make: backed by RAM
File.open: backed by random access file
File.mmap: backed by memory mapped file

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.

Memory bufs may be made immutable by calling Obj.toImmutable. When a buf is made immutable, the original buffer's data is cleared (to avoid copying the backing array). All write operations on an immutable buf will raise a ReadonlyErr. Reads may be performed by acquiring an InStream via the in method. However, read operations which require a mutable Buf pos will raise ReadonlyErr too, including methods such as seek or read. Use dup to copy an immutable buf back into a mutable buf.

bytesEqual

Bool bytesEqual(Buf that)

Source

Return if the buffer contents are the same size and same bytes. Note this could be an extremely expensive call for non-memory buffers.

capacity

Int capacity

Source

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. This method is ignored on a file buffer, and unsupported on mmap.

charset

Charset charset

Source

Character set for both the OutStream and InStream.

clear

This clear()

Source

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

close

Bool close()

Source

If this buffer is backed by a file, then close it. If a memory buffer then do nothing. This method is guaranteed to never throw an IOErr. Return true if the buffer was closed successfully or false if closed abnormally.

crc

Int crc(Str algorithm)

Source

Compute a cycle redundancy check code using this buffer's contents from 0 to size. The supported algorithm names:

"CRC-16": also known as CRC-16-ANSI, CRC-16-IBM; used by USB, ANSI X3.28, and Modbus
"CRC-32": used by Ethernet, MPEG-2, PKZIP, Gzip, PNG
"CRC-32-Adler": used by Zlib

Raise ArgErr if algorithm is not available. This method is only supported for memory based buffers.

dup

Buf dup()

Source

Create a new buffer in memory which deeply clones this buffer. The resulting buf is read/write.

eachLine

Void eachLine(|Str| f)

Source

Convenience for in.eachLine

endian

Endian endian

Source

Byte order mode for both OutStream and InStream. Default is Endian.big (network byte order).

equals

virtual override Bool equals(Obj? that)

Source

Buf equality is based on reference equality using the === operator.

fill

This fill(Int byte, Int times)

Source

Write the specified byte to the end of the buffer using given count.

Examples:

Buf().fill(0xff, 4)  =>  0xffffffff

flip

This flip()

Source

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

flush

@Deprecated { msg="Use sync" } This flush()

Source

Obsolete call to sync. In the future this method may be relaxed to flush only memory buffers, but not force an fsync.

fromBase64

static Buf fromBase64(Str s)

Source

Decode the specified Base64 string into its binary contents. Both MIME RFC 2045 and URI-safe RFC 4648 encodings are supported. 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)

Source

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

@Operator Int get(Int index)

Source

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.

getRange

@Operator Buf getRange(Range range)

Source

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]

hmac

Buf hmac(Str algorithm, Buf key)

Source

Generate an HMAC message authentication as specified by RFC 2104. This buffer is the data input, algorithm specifies the hash digest, and key represents the secret key:

H: specified by algorthim parameter - "MD5" or "SHA1"
K: secret key specified by key parameter
B: fixed at 64
text: this instance

The HMAC is computed using:

ipad = the byte 0x36 repeated B times
opad = the byte 0x5C repeated B times
H(K XOR opad, H(K XOR ipad, text))

Throw ArgErr if the algorithm is not available. This method is only supported for memory buffers.

Examples:

"hi there".toBuf.hmac("MD5", "secret".toBuf)

in

InStream in()

Source

Get the InStream which reads from this buffer. This method always returns the same instance. If this buffer is backed by a file, then in.close will not close the file - you must use Buf.close.

isEmpty

Bool isEmpty()

Source

Return if size() == 0.

make

static new make(Int capacity := 1024)

Source

Allocate a byte buffer in RAM with the initial given capacity.

more

Bool more()

Source

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

out

OutStream out()

Source

Get the OutStream which writes to this buffer. This method always returns the same instance. If this buffer is backed by a file, then out.close will not close the file - you must use Buf.close.

pbk

static Buf pbk(Str algorithm, Str password, Buf salt, Int iterations, Int keyLen)

Source

Generate a password based cryptographic key. Supported algorithms:

"PBKDF2WithHmacSHA1"
"PBKDF2WithHmacSHA256"

Parameters:

password: secret used to generate resulting cryptographic key
salt: cryptographic salt
iterations: number of iterations (the c term)
keyLen: desired length of key in bytes (not bits!)

Throw ArgErr if the algorithm is not available. This method is only supported for memory buffers.

peek

Int? peek()

Source

Convenience for in.peek

peekChar

Int? peekChar()

Source

Convenience for in.peekChar

pos

Int pos()

Source

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

print

This print(Obj? s)

Source

Convenience for out.print Return this.

printLine

This printLine(Obj? obj := "")

Source

Convenience for out.printLine Return this.

random

static Buf random(Int size)

Source

Generate a random series of bytes.

Example:

Buf.random(8).toHex  => "d548b54989028b90"

read

Int? read()

Source

Convenience for in.read

readAllBuf

Buf readAllBuf()

Source

Convenience for in.readAllBuf

readAllLines

Str[] readAllLines()

Source

Convenience for in.readAllLines

readAllStr

Str readAllStr(Bool normalizeNewlines := true)

Source

Convenience for in.readAllStr

readBool

Bool readBool()

Source

Convenience for in.readBool

readBuf

Int? readBuf(Buf buf, Int n)

Source

Convenience for in.readBuf

readBufFully

Buf readBufFully(Buf? buf, Int n)

Source

Convenience for in.readBufFully

readChar

Int? readChar()

Source

Convenience for in.readChar

readChars

Str readChars(Int n)

Source

Convenience for in.readChars

readDecimal

Decimal readDecimal()

Source

Convenience for in.readDecimal

readF4

Float readF4()

Source

Convenience for in.readF4

readF8

Float readF8()

Source

Convenience for in.readF8

readLine

Str? readLine(Int? max := 4096)

Source

Convenience for in.readLine

readObj

Obj? readObj([Str:Obj]? options := null)

Source

Convenience for in.readObj

readProps

Str:Str readProps()

Source

Convenience for in.readProps

readS1

Int readS1()

Source

Convenience for in.readS1

readS2

Int readS2()

Source

Convenience for in.readS2

readS4

Int readS4()

Source

Convenience for in.readS4

readS8

Int readS8()

Source

Convenience for in.readS8

readStrToken

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

Source

Convenience for in.readStrToken

readU1

Int readU1()

Source

Convenience for in.readU1

readU2

Int readU2()

Source

Convenience for in.readU2

readU4

Int readU4()

Source

Convenience for in.readU4

readUtf

Str readUtf()

Source

Convenience for in.readUtf

remaining

Int remaining()

Source

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

seek

This seek(Int pos)

Source

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

@Operator This set(Int index, Int byte)

Source

Set is used to overwrite the byte at the specified 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

Int size

Source

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. A mmap buffer can never be increased from its initial size.

sync

This sync()

Source

If this Buf is backed by a file, then fsync all changes to the storage device. Throw IOErr on error. Return this.

toBase64

Str toBase64()

Source

Encode the buffer contents from 0 to size to a Base64 string as defined by MIME RFC 2045. No line breaks are added. This method is only supported by memory-backed buffers; file-backed buffers will throw UnsupportedErr.

Example:

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

toBase64Uri

Str toBase64Uri()

Source

Encode the buffer contents from 0 to size to a Uri-safe Base64 string as defined by RFC 4648. This means + is encoded as -, and / is encoded as _. Additionally, no padding is applied. This method is only supported by memory-backed buffers; file-backed buffers will throw UnsupportedErr.

Example:

Buf.make.print("safe base64~~").toBase64    => "c2FmZSBiYXNlNjR+fg=="
Buf.make.print("safe base64~~").toBase64Uri => "c2FmZSBiYXNlNjR-fg"

toDigest

Buf toDigest(Str algorithm)

Source

Apply the specified message digest algorithm 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 available via the java.security.MessageDigest API. Throw ArgErr if the algorithm is not available. This method is unsupported for mmap buffers.

Example:

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

toFile

File toFile(Uri uri)

Source

Create an in-memory File instance for this buffer with the given file URI. The buffer must be a RAM based buffer which is converted to an immutable buffer via Obj.toImmutable semantics. The current time is used for the file's modified time.

toHex

Str toHex()

Source

Encode the buffer contents from 0 to size into a hexadecimal string. This method is unsupported for mmap buffers.

Example:

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

toStr

virtual override Str toStr()

Source

Return string summary of the buffer.

trim

This trim()

Source

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

unread

This unread(Int b)

Source

Convenience for in.unread Memory backed buffers support a stack based pushback model like IO streams. File backed buffers will simply rewrite the last position in the file. Return this.

unreadChar

This unreadChar(Int b)

Source

Convenience for in.unreadChar Memory backed buffers support a stack based pushback model like IO streams. File backed buffers will simply rewrite the last position in the file. Return this.

write