pystruct

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 21, 2024 License: MIT Imports: 9 Imported by: 1

README

PyStruct

Go lang implementation of python's struct module

Interpret bytes as packed binary data

[!TIP] If you can't find something in README.md you can search references in Python's struct documentation

[!NOTE] Some functionality not yet implemented, details there

[!NOTE] Tested only with small values

Contents

Installation

go get github.com/o-murphy/pystruct-go

Usage

Example
package main

import (
	"bytes"
	"fmt"

	pystruct "github.com/o-murphy/pystruct-go"
)

func main() {

	// unpack
	byteArray := []byte{97, 98, 99, 100, 101, 102, 103}
	intf, err := pystruct.Unpack(`<3sf`, byteArray)
	if err == nil {
		fmt.Println(intf...)
	}

	// pack
	byteArray2, err := pystruct.Pack(`<3sf`, intf...)
	if err == nil {
		fmt.Println(byteArray2)
	}

	if bytes.Equal(byteArray, byteArray2) {
		fmt.Println("Equal")
	}

	// or use struct
	s := pystruct.NewStruct(`<3sf`)
	byteArray, err := s.Pack(intf...)
	intf, err := s.Unpack(byteArray)

}
Byte Order, Size, and Alignment
Details By default, C types are represented in the machine’s native format and byte order, and properly aligned by skipping pad bytes if necessary (according to the rules used by the C compiler). This behavior is chosen so that the bytes of a packed struct correspond exactly to the memory layout of the corresponding C struct. Whether to use native byte ordering and padding or standard formats depends on the application.

Alternatively, the first character of the format string can be used to indicate the byte order, size and alignment of the packed data, according to the following table:

Character Byte order Size Alignment
@ native native native
= native standard none
< little-endian standard none
> big-endian standard none
! network (= big-endian) standard none

[!TIP] If the first character is not one of these, '@' is assumed.

[!NOTE] Note The number 1023 (0x3ff in hexadecimal) has the following byte representations:

03 ff in big-endian (>)
ff 03 in little-endian (<)

More info there...

Format Characters
Details Format characters have the following meaning; the conversion between C and Python values should be obvious given their types. The ‘Standard size’ column refers to the size of the packed value in bytes when using standard size; that is, when the format string starts with one of '<', '>', '!' or '='. When using native size, the size of the packed value is platform-dependent.

[!NOTE] More info there...

Format C Type Go Type Python Type Standard Size
c char byte bytes of length 1 1
b signed char int8 integer 1
B unsigned char uint8 integer 1
? _Bool bool bool 1
h short int16 integer 2
H unsigned short uint16 integer 2
i int int32 integer 4
I unsigned int uint32 integer 4
l long int32 integer 4
L unsigned long uint32 integer 4
q long long int64 integer 8
Q unsigned long long uint64 integer 8
f float float32 (float64) float 4 (8)
d double float64 (float32) float 8 (4)
s char[] string bytes Variable
x pad byte N/A** no value
n ssize_t N/A** integer
N size_t N/A** integer
e float16 N/A** float 2
p char[] N/A** bytes
P void* N/A** integer
Functions
func CalcSize
func CalcSize(format string) (int, error)

Return the size of the struct (and hence of the bytes object produced by pack(format, ...)) corresponding to the format string format

size, err := pystruct.CalcSize(format)
if err == nil {
  fmt.Println(size)
}
func Pack
func Pack(format string, intf []interface{}) ([]byte, error)

Return a bytes object containing the values v1, v2, … packed according to the format string format. The arguments must match the values required by the format exactly.

intf := []interface{}{"abc", 1.01}
byteArray, err := pystruct.Pack(`<3sf`, intf)
if err == nil {
  fmt.Println(byteArray2)
}
func PackInto
func PackInto(format string, buffer []byte, offset int, intf ...interface{}) ([]byte, error)

Pack the values v1, v2, … according to the format string format and write the packed bytes into the writable buffer starting at position offset. Note that offset is a required argument.

intf := []interface{}{"abc", 1.01}
buffer := []byte{0xff, 0xff, 0xff, 0xff}
byteArray, err := pystruct.PackInto(`<3sf`, buffer, 3, intf)
if err == nil {
  fmt.Println(byteArray)
}
func Unpack
func Unpack(format string, buffer []byte) ([]interface{}, error)

Unpack from the buffer buffer (presumably packed by Pack(format, ...)) according to the format string format. The result is an []interface{} even if it contains exactly one item. The buffer’s size in bytes must match the size required by the format, as reflected by CalcSize().

byteArray := []byte{97, 98, 99, 100, 101, 102, 103}
intf, err := pystruct.Unpack(`<3sf`, byteArray)
if err == nil {
  fmt.Println(intf...)
}
func UnpackFrom
func UnpackFrom(format string, buffer []byte, offset int) ([]interface{}, error)

