mirror/RetroArch
1
0
Fork 0
mirror of https://github.com/libretro/RetroArch synced 2025-02-11 06:40:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

(libretro-common) More documentation refinement

Browse Source
This commit is contained in:
LibretroAdmin 2022-08-01 11:03:58 +02:00
parent c7a1d83675
commit 107c69ab9e
10 changed files with 496 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
libretro-common/encodings/encoding_utf.c
View File

@ -51,9 +51,12 @@ static unsigned leading_ones(uint8_t c)
return ones; return ones;
} }
/* Simple implementation. Assumes the sequence is /**
* properly synchronized and terminated. */ * utf8_conv_utf32:
*
* Simple implementation. Assumes the sequence is
* properly synchronized and terminated.
**/
size_t utf8_conv_utf32(uint32_t *out, size_t out_chars, size_t utf8_conv_utf32(uint32_t *out, size_t out_chars,
const char *in, size_t in_size) const char *in, size_t in_size)
{ {
@ -79,7 +82,7 @@ size_t utf8_conv_utf32(uint32_t *out, size_t out_chars,
for (i = 0; i < extra; i++, in++, shift -= 6) for (i = 0; i < extra; i++, in++, shift -= 6)
c |= (*in & 0x3f) << shift; c |= (*in & 0x3f) << shift;
*out++ = c; *out++ = c;
in_size -= 1 + extra; in_size -= 1 + extra;
out_chars--; out_chars--;
ret++; ret++;
@ -88,6 +91,11 @@ size_t utf8_conv_utf32(uint32_t *out, size_t out_chars,
return ret; return ret;
} }
/**
* utf16_conv_utf8:
*
* Leaf function.
**/
bool utf16_conv_utf8(uint8_t *out, size_t *out_chars, bool utf16_conv_utf8(uint8_t *out, size_t *out_chars,
const uint16_t *in, size_t in_size) const uint16_t *in, size_t in_size)
{ {
@ -148,16 +156,20 @@ bool utf16_conv_utf8(uint8_t *out, size_t *out_chars,
return false; return false;
} }
/* Acts mostly like strlcpy. /**
* utf8cpy:
*
* Acts mostly like strlcpy.
* *
* Copies the given number of UTF-8 characters, * Copies the given number of UTF-8 characters,
* but at most d_len bytes. * but at most @d_len bytes.
* *
* Always NULL terminates. * Always NULL terminates. Does not copy half a character.
* Does not copy half a character. * @s is assumed valid UTF-8.
* Use only if @chars is considerably less than @d_len.
* *
* Returns number of bytes. 's' is assumed valid UTF-8. * @return Number of bytes.
* Use only if 'chars' is considerably less than 'd_len'. */ **/
size_t utf8cpy(char *d, size_t d_len, const char *s, size_t chars) size_t utf8cpy(char *d, size_t d_len, const char *s, size_t chars)
{ {
const uint8_t *sb = (const uint8_t*)s; const uint8_t *sb = (const uint8_t*)s;
@ -186,6 +198,11 @@ size_t utf8cpy(char *d, size_t d_len, const char *s, size_t chars)
return sb-sb_org; return sb-sb_org;
} }
/**
* utf8skip:
*
* Leaf function
**/
const char *utf8skip(const char *str, size_t chars) const char *utf8skip(const char *str, size_t chars)
{ {
const uint8_t *strb = (const uint8_t*)str; const uint8_t *strb = (const uint8_t*)str;
@ -204,6 +221,11 @@ const char *utf8skip(const char *str, size_t chars)
return (const char*)strb; return (const char*)strb;
} }
/**
* utf8len:
*
* Leaf function.
**/
size_t utf8len(const char *string) size_t utf8len(const char *string)
{ {
size_t ret = 0; size_t ret = 0;
@ -220,7 +242,15 @@ size_t utf8len(const char *string)
return ret; return ret;
} }
/* Does not validate the input, returns garbage if it's not UTF-8. */ /**
* utf8_walk:
*
* Does not validate the input.
*
* Leaf function.
*
* @return Returns garbage if it's not UTF-8.
**/
uint32_t utf8_walk(const char **string) uint32_t utf8_walk(const char **string)
{ {
uint8_t first = UTF8_WALKBYTE(string); uint8_t first = UTF8_WALKBYTE(string);
@ -248,23 +278,23 @@ static bool utf16_to_char(uint8_t **utf_data,
size_t *dest_len, const uint16_t *in) size_t *dest_len, const uint16_t *in)
{ {
unsigned len = 0; unsigned len = 0;
while (in[len] != '\0') while (in[len] != '\0')
len++; len++;
utf16_conv_utf8(NULL, dest_len, in, len); utf16_conv_utf8(NULL, dest_len, in, len);
*dest_len += 1; *dest_len += 1;
*utf_data = (uint8_t*)malloc(*dest_len); if ((*utf_data = (uint8_t*)malloc(*dest_len)) != 0)
if (*utf_data != 0)
return utf16_conv_utf8(*utf_data, dest_len, in, len); return utf16_conv_utf8(*utf_data, dest_len, in, len);
return false; return false;
} }
/**
* utf16_to_char_string:
**/
bool utf16_to_char_string(const uint16_t *in, char *s, size_t len) bool utf16_to_char_string(const uint16_t *in, char *s, size_t len)
{ {
size_t dest_len = 0; size_t dest_len = 0;
uint8_t *utf16_data = NULL; uint8_t *utf16_data = NULL;
bool ret = utf16_to_char(&utf16_data, &dest_len, in); bool ret = utf16_to_char(&utf16_data, &dest_len, in);
if (ret) if (ret)
{ {
@ -273,13 +303,17 @@ bool utf16_to_char_string(const uint16_t *in, char *s, size_t len)
} }
free(utf16_data); free(utf16_data);
utf16_data = NULL; utf16_data = NULL;
return ret; return ret;
} }
#if defined(_WIN32) && !defined(_XBOX) && !defined(UNICODE) #if defined(_WIN32) && !defined(_XBOX) && !defined(UNICODE)
/* Returned pointer MUST be freed by the caller if non-NULL. */ /**
* mb_to_mb_string_alloc:
*
* @return Returned pointer MUST be freed by the caller if non-NULL.
**/
static char *mb_to_mb_string_alloc(const char *str, static char *mb_to_mb_string_alloc(const char *str,
enum CodePage cp_in, enum CodePage cp_out) enum CodePage cp_in, enum CodePage cp_out)
{ {
@ -344,35 +378,43 @@ static char *mb_to_mb_string_alloc(const char *str,
} }
#endif #endif
/* Returned pointer MUST be freed by the caller if non-NULL. */ /**
* utf8_to_local_string_alloc:
*
* @return Returned pointer MUST be freed by the caller if non-NULL.
**/
char* utf8_to_local_string_alloc(const char *str) char* utf8_to_local_string_alloc(const char *str)
{ {
#if defined(_WIN32) && !defined(_XBOX) && !defined(UNICODE)
if (str && *str) if (str && *str)
#if defined(_WIN32) && !defined(_XBOX) && !defined(UNICODE)
return mb_to_mb_string_alloc(str, CODEPAGE_UTF8, CODEPAGE_LOCAL); return mb_to_mb_string_alloc(str, CODEPAGE_UTF8, CODEPAGE_LOCAL);
#else #else
/* Assume string needs no modification if not on Windows */ return strdup(str); /* Assume string needs no modification if not on Windows */
if (str && *str)
return strdup(str);
#endif #endif
return NULL; return NULL;
} }
/* Returned pointer MUST be freed by the caller if non-NULL. */ /**
char* local_to_utf8_string_alloc(const char *str) * local_to_utf8_string_alloc:
*
* @return Returned pointer MUST be freed by the caller if non-NULL.
**/
char *local_to_utf8_string_alloc(const char *str)
{ {
#if defined(_WIN32) && !defined(_XBOX) && !defined(UNICODE)
if (str && *str) if (str && *str)
#if defined(_WIN32) && !defined(_XBOX) && !defined(UNICODE)
return mb_to_mb_string_alloc(str, CODEPAGE_LOCAL, CODEPAGE_UTF8); return mb_to_mb_string_alloc(str, CODEPAGE_LOCAL, CODEPAGE_UTF8);
#else #else
/* Assume string needs no modification if not on Windows */ return strdup(str); /* Assume string needs no modification if not on Windows */
if (str && *str)
return strdup(str);
#endif #endif
return NULL; return NULL;
} }
/* Returned pointer MUST be freed by the caller if non-NULL. */ /**
* utf8_to_utf16_string_alloc:
*
* @return Returned pointer MUST be freed by the caller if non-NULL.
**/
wchar_t* utf8_to_utf16_string_alloc(const char *str) wchar_t* utf8_to_utf16_string_alloc(const char *str)
{ {
#ifdef _WIN32 #ifdef _WIN32
@ -430,7 +472,11 @@ wchar_t* utf8_to_utf16_string_alloc(const char *str)
return buf; return buf;
} }
/* Returned pointer MUST be freed by the caller if non-NULL. */ /**
* utf16_to_utf8_string_alloc:
*
* @return Returned pointer MUST be freed by the caller if non-NULL.
**/
char* utf16_to_utf8_string_alloc(const wchar_t *str) char* utf16_to_utf8_string_alloc(const wchar_t *str)
{ {
#ifdef _WIN32 #ifdef _WIN32

140
libretro-common/file/config_file.c
View File

@ -137,7 +137,10 @@ static struct config_entry_list* config_file_merge_sort_linked_list(
return result; return result;
} }
/* Searches input string for a comment ('#') entry /**
* config_file_strip_comment:
*
* Searches input string for a comment ('#') entry
* > If first character is '#', then entire line is * > If first character is '#', then entire line is
* a comment and may correspond to a directive * a comment and may correspond to a directive
* (command action - e.g. include sub-config file). * (command action - e.g. include sub-config file).
@ -151,7 +154,8 @@ static struct config_entry_list* config_file_merge_sort_linked_list(
* > If a '#' character is found anywhere else, then the * > If a '#' character is found anywhere else, then the
* comment text is a suffix of the input string and * comment text is a suffix of the input string and
* has no programmatic value. In this case, the comment * has no programmatic value. In this case, the comment
* is removed from the end of 'str' and NULL is returned */ * is removed from the end of 'str' and NULL is returned
**/
static char *config_file_strip_comment(char *str) static char *config_file_strip_comment(char *str)
{ {
/* Search for a comment (#) character */ /* Search for a comment (#) character */
@ -254,7 +258,8 @@ static char *config_file_extract_value(char *line)
} }
/* Move semantics? */ /* Move semantics? */
static void config_file_add_child_list(config_file_t *parent, config_file_t *child) static void config_file_add_child_list(config_file_t *parent,
config_file_t *child)
{ {
struct config_entry_list *list = child->entries; struct config_entry_list *list = child->entries;
bool merge_hash_map = false; bool merge_hash_map = false;
@ -750,17 +755,27 @@ bool config_file_deinitialize(config_file_t *conf)
return true; return true;
} }
/**
* config_file_free:
*
* Frees config file.
**/
void config_file_free(config_file_t *conf) void config_file_free(config_file_t *conf)
{ {
if (config_file_deinitialize(conf)) if (config_file_deinitialize(conf))
free(conf); free(conf);
} }
/**
* config_append_file:
*
* Loads a new config, and appends its data to @conf.
* The key-value pairs of the new config file takes priority over the old.
**/
bool config_append_file(config_file_t *conf, const char *path) bool config_append_file(config_file_t *conf, const char *path)
{ {
size_t i, cap;
config_file_t *new_conf = config_file_new_from_path_to_string(path); config_file_t *new_conf = config_file_new_from_path_to_string(path);
size_t i;
size_t cap;
if (!new_conf) if (!new_conf)
return false; return false;
@ -791,6 +806,15 @@ bool config_append_file(config_file_t *conf, const char *path)
return true; return true;
} }
/**
* config_file_new_from_string:
*
* Load a config file from a string.
*
* NOTE: This will modify @from_string.
* Pass a copy of source string if original
* contents must be preserved
**/
config_file_t *config_file_new_from_string(char *from_string, config_file_t *config_file_new_from_string(char *from_string,
const char *path) const char *path)
{ {
@ -829,6 +853,15 @@ config_file_t *config_file_new_from_path_to_string(const char *path)
return NULL; return NULL;
} }
/**
* config_file_new_with_callback:
*
* Loads a config file.
* If @path is NULL, will create an empty config file.
* Includes cb callbacks to run custom code during config file processing.
*
* @return Returns NULL if file doesn't exist.
**/
config_file_t *config_file_new_with_callback( config_file_t *config_file_new_with_callback(
const char *path, config_file_cb_t *cb) const char *path, config_file_cb_t *cb)
{ {
@ -849,6 +882,14 @@ config_file_t *config_file_new_with_callback(
return conf; return conf;
} }
/**
* config_file_new:
*
* Loads a config file.
* If @path is NULL, will create an empty config file.
*
* @return Returns NULL if file doesn't exist.
**/
config_file_t *config_file_new(const char *path) config_file_t *config_file_new(const char *path)
{ {
int ret = 0; int ret = 0;
@ -868,6 +909,11 @@ config_file_t *config_file_new(const char *path)
return conf; return conf;
} }
/**
* config_file_initialize:
*
* Leaf function.
**/
void config_file_initialize(struct config_file *conf) void config_file_initialize(struct config_file *conf)
{ {
if (!conf) if (!conf)
@ -894,6 +940,11 @@ config_file_t *config_file_new_alloc(void)
return conf; return conf;
} }
/**
* config_get_entry_internal:
*
* Leaf function.
**/
static struct config_entry_list *config_get_entry_internal( static struct config_entry_list *config_get_entry_internal(
const config_file_t *conf, const config_file_t *conf,
const char *key, struct config_entry_list **prev) const char *key, struct config_entry_list **prev)
@ -921,6 +972,13 @@ struct config_entry_list *config_get_entry(
return RHMAP_GET_STR(conf->entries_map, key); return RHMAP_GET_STR(conf->entries_map, key);
} }
/**
* config_get_double:
*
* Extracts a double from config file.
*
* @return true if found, otherwise false.
**/
bool config_get_double(config_file_t *conf, const char *key, double *in) bool config_get_double(config_file_t *conf, const char *key, double *in)
{ {
const struct config_entry_list *entry = config_get_entry(conf, key); const struct config_entry_list *entry = config_get_entry(conf, key);
@ -932,6 +990,13 @@ bool config_get_double(config_file_t *conf, const char *key, double *in)
return true; return true;
} }
/**
* config_get_float:
*
* Extracts a float from config file.
*
* @return true if found, otherwise false.
**/
bool config_get_float(config_file_t *conf, const char *key, float *in) bool config_get_float(config_file_t *conf, const char *key, float *in)
{ {
const struct config_entry_list *entry = config_get_entry(conf, key); const struct config_entry_list *entry = config_get_entry(conf, key);
@ -1039,6 +1104,14 @@ bool config_get_hex(config_file_t *conf, const char *key, unsigned *in)
return false; return false;
} }
/**
* config_get_char:
*
* Extracts a single char from config file.
* If value consists of several chars, this is an error.
*
* @return true if found, otherwise false.
**/
bool config_get_char(config_file_t *conf, const char *key, char *in) bool config_get_char(config_file_t *conf, const char *key, char *in)
{ {
const struct config_entry_list *entry = config_get_entry(conf, key); const struct config_entry_list *entry = config_get_entry(conf, key);
@ -1055,6 +1128,14 @@ bool config_get_char(config_file_t *conf, const char *key, char *in)
return false; return false;
} }
/**
* config_get_string:
*
* Extracts an allocated string in *in. This must be free()-d if
* this function succeeds.
*
* @return true if found, otherwise false.
**/
bool config_get_string(config_file_t *conf, const char *key, char **str) bool config_get_string(config_file_t *conf, const char *key, char **str)
{ {
const struct config_entry_list *entry = config_get_entry(conf, key); const struct config_entry_list *entry = config_get_entry(conf, key);
@ -1066,6 +1147,12 @@ bool config_get_string(config_file_t *conf, const char *key, char **str)
return true; return true;
} }
/**
* config_get_config_path:
*
* Extracts a string to a preallocated buffer.
* Avoid memory allocation.
**/
bool config_get_config_path(config_file_t *conf, char *s, size_t len) bool config_get_config_path(config_file_t *conf, char *s, size_t len)
{ {
if (conf) if (conf)
@ -1090,7 +1177,6 @@ bool config_get_path(config_file_t *conf, const char *key,
return true; return true;
#else #else
const struct config_entry_list *entry = config_get_entry(conf, key); const struct config_entry_list *entry = config_get_entry(conf, key);
if (entry) if (entry)
{ {
fill_pathname_expand_special(buf, entry->value, size); fill_pathname_expand_special(buf, entry->value, size);
@ -1100,6 +1186,15 @@ bool config_get_path(config_file_t *conf, const char *key,
return false; return false;
} }
/**
* config_get_bool:
*
* Extracts a boolean from config.
* Valid boolean true are "true" and "1". Valid false are "false" and "0".
* Other values will be treated as an error.
*
* @return true if preconditions are true, otherwise false.
**/
bool config_get_bool(config_file_t *conf, const char *key, bool *in) bool config_get_bool(config_file_t *conf, const char *key, bool *in)
{ {
const struct config_entry_list *entry = config_get_entry(conf, key); const struct config_entry_list *entry = config_get_entry(conf, key);
@ -1146,9 +1241,7 @@ void config_set_string(config_file_t *conf, const char *key, const char *val)
} }
else else
{ {
entry = config_get_entry_internal( if ((entry = config_get_entry_internal(conf, key, &last)))
conf, key, &last);
if (entry)
{ {
/* An entry corresponding to 'key' already exists /* An entry corresponding to 'key' already exists
* > Check whether value is currently set */ * > Check whether value is currently set */
@ -1175,8 +1268,7 @@ void config_set_string(config_file_t *conf, const char *key, const char *val)
/* Entry corresponding to 'key' does not exist /* Entry corresponding to 'key' does not exist
* > Create new entry */ * > Create new entry */
entry = (struct config_entry_list*)malloc(sizeof(*entry)); if (!(entry = (struct config_entry_list*)malloc(sizeof(*entry))))
if (!entry)
return; return;
entry->readonly = false; entry->readonly = false;
@ -1287,11 +1379,21 @@ void config_set_char(config_file_t *conf, const char *key, char val)
config_set_string(conf, key, buf); config_set_string(conf, key, buf);
} }
/**
* config_set_bool:
* TODO/FIXME - could be turned into a trivial macro or removed
**/
void config_set_bool(config_file_t *conf, const char *key, bool val) void config_set_bool(config_file_t *conf, const char *key, bool val)
{ {
config_set_string(conf, key, val ? "true" : "false"); config_set_string(conf, key, val ? "true" : "false");
} }
/**
* config_file_write:
*
* Write the current config to a file.
**/
bool config_file_write(config_file_t *conf, const char *path, bool sort) bool config_file_write(config_file_t *conf, const char *path, bool sort)
{ {
if (!conf) if (!conf)
@ -1327,6 +1429,12 @@ bool config_file_write(config_file_t *conf, const char *path, bool sort)
return true; return true;
} }
/**
* config_file_dump:
*
* Dump the current config to an already opened file.
* Does not close the file.
**/
void config_file_dump(config_file_t *conf, FILE *file, bool sort) void config_file_dump(config_file_t *conf, FILE *file, bool sort)
{ {
struct config_entry_list *list = NULL; struct config_entry_list *list = NULL;
@ -1369,6 +1477,11 @@ void config_file_dump(config_file_t *conf, FILE *file, bool sort)
} }
} }
/**
* config_get_entry_list_head:
*
* Leaf function.
**/
bool config_get_entry_list_head(config_file_t *conf, bool config_get_entry_list_head(config_file_t *conf,
struct config_file_entry *entry) struct config_file_entry *entry)
{ {
@ -1383,6 +1496,11 @@ bool config_get_entry_list_head(config_file_t *conf,
return true; return true;
} }
/**
* config_get_entry_list_next:
*
* Leaf function.
**/
bool config_get_entry_list_next(struct config_file_entry *entry) bool config_get_entry_list_next(struct config_file_entry *entry)
{ {
const struct config_entry_list *next = entry->next; const struct config_entry_list *next = entry->next;

6
libretro-common/file/file_path_io.c
View File

@ -74,7 +74,7 @@ int path_stat(const char *path)
* *
* Checks if path is a directory. * Checks if path is a directory.
* *
* Returns: true (1) if path is a directory, otherwise false (0). * @return true if path is a directory, otherwise false.
*/ */
bool path_is_directory(const char *path) bool path_is_directory(const char *path)
{ {
@ -105,8 +105,10 @@ int32_t path_get_size(const char *path)
* @dir : directory * @dir : directory
* *
* Create directory on filesystem. * Create directory on filesystem.
*
* Recursive function.
* *
* Returns: true (1) if directory could be created, otherwise false (0). * @return true if directory could be created, otherwise false.
**/ **/
bool path_mkdir(const char *dir) bool path_mkdir(const char *dir)
{ {

78
libretro-common/include/encodings/utf.h
View File

@ -38,29 +38,99 @@ enum CodePage
CODEPAGE_UTF8 = 65001 /* CP_UTF8 */ CODEPAGE_UTF8 = 65001 /* CP_UTF8 */
}; };
/**
* utf8_conv_utf32:
*
* Simple implementation. Assumes the sequence is
* properly synchronized and terminated.
**/
size_t utf8_conv_utf32(uint32_t *out, size_t out_chars, size_t utf8_conv_utf32(uint32_t *out, size_t out_chars,
const char *in, size_t in_size); const char *in, size_t in_size);
/**
* utf16_conv_utf8:
*
* Leaf function.
**/
bool utf16_conv_utf8(uint8_t *out, size_t *out_chars, bool utf16_conv_utf8(uint8_t *out, size_t *out_chars,
const uint16_t *in, size_t in_size); const uint16_t *in, size_t in_size);
/**
* utf8len:
*
* Leaf function.
**/
size_t utf8len(const char *string); size_t utf8len(const char *string);
/**
* utf8cpy:
*
* Acts mostly like strlcpy.
*
* Copies the given number of UTF-8 characters,
* but at most @d_len bytes.
*
* Always NULL terminates. Does not copy half a character.
* @s is assumed valid UTF-8.
* Use only if @chars is considerably less than @d_len.
*
* Hidden non-leaf function cost:
* - Calls memcpy
*
* @return Number of bytes.
**/
size_t utf8cpy(char *d, size_t d_len, const char *s, size_t chars); size_t utf8cpy(char *d, size_t d_len, const char *s, size_t chars);
/**
* utf8skip:
*
* Leaf function
**/
const char *utf8skip(const char *str, size_t chars); const char *utf8skip(const char *str, size_t chars);
/**
* utf8_walk:
*
* Does not validate the input.
*
* Leaf function.
*
* @return Returns garbage if it's not UTF-8.
**/
uint32_t utf8_walk(const char **string); uint32_t utf8_walk(const char **string);
/**
* utf16_to_char_string:
**/
bool utf16_to_char_string(const uint16_t *in, char *s, size_t len); bool utf16_to_char_string(const uint16_t *in, char *s, size_t len);
char* utf8_to_local_string_alloc(const char *str); /**
* utf8_to_local_string_alloc:
*
* @return Returned pointer MUST be freed by the caller if non-NULL.
**/
char *utf8_to_local_string_alloc(const char *str);
char* local_to_utf8_string_alloc(const char *str); /**
* local_to_utf8_string_alloc:
*
* @return Returned pointer MUST be freed by the caller if non-NULL.
**/
char *local_to_utf8_string_alloc(const char *str);
wchar_t* utf8_to_utf16_string_alloc(const char *str); /**
* utf8_to_utf16_string_alloc:
*
* @return Returned pointer MUST be freed by the caller if non-NULL.
**/
wchar_t *utf8_to_utf16_string_alloc(const char *str);
char* utf16_to_utf8_string_alloc(const wchar_t *str); /**
* utf16_to_utf8_string_alloc:
*
* @return Returned pointer MUST be freed by the caller if non-NULL.
**/
char *utf16_to_utf8_string_alloc(const wchar_t *str);
RETRO_END_DECLS RETRO_END_DECLS

171
libretro-common/include/file/config_file.h
View File

@ -84,37 +84,68 @@ typedef struct config_file_cb config_file_cb_t ;
* Key/value pairs from an #include are read-only, and cannot be modified. * Key/value pairs from an #include are read-only, and cannot be modified.
*/ */
/* Loads a config file. Returns NULL if file doesn't exist. /**
* NULL path will create an empty config file. */ * config_file_new:
*
* Loads a config file.
* If @path is NULL, will create an empty config file.
*
* @return Returns NULL if file doesn't exist.
**/
config_file_t *config_file_new(const char *path); config_file_t *config_file_new(const char *path);
config_file_t *config_file_new_alloc(void); config_file_t *config_file_new_alloc(void);
/**
* config_file_initialize:
*
* Leaf function.
**/
void config_file_initialize(struct config_file *conf); void config_file_initialize(struct config_file *conf);
/* Loads a config file. Returns NULL if file doesn't exist. /**
* NULL path will create an empty config file. * config_file_new_with_callback:
* Includes cb callbacks to run custom code during config file processing.*/ *
config_file_t *config_file_new_with_callback(const char *path, config_file_cb_t *cb); * Loads a config file.
* If @path is NULL, will create an empty config file.
* Includes cb callbacks to run custom code during config file processing.
*
* @return Returns NULL if file doesn't exist.
**/
config_file_t *config_file_new_with_callback(
const char *path, config_file_cb_t *cb);
/* Load a config file from a string. /**
* > WARNING: This will modify 'from_string'. * config_file_new_from_string:
* Pass a copy of source string if original *
* contents must be preserved */ * Load a config file from a string.
*
* NOTE: This will modify @from_string.
* Pass a copy of source string if original
* contents must be preserved
**/
config_file_t *config_file_new_from_string(char *from_string, config_file_t *config_file_new_from_string(char *from_string,
const char *path); const char *path);
config_file_t *config_file_new_from_path_to_string(const char *path); config_file_t *config_file_new_from_path_to_string(const char *path);
/* Frees config file. */ /**
* config_file_free:
*
* Frees config file.
**/
void config_file_free(config_file_t *conf); void config_file_free(config_file_t *conf);
void config_file_add_reference(config_file_t *conf, char *path); void config_file_add_reference(config_file_t *conf, char *path);
bool config_file_deinitialize(config_file_t *conf); bool config_file_deinitialize(config_file_t *conf);
/* Loads a new config, and appends its data to conf. /**
* The key-value pairs of the new config file takes priority over the old. */ * config_append_file:
*
* Loads a new config, and appends its data to @conf.
* The key-value pairs of the new config file takes priority over the old.
**/
bool config_append_file(config_file_t *conf, const char *path); bool config_append_file(config_file_t *conf, const char *path);
/* All extract functions return true when value is valid and exists. /* All extract functions return true when value is valid and exists.
@ -130,7 +161,6 @@ struct config_entry_list
bool readonly; bool readonly;
}; };
struct config_file_entry struct config_file_entry
{ {
const char *key; const char *key;
@ -142,13 +172,45 @@ struct config_file_entry
struct config_entry_list *config_get_entry( struct config_entry_list *config_get_entry(
const config_file_t *conf, const char *key); const config_file_t *conf, const char *key);
bool config_get_entry_list_head(config_file_t *conf, struct config_file_entry *entry); /**
* config_get_entry_list_head:
*
* Leaf function.
**/
bool config_get_entry_list_head(config_file_t *conf,
struct config_file_entry *entry);
/**
* config_get_entry_list_next:
*
* Leaf function.
**/
bool config_get_entry_list_next(struct config_file_entry *entry); bool config_get_entry_list_next(struct config_file_entry *entry);
/* Extracts a double from config file. */ /**
* config_get_double:
*
* Extracts a double from config file.
*
* Hidden non-leaf function cost:
* - Calls config_get_entry()
* - Calls strtod
*
* @return True if double found, otherwise false.
**/
bool config_get_double(config_file_t *conf, const char *entry, double *in); bool config_get_double(config_file_t *conf, const char *entry, double *in);
/* Extracts a float from config file. */ /**
* config_get_float:
*
* Extracts a float from config file.
*
* Hidden non-leaf function cost:
* - Calls config_get_entry()
* - Calls strtod
*
* @return true if found, otherwise false.
**/
bool config_get_float(config_file_t *conf, const char *entry, float *in); bool config_get_float(config_file_t *conf, const char *entry, float *in);
/* Extracts an int from config file. */ /* Extracts an int from config file. */
@ -168,27 +230,63 @@ bool config_get_uint64(config_file_t *conf, const char *entry, uint64_t *in);
/* Extracts an unsigned int from config file treating input as hex. */ /* Extracts an unsigned int from config file treating input as hex. */
bool config_get_hex(config_file_t *conf, const char *entry, unsigned *in); bool config_get_hex(config_file_t *conf, const char *entry, unsigned *in);
/* Extracts a single char. If value consists of several chars, /**
* this is an error. */ * config_get_char:
*
* Extracts a single char from config file.
* If value consists of several chars, this is an error.
*
* Hidden non-leaf function cost:
* - Calls config_get_entry()
*
* @return true if found, otherwise false.
**/
bool config_get_char(config_file_t *conf, const char *entry, char *in); bool config_get_char(config_file_t *conf, const char *entry, char *in);
/* Extracts an allocated string in *in. This must be free()-d if /**
* this function succeeds. */ * config_get_string:
*
* Extracts an allocated string in *in. This must be free()-d if
* this function succeeds.
*
* Hidden non-leaf function cost:
* - Calls config_get_entry()
* - Calls strdup
*
* @return true if found, otherwise false.
**/
bool config_get_string(config_file_t *conf, const char *entry, char **in); bool config_get_string(config_file_t *conf, const char *entry, char **in);
/* Extracts a string to a preallocated buffer. Avoid memory allocation. */ /* Extracts a string to a preallocated buffer. Avoid memory allocation. */
bool config_get_array(config_file_t *conf, const char *entry, char *s, size_t len); bool config_get_array(config_file_t *conf, const char *entry, char *s, size_t len);
/**
* config_get_config_path:
*
* Extracts a string to a preallocated buffer.
* Avoid memory allocation.
*
* Hidden non-leaf function cost:
* - Calls strlcpy
**/
bool config_get_config_path(config_file_t *conf, char *s, size_t len);
/* Extracts a string to a preallocated buffer. Avoid memory allocation. /* Extracts a string to a preallocated buffer. Avoid memory allocation.
* Recognized magic like ~/. Similar to config_get_array() otherwise. */ * Recognized magic like ~/. Similar to config_get_array() otherwise. */
bool config_get_path(config_file_t *conf, const char *entry, char *s, size_t len); bool config_get_path(config_file_t *conf, const char *entry, char *s, size_t len);
/* Extracts a string to a preallocated buffer. Avoid memory allocation. */ /**
bool config_get_config_path(config_file_t *conf, char *s, size_t len); * config_get_bool:
*
/* Extracts a boolean from config. * Extracts a boolean from config.
* Valid boolean true are "true" and "1". Valid false are "false" and "0". * Valid boolean true are "true" and "1". Valid false are "false" and "0".
* Other values will be treated as an error. */ * Other values will be treated as an error.
*
* Hidden non-leaf function cost:
* - Calls string_is_equal() x times
*
* @return true if preconditions are true, otherwise false.
**/
bool config_get_bool(config_file_t *conf, const char *entry, bool *in); bool config_get_bool(config_file_t *conf, const char *entry, bool *in);
/* Setters. Similar to the getters. /* Setters. Similar to the getters.
@ -202,14 +300,29 @@ void config_set_char(config_file_t *conf, const char *entry, char val);
void config_set_string(config_file_t *conf, const char *entry, const char *val); void config_set_string(config_file_t *conf, const char *entry, const char *val);
void config_unset(config_file_t *conf, const char *key); void config_unset(config_file_t *conf, const char *key);
void config_set_path(config_file_t *conf, const char *entry, const char *val); void config_set_path(config_file_t *conf, const char *entry, const char *val);
/**
* config_set_bool:
* TODO/FIXME - could be turned into a trivial macro or removed
**/
void config_set_bool(config_file_t *conf, const char *entry, bool val); void config_set_bool(config_file_t *conf, const char *entry, bool val);
void config_set_uint(config_file_t *conf, const char *key, unsigned int val); void config_set_uint(config_file_t *conf, const char *key, unsigned int val);
/* Write the current config to a file. */ /**
* config_file_write:
*
* Write the current config to a file.
**/
bool config_file_write(config_file_t *conf, const char *path, bool val); bool config_file_write(config_file_t *conf, const char *path, bool val);
/* Dump the current config to an already opened file. /**
* Does not close the file. */ * config_file_dump:
*
* Dump the current config to an already opened file.
* Does not close the file.
**/
void config_file_dump(config_file_t *conf, FILE *file, bool val); void config_file_dump(config_file_t *conf, FILE *file, bool val);
bool config_file_exists(const char *path); bool config_file_exists(const char *path);

21
libretro-common/include/file/file_path.h
View File

@ -119,7 +119,7 @@ const char *path_get_archive_delim(const char *path);
* after the last slash are considered. * after the last slash are considered.
* *
* Hidden non-leaf function cost: * Hidden non-leaf function cost:
* - calls string_is_empty * - calls string_is_empty()
* - calls strrchr * - calls strrchr
* *
* @return extension part from the path. * @return extension part from the path.
@ -153,7 +153,7 @@ char *path_remove_extension(char *path);
* *
* Hidden non-leaf function cost: * Hidden non-leaf function cost:
* - Calls path_get_archive_delim() * - Calls path_get_archive_delim()
* - can call find_last_slash once if it returns NULL * - can call find_last_slash() once if it returns NULL
* *
* @return basename from path. * @return basename from path.
**/ **/
@ -167,7 +167,7 @@ const char *path_basename(const char *path);
* Get basename from @path. * Get basename from @path.
* *
* Hidden non-leaf function cost: * Hidden non-leaf function cost:
* - Calls find_last_slash * - Calls find_last_slash()
* *
* @return basename from path. * @return basename from path.
**/ **/
@ -304,9 +304,9 @@ size_t fill_dated_filename(char *out_filename,
* *
* Hidden non-leaf function cost: * Hidden non-leaf function cost:
* - Calls time * - Calls time
* - Calls rtime_localtime * - Calls rtime_localtime()
* - Calls strlcpy * - Calls strlcpy
* - Calls string_is_empty * - Calls string_is_empty()
* - Calls strftime * - Calls strftime
* - Calls strlcat at least 2x * - Calls strlcat at least 2x
**/ **/
@ -397,7 +397,7 @@ void fill_pathname_basedir(char *out_path, const char *in_path, size_t size);
* *
* Hidden non-leaf function cost: * Hidden non-leaf function cost:
* - Calls strdup * - Calls strdup
* - Calls find_last_slash x times * - Calls find_last_slash() x times
* - Can call strlcpy * - Can call strlcpy
* *
* @return true on success, false if a slash was not found in the path. * @return true on success, false if a slash was not found in the path.
@ -588,6 +588,15 @@ void fill_pathname_home_dir(char *buf, size_t size);
* *
* Create directory on filesystem. * Create directory on filesystem.
* *
* Recursive function.
*
* Hidden non-leaf function cost:
* - Calls strdup
* - Calls path_parent_dir()
* - Calls strcmp
* - Calls path_is_directory()
* - Calls path_mkdir()
*
* @return true if directory could be created, otherwise false. * @return true if directory could be created, otherwise false.
**/ **/
bool path_mkdir(const char *dir); bool path_mkdir(const char *dir);

15
libretro-common/include/lists/dir_list.h
View File

@ -42,7 +42,7 @@ RETRO_BEGIN_DECLS
* *
* Create a directory listing, appending to an existing list * Create a directory listing, appending to an existing list
* *
* Returns: true success, false in case of error. * @return Returns true on success, otherwise false.
**/ **/
bool dir_list_append(struct string_list *list, const char *dir, const char *ext, bool dir_list_append(struct string_list *list, const char *dir, const char *ext,
bool include_dirs, bool include_hidden, bool include_compressed, bool recursive); bool include_dirs, bool include_hidden, bool include_compressed, bool recursive);
@ -58,15 +58,18 @@ bool dir_list_append(struct string_list *list, const char *dir, const char *ext,
* *
* Create a directory listing. * Create a directory listing.
* *
* Returns: pointer to a directory listing of type 'struct string_list *' on success, * @return pointer to a directory listing of type 'struct string_list *' on success,
* NULL in case of error. Has to be freed manually. * NULL in case of error. Has to be freed manually.
**/ **/
struct string_list *dir_list_new(const char *dir, const char *ext, struct string_list *dir_list_new(const char *dir, const char *ext,
bool include_dirs, bool include_hidden, bool include_compressed, bool recursive); bool include_dirs, bool include_hidden, bool include_compressed, bool recursive);
/* Warning: 'list' must zero initialised before /**
* calling this function, otherwise memory leaks/ * dir_list_initialize:
* undefined behaviour will occur */ *
* NOTE: @list must zero initialised before
* calling this function, otherwise UB.
**/
bool dir_list_initialize(struct string_list *list, bool dir_list_initialize(struct string_list *list,
const char *dir, const char *dir,
const char *ext, bool include_dirs, const char *ext, bool include_dirs,
@ -79,7 +82,6 @@ bool dir_list_initialize(struct string_list *list,
* @dir_first : move the directories in the listing to the top? * @dir_first : move the directories in the listing to the top?
* *
* Sorts a directory listing. * Sorts a directory listing.
*
**/ **/
void dir_list_sort(struct string_list *list, bool dir_first); void dir_list_sort(struct string_list *list, bool dir_first);
@ -88,7 +90,6 @@ void dir_list_sort(struct string_list *list, bool dir_first);
* @list : pointer to the directory listing * @list : pointer to the directory listing
* *
* Frees a directory listing. * Frees a directory listing.
*
**/ **/
void dir_list_free(struct string_list *list); void dir_list_free(struct string_list *list);

35
libretro-common/include/lists/string_list.h
View File

@ -59,7 +59,7 @@ struct string_list
* *
* Searches for an element (@elem) inside the string list. * Searches for an element (@elem) inside the string list.
* *
* Returns: true (1) if element could be found, otherwise false (0). * @return Number of elements found, otherwise 0.
*/ */
int string_list_find_elem(const struct string_list *list, const char *elem); int string_list_find_elem(const struct string_list *list, const char *elem);
@ -100,8 +100,8 @@ bool string_split_noalloc(struct string_list *list,
* Includes empty strings - i.e. two adjacent delimiters will resolve * Includes empty strings - i.e. two adjacent delimiters will resolve
* to a string list element of "". * to a string list element of "".
* *
* Returns: new string list if successful, otherwise NULL. * @return New string list if successful, otherwise NULL.
*/ **/
struct string_list *string_separate(char *str, const char *delim); struct string_list *string_separate(char *str, const char *delim);
bool string_separate_noalloc(struct string_list *list, bool string_separate_noalloc(struct string_list *list,
@ -116,8 +116,8 @@ bool string_list_initialize(struct string_list *list);
* *
* Creates a new string list. Has to be freed manually. * Creates a new string list. Has to be freed manually.
* *
* Returns: new string list if successful, otherwise NULL. * @return New string list if successful, otherwise NULL.
*/ **/
struct string_list *string_list_new(void); struct string_list *string_list_new(void);
/** /**
@ -127,8 +127,12 @@ struct string_list *string_list_new(void);
* @attr : attributes of new element. * @attr : attributes of new element.
* *
* Appends a new element to the string list. * Appends a new element to the string list.
* Hidden non-leaf function cost:
* - Calls string_list_capacity()
* - Calls strdup
* *
* Returns: true (1) if successful, otherwise false (0). * @return true if successful, otherwise false.
**/ **/
bool string_list_append(struct string_list *list, const char *elem, bool string_list_append(struct string_list *list, const char *elem,
union string_list_elem_attr attr); union string_list_elem_attr attr);
@ -142,7 +146,12 @@ bool string_list_append(struct string_list *list, const char *elem,
* *
* Appends a new element to the string list. * Appends a new element to the string list.
* *
* Returns: true (1) if successful, otherwise false (0). * Hidden non-leaf function cost:
* - Calls string_list_capacity()
* - Calls malloc
* - Calls strlcpy
*
* @return true if successful, otherwise false.
**/ **/
bool string_list_append_n(struct string_list *list, const char *elem, bool string_list_append_n(struct string_list *list, const char *elem,
unsigned length, union string_list_elem_attr attr); unsigned length, union string_list_elem_attr attr);
@ -152,7 +161,7 @@ bool string_list_append_n(struct string_list *list, const char *elem,
* @list : pointer to string list object * @list : pointer to string list object
* *
* Frees a string list. * Frees a string list.
*/ **/
void string_list_free(struct string_list *list); void string_list_free(struct string_list *list);
/** /**
@ -166,7 +175,11 @@ void string_list_free(struct string_list *list);
* string to @buffer, delimited by @delim. * string to @buffer, delimited by @delim.
* *
* NOTE: @buffer must be NULL-terminated. * NOTE: @buffer must be NULL-terminated.
*/ *
* Hidden non-leaf function cost:
* - Calls strlen_size()
* - Calls strlcat x times in a loop
**/
void string_list_join_concat(char *buffer, size_t size, void string_list_join_concat(char *buffer, size_t size,
const struct string_list *list, const char *sep); const struct string_list *list, const char *sep);
@ -177,6 +190,10 @@ void string_list_join_concat(char *buffer, size_t size,
* @str : value for the element. * @str : value for the element.
* *
* Set value of element inside string list. * Set value of element inside string list.
*
* Hidden non-leaf function cost:
* - Calls free
* - Calls strdup
**/ **/
void string_list_set(struct string_list *list, unsigned idx, void string_list_set(struct string_list *list, unsigned idx,
const char *str); const char *str);

17
libretro-common/lists/dir_list.c
View File

@ -65,7 +65,6 @@ static int qstrcmp_dir(const void *a_, const void *b_)
* @dir_first : move the directories in the listing to the top? * @dir_first : move the directories in the listing to the top?
* *
* Sorts a directory listing. * Sorts a directory listing.
*
**/ **/
void dir_list_sort(struct string_list *list, bool dir_first) void dir_list_sort(struct string_list *list, bool dir_first)
{ {
@ -79,7 +78,6 @@ void dir_list_sort(struct string_list *list, bool dir_first)
* @list : pointer to the directory listing * @list : pointer to the directory listing
* *
* Frees a directory listing. * Frees a directory listing.
*
**/ **/
void dir_list_free(struct string_list *list) void dir_list_free(struct string_list *list)
{ {
@ -105,7 +103,7 @@ bool dir_list_deinitialize(struct string_list *list)
* *
* Add files within a directory to an existing string list * Add files within a directory to an existing string list
* *
* Returns: -1 on error, 0 on success. * @return -1 on error, 0 on success.
**/ **/
static int dir_list_read(const char *dir, static int dir_list_read(const char *dir,
struct string_list *list, struct string_list *ext_list, struct string_list *list, struct string_list *ext_list,
@ -205,7 +203,7 @@ error:
* *
* Create a directory listing, appending to an existing list * Create a directory listing, appending to an existing list
* *
* Returns: true success, false in case of error. * @return Returns true on success, otherwise false.
**/ **/
bool dir_list_append(struct string_list *list, bool dir_list_append(struct string_list *list,
const char *dir, const char *dir,
@ -240,7 +238,7 @@ bool dir_list_append(struct string_list *list,
* *
* Create a directory listing. * Create a directory listing.
* *
* Returns: pointer to a directory listing of type 'struct string_list *' on success, * @return pointer to a directory listing of type 'struct string_list *' on success,
* NULL in case of error. Has to be freed manually. * NULL in case of error. Has to be freed manually.
**/ **/
struct string_list *dir_list_new(const char *dir, struct string_list *dir_list_new(const char *dir,
@ -263,9 +261,12 @@ struct string_list *dir_list_new(const char *dir,
return list; return list;
} }
/* Warning: 'list' must zero initialised before /**
* calling this function, otherwise memory leaks/ * dir_list_initialize:
* undefined behaviour will occur */ *
* NOTE: @list must zero initialised before
* calling this function, otherwise UB.
**/
bool dir_list_initialize(struct string_list *list, bool dir_list_initialize(struct string_list *list,
const char *dir, const char *dir,
const char *ext, bool include_dirs, const char *ext, bool include_dirs,

20
libretro-common/lists/string_list.c
View File

@ -62,7 +62,7 @@ static bool string_list_deinitialize_internal(struct string_list *list)
* *
* Change maximum capacity of string list's size. * Change maximum capacity of string list's size.
* *
* Returns: true (1) if successful, otherwise false (0). * @return true if successful, otherwise false.
**/ **/
static bool string_list_capacity(struct string_list *list, size_t cap) static bool string_list_capacity(struct string_list *list, size_t cap)
{ {
@ -85,7 +85,7 @@ static bool string_list_capacity(struct string_list *list, size_t cap)
* @list : pointer to string list object * @list : pointer to string list object
* *
* Frees a string list. * Frees a string list.
*/ **/
void string_list_free(struct string_list *list) void string_list_free(struct string_list *list)
{ {
if (!list) if (!list)
@ -113,8 +113,8 @@ bool string_list_deinitialize(struct string_list *list)
* *
* Creates a new string list. Has to be freed manually. * Creates a new string list. Has to be freed manually.
* *
* Returns: new string list if successful, otherwise NULL. * @return New string list if successful, otherwise NULL.
*/ **/
struct string_list *string_list_new(void) struct string_list *string_list_new(void)
{ {
struct string_list_elem * struct string_list_elem *
@ -164,7 +164,7 @@ bool string_list_initialize(struct string_list *list)
* *
* Appends a new element to the string list. * Appends a new element to the string list.
* *
* Returns: true (1) if successful, otherwise false (0). * @return true if successful, otherwise false.
**/ **/
bool string_list_append(struct string_list *list, const char *elem, bool string_list_append(struct string_list *list, const char *elem,
union string_list_elem_attr attr) union string_list_elem_attr attr)
@ -201,7 +201,7 @@ bool string_list_append(struct string_list *list, const char *elem,
* *
* Appends a new element to the string list. * Appends a new element to the string list.
* *
* Returns: true (1) if successful, otherwise false (0). * @return true if successful, otherwise false.
**/ **/
bool string_list_append_n(struct string_list *list, const char *elem, bool string_list_append_n(struct string_list *list, const char *elem,
unsigned length, union string_list_elem_attr attr) unsigned length, union string_list_elem_attr attr)
@ -248,7 +248,7 @@ void string_list_set(struct string_list *list,
* *
* A string list will be joined/concatenated as a * A string list will be joined/concatenated as a
* string to @buffer, delimited by @delim. * string to @buffer, delimited by @delim.
*/ **/
void string_list_join_concat(char *buffer, size_t size, void string_list_join_concat(char *buffer, size_t size,
const struct string_list *list, const char *delim) const struct string_list *list, const char *delim)
{ {
@ -362,8 +362,8 @@ bool string_split_noalloc(struct string_list *list,
* Includes empty strings - i.e. two adjacent delimiters will resolve * Includes empty strings - i.e. two adjacent delimiters will resolve
* to a string list element of "". * to a string list element of "".
* *
* Returns: new string list if successful, otherwise NULL. * @return New string list if successful, otherwise NULL.
*/ **/
struct string_list *string_separate(char *str, const char *delim) struct string_list *string_separate(char *str, const char *delim)
{ {
char *token = NULL; char *token = NULL;
@ -442,7 +442,7 @@ bool string_separate_noalloc(
* *
* Searches for an element (@elem) inside the string list. * Searches for an element (@elem) inside the string list.
* *
* @return number of element found, otherwise 0. * @return Number of elements found, otherwise 0.
*/ */
int string_list_find_elem(const struct string_list *list, const char *elem) int string_list_find_elem(const struct string_list *list, const char *elem)
{ {