src Bool bytesEqual(Buf that)

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

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

src Charset charset

Character set for both the OutStream and InStream.

src This 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. Return this.

src Bool close()

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.

src Int crc(Str algorithm)

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.

src Buf dup()

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

src Void eachLine(|Str| f)

Convenience for in.eachLine

src Endian endian

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

src virtual override Bool equals(Obj? that)

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

src This fill(Int byte, Int times)

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

Examples:

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

src This flip()

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

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

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

src static Buf fromBase64(Str s)

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"

src 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"

src @Operator
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.

src @Operator
Buf getRange(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]

src Buf hmac(Str algorithm, Buf key)

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)

src InStream in()

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.

src Bool isEmpty()

Return if size() == 0.

src static new make(Int capacity := 1024)

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

src Bool more()

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

src OutStream out()

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.

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

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.

src Int? peek()

Convenience for in.peek

src Int? peekChar()

Convenience for in.peekChar

src Int pos()

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.

src This print(Obj? s)

Convenience for out.print Return this.

src This printLine(Obj? obj := "")

Convenience for out.printLine Return this.

src static Buf random(Int size)

Generate a random series of bytes.

Example:

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

src Int? read()

Convenience for in.read

src Buf readAllBuf()

Convenience for in.readAllBuf

src Str[] readAllLines()

Convenience for in.readAllLines

src Str readAllStr(Bool normalizeNewlines := true)

Convenience for in.readAllStr

src Bool readBool()

Convenience for in.readBool

src Int? readBuf(Buf buf, Int n)

Convenience for in.readBuf

src Buf readBufFully(Buf? buf, Int n)

Convenience for in.readBufFully

src Int? readChar()

Convenience for in.readChar

src Str readChars(Int n)

Convenience for in.readChars

src Decimal readDecimal()

Convenience for in.readDecimal

src Float readF4()

Convenience for in.readF4

src Float readF8()

Convenience for in.readF8

src Str? readLine(Int? max := 4096)

Convenience for in.readLine

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

Convenience for in.readObj

src Str:Str readProps()

Convenience for in.readProps

src Int readS1()

Convenience for in.readS1

src Int readS2()

Convenience for in.readS2

src Int readS4()

Convenience for in.readS4

src Int readS8()

Convenience for in.readS8

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

Convenience for in.readStrToken

src Int readU1()

Convenience for in.readU1

src Int readU2()

Convenience for in.readU2

src Int readU4()

Convenience for in.readU4

src Str readUtf()

Convenience for in.readUtf

src Int remaining()

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

src This 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.

src @Operator
This set(Int index, Int byte)

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.

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

src This sync()

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

src 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. 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"

src Str toBase64Uri()

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"

src Buf toDigest(Str algorithm)

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"

src File toFile(Uri uri)

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.

src Str toHex()

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"

src virtual override Str toStr()

Return string summary of the buffer.

src This trim()

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

src This unread(Int b)

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.

src This unreadChar(Int b)

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.

src This write(Int byte)

Convenience for out.write Return this.

src This writeBool(Bool b)

Convenience for out.writeBool Return this.

src This writeBuf(Buf buf, Int n := buf.remaining())

Convenience for out.writeBuf Return this.

src This writeChar(Int char)

Convenience for out.writeChar Return this.

src This writeChars(Str str, Int off := 0, Int len := str.size() - off)

Convenience for out.writeChars Return this.

src This writeDecimal(Decimal d)

Convenience for out.writeDecimal Return this.

src This writeF4(Float r)

Convenience for out.writeF4 Return this.

src This writeF8(Float r)

Convenience for out.writeF8 Return this.

src This writeI2(Int n)

Convenience for out.writeI2 Return this.

src This writeI4(Int n)

Convenience for out.writeI4 Return this.

src This writeI8(Int n)

Convenience for out.writeI8 Return this.

src This writeObj(Obj? obj, [Str:Obj]? options := null)

Convenience for out.writeObj Return this.

src This writeProps(Str:Str props)

Convenience for out.writeProps Return this.

src This writeUtf(Str s)

Convenience for out.writeUtf Return this.

src This writeXml(Str s, Int flags := 0)

Convenience for out.writeXml Return this.