# struct_util

**Repository Path**: zhaojiajun21/struct_util

## Basic Information

- **Project Name**: struct_util
- **Description**: 二进制协议拼包及解包，用法类似sscanf/sprintf
- **Primary Language**: C
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2022-06-12
- **Last Updated**: 2023-12-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: mcu, stm32, 单片机

## README

# struct_util

## 介绍

结构化数据与字节流相互转化，用于二进制协议的数据打包及解包

## 使用说明

### 函数原型

```int struct_util_pack(char* data, const char* format, ...);```

* data 打包后数据的存放位置
* format:格式化字符串，根据此字符串填充data缓冲区
* \[retval\]:填充了多少字节

```int struct_util_unpack(const char* data, const char* format, ...);```
* data :数据的存放位置
* format:格式化字符串，根据此字符串解析数据
* \[retval\]:解析了多少字节

> 两个函数互为逆过程，由`struct_util_pack`拼包的数据，使用相同`format`参数可由`struct_util_unpack`原样解包

支持的格式化字符

|format     | c type                        |supported  |
|---        |---                            |---        |
|x/X		|pad byte                       |√          |
|c/b		|s8/u8/char                     |√          |
|h			|s16/u16                        |√          |
|t          |u24                            |√          |
|i			|s32/u32                        |√          |
|l			|s64/u64                        |×          |
|f			|float                          |√          |
|d			|double                         |×          |
|s/S		|pointer of char, end with ‘\0’ |√          |
|B			|pointer of s8/u8               |√          |
|H			|pointer of s16/u16             |√          |
|I			|pointer of s32/u32             |√          |
|L			|pointer of s64/u64             |×          |
|F			|pointer of float               |√          |
|D			|pointer of double              |×          |

|format     | endian                        |supported  |
|---        |---                            |---        |
|>          |big endian      (ABCD)         |√          |
|<          |little endian   (DCBA)         |√          |
|<          |little word   (BADC)           |×          |
|<          |big word   (CDAB)              |×          |
|!          |host endian                    |√          |

> `lite word` == `PDP-11`

> `big word` == `Honeywell 316`

---

### 示例

```C
// 默认大端填充
n = struct_util_pack(buffer, "bhti", 0x11,0x2122,0x313233,0x41424344);
// buffer = {0x11,  0x21,0x22,  0x31,0x32,0x33, 0x41,0x42,0x43,0x44}
// n = 10

// 在格式化字符前指定字节序
n = struct_util_pack(buffer, "b<h>i", 0x11,0x2122,0x31323334);
// buffer = {0x11,  0x22,0x21,  0x31,0x32,0x33,0x34}
// n = 7

// 指定数据数量
n = struct_util_pack(buffer, "3bhi", 0x11,0x12,0x13,0x2122,0x31323334);
// buffer = {0x11,0x12,0x13  0x21,0x22,  0x31,0x32,0x33,0x34}
// n = 7


// 传入数组而不是元素
uint16_t u16data[10] = {0x2122, 0x2324, 0x2526, 0x2728, 0x292a};
n = struct_util_pack(buffer, "3b4H<h", 0x02, 0x03, 0x08, u16data,0xB1B2);
// buffer = {0x02, 0x03 ,0x08 ,0x21,0x22 ,0x23,0x24 ,0x25,0x26 ,0x27,0x28 ,0xB2,0xB1}
// n = 13
```

> 对于字符串数组，格式字符应使用`S`而不是`B`，前者在pack时，可通过'\0'自动识别字符串长度，unpack时可自动添加'\0'

> 除字符串拼包时可省略以自动识别长度，其他格式字符必须提供数字前缀指示长度，否则默认长度为1