1 files changed, 146 insertions, 0 deletions
diff --git a/source/blender/blenkernel/BKE_asset_catalog_path.hh b/source/blender/blenkernel/BKE_asset_catalog_path.hh
new file mode 100644
index 00000000000..f51232334f2
--- /dev/null
+++ b/source/blender/blenkernel/BKE_asset_catalog_path.hh
@@ -0,0 +1,146 @@
+/*
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ */
+
+/** \file
+ * \ingroup bke
+ */
+
+#pragma once
+
+#ifndef __cplusplus
+#  error This is a C++ header.
+#endif
+
+#include "BLI_function_ref.hh"
+#include "BLI_string_ref.hh"
+#include "BLI_sys_types.h"
+
+#include <string>
+
+namespace blender::bke {
+
+/**
+ * Location of an Asset Catalog in the catalog tree, denoted by slash-separated path components.
+ *
+ * Each path component is a string that is not allowed to have slashes or colons. The latter is to
+ * make things easy to save in the colon-delimited Catalog Definition File format.
+ *
+ * The path of a catalog determines where in the catalog hierarchy the catalog is shown. Examples
+ * are "Characters/Ellie/Poses/Hand" or "Kit_bash/City/Skyscrapers". The path looks like a
+ * file-system path, with a few differences:
+ *
+ * - Only slashes are used as path component separators.
+ * - All paths are absolute, so there is no need for a leading slash.
+ *
+ * See https://wiki.blender.org/wiki/Source/Architecture/Asset_System/Catalogs
+ *
+ * Paths are stored as byte sequences, and assumed to be UTF-8.
+ */
+class AssetCatalogPath {
+  friend std::ostream &operator<<(std::ostream &stream, const AssetCatalogPath &path_to_append);
+
+ private:
+  /**
+   * The path itself, such as "Agents/Secret/327".
+   */
+  std::string path_ = "";
+
+ public:
+  static const char SEPARATOR;
+
+  AssetCatalogPath() = default;
+  AssetCatalogPath(StringRef path);
+  AssetCatalogPath(const std::string &path);
+  AssetCatalogPath(const char *path);
+  AssetCatalogPath(const AssetCatalogPath &other_path) = default;
+  AssetCatalogPath(AssetCatalogPath &&other_path) noexcept;
+  ~AssetCatalogPath() = default;
+
+  uint64_t hash() const;
+  uint64_t length() const; /* Length of the path in bytes. */
+
+  /** C-string representation of the path. */
+  const char *c_str() const;
+  const std::string &str() const;
+
+  /* The last path component, used as label in the tree view. */
+  StringRefNull name() const;
+
+  /* In-class operators, because of the implicit `AssetCatalogPath(StringRef)` constructor.
+   * Otherwise `string == string` could cast both sides to `AssetCatalogPath`. */
+  bool operator==(const AssetCatalogPath &other_path) const;
+  bool operator!=(const AssetCatalogPath &other_path) const;
+  bool operator<(const AssetCatalogPath &other_path) const;
+  AssetCatalogPath &operator=(const AssetCatalogPath &other_path) = default;
+  AssetCatalogPath &operator=(AssetCatalogPath &&other_path) = default;
+
+  /** Concatenate two paths, returning the new path. */
+  AssetCatalogPath operator/(const AssetCatalogPath &path_to_append) const;
+
+  /* False when the path is empty, true otherwise. */
+  operator bool() const;
+
+  /**
+   * Clean up the path. This ensures:
+   * - Every path component is stripped of its leading/trailing spaces.
+   * - Empty components (caused by double slashes or leading/trailing slashes) are removed.
+   * - Invalid characters are replaced with valid ones.
+   */
+  [[nodiscard]] AssetCatalogPath cleanup() const;
+
+  /**
+   * \return true only if the given path is a parent of this catalog's path.
+   * When this catalog's path is equal to the given path, return true as well.
+   * In other words, this defines a weak subset.
+   *
+   * True: "some/path/there" is contained in "some/path" and "some".
+   * False: "path/there" is not contained in "some/path/there".
+   *
+   * Note that non-cleaned-up paths (so for example starting or ending with a
+   * slash) are not supported, and result in undefined behavior.
+   */
+  bool is_contained_in(const AssetCatalogPath &other_path) const;
+
+  /**
+   * \return the parent path, or an empty path if there is no parent.
+   */
+  AssetCatalogPath parent() const;
+
+  /**
+   * Change the initial part of the path from `from_path` to `to_path`.
+   * If this path does not start with `from_path`, return an empty path as result.
+   *
+   * Example:
+   *
+   * AssetCatalogPath path("some/path/to/some/catalog");
+   * path.rebase("some/path", "new/base") -> "new/base/to/some/catalog"
+   */
+  AssetCatalogPath rebase(const AssetCatalogPath &from_path,
+                          const AssetCatalogPath &to_path) const;
+
+  /** Call the callback function for each path component, in left-to-right order. */
+  using ComponentIteratorFn = FunctionRef<void(StringRef component_name, bool is_last_component)>;
+  void iterate_components(ComponentIteratorFn callback) const;
+
+ protected:
+  /** Strip leading/trailing spaces and replace disallowed characters. */
+  static std::string cleanup_component(StringRef component_name);
+};
+
+/** Output the path as string. */
+std::ostream &operator<<(std::ostream &stream, const AssetCatalogPath &path_to_append);
+
+}  // namespace blender::bke