# String

**命名空间**: `XCEngine::Containers`

**类型**: `class`

**描述**: 动态字符串类，提供 UTF-8 编码的字符串操作。

## 概述

`String` 是一个自定义动态字符串类，提供常见的字符串操作功能，支持拷贝构造、移动构造和多种字符串操作方法。

## 类型别名

| 别名 | 类型 | 描述 |
|------|------|------|
| `SizeType` | `size_t` | 大小类型 |

## 常量

| 常量 | 值 | 描述 |
|------|-----|------|
| `static constexpr SizeType npos` | `static_cast<SizeType>(-1)` | 无效位置标识 |

## 公共方法

### 构造/析构

| 方法 | 描述 |
|------|------|
| `String()` | 默认构造空字符串 |
| `String(const char* str)` | 从 C 字符串构造 |
| `String(const char* str, SizeType len)` | 从指定长度的 C 字符串构造 |
| `String(const String& other)` | 拷贝构造 |
| `String(String&& other) noexcept` | 移动构造 |
| `~String()` | 析构函数 |

### 赋值运算符

| 方法 | 描述 |
|------|------|
| `String& operator=(const String& other)` | 拷贝赋值 |
| `String& operator=(String&& other) noexcept` | 移动赋值 |
| `String& operator=(const char* str)` | C 字符串赋值 |

### 连接运算符

| 方法 | 描述 |
|------|------|
| `String& operator+=(const String& other)` | 追加字符串 |
| `String& operator+=(const char* str)` | 追加 C 字符串 |
| `String& operator+=(char c)` | 追加字符 |

### 字符串操作

| 方法 | 描述 |
|------|------|
| `String Substring(SizeType pos, SizeType len = npos) const` | 获取子串 |
| `String Trim() const` | 去除首尾空白 |
| `String ToLower() const` | 转换为小写 |
| `String ToUpper() const` | 转换为大写 |
| `SizeType Find(const char* str, SizeType pos = 0) const` | 查找子串位置 |
| `bool StartsWith(const String& prefix) const` | 检查是否以指定前缀开头 |
| `bool StartsWith(const char* prefix) const` | 检查是否以指定前缀开头 |
| `bool EndsWith(const String& suffix) const` | 检查是否以指定后缀结尾 |
| `bool EndsWith(const char* suffix) const` | 检查是否以指定后缀结尾 |

### 元素访问

| 方法 | 描述 |
|------|------|
| `const char* CStr() const` | 获取 C 字符串指针 |
| `SizeType Length() const` | 获取字符串长度 |
| `SizeType Capacity() const` | 获取容量 |
| `bool Empty() const` | 检查是否为空 |
| `char& operator[](SizeType index)` | 下标访问 |
| `const char& operator[](SizeType index) const` | 常量下标访问 |

### 容量管理

| 方法 | 描述 |
|------|------|
| `void Clear()` | 清空字符串 |
| `void Reserve(SizeType capacity)` | 预留容量 |
| `void Resize(SizeType newSize)` | 调整大小 |
| `void Resize(SizeType newSize, char fillChar)` | 调整大小并填充 |

## 友元函数

| 函数 | 描述 |
|------|------|
| `operator+(const String& lhs, const String& rhs)` | 字符串连接 |
| `operator==(const String& lhs, const String& rhs)` | 相等比较 |
| `operator!=(const String& lhs, const String& rhs)` | 不等比较 |

## std::hash 特化

```cpp
namespace std {
    template<>
    struct hash<XCEngine::Containers::String> {
        size_t operator()(const XCEngine::Containers::String& str) const noexcept;
    };
}
```

## 使用示例

```cpp
#include <XCEngine/Containers/String.h>

// 基本用法
Containers::String str = "Hello";
str += ", World!";

// 字符串操作
Containers::String sub = str.Substring(0, 5);  // "Hello"
bool hasPrefix = str.StartsWith("Hello");
bool hasSuffix = str.EndsWith("!");

// 查找
SizeType pos = str.Find("World");  // 返回 7

// 转换
Containers::String upper = str.ToUpper();
Containers::String lower = str.ToLower();
```

## 相关文档

- [Array](./container-array.md) - 动态数组
- [HashMap](./container-hashmap.md) - 哈希表