Buf

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.

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

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.

Character set for both the OutStream and InStream.

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.

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.

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.

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

Convenience for in.eachLine

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

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

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

Examples:

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

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

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

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"

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

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]

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)

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.

Return if size() == 0.

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

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

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.

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.

Convenience for in.peek

Convenience for in.peekChar

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.

Convenience for out.print Return this.

Convenience for out.printLine Return this.

Generate a random series of bytes.

Example:

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

Convenience for in.read

Convenience for in.readAllBuf

Convenience for in.readAllLines

Convenience for in.readAllStr

Convenience for in.readBool

Convenience for in.readBuf

Convenience for in.readBufFully

Convenience for in.readChar

Convenience for in.readChars

Convenience for in.readDecimal

Convenience for in.readF4

Convenience for in.readF8

Convenience for in.readLine

Convenience for in.readObj

Convenience for in.readProps

Convenience for in.readS1

Convenience for in.readS2

Convenience for in.readS4

Convenience for in.readS8

Convenience for in.readStrToken

Convenience for in.readU1

Convenience for in.readU2

Convenience for in.readU4

Convenience for in.readUtf

Return the remaining number of bytes to read: size-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 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.

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.

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

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"

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"

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"

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.

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"

Return string summary of the buffer.

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

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.

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.

Convenience for out.write Return this.

Convenience for out.writeBool Return this.

Convenience for out.writeBuf Return this.

Convenience for out.writeChar Return this.

Convenience for out.writeChars Return this.

Convenience for out.writeDecimal Return this.

Convenience for out.writeF4 Return this.

Convenience for out.writeF8 Return this.

Convenience for out.writeI2 Return this.

Convenience for out.writeI4 Return this.

Convenience for out.writeI8 Return this.

Convenience for out.writeObj Return this.

Convenience for out.writeProps Return this.

Convenience for out.writeUtf Return this.

Convenience for out.writeXml Return this.