diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:44 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:44 +0300 |
commit | 9e365069afe156f33fadfad9705e1325f894cd54 (patch) | |
tree | 78373044d029feb51f987b45208e0c1a36958625 /source/blender/blenlib/intern/path_util.c | |
parent | d8b42751625c915113b64f5a2d9c72f19f009fee (diff) |
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
Diffstat (limited to 'source/blender/blenlib/intern/path_util.c')
-rw-r--r-- | source/blender/blenlib/intern/path_util.c | 243 |
1 files changed, 0 insertions, 243 deletions
diff --git a/source/blender/blenlib/intern/path_util.c b/source/blender/blenlib/intern/path_util.c index 182fe211110..c40eed711f5 100644 --- a/source/blender/blenlib/intern/path_util.c +++ b/source/blender/blenlib/intern/path_util.c @@ -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 |