From 1da641f46b49d3d9a92351f8309f4881dfbf2dc2 Mon Sep 17 00:00:00 2001 From: Determinant Date: Mon, 17 Jun 2019 14:56:30 -0400 Subject: add doc to stream.go; other minor changes --- netaddr.go | 2 +- salticidae | 2 +- stream.go | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++---------- 3 files changed, 69 insertions(+), 14 deletions(-) diff --git a/netaddr.go b/netaddr.go index 09d9c8b..11f3f2b 100644 --- a/netaddr.go +++ b/netaddr.go @@ -67,7 +67,7 @@ func (self NetAddr) GetPort() uint16 { return uint16(C.netaddr_get_port(self.inn // Make a copy of the object. This is required if you want to keep the NetAddr // returned (or passed as a callback parameter) by other salticidae objects -// (such like MsgNetwork/PeerNetwork). +// (such like MsgNetwork/PeerNetwork), unless the function returns a moved object. func (self NetAddr) Copy() NetAddr { res := &netAddr{ inner: C.netaddr_copy(self.inner) } runtime.SetFinalizer(res, func(self NetAddr) { self.free() }) diff --git a/salticidae b/salticidae index c69b015..01a5e35 160000 --- a/salticidae +++ b/salticidae @@ -1 +1 @@ -Subproject commit c69b0150fe0c50b91c7c8a406f096de8e9cf62fc +Subproject commit 01a5e352f11ee4c507f4304e4d41e069276164f0 diff --git a/stream.go b/stream.go index 7d42020..badf471 100644 --- a/stream.go +++ b/stream.go @@ -8,8 +8,10 @@ import "runtime" type byteArray struct { inner *C.bytearray_t } +// Array of binary data. type ByteArray = *byteArray +// Create an empty byte array (with zero contained bytes). func NewByteArray() ByteArray { res := &byteArray{ inner: C.bytearray_new() } runtime.SetFinalizer(res, func(self ByteArray) { self.free() }) @@ -18,6 +20,10 @@ func NewByteArray() ByteArray { func (self ByteArray) free() { C.bytearray_free(self.inner) } +// Create a byte array by taking out all data from src. Notice this is a +// zero-copy operation that consumes and invalidates the data in src ("move" +// semantics) so that no more operation should be done to src after this +// function call. func NewByteArrayMovedFromDataStream(src DataStream) ByteArray { res := &byteArray{ inner: C.bytearray_new_moved_from_datastream(src.inner) } runtime.SetFinalizer(res, func(self ByteArray) { self.free() }) @@ -28,14 +34,17 @@ type dataStream struct { inner *C.datastream_t } +// Stream of binary data. type DataStream = *dataStream +// Create an empty DataStream. func NewDataStream() DataStream { res := &dataStream{ inner: C.datastream_new() } runtime.SetFinalizer(res, func(self DataStream) { self.free() }) return res } +// Create a DataStream with data copied from bytes. func NewDataStreamFromBytes(bytes []byte) (res DataStream) { size := len(bytes) if size > 0 { @@ -50,30 +59,39 @@ func NewDataStreamFromBytes(bytes []byte) (res DataStream) { func (self DataStream) free() { C.datastream_free(self.inner) } -func (self DataStream) AssignByCopy(src DataStream) { - C.datastream_assign_by_copy(self.inner, src.inner) -} - -func (self DataStream) AssignByMove(src DataStream) { - C.datastream_assign_by_move(self.inner, src.inner) +// Make a copy of the object. +func (self DataStream) Copy() DataStream { + res := &dataStream{ inner: C.datastream_copy(self.inner) } + runtime.SetFinalizer(res, func(self DataStream) { self.free() }) + return res } // TODO: datastream_data +// Empty the DataStream. func (self DataStream) Clear() { C.datastream_clear(self.inner) } func (self DataStream) Size() int { return int(C.datastream_size(self.inner)) } +// Write a uint8 integer to the stream (no byte order conversion). func (self DataStream) PutU8(v uint8) bool { return bool(C.datastream_put_u8(self.inner, C.uint8_t(v))) } +// Write a uint16 integer to the stream (no byte order conversion). func (self DataStream) PutU16(v uint16) bool { return bool(C.datastream_put_u16(self.inner, C.uint16_t(v))) } +// Write a uint32 integer to the stream (no byte order conversion). func (self DataStream) PutU32(v uint32) bool { return bool(C.datastream_put_u32(self.inner, C.uint32_t(v))) } -func (self DataStream) PutU64(v uint32) bool { return bool(C.datastream_put_u64(self.inner, C.uint64_t(v))) } +// Write a uint64 integer to the stream (no byte order conversion). +func (self DataStream) PutU64(v uint64) bool { return bool(C.datastream_put_u64(self.inner, C.uint64_t(v))) } +// Write an int8 integer to the stream (no byte order conversion). func (self DataStream) PutI8(v int8) bool { return bool(C.datastream_put_i8(self.inner, C.int8_t(v))) } +// Write an int16 integer to the stream (no byte order conversion). func (self DataStream) PutI16(v int16) bool { return bool(C.datastream_put_i16(self.inner, C.int16_t(v))) } +// Write an int32 integer to the stream (no byte order conversion). func (self DataStream) PutI32(v int32) bool { return bool(C.datastream_put_i32(self.inner, C.int32_t(v))) } +// Write an int64 integer to the stream (no byte order conversion). func (self DataStream) PutI64(v int32) bool { return bool(C.datastream_put_i64(self.inner, C.int64_t(v))) } +// Write arbitrary bytes to the stream. func (self DataStream) PutData(bytes []byte) bool { size := len(bytes) if size > 0 { @@ -82,28 +100,54 @@ func (self DataStream) PutData(bytes []byte) bool { } else { return true } } +// Parse a uint8 integer by consuming the stream (no byte order conversion). func (self DataStream) GetU8(succ *bool) uint8 { return uint8(C.datastream_get_u8(self.inner, (*C.bool)(succ))) } +// Parse a uint16 integer by consuming the stream (no byte order conversion). func (self DataStream) GetU16(succ *bool) uint16 { return uint16(C.datastream_get_u16(self.inner, (*C.bool)(succ))) } +// Parse a uint32 integer by consuming the stream (no byte order conversion). func (self DataStream) GetU32(succ *bool) uint32 { return uint32(C.datastream_get_u32(self.inner, (*C.bool)(succ))) } +// Parse a uint64 integer by consuming the stream (no byte order conversion). func (self DataStream) GetU64(succ *bool) uint64 { return uint64(C.datastream_get_u64(self.inner, (*C.bool)(succ))) } +// Parse an int8 integer by consuming the stream (no byte order conversion). func (self DataStream) GetI8(succ *bool) int8 { return int8(C.datastream_get_i8(self.inner, (*C.bool)(succ))) } +// Parse an int16 integer by consuming the stream (no byte order conversion). func (self DataStream) GetI16(succ *bool) int16 { return int16(C.datastream_get_i16(self.inner, (*C.bool)(succ))) } +// Parse an int32 integer by consuming the stream (no byte order conversion). func (self DataStream) GetI32(succ *bool) int32 { return int32(C.datastream_get_i32(self.inner, (*C.bool)(succ))) } +// Parse an int64 integer by consuming the stream (no byte order conversion). func (self DataStream) GetI64(succ *bool) int64 { return int64(C.datastream_get_i64(self.inner, (*C.bool)(succ))) } +// The handle returned by GetDataInPlace. The Go slice returned by Get() is +// valid only during the lifetime of the handle. +type dataStreamBytes struct { + bytes []byte + ds DataStream +} + +type DataStreamBytes = *dataStreamBytes + +func (self DataStreamBytes) Get() []byte { return self.bytes } -func (self DataStream) GetDataInPlace(length int) []byte { +// Get the given length of preceeding bytes from the stream as a byte slice by +// consuming the stream. Notice this function does not copy the bytes, so the +// slice is only valid during the lifetime of DataStreamBytes handle. +func (self DataStream) GetDataInPlace(length int) DataStreamBytes { base := C.datastream_get_data_inplace(self.inner, C.size_t(length)) - return C.GoBytes(rawptr_t(base), C.int(length)) + return &dataStreamBytes{ + bytes: C.GoBytes(rawptr_t(base), C.int(length)), + ds: self, + } } type uint256 struct { inner *C.uint256_t } +// 256-bit integer. type UInt256 = *uint256 +// Create a 256-bit integer. func NewUInt256() UInt256 { res := &uint256{ inner: C.uint256_new() } runtime.SetFinalizer(res, func(self UInt256) { self.free() }) @@ -111,18 +155,28 @@ func NewUInt256() UInt256 { } func (self UInt256) free() { C.uint256_free(self.inner) } -func (self UInt256) UInt256IsNull() bool { return bool(C.uint256_is_null(self.inner)) } -func (self UInt256) UInt256IsEq(other UInt256) bool { return bool(C.uint256_is_eq(self.inner, other.inner)) } + +func (self UInt256) IsNull() bool { return bool(C.uint256_is_null(self.inner)) } + +// Check if two 256-bit integers are equal. +func (self UInt256) IsEq(other UInt256) bool { return bool(C.uint256_is_eq(self.inner, other.inner)) } + +// Write the integer to the given DataStream. func (self UInt256) Serialize(s DataStream) { C.uint256_serialize(self.inner, s.inner) } + +// Parse the integer from the given DataStream. func (self UInt256) Unserialize(s DataStream) { C.uint256_unserialize(self.inner, s.inner) } -func (self UInt256) IsEq(other UInt256) bool { return bool(C.uint256_is_eq(self.inner, other.inner)) } +// Get the Sha256 hash of the given DataStream content (without consuming the +// stream). func (self DataStream) GetHash() UInt256 { res := &uint256{ inner: C.datastream_get_hash(self.inner) } runtime.SetFinalizer(res, func(self UInt256) { self.free() }) return res } +// Get hexadicemal string representation of the given DataStream content +// (without consuming the stream). func (self DataStream) GetHex() string { tmp := C.datastream_get_hex(self.inner) res := C.GoString(tmp) @@ -130,6 +184,7 @@ func (self DataStream) GetHex() string { return res } +// Get hexadicemal string representation of the 256-bit integer. func (self UInt256) GetHex() string { s := NewDataStream() self.Serialize(s) -- cgit v1.2.3-70-g09d2