> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arkffi.hmbill.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# CString

> 從原始指針讀取 C 字符串

`CString` 包裝一個原始 C 字符串指針（`const char*`）並提供安全讀取。

## 示例

```typescript theme={null}
import { dlopen, FFIType, CString } from 'arkffi';

const lib = dlopen('libffi_target.so', {
  getVersion: { args: [], returns: FFIType.int64 },
});

const ptr: number = lib.symbols.getVersion();
const cstr = new CString(ptr);

cstr.toString(); // → "1.0.0"
cstr.length;     // → 5

lib.close();
```

## 構造函數

```typescript theme={null}
constructor(ptr: number, byteOffset?: number, byteLength?: number);
```

| 參數           | 類型       | 默認值          | 說明             |
| ------------ | -------- | ------------ | -------------- |
| `ptr`        | `number` | —            | C 字符串的內存地址     |
| `byteOffset` | `number` | `0`          | 跳過前 N 個字節再開始讀取 |
| `byteLength` | `number` | 自動檢測 null 結尾 | 顯式指定讀取長度       |

從原始內存地址創建 `CString`。指針必須指向有效的 C 字符串。可選地指定偏移量和長度。

```typescript theme={null}
const cstr = new CString(ptr, 0, 5);
cstr.toString(); // 讀取前 5 個字節
```

## 屬性

### `length`

```typescript theme={null}
get length(): number;
```

返回 C 字符串的長度（字符數）。

## 方法

### `toString()`

```typescript theme={null}
toString(): string;
```

讀取 C 字符串並以 ArkTS 字符串返回。

## 空指針

傳入 `0`（空指針）是安全的，返回空字符串：

```typescript theme={null}
const cstr = new CString(0);
cstr.toString(); // → ""
cstr.length;     // → 0
```