mirror/RetroArch
1
0
Fork 0
mirror of https://github.com/libretro/RetroArch synced 2025-02-06 00:39:53 +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;
}
/* 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,
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)
c |= (*in & 0x3f) << shift;
*out++ = c;
*out++ = c;
in_size -= 1 + extra;
out_chars--;
ret++;
@ -88,6 +91,11 @@ size_t utf8_conv_utf32(uint32_t *out, size_t out_chars,
return ret;
}
/**
* utf16_conv_utf8:
*
* Leaf function.
**/
bool utf16_conv_utf8(uint8_t *out, size_t *out_chars,
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;
}
/* Acts mostly like strlcpy.
/**
* utf8cpy:
*
* Acts mostly like strlcpy.
*
* Copies the given number of UTF-8 characters,
* but at most d_len bytes.
* but at most @d_len bytes.
*
* Always NULL terminates.
* Does not copy half a character.
* 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.
*
* Returns number of bytes. 's' is assumed valid UTF-8.
* Use only if 'chars' is considerably less than 'd_len'. */
* @return Number of bytes.
**/
size_t utf8cpy(char *d, size_t d_len, const char *s, size_t chars)
{
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;
}
/**
* utf8skip:
*
* Leaf function
**/
const char *utf8skip(const char *str, size_t chars)
{
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;
}
/**
* utf8len:
*
* Leaf function.
**/
size_t utf8len(const char *string)
{
size_t ret = 0;
@ -220,7 +242,15 @@ size_t utf8len(const char *string)
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)
{
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)
{
unsigned len = 0;
while (in[len] != '\0')
len++;
utf16_conv_utf8(NULL, dest_len, in, len);
*dest_len += 1;
*utf_data = (uint8_t*)malloc(*dest_len);
if (*utf_data != 0)
if ((*utf_data = (uint8_t*)malloc(*dest_len)) != 0)
return utf16_conv_utf8(*utf_data, dest_len, in, len);
return false;
}
/**
* utf16_to_char_string:
**/
bool utf16_to_char_string(const uint16_t *in, char *s, size_t len)
{
size_t dest_len = 0;
uint8_t *utf16_data = NULL;
bool ret = utf16_to_char(&utf16_data, &dest_len, in);
size_t dest_len = 0;
uint8_t *utf16_data = NULL;
bool ret = utf16_to_char(&utf16_data, &dest_len, in);
if (ret)
{
@ -273,13 +303,17 @@ bool utf16_to_char_string(const uint16_t *in, char *s, size_t len)
}
free(utf16_data);
utf16_data = NULL;
utf16_data = NULL;
return ret;
}
#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,
enum CodePage cp_in, enum CodePage cp_out)
{
@ -344,35 +378,43 @@ static char *mb_to_mb_string_alloc(const char *str,
}
#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)
{
#if defined(_WIN32) && !defined(_XBOX) && !defined(UNICODE)
if (str && *str)
#if defined(_WIN32) && !defined(_XBOX) && !defined(UNICODE)
return mb_to_mb_string_alloc(str, CODEPAGE_UTF8, CODEPAGE_LOCAL);
#else
/* Assume string needs no modification if not on Windows */
if (str && *str)
return strdup(str);
return strdup(str); /* Assume string needs no modification if not on Windows */
#endif
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 defined(_WIN32) && !defined(_XBOX) && !defined(UNICODE)
return mb_to_mb_string_alloc(str, CODEPAGE_LOCAL, CODEPAGE_UTF8);
#else
/* Assume string needs no modification if not on Windows */
if (str && *str)
return strdup(str);
return strdup(str); /* Assume string needs no modification if not on Windows */
#endif
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)
{
#ifdef _WIN32
@ -430,7 +472,11 @@ wchar_t* utf8_to_utf16_string_alloc(const char *str)
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)
{
#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;
}
/* 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
* a comment and may correspond to a directive
* (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
* comment text is a suffix of the input string and
* 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)
{
/* Search for a comment (#) character */
@ -254,7 +258,8 @@ static char *config_file_extract_value(char *line)
}
/* 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;
bool merge_hash_map = false;
@ -750,17 +755,27 @@ bool config_file_deinitialize(config_file_t *conf)
return true;
}
/**
* config_file_free:
*
* Frees config file.
**/
void config_file_free(config_file_t *conf)
{
if (config_file_deinitialize(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)
{
size_t i, cap;
config_file_t *new_conf = config_file_new_from_path_to_string(path);
size_t i;
size_t cap;
if (!new_conf)
return false;
@ -791,6 +806,15 @@ bool config_append_file(config_file_t *conf, const char *path)
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,
const char *path)
{
@ -829,6 +853,15 @@ config_file_t *config_file_new_from_path_to_string(const char *path)
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(
const char *path, config_file_cb_t *cb)
{
@ -849,6 +882,14 @@ config_file_t *config_file_new_with_callback(
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)
{
int ret = 0;
@ -868,6 +909,11 @@ config_file_t *config_file_new(const char *path)
return conf;
}
/**
* config_file_initialize:
*
* Leaf function.
**/
void config_file_initialize(struct config_file *conf)
{
if (!conf)
@ -894,6 +940,11 @@ config_file_t *config_file_new_alloc(void)
return conf;
}
/**
* config_get_entry_internal:
*
* Leaf function.
**/
static struct config_entry_list *config_get_entry_internal(
const config_file_t *conf,
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);
}
/**
* 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)
{
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;
}
/**
* 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)
{
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;
}
/**
* 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)
{
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;
}
/**
* 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)
{
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;
}
/**
* 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)
{
if (conf)
@ -1090,7 +1177,6 @@ bool config_get_path(config_file_t *conf, const char *key,
return true;
#else
const struct config_entry_list *entry = config_get_entry(conf, key);
if (entry)
{
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;
}
/**
* 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)
{
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
{
entry = config_get_entry_internal(
conf, key, &last);
if (entry)
if ((entry = config_get_entry_internal(conf, key, &last)))
{
/* An entry corresponding to 'key' already exists
* > 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
* > Create new entry */
entry = (struct config_entry_list*)malloc(sizeof(*entry));
if (!entry)
if (!(entry = (struct config_entry_list*)malloc(sizeof(*entry))))
return;
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_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)
{
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)
{
if (!conf)
@ -1327,6 +1429,12 @@ bool config_file_write(config_file_t *conf, const char *path, bool sort)
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)
{
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,
struct config_file_entry *entry)
{
@ -1383,6 +1496,11 @@ bool config_get_entry_list_head(config_file_t *conf,
return true;
}
/**
* config_get_entry_list_next:
*
* Leaf function.
**/
bool config_get_entry_list_next(struct config_file_entry *entry)
{
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.
*
* 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)
{
@ -105,8 +105,10 @@ int32_t path_get_size(const char *path)
* @dir : directory
*
* 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)
{

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

@ -38,29 +38,99 @@ enum CodePage
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,
const char *in, size_t in_size);
/**
* utf16_conv_utf8:
*
* Leaf function.
**/
bool utf16_conv_utf8(uint8_t *out, size_t *out_chars,
const uint16_t *in, size_t in_size);
/**
* utf8len:
*
* Leaf function.
**/
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);
/**
* utf8skip:
*
* Leaf function
**/
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);
/**
* utf16_to_char_string:
**/
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

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.
*/
/* 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_alloc(void);
/**
* config_file_initialize:
*
* Leaf function.
**/
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.
* 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);
/**
* 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(
const char *path, config_file_cb_t *cb);
/* Load a config file from a string.
* > WARNING: This will modify 'from_string'.
* Pass a copy of source string if original
* contents must be preserved */
/**
* 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,
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_add_reference(config_file_t *conf, char *path);
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);
/* All extract functions return true when value is valid and exists.
@ -130,7 +161,6 @@ struct config_entry_list
bool readonly;
};
struct config_file_entry
{
const char *key;
@ -142,13 +172,45 @@ struct config_file_entry
struct config_entry_list *config_get_entry(
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);
/* 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);
/* 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);
/* 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. */
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);
/* 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);
/* 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);
/**
* 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.
* 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);
/* Extracts a string to a preallocated buffer. Avoid memory allocation. */
bool config_get_config_path(config_file_t *conf, char *s, size_t len);
/* Extracts a boolean from config.
/**
* 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. */
* 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);
/* 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_unset(config_file_t *conf, const char *key);
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_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);
/* 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);
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.
*
* Hidden non-leaf function cost:
* - calls string_is_empty
* - calls string_is_empty()
* - calls strrchr
*
* @return extension part from the path.
@ -153,7 +153,7 @@ char *path_remove_extension(char *path);
*
* Hidden non-leaf function cost:
* - 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.
**/
@ -167,7 +167,7 @@ const char *path_basename(const char *path);
* Get basename from @path.
*
* Hidden non-leaf function cost:
* - Calls find_last_slash
* - Calls find_last_slash()
*
* @return basename from path.
**/
@ -304,9 +304,9 @@ size_t fill_dated_filename(char *out_filename,
*
* Hidden non-leaf function cost:
* - Calls time
* - Calls rtime_localtime
* - Calls rtime_localtime()
* - Calls strlcpy
* - Calls string_is_empty
* - Calls string_is_empty()
* - Calls strftime
* - 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:
* - Calls strdup
* - Calls find_last_slash x times
* - Calls find_last_slash() x times
* - Can call strlcpy
*
* @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.
*
* 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.
**/
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
*
* 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 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.
*
* 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.
**/
struct string_list *dir_list_new(const char *dir, const char *ext,
bool include_dirs, bool include_hidden, bool include_compressed, bool recursive);
/* Warning: 'list' must zero initialised before
* calling this function, otherwise memory leaks/
* undefined behaviour will occur */
/**
* dir_list_initialize:
*
* NOTE: @list must zero initialised before
* calling this function, otherwise UB.
**/
bool dir_list_initialize(struct string_list *list,
const char *dir,
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?
*
* Sorts a directory listing.
*
**/
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
*
* Frees a directory listing.
*
**/
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.
*
* 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);
@ -100,8 +100,8 @@ bool string_split_noalloc(struct string_list *list,
* Includes empty strings - i.e. two adjacent delimiters will resolve
* 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);
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.
*
* Returns: new string list if successful, otherwise NULL.
*/
* @return New string list if successful, otherwise NULL.
**/
struct string_list *string_list_new(void);
/**
@ -127,8 +127,12 @@ struct string_list *string_list_new(void);
* @attr : attributes of new element.
*
* 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,
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.
*
* 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,
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
*
* Frees a string 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.
*
* 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,
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.
*
* 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,
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?
*
* Sorts a directory listing.
*
**/
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
*
* Frees a directory listing.
*
**/
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
*
* Returns: -1 on error, 0 on success.
* @return -1 on error, 0 on success.
**/
static int dir_list_read(const char *dir,
struct string_list *list, struct string_list *ext_list,
@ -205,7 +203,7 @@ error:
*
* 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,
@ -240,7 +238,7 @@ bool dir_list_append(struct string_list *list,
*
* 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.
**/
struct string_list *dir_list_new(const char *dir,
@ -263,9 +261,12 @@ struct string_list *dir_list_new(const char *dir,
return list;
}
/* Warning: 'list' must zero initialised before
* calling this function, otherwise memory leaks/
* undefined behaviour will occur */
/**
* dir_list_initialize:
*
* NOTE: @list must zero initialised before
* calling this function, otherwise UB.
**/
bool dir_list_initialize(struct string_list *list,
const char *dir,
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.
*
* 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)
{
@ -85,7 +85,7 @@ static bool string_list_capacity(struct string_list *list, size_t cap)
* @list : pointer to string list object
*
* Frees a string list.
*/
**/
void string_list_free(struct string_list *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.
*
* 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_elem *
@ -164,7 +164,7 @@ bool string_list_initialize(struct string_list *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,
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.
*
* 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,
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
* string to @buffer, delimited by @delim.
*/
**/
void string_list_join_concat(char *buffer, size_t size,
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
* 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)
{
char *token = NULL;
@ -442,7 +442,7 @@ bool string_separate_noalloc(
*
* 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)
{