# fs

<a id="fs"></a>

# fs

Cross-platform filesystem path and file helpers.

## Functions

| Return | Name | Description |
|--------|------|-------------|
| `std::string` | [`filename`](#filename-1)  | Returns the file name and extension part of the given path. |
| `std::string` | [`basename`](#basename)  | Returns the file name without its extension. |
| `std::string` | [`dirname`](#dirname)  | Returns the directory part of the path. |
| `std::string` | [`extname`](#extname)  | Returns the file extension part of the path. |
| `bool` | [`exists`](#exists-3)  | Returns true if the file or directory exists. |
| `bool` | [`isdir`](#isdir)  | Returns true if the path refers to a directory. |
| `std::int64_t` | [`filesize`](#filesize)  | Returns the size in bytes of the given file. |
| `void` | [`readdir`](#readdir)  | Populates `res` with the names of all entries in the given directory. |
| `void` | [`mkdir`](#mkdir)  | Creates a single directory. |
| `void` | [`mkdirr`](#mkdirr)  | Creates a directory and all missing parent directories. |
| `void` | [`rmdir`](#rmdir)  | Removes an empty directory. |
| `void` | [`unlink`](#unlink)  | Deletes a file. |
| `void` | [`rename`](#rename)  | Renames or moves the given file to the target path. |
| `void` | [`addsep`](#addsep)  | Appends the platform-specific path separator to `path` if not already present. |
| `void` | [`addnode`](#addnode)  | Appends a path node to `path`, inserting a separator if necessary. |
| `std::string` | [`makePath`](#makepath)  | Joins a base path and a node component into a single path string. |
| `std::string` | [`normalize`](#normalize-1)  | Normalizes a path by resolving `.` and `..` segments and converting separators to the native platform style. |
| `std::string` | [`transcode`](#transcode)  | Transcodes a path to the native platform format. On Windows with `ICY_UNICODE` defined, converts to the Windows-native wide-to-narrow format. On other platforms, returns the path unchanged. |
| `bool` | [`savefile`](#savefile)  | Writes `size` bytes from `data` to the file at `path`, creating or overwriting it. |

---

<a id="filename-1"></a>

### filename

```cpp
std::string filename(std::string_view path)
```

[Defined in src/base/include/icy/filesystem.h:38](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L38)

Returns the file name and extension part of the given path. 
#### Returns
Filename component including extension (e.g. "file.txt").

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Filesystem path to parse. |

---

<a id="basename"></a>

### basename

```cpp
std::string basename(std::string_view path)
```

[Defined in src/base/include/icy/filesystem.h:43](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L43)

Returns the file name without its extension. 
#### Returns
Filename without the extension (e.g. "file").

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Filesystem path to parse. |

---

<a id="dirname"></a>

### dirname

```cpp
std::string dirname(std::string_view path)
```

[Defined in src/base/include/icy/filesystem.h:48](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L48)

Returns the directory part of the path. 
#### Returns
Directory component including trailing separator (e.g. "/usr/local/").

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Filesystem path to parse. |

---

<a id="extname"></a>

### extname

```cpp
std::string extname(std::string_view path, bool includeDot = true)
```

[Defined in src/base/include/icy/filesystem.h:54](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L54)

Returns the file extension part of the path. 
#### Returns
Extension string, or empty if the path has no extension.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Filesystem path to parse. |
| `includeDot` | `bool` | If true (default), includes the leading dot (e.g. ".txt"); if false, the dot is stripped. |

---

<a id="exists-3"></a>

### exists

```cpp
bool exists(std::string_view path)
```

[Defined in src/base/include/icy/filesystem.h:59](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L59)

Returns true if the file or directory exists. 
#### Returns
True if the path exists on the filesystem.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Path to check. |

---

<a id="isdir"></a>

### isdir

```cpp
bool isdir(std::string_view path)
```

[Defined in src/base/include/icy/filesystem.h:64](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L64)

Returns true if the path refers to a directory. 
#### Returns
True if the path exists and is a directory.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Path to check. |

---

<a id="filesize"></a>

### filesize

```cpp
std::int64_t filesize(std::string_view path)
```

[Defined in src/base/include/icy/filesystem.h:69](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L69)

Returns the size in bytes of the given file. 
#### Returns
File size in bytes, or -1 if the file does not exist.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Path to the file. |

---

<a id="readdir"></a>

### readdir

```cpp
void readdir(std::string_view path, std::vector< std::string > & res)
```

[Defined in src/base/include/icy/filesystem.h:74](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L74)

Populates `res` with the names of all entries in the given directory.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Path to the directory to read. |
| `res` | `std::vector< std::string > &` | Vector to receive the list of entry names. |

---

<a id="mkdir"></a>

### mkdir

```cpp
void mkdir(std::string_view path, int mode = 0755)
```

[Defined in src/base/include/icy/filesystem.h:79](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L79)

Creates a single directory.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Path of the directory to create. |
| `mode` | `int` | Permission bits (default: 0755). Ignored on Windows. |

---

<a id="mkdirr"></a>

### mkdirr

```cpp
void mkdirr(std::string_view path, int mode = 0755)
```

[Defined in src/base/include/icy/filesystem.h:84](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L84)

Creates a directory and all missing parent directories.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Path of the directory hierarchy to create. |
| `mode` | `int` | Permission bits (default: 0755). Ignored on Windows. |

---

<a id="rmdir"></a>

### rmdir

```cpp
void rmdir(std::string_view path)
```

[Defined in src/base/include/icy/filesystem.h:88](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L88)

Removes an empty directory.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Path of the directory to remove. |

---

<a id="unlink"></a>

### unlink

```cpp
void unlink(std::string_view path)
```

[Defined in src/base/include/icy/filesystem.h:92](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L92)

Deletes a file.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Path of the file to delete. |

---

<a id="rename"></a>

### rename

```cpp
void rename(std::string_view path, std::string_view target)
```

[Defined in src/base/include/icy/filesystem.h:97](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L97)

Renames or moves the given file to the target path.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Source file path. |
| `target` | `std::string_view` | Destination file path. |

---

<a id="addsep"></a>

### addsep

```cpp
void addsep(std::string & path)
```

[Defined in src/base/include/icy/filesystem.h:101](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L101)

Appends the platform-specific path separator to `path` if not already present.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string &` | Path string to modify in place. |

---

<a id="addnode"></a>

### addnode

```cpp
void addnode(std::string & path, std::string_view node)
```

[Defined in src/base/include/icy/filesystem.h:106](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L106)

Appends a path node to `path`, inserting a separator if necessary.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string &` | Base path string to modify in place. |
| `node` | `std::string_view` | Directory or file name component to append. |

---

<a id="makepath"></a>

### makePath

```cpp
std::string makePath(std::string_view base, std::string_view node)
```

[Defined in src/base/include/icy/filesystem.h:112](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L112)

Joins a base path and a node component into a single path string. 
#### Returns
Joined path string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `base` | `std::string_view` | Base directory path. |
| `node` | `std::string_view` | Directory or file name component to append. |

---

<a id="normalize-1"></a>

### normalize

```cpp
std::string normalize(std::string_view path)
```

[Defined in src/base/include/icy/filesystem.h:118](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L118)

Normalizes a path by resolving `.` and `..` segments and converting separators to the native platform style. 
#### Returns
Normalized path string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Path string to normalize. |

---

<a id="transcode"></a>

### transcode

```cpp
std::string transcode(std::string_view path)
```

[Defined in src/base/include/icy/filesystem.h:125](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L125)

Transcodes a path to the native platform format. On Windows with `ICY_UNICODE` defined, converts to the Windows-native wide-to-narrow format. On other platforms, returns the path unchanged. 
#### Returns
Transcoded path string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Path string to transcode. |

---

<a id="savefile"></a>

### savefile

```cpp
bool savefile(std::string_view path, const char * data, size_t size, bool whiny = false)
```

[Defined in src/base/include/icy/filesystem.h:133](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L133)

Writes `size` bytes from `data` to the file at `path`, creating or overwriting it. 
#### Returns
True on success, false on failure (when `whiny` is false).

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `std::string_view` | Destination file path. Parent directories must already exist. |
| `data` | `const char *` | Pointer to the data to write. |
| `size` | `size_t` | Number of bytes to write. |
| `whiny` | `bool` | If true, throws a `std::runtime_error` on failure instead of returning false. |

## Variables

| Return | Name | Description |
|--------|------|-------------|
| `const char *` | [`separator`](#separator)  | The platform specific path separator string: "/" on unix and "\\" on windows. |
| `const char` | [`delimiter`](#delimiter)  | The platform specific path separator character: '/' on unix and '\' on windows. |

---

<a id="separator"></a>

### separator

```cpp
const char * separator
```

[Defined in src/base/include/icy/filesystem.h:29](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L29)

The platform specific path separator string: "/" on unix and "\\" on windows.

---

<a id="delimiter"></a>

### delimiter

```cpp
const char delimiter
```

[Defined in src/base/include/icy/filesystem.h:33](https://github.com/auscaster/icey/blob/main/src/base/include/icy/filesystem.h#L33)

The platform specific path separator character: '/' on unix and '\' on windows.