Binary Variables¶
/bread¶
Added in 1.9.0
/bread [-ta] <filename> <S> <N> <&binvar>
Reads <N> bytes starting at byte position <S> in the file and stores the result in &binvar.
Switches
-t - reads data until the next $crlf or EOF.
-a - Disables UTF-8 encoding of characters in the range 0-255, as long as the line contains no characters > 255.
Parameters
<filename> - The binary file to read.
<S> - The byte position in the file to start reading from.
<N> - Number of bytes to read.
<&binvar> - The &binvar to read the data into.
Example
;noop $example(FileA, FileB)
alias example {
;Read the whole file into a binary variable
bread $qt($1) 0 $file($1).size &tempFile
;Write the bytes form the binary variable to a file
bwrite $qt($2) 0 -1 &tempFile
}
/bwrite¶
Added in 1.9.0
/bwrite [-ta] <filename> <S> [N] <text|%var|&binvar>
Writes [N] bytes from <text|%var|&binvar> to the file starting at byte position <S> or 0, any existing information at this position is overwritten.
Switches
-t - Treat <text|%var|&binvar> as plain text.
-a - TODO
Parameters
<filename> - File to modify.
<S> - Byte position in the file to start writing to.
[N] - Byte count from <text|%var|&binvar> to write.
<text|%var|&binvar> - Text/%variable/&binvar to write to file.
Example
alias example {
;Write some text to a file at beginning of the file
/bwrite file.txt 0 hello there!
;Read the binary data into binary variable &tempfile
/bread $qt(file.txt) 0 $file(file.txt).size &tempfile
;Print the binary variable data as text, outputs 'Hello there!'
echo -ag $bvar(&tempfile, 1-).text
;Replace "there!" with "world!"
/bwrite file.txt 6 world!
;Read the binary data into binary variable &tempfile
/bread $qt(file.txt) 0 $file(file.txt).size &tempfile
;Print the binary variable data as text, outputs 'Hello world!'
echo -ag $bvar(&tempfile, 1-).text
}
/bset¶
Added in 1.9.0
/bset [-ta] <&binvar> <N> <asciivalue> [asciivalue ... asciivalue]
Sets the <N>th byte in binary variable &binvar to the specified ascii value.
If the &binvar docent exists it is created.
If <N> is larger than the size of &binvar it will be zero filled up to <N> bytes.
If you specify multiple ASCII values, they are copied to successive positions after byte position N.
Switches
-t - Treat values a plain text.
-a - Disables UTF-8 encoding of characters in the range 0-255, as long as the line contains no characters > 255.
Parameters
<&binvar> - The &binvar to modify.
<N> - The byte to modify.
<asciivalue> - The ASCII value to insert.
Example
alias example {
; Create a binary variable set it to "This is fun!"
bset -t &Example 1 This is fun!
; Print out the content of the variable
echo -a $bvar(&Example, 1-).text
}
/bunset¶
Added in 1.9.0
/bunset <&binvar> [&binvar ... &binvar]
Unsets the specified list of &binvars.
Parameters
<&binvar> - The &binvar to unset.
[&binvar ... &binvar] - Additional &binvars to unset.
/bcopy¶
Added in 1.9.0
/bcopy [-zc] <&binvar> <N> <&binvar> <S> <M>
Copies <M> bytes from position <S> in the second &binvar to the first &binvar at position <N>.
This can also be used to copy overlapping parts of a &binvar to itself.
Switches
-z - The bytes in the second &binvar that is copied are zero-filled after the copy.
-c - The first &binvar is chopped to <N> + <M>.
Parameters
<&binvar> - Target &binvar to copy to.
<N> - Target position in the first &binvar to copy to.
<&binvar> - Source &binvar to copy from.
<S> - Source position to copy from.
<M> - Number of bytes to copy.
Example
alias /example {
;Create a binary variable and assign it some text
bset -t &example 1 This is a test!
;Copy from 'example' from the 11th byte 10 bytes onward
;Zero-fill the part that was copied
bcopy -z &example2 1 &example 11 10
;Print out &example's content (up to the first null)
echo -a $bvar(&example, 1-).text
;Print out &example2's content
echo -a $bvar(&example2, 1-).text
}
/breplace¶
Added in 1.9.0
/breplace <&binvar> <oldvalue> <newvalue> [oldvalue newvalue...]
Replaces all matching ASCII values in &binvar with new values.
Multiple values can be replaced by adding more old/new parameters.
Parameters
<&binvar>- The &binvar to modify.
<oldvalue> - ASCII value to replace.
<newvalue> - ASCII value to insert.
Example
alias example {
;Create a binary variable set it to "Hello World"
bset -t &Example 1 Hello World
;Replace e (ASCII value 101) with 3 (ASCII value 51)
breplace &Example 101 51
;Echo our new string
echo -a $bvar(&Example,1,$bvar(&Example,0)).text
}
/btrunc¶
Added in 1.9.0
/btrunc <filename> <bytes>
Truncates/extends a file to the specified length.
Parameters
<filename> - The file to truncate.
<bytes> - Number of bytes to truncate/extend to.
Example
alias example {
;Create variable %temp and add some data.
/var %temp = Hello! World
;Write to variable %temp's content.
/bwrite Example 0 $len(%temp) %temp
;Truncate the file down to 6 bytes.
/btrunc Example 6
;Read the file into a variable.
/bread Example 0 $file(Example).size &Example
;Print out the variable's content.
/echo -a $bvar(&Example,1,$bvar(&Example,0)).text
;Delete the file.
/remove Example
}
$bvar¶
Added in 1.9.0
$bvar(&binvar,N,M)
Returns M ASCII values from a &binvar starting from the Nth byte.
N-N2 can be used to get a range of ASCII values.
N- can be used to get all ASCII values from position N.
Parameters
&binvar - The &binvar to use.
N - Position to start retrieving bytes.
M - Numbers of bytes to get.
Properties
.text - Returns plain text instead of ASCII values.
.word - TODO
.nword - TODO
.long - TODO
.nlong - TODO
Example
; Returns the length of the binary variable. //echo -ag $bvar(&binvar,0) ; Returns ASCII value at position N. //echo -ag $bvar(&binvar,1) ; Returns ASCII values from 5 to 8. //echo -ag $bvar(&binvar,5,3) ; Returns ASCII values from 5 to end. //echo -ag $bvar(&binvar,5-) ; Returns plain text from 5 to 8 up to the first zero character. //echo -ag $bvar(&binvar,5,3).text ; Returns &binvar if the binvar exists. //echo -ag $bvar(&binvar)
$bfind¶
Added in 1.9.0
$bfind(&binvar, N, M)
Searches a &binvar for a matching value.
The search is case-insensitive.
Parameters
&binvar - The &binvar to search.
N - The position of the &binvar to start the search.
M - Numeric ASCII character(s) or text to search.
Properties
.text - Force a text search if the search text (M) is a number.
Example
; Finds "test" starting from position 1. //echo -a $bfind(&test, 1, test) ; Finds character 32 (a space) from position 5. //echo -a $bfind(&test, 5, 32) ; Finds WAV from position 1. //echo -a $bfind(&test, 1, 87 65 86)