大小端转换器

定义

命名空间：TouchSocket.Core
程序集：TouchSocket.Core.dll

一、基本概念

1. 大小端模式

• 大端模式 (Big Endian)
  高位字节存储在内存低地址，低位字节存储在高地址。
  *示例：整数 10 的4字节大端表示为 {0, 0, 0, 10}*

• 小端模式 (Little Endian)
  低位字节存储在内存低地址，高位字节存储在高地址。
  *示例：整数 10 的4字节小端表示为 {10, 0, 0, 0}

2. 端序类型枚举

public enum EndianType {
    Big,        // 标准大端
    Little,     // 标准小端
    BigSwap,    // 交换大端（特殊场景）
    LittleSwap  // 交换小端（特殊场景）
}

---

二、核心 API 使用

1. 直接指定端序转换器

// 预定义静态实例
TouchSocketBitConverter.BigEndian        // 绝对大端
TouchSocketBitConverter.LittleEndian     // 绝对小端
TouchSocketBitConverter.BigSwapEndian    // 交换大端
TouchSocketBitConverter.LittleSwapEndian // 交换小端

2. 默认端序配置

// 默认小端模式（可全局修改）
TouchSocketBitConverter.DefaultEndianType = EndianType.Big;

// 获取当前默认转换器
TouchSocketBitConverter.Default.GetBytes(123);

---

三、基础数据类型转换

1. 数值类型转换

转换整型 (int)

// int -> byte[]
byte[] data = TouchSocketBitConverter.BigEndian.GetBytes(0x12345678); 

// byte[] -> int
int value = TouchSocketBitConverter.BigEndian.ToInt32(data, 0);

转换浮点型 (float)

// float -> byte[]
float num = 3.14f;
byte[] bytes = TouchSocketBitConverter.LittleEndian.GetBytes(num);

// byte[] -> float
float result = TouchSocketBitConverter.LittleEndian.ToSingle(bytes, 0);

2. 长数据类型处理

转换长整型 (long)

// long -> byte[]
long bigValue = 0x123456789ABCDEF0;
byte[] data = TouchSocketBitConverter.Default.GetBytes(bigValue);

// byte[] -> long
long restored = TouchSocketBitConverter.Default.ToInt64(data, 0);

转换高精度小数 (decimal)

// decimal -> byte[]
decimal money = 123456.78m;
byte[] decimalBytes = TouchSocketBitConverter.BigEndian.GetBytes(money);

// byte[] -> decimal
decimal result = TouchSocketBitConverter.BigEndian.ToDecimal(decimalBytes, 0);

---

四、高级功能

1. 不安全内存操作

unsafe {
    byte[] buffer = new byte[8];
    long value = 0x1122334455667788;

    // 直接内存写入
    fixed (byte* ptr = buffer) {
        TouchSocketBitConverter.LittleEndian.UnsafeWriteBytes(ref *ptr, value);
    }

    // 直接内存读取
    long readValue = TouchSocketBitConverter.LittleEndian.UnsafeTo<long>(ref buffer[0]);
}

2. 布尔数组转换

// bool[] -> byte[]
bool[] flags = { true, false, true, true, false, true, false, true };
byte[] boolBytes = TouchSocketBitConverter.Default.GetBytes(flags);

// byte[] -> bool[]
bool[] decodedFlags = TouchSocketBitConverter.Default.ToBooleans(boolBytes, length: 1);

---

五、特殊场景处理

1. 字节序验证

// 检查当前配置是否与系统字节序一致
bool isCompatible = TouchSocketBitConverter.Default.IsSameOfSet();

2. 交换端序模式

// 使用 BigSwap 模式处理网络数据包
byte[] swappedData = TouchSocketBitConverter.BigSwapEndian.GetBytes(0xAABBCCDD);

---

六、注意事项

1. 字节数组长度验证
   所有转换方法会检查数组长度，不足时抛出 ArgumentOutOfRangeException

2. 跨平台兼容性
   建议通过 IsSameOfSet() 验证端序一致性

3. 性能优化
   对性能敏感场景推荐使用 UnsafeWriteBytes 和 UnsafeTo 方法

---

七、完整示例

网络数据包处理

// 配置全局大端模式
TouchSocketBitConverter.DefaultEndianType = EndianType.Big;

// 构造数据包
var packet = new byte[16];
int header = 0x4D534754;  // "MSGT"
float payload = 1024.5f;

// 写入数据
TouchSocketBitConverter.Default.WriteBytes(packet.AsSpan(0, 4), header);
TouchSocketBitConverter.Default.WriteBytes(packet.AsSpan(4, 4), payload);

// 解析数据
int parsedHeader = TouchSocketBitConverter.Default.ToInt32(packet, 0);
float parsedPayload = TouchSocketBitConverter.Default.ToSingle(packet, 4);

---

八、API 参考

方法	说明
GetBytes<T>(T value)	将值转换为字节数组
To<T>(ReadOnlySpan<byte>)	从字节跨度转换回值
WriteBytes(Span<byte>, T)	将值写入字节跨度
UnsafeWriteBytes(ref byte, T)	不安全内存写入
UnsafeTo<T>(ref byte)	不安全内存读取