OCFileUtilities

group OCFileUtilities

File, path, and JSON (de)serialization helpers.

Functions

OCStringRef OCPathJoin(OCStringRef a, OCStringRef b)

Join two path components with the platform’s separator.

Parameters:

  • a – First path component.

  • b – Second path component.

Returns:

New OCStringRef of “a/b” (ownership transferred to caller).

OCStringRef OCPathDirname(OCStringRef path)

Return the parent directory of a path.

Parameters:

  • path – The full path.

Returns:

New OCStringRef of the directory portion (ownership transferred).

OCStringRef OCPathBasename(OCStringRef path)

Return the final component of a path.

Parameters:

  • path – The full path.

Returns:

New OCStringRef of the basename (ownership transferred).

OCStringRef OCPathExtension(OCStringRef path)

Extract the “.ext” suffix from a path.

Parameters:

  • path – The full path.

Returns:

New OCStringRef of the extension (including ‘.’), or empty string if none (ownership transferred).

OCStringRef OCPathByReplacingExtension(OCStringRef path, OCStringRef newExt)

Replace the existing extension on a path.

Parameters:

  • path – The original path.

  • newExt – Extension to use (with or without leading ‘.’).

Returns:

New OCStringRef of the modified path (ownership transferred).

bool OCFileExists(const char *path)

Does the given path exist?

Parameters:

  • path – Filesystem path.

Returns:

true if stat(2) succeeds.

bool OCIsDirectory(const char *path)

Is the given path a directory?

Parameters:

  • path – Filesystem path.

Returns:

true if stat(2) shows S_ISDIR.

bool OCIsRegularFile(const char *path)

Is the given path a regular file?

Parameters:

  • path – Filesystem path.

Returns:

true if stat(2) shows S_ISREG.

bool OCCreateDirectory(const char *path, bool recursive, OCStringRef *err)

Create a directory, optionally recursing like “mkdir -p”.

Parameters:

  • path – Directory to create.

  • recursive – If true, build out all parent components.

  • err – On failure, *err is set to a human‐readable message.

Returns:

true on success.

OCArrayRef OCListDirectory(const char *path, bool recursive, OCStringRef *err)

List every regular file under a folder.

Parameters:

  • path – Base directory.

  • recursive – If true, descend into subdirectories.

  • err – On failure, *err is set to a human‐readable message.

Returns:

New OCArrayRef of OCStringRef relative paths, or NULL on error (ownership transferred).

bool OCRemoveItem(const char *path, OCStringRef *err)

Remove a file or empty directory.

Parameters:

  • path – Path to delete.

  • err – On failure, *err is set to a human‐readable message.

Returns:

true on success (or if path didn’t exist).

bool OCRenameItem(const char *oldPath, const char *newPath, OCStringRef *err)

Rename or move a file or directory.

Parameters:

  • oldPath – Existing path.

  • newPath – New path.

  • err – On failure, *err is set to a human‐readable message.

Returns:

true on success.

OCStringRef OCStringCreateWithContentsOfFile(const char *path, OCStringRef *err)

Read a UTF-8 text file into an OCString.

Parameters:

  • path – File path.

  • err – On failure, *err is set to a human‐readable message.

Returns:

New OCStringRef of file contents (ownership transferred), or NULL.

bool OCStringWriteToFile(OCStringRef str, const char *path, OCStringRef *err)

Write an OCString (UTF-8) to a file.

Parameters:

  • str – The string to write.

  • path – Destination filename.

  • err – On failure, *err is set to a human‐readable message.

Returns:

true on success.

OCDictionaryRef OCDictionaryCreateWithContentsOfFolder(const char *folderPath, int maxDepth, OCStringRef *err)

Load all files under a folder (up to maxDepth) into a dictionary.

Parameters:

  • folderPath – Base directory.

  • maxDepth – Levels of recursion (0 = just top-level).

  • err – On failure, *err is set to a human‐readable message.

Returns:

New OCDictionaryRef ⟨relative-path→OCDataRef⟩, or NULL on failure (ownership transferred).

bool OCTypeWriteJSONToFile(OCTypeRef obj, bool typed, bool formatted, const char *path, OCStringRef *error)

Write any OCTypes object (string, number, bool, array, dict…) to a compact JSON file.

Parameters:

  • obj – An OCTypeRef (OCString, OCNumber, OCBoolean, OCArray, OCDictionary…)

  • path – Path to write.

  • err – On failure, *err is set to a human-readable message.

Returns:

true on success.