native_support.h

Go to the documentation of this file.

/**
 * @file
 * @brief Declares shared low-level support helpers used across the Pharos native runtime.
 */
 
#ifndef PHAROS_NATIVE_SUPPORT_H
#define PHAROS_NATIVE_SUPPORT_H
 
#include <stddef.h>
 
/**
 * @brief Growable byte buffer used by parsing and string assembly helpers.
 */
typedef struct {
  char *data;   /**< Owned buffer storage. */
  size_t len;   /**< Number of bytes currently populated. */
  size_t cap;   /**< Total allocated capacity in bytes. */
} Buffer;
 
/** @name Shared support helpers
 * @{
 */
/**
 * @brief Initializes a growable buffer to an empty state.
 * @param buffer Buffer to initialize.
 */
void buffer_init(Buffer *buffer);
/**
 * @brief Releases memory owned by a growable buffer.
 * @param buffer Buffer to clear.
 */
void buffer_free(Buffer *buffer);
/**
 * @brief Ensures a buffer can hold at least a requested number of bytes.
 * @param buffer Buffer whose capacity may grow.
 * @param needed Minimum required capacity in bytes.
 * @return 0 on success, or -1 on allocation or overflow failure.
 */
int buffer_reserve(Buffer *buffer, size_t needed);
/**
 * @brief Appends bytes to a growable buffer and maintains a trailing NUL byte.
 * @param buffer Buffer to append into.
 * @param data Source bytes to append.
 * @param len Number of bytes to append.
 * @return 0 on success, or -1 on allocation failure.
 */
int buffer_append(Buffer *buffer, const void *data, size_t len);
/**
 * @brief Duplicates a byte range into a newly allocated NUL-terminated string.
 * @param start Pointer to the first byte to copy.
 * @param len Number of bytes to copy.
 * @return Newly allocated string, or NULL on allocation failure.
 */
char *dup_range(const char *start, size_t len);
/**
 * @brief Trims leading and trailing ASCII whitespace from a string in place.
 * @param text Mutable string buffer to normalize.
 */
void trim_in_place(char *text);
/**
 * @brief Tests whether one string starts with another string.
 * @param value Candidate full string.
 * @param prefix Prefix to test.
 * @return Non-zero when value starts with prefix, otherwise 0.
 */
int starts_with(const char *value, const char *prefix);
/**
 * @brief Tests whether two strings are exactly equal.
 * @param a First string.
 * @param b Second string.
 * @return Non-zero when the strings are equal, otherwise 0.
 */
int streq(const char *a, const char *b);
/**
 * @brief Joins two path segments using the native path separator.
 * @param left Left path segment.
 * @param right Right path segment.
 * @return Newly allocated joined path, or NULL on allocation failure.
 */
char *path_join(const char *left, const char *right);
/**
 * @brief Returns the parent directory component of a path.
 * @param path Source path.
 * @return Newly allocated directory path.
 */
char *path_dirname(const char *path);
/**
 * @brief Tests whether a filesystem path currently exists.
 * @param path Path to test.
 * @return Non-zero when the path exists, otherwise 0.
 */
int path_exists(const char *path);
/**
 * @brief Tests whether a filesystem path refers to a directory.
 * @param path Path to test.
 * @return Non-zero when the path is a directory, otherwise 0.
 */
int path_is_directory(const char *path);
/**
 * @brief Tests whether a filesystem path is writable by the current process.
 * @param path Path to test.
 * @return Non-zero when the path is writable, otherwise 0.
 */
int path_is_writable(const char *path);
/**
 * @brief Normalizes a path by collapsing redundant separators and dot segments.
 * @param path Path to canonicalize.
 * @return Newly allocated canonicalized path, or NULL on failure.
 */
char *path_canonicalize(const char *path);
/**
 * @brief Resolves a path value relative to a base directory when needed.
 * @param base_dir Base directory used for relative values.
 * @param value Raw path value to resolve.
 * @return Newly allocated resolved path, or NULL on failure.
 */
char *resolve_relative_to(const char *base_dir, const char *value);
/**
 * @brief Returns the current working directory.
 * @return Newly allocated working directory path, or NULL on failure.
 */
char *current_working_directory(void);
/**
 * @brief Reads an entire file into a newly allocated text buffer.
 * @param path File path to read.
 * @return Newly allocated text buffer, or NULL on failure.
 */
char *read_file_text(const char *path);
 
 
/** @} */
#endif