Difference between revisions of "RawData"

From MiniScript Wiki
Jump to navigation Jump to search
m (added see-also)
(→‎Examples: + Convert string -> RawData)
 
(3 intermediate revisions by 2 users not shown)
Line 56: Line 56:
 
| <c>[[RawData.utf8|utf8]](''self, offset=0, bytes=-1'')</c> || get a string of ASCII or UTF-8 text
 
| <c>[[RawData.utf8|utf8]](''self, offset=0, bytes=-1'')</c> || get a string of ASCII or UTF-8 text
 
|-
 
|-
| <c>[[RawData.setUtf8|setUtf8]](''self, offset=0, value=""'')</c> || set a string as UTF-8
+
| <c>[[RawData.setUtf8|setUtf8]](''self, offset=0, value=""'')</c> || set a string as UTF-8; return number of bytes written
 
|}
 
|}
 +
 +
==== Notes ====
 +
 +
The getter and setter methods accept <c>offset</c> argument which, as with [[string]] and [[list]] indexing, may be <c>0 .. (len-1)</c> or <c>-len .. -1</c> where the negative indexes mean offset from the end of data.
 +
 +
If offset (positive or negative) is out of range, an <c>IndexError</c> is raised. Same error is raised if the span of read or written bytes go beyond the data boundaries, with the exception of <c>.setUtf8</c> that writes as much of its string value as possible and drops the rest.
 +
 +
=== Examples ===
 +
 +
<ms>
 +
r = new RawData  // Create new RawData of zero length
 +
 +
r.resize 100  // resize it before writing and reading data
 +
 +
r.setByte 42, 200
 +
 +
print r.sbyte(42)  // prints: -56
 +
</ms>
 +
 +
==== Converting a string to RawData ====
 +
 +
There's no easy way to know how big a string will be in bytes, but it should be less than (or equal to) 4 times the length.  So start with a buffer equal to 4 times s.len, and then after you setUtf8 you can get the actual byte count, and resize your rawData down to size.
 +
 +
<ms>
 +
r = new RawData
 +
 +
s = "ॐ मणि पद्मे हूँ"
 +
 +
r.resize s.len * 4
 +
 +
r.resize r.setUtf8(0, s)
 +
 +
print r.utf8 == "ॐ मणि पद्मे हूँ"  // prints: 1
 +
</ms>

Latest revision as of 10:58, 15 May 2024

The RawData class in Mini Micro represents a buffer of raw bytes. Interpretation of these bytes is entirely up to the programmer.

See also: file.loadRaw, file.saveRaw

Properties

Property Name Type Default Value Meaning
littleEndian number (boolean) true whether multi-byte values are stored with least significant byte first


Methods

Method Description
len returns the length of the raw data buffer, in bytes
resize(bytes=32) change the size of the raw data buffer
byte(self, offset=0) get one unsigned byte of data
setByte(self, offset=0, value=0) set one unsigned byte value
sbyte(self, offset=0) get one signed byte of data
setSbyte(self, offset=0, value=0) set one signed byte value
ushort(self, offset=0) get an unsigned 16-bit integer value
setUshort(self, offset=0, value=0) set an unsigned 16-bit integer value
short(self, offset=0) get a signed 16-bit integer value
setShort(self, offset=0, value=0) set a signed 16-bit integer value
uint(self, offset=0) get an unsigned 32-bit integer value
setUint(self, offset=0, value=0) set an unsigned 32-bit integer value
int(self, offset=0) get a signed 32-bit integer value
setInt(self, offset=0, value=0) set a signed 32-bit integer value
float(self, offset=0) get a 32-bit floating-point value
setFloat(self, offset=0, value=0) set a 32-bit floating-point value
double(self, offset=0) get a 64-bit floating-point value
setDouble(self, offset=0, value=0) set a 64-bit floating-point value
utf8(self, offset=0, bytes=-1) get a string of ASCII or UTF-8 text
setUtf8(self, offset=0, value="") set a string as UTF-8; return number of bytes written

Notes

The getter and setter methods accept offset argument which, as with string and list indexing, may be 0 .. (len-1) or -len .. -1 where the negative indexes mean offset from the end of data.

If offset (positive or negative) is out of range, an IndexError is raised. Same error is raised if the span of read or written bytes go beyond the data boundaries, with the exception of .setUtf8 that writes as much of its string value as possible and drops the rest.

Examples

r = new RawData  // Create new RawData of zero length

r.resize 100  // resize it before writing and reading data

r.setByte 42, 200

print r.sbyte(42)  // prints: -56

Converting a string to RawData

There's no easy way to know how big a string will be in bytes, but it should be less than (or equal to) 4 times the length. So start with a buffer equal to 4 times s.len, and then after you setUtf8 you can get the actual byte count, and resize your rawData down to size.

r = new RawData

s = "ॐ मणि पद्मे हूँ"

r.resize s.len * 4

r.resize r.setUtf8(0, s)

print r.utf8 == "ॐ मणि पद्मे हूँ"  // prints: 1