BLI_path_utils.hh

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2001-2002 NaN Holding BV. All rights reserved.
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */
#pragma once

 
#include "BLI_compiler_attrs.h"
#include "BLI_compiler_compat.h"
#include "BLI_utildefines.h"
#include "BLI_utildefines_variadic.h"
 
/* -------------------------------------------------------------------- */

bool BLI_path_name_at_index(const char *__restrict path,
                            int index,
                            int *__restrict r_offset,
                            int *__restrict r_len) ATTR_NONNULL(1, 3, 4) ATTR_WARN_UNUSED_RESULT;

bool BLI_path_is_unc(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
 
bool BLI_path_is_win32_drive(const char *path);
bool BLI_path_is_win32_drive_only(const char *path);
bool BLI_path_is_win32_drive_with_slash(const char *path);

 
/* -------------------------------------------------------------------- */

bool BLI_path_parent_dir(char *path) ATTR_NONNULL(1);
bool BLI_path_parent_dir_until_exists(char *path) ATTR_NONNULL(1);

const char *BLI_path_parent_dir_end(const char *path, size_t path_len)
    ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;

 
/* -------------------------------------------------------------------- */

bool BLI_path_make_safe_filename_ex(char *filename, bool allow_tokens) ATTR_NONNULL(1);
bool BLI_path_make_safe_filename(char *filename) ATTR_NONNULL(1);

bool BLI_path_make_safe(char *path) ATTR_NONNULL(1);

void BLI_path_to_display_name(char *display_name, int display_name_maxncpy, const char *name)
    ATTR_NONNULL(1, 3);

 
/* -------------------------------------------------------------------- */

int BLI_path_normalize(char *path) ATTR_NONNULL(1);

int BLI_path_normalize_native(char *path) ATTR_NONNULL(1);

int BLI_path_normalize_dir(char *dir, size_t dir_maxncpy) ATTR_NONNULL(1);
 
#if defined(WIN32)
void BLI_path_normalize_unc_16(wchar_t *path_16);
void BLI_path_normalize_unc(char *path, int path_maxncpy);
#endif

 
/* -------------------------------------------------------------------- */

int BLI_path_canonicalize_native(char *path, int path_maxncpy);

 
/* -------------------------------------------------------------------- */

bool BLI_path_filename_ensure(char *filepath, size_t filepath_maxncpy, const char *filename)
    ATTR_NONNULL(1, 3);

bool BLI_path_suffix(char *path, size_t path_maxncpy, const char *suffix, const char *sep)
    ATTR_NONNULL(1, 3, 4);

 
/* -------------------------------------------------------------------- */

const char *BLI_path_slash_find(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
const char *BLI_path_slash_rfind(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
int BLI_path_slash_ensure_ex(char *path, size_t path_maxncpy, const size_t path_len)
    ATTR_NONNULL(1);
int BLI_path_slash_ensure(char *path, size_t path_maxncpy) ATTR_NONNULL(1);
void BLI_path_slash_rstrip(char *path) ATTR_NONNULL(1);
const char *BLI_path_slash_skip(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
void BLI_path_slash_native(char *path) ATTR_NONNULL(1);

 
/* -------------------------------------------------------------------- */

void BLI_path_split_dir_file(const char *filepath,
                             char *dir,
                             size_t dir_maxncpy,
                             char *file,
                             size_t file_maxncpy) ATTR_NONNULL(1, 2, 4);
void BLI_path_split_dir_part(const char *filepath, char *dir, size_t dir_maxncpy)
    ATTR_NONNULL(1, 2);
void BLI_path_split_file_part(const char *filepath, char *file, size_t file_maxncpy)
    ATTR_NONNULL(1, 2);

const char *BLI_path_basename(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;

 
/* -------------------------------------------------------------------- */

bool BLI_path_has_hidden_component(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;

 
/* -------------------------------------------------------------------- */

size_t BLI_path_append(char *__restrict dst, size_t dst_maxncpy, const char *__restrict file)
    ATTR_NONNULL(1, 3);
size_t BLI_path_append_dir(char *__restrict dst, size_t dst_maxncpy, const char *__restrict dir)
    ATTR_NONNULL(1, 3);

 
/* -------------------------------------------------------------------- */

size_t BLI_path_join_array(char *__restrict dst,
                           const size_t dst_maxncpy,
                           const char *path_array[],
                           const int path_array_num) ATTR_NONNULL(1, 3);

#define BLI_path_join(...) VA_NARGS_CALL_OVERLOAD(_BLI_path_join_, __VA_ARGS__)
 
#define _BLI_PATH_JOIN_ARGS_1 char *__restrict dst, size_t dst_maxncpy, const char *a
#define _BLI_PATH_JOIN_ARGS_2 _BLI_PATH_JOIN_ARGS_1, const char *b
#define _BLI_PATH_JOIN_ARGS_3 _BLI_PATH_JOIN_ARGS_2, const char *c
#define _BLI_PATH_JOIN_ARGS_4 _BLI_PATH_JOIN_ARGS_3, const char *d
#define _BLI_PATH_JOIN_ARGS_5 _BLI_PATH_JOIN_ARGS_4, const char *e
#define _BLI_PATH_JOIN_ARGS_6 _BLI_PATH_JOIN_ARGS_5, const char *f
#define _BLI_PATH_JOIN_ARGS_7 _BLI_PATH_JOIN_ARGS_6, const char *g
#define _BLI_PATH_JOIN_ARGS_8 _BLI_PATH_JOIN_ARGS_7, const char *h
#define _BLI_PATH_JOIN_ARGS_9 _BLI_PATH_JOIN_ARGS_8, const char *i
#define _BLI_PATH_JOIN_ARGS_10 _BLI_PATH_JOIN_ARGS_9, const char *j
 
BLI_INLINE size_t _BLI_path_join_3(_BLI_PATH_JOIN_ARGS_1) ATTR_NONNULL();
BLI_INLINE size_t _BLI_path_join_4(_BLI_PATH_JOIN_ARGS_2) ATTR_NONNULL();
BLI_INLINE size_t _BLI_path_join_5(_BLI_PATH_JOIN_ARGS_3) ATTR_NONNULL();
BLI_INLINE size_t _BLI_path_join_6(_BLI_PATH_JOIN_ARGS_4) ATTR_NONNULL();
BLI_INLINE size_t _BLI_path_join_7(_BLI_PATH_JOIN_ARGS_5) ATTR_NONNULL();
BLI_INLINE size_t _BLI_path_join_8(_BLI_PATH_JOIN_ARGS_6) ATTR_NONNULL();
BLI_INLINE size_t _BLI_path_join_9(_BLI_PATH_JOIN_ARGS_7) ATTR_NONNULL();
BLI_INLINE size_t _BLI_path_join_10(_BLI_PATH_JOIN_ARGS_8) ATTR_NONNULL();
BLI_INLINE size_t _BLI_path_join_11(_BLI_PATH_JOIN_ARGS_9) ATTR_NONNULL();
BLI_INLINE size_t _BLI_path_join_12(_BLI_PATH_JOIN_ARGS_10) ATTR_NONNULL();
 
BLI_INLINE size_t _BLI_path_join_3(_BLI_PATH_JOIN_ARGS_1)
{
  const char *path_array[] = {a};
  return BLI_path_join_array(dst, dst_maxncpy, path_array, ARRAY_SIZE(path_array));
}
BLI_INLINE size_t _BLI_path_join_4(_BLI_PATH_JOIN_ARGS_2)
{
  const char *path_array[] = {a, b};
  return BLI_path_join_array(dst, dst_maxncpy, path_array, ARRAY_SIZE(path_array));
}
BLI_INLINE size_t _BLI_path_join_5(_BLI_PATH_JOIN_ARGS_3)
{
  const char *path_array[] = {a, b, c};
  return BLI_path_join_array(dst, dst_maxncpy, path_array, ARRAY_SIZE(path_array));
}
BLI_INLINE size_t _BLI_path_join_6(_BLI_PATH_JOIN_ARGS_4)
{
  const char *path_array[] = {a, b, c, d};
  return BLI_path_join_array(dst, dst_maxncpy, path_array, ARRAY_SIZE(path_array));
}
BLI_INLINE size_t _BLI_path_join_7(_BLI_PATH_JOIN_ARGS_5)
{
  const char *path_array[] = {a, b, c, d, e};
  return BLI_path_join_array(dst, dst_maxncpy, path_array, ARRAY_SIZE(path_array));
}
BLI_INLINE size_t _BLI_path_join_8(_BLI_PATH_JOIN_ARGS_6)
{
  const char *path_array[] = {a, b, c, d, e, f};
  return BLI_path_join_array(dst, dst_maxncpy, path_array, ARRAY_SIZE(path_array));
}
BLI_INLINE size_t _BLI_path_join_9(_BLI_PATH_JOIN_ARGS_7)
{
  const char *path_array[] = {a, b, c, d, e, f, g};
  return BLI_path_join_array(dst, dst_maxncpy, path_array, ARRAY_SIZE(path_array));
}
BLI_INLINE size_t _BLI_path_join_10(_BLI_PATH_JOIN_ARGS_8)
{
  const char *path_array[] = {a, b, c, d, e, f, g, h};
  return BLI_path_join_array(dst, dst_maxncpy, path_array, ARRAY_SIZE(path_array));
}
BLI_INLINE size_t _BLI_path_join_11(_BLI_PATH_JOIN_ARGS_9)
{
  const char *path_array[] = {a, b, c, d, e, f, g, h, i};
  return BLI_path_join_array(dst, dst_maxncpy, path_array, ARRAY_SIZE(path_array));
}
BLI_INLINE size_t _BLI_path_join_12(_BLI_PATH_JOIN_ARGS_10)
{
  const char *path_array[] = {a, b, c, d, e, f, g, h, i, j};
  return BLI_path_join_array(dst, dst_maxncpy, path_array, ARRAY_SIZE(path_array));
}
 
#undef _BLI_PATH_JOIN_ARGS_1
#undef _BLI_PATH_JOIN_ARGS_2
#undef _BLI_PATH_JOIN_ARGS_3
#undef _BLI_PATH_JOIN_ARGS_4
#undef _BLI_PATH_JOIN_ARGS_5
#undef _BLI_PATH_JOIN_ARGS_6
#undef _BLI_PATH_JOIN_ARGS_7
#undef _BLI_PATH_JOIN_ARGS_8
#undef _BLI_PATH_JOIN_ARGS_9
#undef _BLI_PATH_JOIN_ARGS_10

 
/* -------------------------------------------------------------------- */

const char *BLI_path_extension_or_end(const char *filepath)
    ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT ATTR_RETURNS_NONNULL;
const char *BLI_path_extension(const char *filepath) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;

bool BLI_path_extension_check(const char *path, const char *ext)
    ATTR_NONNULL(1, 2) ATTR_WARN_UNUSED_RESULT;
bool BLI_path_extension_check_n(const char *path, ...) ATTR_NONNULL(1) ATTR_SENTINEL(0);
bool BLI_path_extension_check_array(const char *path, const char **ext_array)
    ATTR_NONNULL(1, 2) ATTR_WARN_UNUSED_RESULT;
bool BLI_path_extension_check_glob(const char *path, const char *ext_fnmatch)
    ATTR_NONNULL(1, 2) ATTR_WARN_UNUSED_RESULT;
bool BLI_path_extension_glob_validate(char *ext_fnmatch) ATTR_NONNULL(1);
bool BLI_path_extension_replace(char *path, size_t path_maxncpy, const char *ext)
    ATTR_NONNULL(1, 3);
bool BLI_path_extension_strip(char *path) ATTR_NONNULL(1);
bool BLI_path_extension_ensure(char *path, size_t path_maxncpy, const char *ext)
    ATTR_NONNULL(1, 3);

 
/* -------------------------------------------------------------------- */
 
/* Path string comparisons: case-insensitive for Windows, case-sensitive otherwise. */
#if defined(WIN32)
#  define BLI_path_cmp BLI_strcasecmp
#  define BLI_path_ncmp BLI_strncasecmp
#else
#  define BLI_path_cmp strcmp
#  define BLI_path_ncmp strncmp
#endif

int BLI_path_cmp_normalized(const char *p1, const char *p2)
    ATTR_NONNULL(1, 2) ATTR_WARN_UNUSED_RESULT;

bool BLI_path_contains(const char *container_path, const char *containee_path)
    ATTR_NONNULL(1, 2) ATTR_WARN_UNUSED_RESULT;

 
/* -------------------------------------------------------------------- */
 
#ifdef _WIN32
bool BLI_path_program_extensions_add_win32(char *program_name, size_t program_name_maxncpy);
#endif
bool BLI_path_program_search(char *program_filepath,
                             size_t program_filepath_maxncpy,
                             const char *program_name) ATTR_NONNULL(1, 3);

 
/* -------------------------------------------------------------------- */

void BLI_path_sequence_encode(char *path,
                              size_t path_maxncpy,
                              const char *head,
                              const char *tail,
                              unsigned short numlen,
                              int pic);

int BLI_path_sequence_decode(const char *path,
                             char *head,
                             size_t head_maxncpy,
                             char *tail,
                             size_t tail_maxncpy,
                             unsigned short *r_digits_len);

 
/* -------------------------------------------------------------------- */

bool BLI_path_frame(char *path, size_t path_maxncpy, int frame, int digits) ATTR_NONNULL(1);
bool BLI_path_frame_range(char *path, size_t path_maxncpy, int sta, int end, int digits)
    ATTR_NONNULL(1);
bool BLI_path_frame_get(const char *path, int *r_frame, int *r_digits_len) ATTR_NONNULL(1, 2, 3);
void BLI_path_frame_strip(char *path, char *r_ext, size_t ext_maxncpy) ATTR_NONNULL(1, 2);
bool BLI_path_frame_check_chars(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;

 
/* -------------------------------------------------------------------- */

#ifndef FILE_MAXDIR
#  define FILE_MAXDIR 768
#  define FILE_MAXFILE 256
#  define FILE_MAX 1024
#endif

bool BLI_path_abs(char path[FILE_MAX], const char *basepath) ATTR_NONNULL(1, 2);
void BLI_path_rel(char path[FILE_MAX], const char *basepath) ATTR_NONNULL(1);

bool BLI_path_is_rel(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;

 
/* -------------------------------------------------------------------- */

bool BLI_path_is_abs_from_cwd(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;
bool BLI_path_abs_from_cwd(char *path, size_t path_maxncpy) ATTR_NONNULL(1);

 
/* -------------------------------------------------------------------- */
 
#ifdef WIN32
#  define SEP '\\'
#  define ALTSEP '/'
#  define SEP_STR "\\"
#  define ALTSEP_STR "/"
#else
#  define SEP '/'
#  define ALTSEP '\\'
#  define SEP_STR "/"
#  define ALTSEP_STR "\\"
#endif

BLI_INLINE bool BLI_path_slash_is_native_compat(const char ch)
{
  /* On UNIX it only makes sense to treat `/` as a path separator.
   * On WIN32 either may be used. */
  if (ch == SEP) {
    return true;
  }
#ifdef WIN32
  if (ch == ALTSEP) {
    return true;
  }
#endif
  return false;
}

 
/* -------------------------------------------------------------------- */

void BLI_setenv(const char *env, const char *val) ATTR_NONNULL(1);
void BLI_setenv_if_new(const char *env, const char *val) ATTR_NONNULL(1);
const char *BLI_getenv(const char *env) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT;

 
/* -------------------------------------------------------------------- */
 
/* Parent and current dir helpers. */
#define FILENAME_PARENT ".."
#define FILENAME_CURRENT "."
 
/* Avoid calling `strcmp` on one or two chars! */
#define FILENAME_IS_PARENT(_n) (((_n)[0] == '.') && ((_n)[1] == '.') && ((_n)[2] == '\0'))
#define FILENAME_IS_CURRENT(_n) (((_n)[0] == '.') && ((_n)[1] == '\0'))
#define FILENAME_IS_CURRPAR(_n) \
  (((_n)[0] == '.') && (((_n)[1] == '\0') || (((_n)[1] == '.') && ((_n)[2] == '\0'))))