Unpack from buffer starting at position offset, according to the format string format. The result is an []interface{} even if it contains exactly one item. The buffer’s size in bytes, starting at position offset, must be at least the size required by the format, as reflected by CalcSize().

byteArray := []byte{0, 0, 0, 97, 98, 99, 100, 101, 102, 103}
intf, err := pystruct.UnpackFrom(`<3sf`, byteArray, 3)
if err == nil {
  fmt.Println(intf...)
}
func IterUnpack
func IterUnpack(format string, buffer []byte) (<-chan interface{}, <-chan error)

Iteratively unpack from the buffer buffer according to the format string format. This function returns an iterator which will read equally sized chunks from the buffer until all its contents have been consumed. The buffer’s size in bytes must be a multiple of the size required by the format, as reflected by CalcSize()

format := `<3si`
byteArray := []byte{97, 98, 99, 100, 101, 102, 103}
iterator, errs := pystruct.IterUnpack(format, byteArray)

i := 0
for value := range iterator {
	fmt.Println(i, value)
  i++
}
Types
type PyStruct
type PyStruct struct {
	format string
}

PyStruct(fmt) --> compiled PyStruct object

func NewStruct
NewStruct(format string) (PyStruct, error)

NewStruct(fmt) --> compiled PyStruct object Methods bellow this just binds for same named functions

func CalcSize

(⬆️CalcSize)

func (s *PyStruct) CalcSize() (int, error)
func Pack

(⬆️Pack)

func (s *PyStruct) Pack(intf ...interface{}) ([]byte, error)
func PackInto

(⬆️PackInto)

func (s *PyStruct) PackInto(buffer []byte, offset int, intf ...interface{}) ([]byte, error)
func Unpack

(⬆️Unpack)

func (s *PyStruct) Unpack(buffer []byte) ([]interface{}, error)
func UnpackFrom

(⬆️UnpackFrom)

func (s *PyStruct) UnpackFrom(buffer []byte, offset int) ([]interface{}, error)
func IterUnpack

(⬆️IterUnpack)

func (s *PyStruct) IterUnpack(format string, buffer []byte) (<-chan interface{}, <-chan error)
Not yet implemented
N/A
  • p char[] - Pascal string
  • P void*
  • x PadByte
  • n ssize_t
  • N size_t
Float16
  • e Float16 - (IEEE 754 binary16 half precision float)
RISK NOTICE

[!IMPORTANT] THE CODE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CalcSize 

func CalcSize(format string) (int, error)

Return the size of the struct (and hence of the bytes object produced by pack(format, ...)) corresponding to the format string format

func CalcSize_old added in v0.0.4 

func CalcSize_old(format string) (int, error)

Return the size of the struct (and hence of the bytes object produced by pack(format, ...)) corresponding to the format string format

func IterUnpack 

func IterUnpack(format string, buffer []byte) (<-chan interface{}, <-chan error)

Iteratively unpack from the buffer buffer according to the format string format. This function returns an iterator which will read equally sized chunks from the buffer until all its contents have been consumed. The buffer’s size in bytes must be a multiple of the size required by the format, as reflected by CalcSize()

func IterUnpack_old added in v0.0.4 

func IterUnpack_old(format string, buffer []byte) (<-chan interface{}, <-chan error)

Iteratively unpack from the buffer buffer according to the format string format. This function returns an iterator which will read equally sized chunks from the buffer until all its contents have been consumed. The buffer’s size in bytes must be a multiple of the size required by the format, as reflected by CalcSize()

func Pack 

func Pack(format string, intf ...interface{}) ([]byte, error)

Return a bytes object containing the values v1, v2, … packed according to the format string format. The arguments must match the values required by the format exactly.

func PackInto added in v0.0.2 

func PackInto(format string, buffer []byte, offset int, intf ...interface{}) ([]byte, error)

Pack the values v1, v2, … according to the format string format and write the packed bytes into the writable buffer starting at position offset. Note that offset is a required argument.

func PackInto_old added in v0.0.4 

func PackInto_old(format string, buffer []byte, offset int, intf ...interface{}) ([]byte, error)

Pack the values v1, v2, … according to the format string format and write the packed bytes into the writable buffer starting at position offset. Note that offset is a required argument.

func Pack_old added in v0.0.4 

func Pack_old(format string, intf ...interface{}) ([]byte, error)

Return a bytes object containing the values v1, v2, … packed according to the format string format. The arguments must match the values required by the format exactly.

func Unpack 

func Unpack(format string, buffer []byte) ([]interface{}, error)

