Update README.

This commit is contained in:
yukirij 2023-08-18 14:23:52 -07:00
parent 360152a84f
commit 404a798b20
3 changed files with 108 additions and 11 deletions

111
README.md
View File

@ -33,7 +33,7 @@ While the runtime provides methods for directly acquring and releasing memory, i
|Boolean|x02|--|True or false|
|Natural|x10|--|Non-negative integers|
|Integer|x11|--|Integers|
|Decimal|x12|--|Floating-point representable numbers|
|Significant|x13|--|Fixed-precision, variable-magnitude numbers|
|Block|x1e|size|Constant-sized series of bytes|
|Sequence|x1f|--|Variable-sized series of bytes|
|Array|x22|size, type|Constant-sized, ordered collection|
@ -48,6 +48,7 @@ Type building functions are used to generate identifiers used in the constructio
* `boolean()`
* `natural()`
* `integer()`
* `significant()`
* `block(size)`
* `sequence()`
* `array(size, type)`
@ -62,6 +63,78 @@ let type_id = block(4);
let list = List::new(type_id);
```
## Code Examples
### Example 1
```
const VEC3F :usize = 0x200;
const VEC3U :usize = 0x201;
const MESH :usize = 0x202;
fn vec3f(x:f64, y:f64, z:f64) -> szun::Record
{
use szun::*;
Record::with_values(VEC3F, vec![
*Significant::with(x),
*Significant::with(y),
*Significant::with(z),
]).unwrap()
}
fn vec3u(x:u64, y:u64, z:u64) -> szun::Record
{
use szun::*;
Record::with_values(VEC3U, vec![
*Natural::with(x),
*Natural::with(y),
*Natural::with(z),
]).unwrap()
}
fn main()
{
use szun::*;
// Vec3f
Schema::with(vec![
("x", significant()),
("y", significant()),
("z", significant()),
]).bind(VEC3F);
// Vec3u
Schema::with(vec![
("x", natural()),
("y", natural()),
("z", natural()),
]).bind(VEC3U);
// Mesh
Schema::with(vec![
("vertices", list(record(VEC3F))),
("faces", list(record(VEC3U))),
]).bind(MESH);
let pyramid = Record::with(MESH, vec![
("vertices", *List::with(record(VEC3F), vec![
*vec3f(0.0, 2.0, 0.0),
*vec3f(1.0, 0.0, 1.0),
*vec3f(1.0, 0.0, -1.0),
*vec3f(-1.0, 0.0, -1.0),
*vec3f(-1.0, 0.0, 1.0),
])),
("faces", *List::with(record(VEC3U), vec![
*vec3u(0, 1, 2),
*vec3u(0, 2, 3),
*vec3u(0, 3, 4),
*vec3u(0, 4, 1),
*vec3u(1, 2, 3),
*vec3u(1, 3, 4),
])),
]).unwrap();
}
```
## Global Functions
`acquire(type) -> Reference`
@ -81,13 +154,39 @@ release(refer);
---
`transfer(dst:Reference, src:Reference) -> Result<(),()>`
Move an object from one location to another, clearing the original.
```
let original = Sequence::with("Hello, world!");
let target = Sequence::new();
println!("{}", original.get()); // prints "Hello, world!"
println!("{}", target.get()); // prints ""
transfer(target, original);
println!("{}", original.get()); // prints ""
println!("{}", target.get()); // prints "Hello, world!"
```
---
`copy(dst:Reference, src:Reference) -> Result<(),()>`
Copy the contents of an objcet to another location, keeping the original.
```
let original = Sequence::with("Hello, world!");
let target = Sequence::new();
println!("{}", original.get()); // prints "Hello, world!"
println!("{}", target.get()); // prints ""
copy(target, original);
println!("{}", original.get()); // prints "Hello, world!"
println!("{}", target.get()); // prints "Hello, world!"
```
---
## Encoding
@ -97,8 +196,9 @@ Encoding converts data between runtime memory and binary serialization.
`encode_raw(refer:Reference) -> Vec<u8>`
`encode_tag(refer:Reference) -> Vec<u8>`
Serializes an object into binary encoding.
The raw variant does not produce a tag prefix for the root object.
Serializes an object into binary encoding.
The raw variant does not produce a tag prefix for the root object.
The tag variant only produces a tag prefix.
---
@ -106,8 +206,9 @@ The raw variant does not produce a tag prefix for the root object.
`decode_raw(data:&Vec<u8>, type_id:usize, index:&mut usize) -> Result<Type,()>`
`decode_tag(data:&Vec<u8>, index:&mut usize) -> Result<usize,()>`
Parses a valid binary encoding and produces the represented object.
The raw variant does not decode a tag prefix on the root object.
Parses a valid binary encoding and produces the represented object.
The raw variant does not decode a tag prefix on the root object.
The tag variant only decodes a tag prefix.
---

View File

@ -1,4 +1 @@
fn main()
{
szun::test();
}
fn main() { szun::test(); }

View File

@ -3,8 +3,7 @@
mod tag;
mod util;
mod runtime;
mod interface;
pub use interface::*;
mod interface; pub use interface::*;
mod encoding; pub use encoding::*;
pub fn test() {