type
Buf
class Buf : Obj
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 RAMFile.open
: backed by random access fileFile.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 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, reads 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.
constructors
make |
Allocate a byte buffer in RAM with the initial given capacity. |
---|
fields
capacity |
The number of bytes this buffer can hold without allocating more memory. |
---|---|
charset |
Character set for both the OutStream and InStream. |
endian |
Byte order mode for both OutStream and InStream. |
size |
Return the total number of bytes in the buffer. |
methods
bytesEqual |
Return if the buffer contents are the same size and same bytes. |
---|---|
clear |
Read the buffer for a fresh read by reseting the buffer's pos and size to zero. |
close |
If this buffer is backed by a file, then close it. |
crc |
Compute a cycle reduancy check code using this buffer's contents from 0 to size. |
dup |
Create a new buffer in memory which deeply clones this buffer. |
eachLine |
Convenience for |
equals |
Buf equality is based on reference equality using the === operator. |
fill |
Write the specified byte to the end of the buffer using given count. |
flip |
Flip a buffer from write-mode to read-mode. |
flush |
Obsolete call to |
fromBase64 |
Decode the specified Base64 string into its binary contents. |
fromHex |
Decode the specified hexadecimal string into its binary contents. |
get |
Get the byte at the specified absolute index. |
getRange |
Return a new buffer containing the bytes in the specified absolute range. |
hmac |
Generate an HMAC message authentication as specified by RFC 2104. |
in |
Get the InStream which reads from this buffer. |
isEmpty |
Return if size() == 0. |
more |
Return if more bytes are available to read: remaining() > 0. |
out |
Get the OutStream which writes to this buffer. |
pbk |
Generate a password based cryptographic key. |
peek |
Convenience for |
peekChar |
Convenience for |
pos |
Return the current position for the next read or write. |
Convenience for |
|
printLine |
Convenience for |
random |
Generate a random series of bytes. |
read |
Convenience for |
readAllBuf |
Convenience for |
readAllLines |
Convenience for |
readAllStr |
Convenience for |
readBool |
Convenience for |
readBuf |
Convenience for |
readBufFully |
Convenience for |
readChar |
Convenience for |
readChars |
Convenience for |
readDecimal |
Convenience for |
readF4 |
Convenience for |
readF8 |
Convenience for |
readLine |
Convenience for |
readObj |
Convenience for |
readProps |
Convenience for |
readS1 |
Convenience for |
readS2 |
Convenience for |
readS4 |
Convenience for |
readS8 |
Convenience for |
readStrToken |
Convenience for |
readU1 |
Convenience for |
readU2 |
Convenience for |
readU4 |
Convenience for |
readUtf |
Convenience for |
remaining |
Return the remaining number of bytes to read: size-pos. |
seek |
Set the current position to the specified byte offset. |
set |
Set is used to overwrite the byte at the specified the index. |
sync |
If this Buf is backed by a file, then fsync all changes to the storage device. |
toBase64 |
Encode the buffer contents from 0 to size to a Base64 string as defined by MIME RFC 2045. |
toBase64Uri |
Encode the buffer contents from 0 to size to a Uri-safe Base64 string as defined by RFC 4648. |
toDigest |
Apply the specified message digest algorthm to this buffer's contents from 0 to size and return the resulting hash. |
toFile |
Create an in-memory File instance for this buffer with the given file URI. |
toHex |
Encode the buffer contents from 0 to size into a hexadecimal string. |
toStr |
Return string summary of the buffer. |
trim |
Trim the capacity such that the underlying storage is optimized for the current size. |
unread |
Convenience for |
unreadChar |
Convenience for |
write |
Convenience for |
writeBool |
Convenience for |
writeBuf |
Convenience for |
writeChar |
Convenience for |
writeChars |
Convenience for |
writeDecimal |
Convenience for |
writeF4 |
Convenience for |
writeF8 |
Convenience for |
writeI2 |
Convenience for |
writeI4 |
Convenience for |
writeI8 |
Convenience for |
writeObj |
Convenience for |
writeProps |
Convenience for |
writeUtf |
Convenience for |
writeXml |
Convenience for |
Slot Details
bytesEqual
capacity
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.
charset
Charset charset
Character set for both the OutStream and InStream.
clear
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.
close
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.
crc
Compute a cycle reduancy 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 is algorithm is not available. This method is only supported for memory based buffers.
dup
Buf dup()
Create a new buffer in memory which deeply clones this buffer. The resulting buf is read/write.
eachLine
Convenience for in.eachLine
endian
Endian endian
Byte order mode for both OutStream and InStream. Default is Endian.big
(network byte order).
equals
fill
flip
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.
flush
@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.
fromBase64
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
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
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)
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)
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 parameterB
: fixed at 64text
: 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
isEmpty
Bool isEmpty()
Return if size() == 0.
make
static new make(Int capacity := 1024)
Allocate a byte buffer in RAM with the initial given capacity.
more
Bool more()
Return if more bytes are available to read: remaining() > 0.
out
pbk
static Buf pbk(Str algorithm, Str password, Buf salt, Int iterations, Int keyLen)
Generate a password based cryptographic key. Supported algoriths:
- "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
peekChar
Int? peekChar()
Convenience for in.peekChar
pos
printLine
This printLine(Obj? obj := "")
Convenience for out.printLine
Return this.
random
read
readAllBuf
Buf readAllBuf()
Convenience for in.readAllBuf
readAllLines
Str[] readAllLines()
Convenience for in.readAllLines
readAllStr
Str readAllStr(Bool normalizeNewlines := true)
Convenience for in.readAllStr
readBool
Bool readBool()
Convenience for in.readBool
readBuf
Convenience for in.readBuf
readBufFully
Buf readBufFully(Buf? buf, Int n)
Convenience for in.readBufFully
readChar
Int? readChar()
Convenience for in.readChar
readChars
Convenience for in.readChars
readDecimal
Decimal readDecimal()
Convenience for in.readDecimal
readF4
readF8
readLine
Str? readLine(Int? max := 4096)
Convenience for in.readLine
readObj
Obj? readObj([Str:Obj]? options := null)
Convenience for in.readObj
readProps
Convenience for in.readProps
readS1
readS2
readS4
readS8
readStrToken
Str? readStrToken(Int? max := null, |Int->Bool|? c := null)
Convenience for in.readStrToken
readU1
readU2
readU4
readUtf
Str readUtf()
Convenience for in.readUtf
remaining
Int remaining()
Return the remaining number of bytes to read: size-pos.
seek
set
size
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.
sync
This sync()
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()
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()
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
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. This method is unsupported for mmap buffers.
Example:
Buf.make.print("password").print("salt").toDigest("MD5").toHex => "b305cadbb3bce54f3aa59c64fec00dea"
toFile
toHex
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"
toStr
virtual override Str toStr()
Return string summary of the buffer.
trim
This trim()
Trim the capacity such that the underlying storage is optimized for the current size. Return this.
unread
unreadChar
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
writeBool
Convenience for out.writeBool
Return this.
writeBuf
This writeBuf(Buf buf, Int n := buf.remaining())
Convenience for out.writeBuf
Return this.
writeChar
Convenience for out.writeChar
Return this.
writeChars
This writeChars(Str str, Int off := 0, Int len := str.size() - off)
Convenience for out.writeChars
Return this.
writeDecimal
Convenience for out.writeDecimal
Return this.
writeF4
Convenience for out.writeF4
Return this.
writeF8
Convenience for out.writeF8
Return this.
writeI2
Convenience for out.writeI2
Return this.
writeI4
Convenience for out.writeI4
Return this.
writeI8
Convenience for out.writeI8
Return this.
writeObj
This writeObj(Obj? obj, [Str:Obj]? options := null)
Convenience for out.writeObj
Return this.
writeProps
This writeProps(Str:Str props)
Convenience for out.writeProps
Return this.
writeUtf
Convenience for out.writeUtf
Return this.
writeXml
This writeXml(Str s, Int flags := 0)
Convenience for out.writeXml
Return this.