Unpack from the buffer buffer (presumably packed by Pack(format, ...)) according to the format string format. The result is an []interface{} even if it contains exactly one item. The buffer’s size in bytes must match the size required by the format, as reflected by CalcSize().

func UnpackFrom 

func UnpackFrom(format string, buffer []byte, offset int) ([]interface{}, error)

Unpack from buffer starting at position offset, according to the format string format. The result is an []interface{} even if it contains exactly one item. The buffer’s size in bytes, starting at position offset, must be at least the size required by the format, as reflected by CalcSize().

func UnpackFrom_old added in v0.0.4 

func UnpackFrom_old(format string, buffer []byte, offset int) ([]interface{}, error)

Unpack from buffer starting at position offset, according to the format string format. The result is an []interface{} even if it contains exactly one item. The buffer’s size in bytes, starting at position offset, must be at least the size required by the format, as reflected by CalcSize().

func Unpack_old added in v0.0.4 

func Unpack_old(format string, buffer []byte) ([]interface{}, error)

Unpack_old from the buffer buffer (presumably packed by Pack(format, ...)) according to the format string format. The result is an []interface{} even if it contains exactly one item. The buffer’s size in bytes must match the size required by the format, as reflected by CalcSize().

Types

type PyStruct added in v0.0.6 

type PyStruct struct {
	// contains filtered or unexported fields
}

NewStruct(fmt) --> compiled PyStruct object Don't create directly, use NewStruct(fmt) instead

func NewStruct added in v0.0.4 

func NewStruct(format string) (PyStruct, error)

NewStruct(fmt) --> compiled pyStruct object

func (*PyStruct) Format added in v0.0.6 

func (s *PyStruct) Format() string

func (*PyStruct) IterUnpack added in v0.0.6 

func (s *PyStruct) IterUnpack(buffer []byte) (<-chan interface{}, <-chan error)

Iteratively unpack from the buffer buffer according to the format string format. This function returns an iterator which will read equally sized chunks from the buffer until all its contents have been consumed. The buffer’s size in bytes must be a multiple of the size required by the format, as reflected by CalcSize()

func (*PyStruct) Pack added in v0.0.6 

func (s *PyStruct) Pack(intf ...interface{}) ([]byte, error)

Return a bytes object containing the values v1, v2, … packed according to the format string format. The arguments must match the values required by the format exactly.

func (*PyStruct) PackInto added in v0.0.6 

func (s *PyStruct) PackInto(buffer []byte, offset int, intf ...interface{}) ([]byte, error)

Pack the values v1, v2, … according to the format string format and write the packed bytes into the writable buffer starting at position offset. Note that offset is a required argument.

func (*PyStruct) Size added in v0.0.6 

func (s *PyStruct) Size() int

func (*PyStruct) Unpack added in v0.0.6 

func (s *PyStruct) Unpack(buffer []byte) ([]interface{}, error)

Unpack from the buffer buffer (presumably packed by Pack(format, ...)) according to the format string format. The result is an []interface{} even if it contains exactly one item. The buffer’s size in bytes must match the size required by the format, as reflected by CalcSize().

func (*PyStruct) UnpackFrom added in v0.0.6 

func (s *PyStruct) UnpackFrom(buffer []byte, offset int) ([]interface{}, error)

Unpack from buffer starting at position offset, according to the format string format. The result is an []interface{} even if it contains exactly one item. The buffer’s size in bytes, starting at position offset, must be at least the size required by the format, as reflected by CalcSize().

type Struct_old added in v0.0.4 

type Struct_old struct {
	// contains filtered or unexported fields
}

Struct_old(fmt) --> compiled struct object

func (*Struct_old) CalcSize added in v0.0.4 

func (s *Struct_old) CalcSize() (int, error)

bind method CalcSize for Struct instance

func (*Struct_old) IterUnpack added in v0.0.4 

func (s *Struct_old) IterUnpack(format string, buffer []byte) (<-chan interface{}, <-chan error)

bind method IterUnpack for Struct instance

func (*Struct_old) Pack added in v0.0.4 

func (s *Struct_old) Pack(intf ...interface{}) ([]byte, error)

bind method Pack for Struct instance

func (*Struct_old) PackInto added in v0.0.4 

func (s *Struct_old) PackInto(buffer []byte, offset int, intf ...interface{}) ([]byte, error)

bind method PackInto for Struct instance

func (*Struct_old) Unpack added in v0.0.4 

func (s *Struct_old) Unpack(buffer []byte) ([]interface{}, error)

bind method Unpack for Struct instance

func (*Struct_old) UnpackFrom added in v0.0.4 

func (s *Struct_old) UnpackFrom(buffer []byte, offset int) ([]interface{}, error)

bind method UnpackFrom for Struct instance

Source Files

View all Source files

Directories

Path Synopsis
example module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.