Cleanup: move public doc-strings into headers for 'blenlib'
- Added space below non doc-string comments to make it clear these aren't comments for the symbols directly below them. - Use doxy sections for some headers. - Minor improvements to doc-strings. Ref T92709
This commit is contained in:
@@ -69,17 +69,6 @@ static bool BLI_path_is_abs(const char *name);
|
||||
|
||||
/* implementation */
|
||||
|
||||
/**
|
||||
* Looks for a sequence of decimal digits in string, preceding any filename extension,
|
||||
* returning the integer value if found, or 0 if not.
|
||||
*
|
||||
* \param string: String to scan.
|
||||
* \param head: Optional area to return copy of part of string prior to digits,
|
||||
* or before dot if no digits.
|
||||
* \param tail: Optional area to return copy of part of string following digits,
|
||||
* or from dot if no digits.
|
||||
* \param r_num_len: Optional to return number of digits found.
|
||||
*/
|
||||
int BLI_path_sequence_decode(const char *string, char *head, char *tail, ushort *r_num_len)
|
||||
{
|
||||
uint nums = 0, nume = 0;
|
||||
@@ -147,10 +136,6 @@ int BLI_path_sequence_decode(const char *string, char *head, char *tail, ushort
|
||||
return 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns in area pointed to by string a string of the form "<head><pic><tail>", where pic
|
||||
* is formatted as numlen digits with leading zeroes.
|
||||
*/
|
||||
void BLI_path_sequence_encode(
|
||||
char *string, const char *head, const char *tail, unsigned short numlen, int pic)
|
||||
{
|
||||
@@ -161,15 +146,6 @@ static int BLI_path_unc_prefix_len(const char *path); /* defined below in same f
|
||||
|
||||
/* ******************** string encoding ***************** */
|
||||
|
||||
/**
|
||||
* Remove redundant characters from \a path and optionally make absolute.
|
||||
*
|
||||
* \param relabase: The path this is relative to, or ignored when NULL.
|
||||
* \param path: Can be any input, and this function converts it to a regular full path.
|
||||
* Also removes garbage from directory paths, like `/../` or double slashes etc.
|
||||
*
|
||||
* \note \a path isn't protected for max string names...
|
||||
*/
|
||||
void BLI_path_normalize(const char *relabase, char *path)
|
||||
{
|
||||
ptrdiff_t a;
|
||||
@@ -260,9 +236,6 @@ void BLI_path_normalize(const char *relabase, char *path)
|
||||
#endif
|
||||
}
|
||||
|
||||
/**
|
||||
* Cleanup filepath ensuring a trailing slash.
|
||||
*/
|
||||
void BLI_path_normalize_dir(const char *relabase, char *dir)
|
||||
{
|
||||
/* Would just create an unexpected "/" path, just early exit entirely. */
|
||||
@@ -274,28 +247,6 @@ void BLI_path_normalize_dir(const char *relabase, char *dir)
|
||||
BLI_path_slash_ensure(dir);
|
||||
}
|
||||
|
||||
/**
|
||||
* Make given name safe to be used in paths.
|
||||
*
|
||||
* \return true if \a fname was changed, false otherwise.
|
||||
*
|
||||
* For now, simply replaces reserved chars (as listed in
|
||||
* https://en.wikipedia.org/wiki/Filename#Reserved_characters_and_words )
|
||||
* by underscores ('_').
|
||||
*
|
||||
* \note Space case ' ' is a bit of an edge case here - in theory it is allowed,
|
||||
* but again can be an issue in some cases, so we simply replace it by an underscore too
|
||||
* (good practice anyway).
|
||||
* REMOVED based on popular demand (see T45900).
|
||||
* Percent '%' char is a bit same case - not recommended to use it,
|
||||
* but supported by all decent file-systems/operating-systems around.
|
||||
*
|
||||
* \note On Windows, it also ensures there is no '.' (dot char) at the end of the file,
|
||||
* this can lead to issues.
|
||||
*
|
||||
* \note On Windows, it also checks for forbidden names
|
||||
* (see https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247%28v=vs.85%29.aspx ).
|
||||
*/
|
||||
bool BLI_filename_make_safe(char *fname)
|
||||
{
|
||||
const char *invalid =
|
||||
@@ -366,11 +317,6 @@ bool BLI_filename_make_safe(char *fname)
|
||||
return changed;
|
||||
}
|
||||
|
||||
/**
|
||||
* Make given path OS-safe.
|
||||
*
|
||||
* \return true if \a path was changed, false otherwise.
|
||||
*/
|
||||
bool BLI_path_make_safe(char *path)
|
||||
{
|
||||
/* Simply apply BLI_filename_make_safe() over each component of the path.
|
||||
@@ -404,16 +350,11 @@ bool BLI_path_make_safe(char *path)
|
||||
return changed;
|
||||
}
|
||||
|
||||
/**
|
||||
* Does path begin with the special "//" prefix that Blender uses to indicate
|
||||
* a path relative to the .blend file.
|
||||
*/
|
||||
bool BLI_path_is_rel(const char *path)
|
||||
{
|
||||
return path[0] == '/' && path[1] == '/';
|
||||
}
|
||||
|
||||
/* return true if the path is a UNC share */
|
||||
bool BLI_path_is_unc(const char *name)
|
||||
{
|
||||
return name[0] == '\\' && name[1] == '\\';
|
||||
@@ -512,10 +453,6 @@ void BLI_path_normalize_unc_16(wchar_t *path_16)
|
||||
}
|
||||
#endif
|
||||
|
||||
/**
|
||||
* Replaces `file` with a relative version (prefixed by "//") such that #BLI_path_abs, given
|
||||
* the same `relfile`, will convert it back to its original value.
|
||||
*/
|
||||
void BLI_path_rel(char *file, const char *relfile)
|
||||
{
|
||||
const char *lslash;
|
||||
@@ -654,18 +591,6 @@ void BLI_path_rel(char *file, const char *relfile)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Appends a suffix to the string, fitting it before the extension
|
||||
*
|
||||
* string = Foo.png, suffix = 123, separator = _
|
||||
* Foo.png -> Foo_123.png
|
||||
*
|
||||
* \param string: original (and final) string
|
||||
* \param maxlen: Maximum length of string
|
||||
* \param suffix: String to append to the original string
|
||||
* \param sep: Optional separator character
|
||||
* \return true if succeeded
|
||||
*/
|
||||
bool BLI_path_suffix(char *string, size_t maxlen, const char *suffix, const char *sep)
|
||||
{
|
||||
#ifdef DEBUG_STRSIZE
|
||||
@@ -701,10 +626,6 @@ bool BLI_path_suffix(char *string, size_t maxlen, const char *suffix, const char
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Replaces path with the path of its parent directory, returning true if
|
||||
* it was able to find a parent directory within the path.
|
||||
*/
|
||||
bool BLI_path_parent_dir(char *path)
|
||||
{
|
||||
const char parent_dir[] = {'.', '.', SEP, '\0'}; /* "../" or "..\\" */
|
||||
@@ -721,10 +642,6 @@ bool BLI_path_parent_dir(char *path)
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Strips off nonexistent (or non-accessible) sub-directories from the end of `dir`,
|
||||
* leaving the path of the lowest-level directory that does exist and we can read.
|
||||
*/
|
||||
bool BLI_path_parent_dir_until_exists(char *dir)
|
||||
{
|
||||
bool valid_path = true;
|
||||
@@ -795,10 +712,6 @@ static void ensure_digits(char *path, int digits)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Replaces "#" character sequence in last slash-separated component of `path`
|
||||
* with frame as decimal integer, with leading zeroes as necessary, to make digits digits.
|
||||
*/
|
||||
bool BLI_path_frame(char *path, int frame, int digits)
|
||||
{
|
||||
int ch_sta, ch_end;
|
||||
@@ -817,11 +730,6 @@ bool BLI_path_frame(char *path, int frame, int digits)
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Replaces "#" character sequence in last slash-separated component of `path`
|
||||
* with sta and end as decimal integers, with leading zeroes as necessary, to make digits
|
||||
* digits each, with a hyphen in-between.
|
||||
*/
|
||||
bool BLI_path_frame_range(char *path, int sta, int end, int digits)
|
||||
{
|
||||
int ch_sta, ch_end;
|
||||
@@ -848,9 +756,6 @@ bool BLI_path_frame_range(char *path, int sta, int end, int digits)
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the frame from a filename formatted by blender's frame scheme
|
||||
*/
|
||||
bool BLI_path_frame_get(char *path, int *r_frame, int *r_numdigits)
|
||||
{
|
||||
if (*path) {
|
||||
@@ -952,19 +857,12 @@ void BLI_path_frame_strip(char *path, char *r_ext)
|
||||
*c = '\0';
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if we have '#' chars, usable for #BLI_path_frame, #BLI_path_frame_range
|
||||
*/
|
||||
bool BLI_path_frame_check_chars(const char *path)
|
||||
{
|
||||
int ch_sta, ch_end; /* dummy args */
|
||||
return stringframe_chars(path, &ch_sta, &ch_end);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a display string from path to be used menus and the user interface.
|
||||
* Like `bpy.path.display_name()`.
|
||||
*/
|
||||
void BLI_path_to_display_name(char *display_name, int maxlen, const char *name)
|
||||
{
|
||||
/* Strip leading underscores and spaces. */
|
||||
@@ -1003,16 +901,6 @@ void BLI_path_to_display_name(char *display_name, int maxlen, const char *name)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* If path begins with "//", strips that and replaces it with `basepath` directory.
|
||||
*
|
||||
* \note Also converts drive-letter prefix to something more sensible
|
||||
* if this is a non-drive-letter-based system.
|
||||
*
|
||||
* \param path: The path to convert.
|
||||
* \param basepath: The directory to base relative paths with.
|
||||
* \return true if the path was relative (started with "//").
|
||||
*/
|
||||
bool BLI_path_abs(char *path, const char *basepath)
|
||||
{
|
||||
const bool wasrelative = BLI_path_is_rel(path);
|
||||
@@ -1114,14 +1002,6 @@ bool BLI_path_abs(char *path, const char *basepath)
|
||||
return wasrelative;
|
||||
}
|
||||
|
||||
/**
|
||||
* Checks for relative path, expanding them relative to the current working directory.
|
||||
* Returns true if the expansion was performed.
|
||||
*
|
||||
* \note Should only be called with command line paths.
|
||||
* This is _not_ something Blender's internal paths support, instead they use the "//" prefix.
|
||||
* In most cases #BLI_path_abs should be used instead.
|
||||
*/
|
||||
bool BLI_path_abs_from_cwd(char *path, const size_t maxlen)
|
||||
{
|
||||
#ifdef DEBUG_STRSIZE
|
||||
@@ -1209,9 +1089,6 @@ bool BLI_path_program_extensions_add_win32(char *name, const size_t maxlen)
|
||||
}
|
||||
#endif /* WIN32 */
|
||||
|
||||
/**
|
||||
* Search for a binary (executable)
|
||||
*/
|
||||
bool BLI_path_program_search(char *fullname, const size_t maxlen, const char *name)
|
||||
{
|
||||
#ifdef DEBUG_STRSIZE
|
||||
@@ -1264,10 +1141,6 @@ bool BLI_path_program_search(char *fullname, const size_t maxlen, const char *na
|
||||
return retval;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sets the specified environment variable to the specified value,
|
||||
* and clears it if `val == NULL`.
|
||||
*/
|
||||
void BLI_setenv(const char *env, const char *val)
|
||||
{
|
||||
/* free windows */
|
||||
@@ -1286,12 +1159,6 @@ void BLI_setenv(const char *env, const char *val)
|
||||
#endif
|
||||
}
|
||||
|
||||
/**
|
||||
* Only set an env var if already not there.
|
||||
* Like Unix setenv(env, val, 0);
|
||||
*
|
||||
* (not used anywhere).
|
||||
*/
|
||||
void BLI_setenv_if_new(const char *env, const char *val)
|
||||
{
|
||||
if (BLI_getenv(env) == NULL) {
|
||||
@@ -1299,14 +1166,6 @@ void BLI_setenv_if_new(const char *env, const char *val)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get an env var, result has to be used immediately.
|
||||
*
|
||||
* On windows #getenv gets its variables from a static copy of the environment variables taken at
|
||||
* process start-up, causing it to not pick up on environment variables created during runtime.
|
||||
* This function uses an alternative method to get environment variables that does pick up on
|
||||
* runtime environment variables. The result will be UTF-8 encoded.
|
||||
*/
|
||||
const char *BLI_getenv(const char *env)
|
||||
{
|
||||
#ifdef _MSC_VER
|
||||
@@ -1336,11 +1195,6 @@ const char *BLI_getenv(const char *env)
|
||||
#endif
|
||||
}
|
||||
|
||||
/**
|
||||
* Ensures that the parent directory of `name` exists.
|
||||
*
|
||||
* \return true on success (i.e. given path now exists on file-system), false otherwise.
|
||||
*/
|
||||
bool BLI_make_existing_file(const char *name)
|
||||
{
|
||||
char di[FILE_MAX];
|
||||
@@ -1350,15 +1204,6 @@ bool BLI_make_existing_file(const char *name)
|
||||
return BLI_dir_create_recursive(di);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns in `string` the concatenation of `dir` and `file` (also with `relabase` on the
|
||||
* front if specified and `dir` begins with "//"). Normalizes all occurrences of path
|
||||
* separators, including ensuring there is exactly one between the copies of `dir` and `file`,
|
||||
* and between the copies of `relabase` and `dir`.
|
||||
*
|
||||
* \param relabase: Optional prefix to substitute for "//" on front of `dir`.
|
||||
* \param string: Area to return result.
|
||||
*/
|
||||
void BLI_make_file_string(const char *relabase, char *string, const char *dir, const char *file)
|
||||
{
|
||||
int sl;
|
||||
@@ -1452,7 +1297,6 @@ static bool path_extension_check_ex(const char *str,
|
||||
(BLI_strcasecmp(ext, str + str_len - ext_len) == 0));
|
||||
}
|
||||
|
||||
/* does str end with ext. */
|
||||
bool BLI_path_extension_check(const char *str, const char *ext)
|
||||
{
|
||||
return path_extension_check_ex(str, strlen(str), ext, strlen(ext));
|
||||
@@ -1480,7 +1324,6 @@ bool BLI_path_extension_check_n(const char *str, ...)
|
||||
return ret;
|
||||
}
|
||||
|
||||
/* does str end with any of the suffixes in *ext_array. */
|
||||
bool BLI_path_extension_check_array(const char *str, const char **ext_array)
|
||||
{
|
||||
const size_t str_len = strlen(str);
|
||||
@@ -1496,10 +1339,6 @@ bool BLI_path_extension_check_array(const char *str, const char **ext_array)
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Semicolon separated wildcards, eg: `*.zip;*.py;*.exe`
|
||||
* does str match any of the semicolon-separated glob patterns in #fnmatch.
|
||||
*/
|
||||
bool BLI_path_extension_check_glob(const char *str, const char *ext_fnmatch)
|
||||
{
|
||||
const char *ext_step = ext_fnmatch;
|
||||
@@ -1526,15 +1365,6 @@ bool BLI_path_extension_check_glob(const char *str, const char *ext_fnmatch)
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Does basic validation of the given glob string, to prevent common issues from string
|
||||
* truncation.
|
||||
*
|
||||
* For now, only forbids last group to be a wildcard-only one, if there are more than one group
|
||||
* (i.e. things like `*.txt;*.cpp;*` are changed to `*.txt;*.cpp;`)
|
||||
*
|
||||
* \returns true if it had to modify given \a ext_fnmatch pattern.
|
||||
*/
|
||||
bool BLI_path_extension_glob_validate(char *ext_fnmatch)
|
||||
{
|
||||
bool only_wildcards = false;
|
||||
@@ -1561,10 +1391,6 @@ bool BLI_path_extension_glob_validate(char *ext_fnmatch)
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes any existing extension on the end of \a path and appends \a ext.
|
||||
* \return false if there was no room.
|
||||
*/
|
||||
bool BLI_path_extension_replace(char *path, size_t maxlen, const char *ext)
|
||||
{
|
||||
#ifdef DEBUG_STRSIZE
|
||||
@@ -1592,9 +1418,6 @@ bool BLI_path_extension_replace(char *path, size_t maxlen, const char *ext)
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Strip's trailing '.'s and adds the extension only when needed
|
||||
*/
|
||||
bool BLI_path_extension_ensure(char *path, size_t maxlen, const char *ext)
|
||||
{
|
||||
#ifdef DEBUG_STRSIZE
|
||||
@@ -1640,14 +1463,6 @@ bool BLI_path_filename_ensure(char *filepath, size_t maxlen, const char *filenam
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Converts `/foo/bar.txt` to `/foo/` and `bar.txt`
|
||||
*
|
||||
* - Won't change \a string.
|
||||
* - Won't create any directories.
|
||||
* - Doesn't use CWD, or deal with relative paths.
|
||||
* - Only fill's in \a dir and \a file when they are non NULL.
|
||||
*/
|
||||
void BLI_split_dirfile(
|
||||
const char *string, char *dir, char *file, const size_t dirlen, const size_t filelen)
|
||||
{
|
||||
@@ -1673,26 +1488,16 @@ void BLI_split_dirfile(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Copies the parent directory part of string into `dir`, max length `dirlen`.
|
||||
*/
|
||||
void BLI_split_dir_part(const char *string, char *dir, const size_t dirlen)
|
||||
{
|
||||
BLI_split_dirfile(string, dir, NULL, dirlen, 0);
|
||||
}
|
||||
|
||||
/**
|
||||
* Copies the leaf filename part of string into `file`, max length `filelen`.
|
||||
*/
|
||||
void BLI_split_file_part(const char *string, char *file, const size_t filelen)
|
||||
{
|
||||
BLI_split_dirfile(string, NULL, file, 0, filelen);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a pointer to the last extension (e.g. the position of the last period).
|
||||
* Returns NULL if there is no extension.
|
||||
*/
|
||||
const char *BLI_path_extension(const char *filepath)
|
||||
{
|
||||
const char *extension = strrchr(filepath, '.');
|
||||
@@ -1707,9 +1512,6 @@ const char *BLI_path_extension(const char *filepath)
|
||||
return extension;
|
||||
}
|
||||
|
||||
/**
|
||||
* Append a filename to a dir, ensuring slash separates.
|
||||
*/
|
||||
void BLI_path_append(char *__restrict dst, const size_t maxlen, const char *__restrict file)
|
||||
{
|
||||
size_t dirlen = BLI_strnlen(dst, maxlen);
|
||||
@@ -1727,13 +1529,6 @@ void BLI_path_append(char *__restrict dst, const size_t maxlen, const char *__re
|
||||
BLI_strncpy(dst + dirlen, file, maxlen - dirlen);
|
||||
}
|
||||
|
||||
/**
|
||||
* Simple appending of filename to dir, does not check for valid path!
|
||||
* Puts result into `dst`, which may be same area as `dir`.
|
||||
*
|
||||
* \note Consider using #BLI_path_join for more general path joining
|
||||
* that de-duplicates separators and can handle an arbitrary number of paths.
|
||||
*/
|
||||
void BLI_join_dirfile(char *__restrict dst,
|
||||
const size_t maxlen,
|
||||
const char *__restrict dir,
|
||||
@@ -1776,13 +1571,6 @@ void BLI_join_dirfile(char *__restrict dst,
|
||||
BLI_strncpy(dst + dirlen, file, maxlen - dirlen);
|
||||
}
|
||||
|
||||
/**
|
||||
* Join multiple strings into a path, ensuring only a single path separator between each,
|
||||
* and trailing slash is kept.
|
||||
*
|
||||
* \note If you want a trailing slash, add `SEP_STR` as the last path argument,
|
||||
* duplicate slashes will be cleaned up.
|
||||
*/
|
||||
size_t BLI_path_join(char *__restrict dst, const size_t dst_len, const char *path, ...)
|
||||
{
|
||||
#ifdef DEBUG_STRSIZE
|
||||
@@ -1863,27 +1651,12 @@ size_t BLI_path_join(char *__restrict dst, const size_t dst_len, const char *pat
|
||||
return ofs;
|
||||
}
|
||||
|
||||
/**
|
||||
* like Python's `os.path.basename()`
|
||||
*
|
||||
* \return The pointer into \a path string immediately after last slash,
|
||||
* or start of \a path if none found.
|
||||
*/
|
||||
const char *BLI_path_basename(const char *path)
|
||||
{
|
||||
const char *const filename = BLI_path_slash_rfind(path);
|
||||
return filename ? filename + 1 : path;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get an element of the path at an index, eg:
|
||||
* "/some/path/file.txt" where an index of...
|
||||
* - 0 or -3: "some"
|
||||
* - 1 or -2: "path"
|
||||
* - 2 or -1: "file.txt"
|
||||
*
|
||||
* Ignores multiple slashes at any point in the path (including start/end).
|
||||
*/
|
||||
bool BLI_path_name_at_index(const char *__restrict path,
|
||||
const int index,
|
||||
int *__restrict r_offset,
|
||||
@@ -1975,9 +1748,6 @@ bool BLI_path_contains(const char *container_path, const char *containee_path)
|
||||
return BLI_str_startswith(containee_native, container_native);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns pointer to the leftmost path separator in string. Not actually used anywhere.
|
||||
*/
|
||||
const char *BLI_path_slash_find(const char *string)
|
||||
{
|
||||
const char *const ffslash = strchr(string, '/');
|
||||
@@ -1993,9 +1763,6 @@ const char *BLI_path_slash_find(const char *string)
|
||||
return (ffslash < fbslash) ? ffslash : fbslash;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns pointer to the rightmost path separator in string.
|
||||
*/
|
||||
const char *BLI_path_slash_rfind(const char *string)
|
||||
{
|
||||
const char *const lfslash = strrchr(string, '/');
|
||||
@@ -2011,10 +1778,6 @@ const char *BLI_path_slash_rfind(const char *string)
|
||||
return (lfslash > lbslash) ? lfslash : lbslash;
|
||||
}
|
||||
|
||||
/**
|
||||
* Appends a slash to string if there isn't one there already.
|
||||
* Returns the new length of the string.
|
||||
*/
|
||||
int BLI_path_slash_ensure(char *string)
|
||||
{
|
||||
int len = strlen(string);
|
||||
@@ -2026,9 +1789,6 @@ int BLI_path_slash_ensure(char *string)
|
||||
return len;
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes the last slash and everything after it to the end of string, if there is one.
|
||||
*/
|
||||
void BLI_path_slash_rstrip(char *string)
|
||||
{
|
||||
int len = strlen(string);
|
||||
@@ -2043,9 +1803,6 @@ void BLI_path_slash_rstrip(char *string)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Changes to the path separators to the native ones for this OS.
|
||||
*/
|
||||
void BLI_path_slash_native(char *path)
|
||||
{
|
||||
#ifdef WIN32
|
||||
|
||||
Reference in New Issue
Block a user