pyurd 0.1.0__py3-none-any.whl

pyurd/__init__.py

@@ -0,0 +1,95 @@
+# Copyright (C) 2026 Dominik Drexler
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""urd's headers and CMake package: the paths of the bundled prefix. The libraries urd's headers include are
+pyurd-native's (``pyurd_native.native_prefix()``)."""
+
+import tomllib as _tomllib
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+
+def _has_urd_headers(path: Path) -> bool:
+    return (path / "include" / "urd").is_dir()
+
+
+def source_version() -> str:
+    for parent in Path(__file__).resolve().parents:
+        pyproject = parent / "pyproject.toml"
+        if not pyproject.exists():
+            continue
+
+        project_version = _tomllib.loads(pyproject.read_text(encoding="utf-8")).get("project", {}).get("version")
+        if project_version is not None:
+            return project_version
+
+    return "0.0.0"
+
+
+try:
+    __version__ = version("pyurd")
+except PackageNotFoundError:
+    __version__ = source_version()
+
+
+def native_prefix() -> Path:
+    """Return the directory containing urd's headers and CMake package."""
+    package_dir = Path(__file__).resolve().parent
+    if _has_urd_headers(package_dir):
+        return package_dir
+    for parent in package_dir.parents:
+        if (parent / "pyproject.toml").exists() and _has_urd_headers(parent):
+            return parent
+
+    return package_dir
+
+
+def include_dir() -> Path:
+    """Return the bundled C++ header include directory."""
+    return native_prefix() / "include"
+
+
+def library_dirs() -> tuple[Path, ...]:
+    """Return existing bundled native library directories."""
+    prefix = native_prefix()
+    return tuple(path for path in (prefix / "lib", prefix / "lib64") if path.is_dir())
+
+
+def cmake_dirs() -> tuple[Path, ...]:
+    """Return existing bundled CMake package directories."""
+    return tuple(path / "cmake" for path in library_dirs() if (path / "cmake").is_dir())
+
+
+def cmake_prefix() -> Path:
+    """Return the prefix to put on CMAKE_PREFIX_PATH.
+
+    find_package then finds urd there; its dependencies are under pyurd-native's prefix, which goes on
+    CMAKE_PREFIX_PATH too.
+    """
+    return native_prefix()
+
+
+def cmake_dir() -> Path:
+    """Return the directory containing urdConfig.cmake."""
+    for cmake_packages_dir in cmake_dirs():
+        candidate = cmake_packages_dir / "urd"
+        if (candidate / "urdConfig.cmake").is_file():
+            return candidate
+
+    msg = (
+        "urdConfig.cmake not found under "
+        f"{[str(path) for path in cmake_dirs()] or native_prefix()}; "
+        "the installed pyurd is too old or incomplete."
+    )
+    raise FileNotFoundError(msg)
+
+
+__all__ = [
+    "__version__",
+    "cmake_dir",
+    "cmake_dirs",
+    "cmake_prefix",
+    "include_dir",
+    "library_dirs",
+    "native_prefix",
+]

pyurd/__main__.py

@@ -0,0 +1,51 @@
+# Copyright (C) 2026 Dominik Drexler
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""``python -m pyurd``: print where urd's headers and CMake package are."""
+
+import argparse
+
+import pyurd
+
+
+def main() -> None:
+    """Print the requested path or version."""
+    parser = argparse.ArgumentParser(
+        prog="python -m pyurd",
+        description="Print discovery paths for urd's headers and CMake package.",
+    )
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument(
+        "--prefix",
+        action="store_true",
+        help="Print the prefix to put on CMAKE_PREFIX_PATH.",
+    )
+    group.add_argument(
+        "--include-dir",
+        action="store_true",
+        help="Print the bundled C++ header include directory.",
+    )
+    group.add_argument(
+        "--cmake-dir",
+        action="store_true",
+        help="Print the directory containing urdConfig.cmake.",
+    )
+    group.add_argument(
+        "--version",
+        action="store_true",
+        help="Print the pyurd version.",
+    )
+    args = parser.parse_args()
+
+    if args.prefix:
+        print(pyurd.cmake_prefix())
+    elif args.include_dir:
+        print(pyurd.include_dir())
+    elif args.cmake_dir:
+        print(pyurd.cmake_dir())
+    elif args.version:
+        print(pyurd.__version__)
+
+
+if __name__ == "__main__":
+    main()

pyurd/include/urd/bits.hpp

@@ -0,0 +1,36 @@
+#pragma once
+
+// urd's bit vocabulary, for code outside urd: a span over the words of a bitset, its set bits as a range, and the
+// helpers that read and write integers packed into words. These are the names to use; urd::repr is urd's own. (The
+// tag urd::bit is a request's; the helpers are urd::bits.)
+
+#include "urd/repr/containers/bit.hpp"
+#include "urd/repr/containers/bitset_span.hpp"
+
+namespace urd
+{
+
+/// A span over the words of a bitset, a bit per index below its length.
+template<typename Block>
+using bitset_span = repr::BitsetSpan<Block>;
+/// The set bits of a bitset_span, as a range of their indices: what set_bit_indices gives.
+template<typename Block>
+using set_bit_indices_view = repr::SetBitIndices<Block>;
+using repr::for_each_bit;
+using repr::set_bit_indices;
+
+namespace bits
+{
+
+using repr::bit::bits_needed;
+using repr::bit::bits_per_block_v;
+using repr::bit::ceil_div;
+using repr::bit::for_each_set_bit;
+using repr::bit::int_reference;
+using repr::bit::lo_set;
+using repr::bit::read_int;
+using repr::bit::write_int;
+
+}  // namespace bits
+
+}  // namespace urd

pyurd/include/urd/config.hpp

@@ -0,0 +1,47 @@
+#pragma once
+
+#include <cassert>
+#include <cstddef>
+#include <cstdint>
+#include <limits>
+
+namespace urd
+{
+
+/// urd's word: the unsigned integer that bit-packed storage is made of (rows of a bit width or of column widths, sets
+/// kept as bits), and that a packed value is read and written as.
+using word_t = std::uint64_t;
+
+/// Its bits, derived from it: the most a packed value takes. No code spells them as a number.
+inline constexpr std::size_t word_bits = std::numeric_limits<word_t>::digits;
+
+}  // namespace urd
+
+// NOLINTBEGIN(cppcoreguidelines-macro-usage): each must expand at its call site
+/// States an invariant of side-effect free `condition`: asserted in Debug, assumed in Release (undefined
+/// behavior if false, at no cost), and visible to static analysis in both, unlike a plain assert under NDEBUG
+/// (a function would hide the condition from the analysis of optionals).
+#if defined(_MSC_VER)
+#define URD_ASSUME(condition) (assert(condition), (condition) ? void(0) : __assume(0))
+#else
+#define URD_ASSUME(condition) (assert(condition), (condition) ? void(0) : __builtin_unreachable())
+#endif
+
+/// Keeps a rarely taken helper out of line, so its size does not count towards the inlined size of its caller.
+#if defined(_MSC_VER)
+#define URD_NOINLINE __declspec(noinline)
+#else
+#define URD_NOINLINE [[gnu::noinline]]
+#endif
+
+/// Marks a parameter that the function's result refers to, so the compiler can warn when the result outlives a
+/// temporary argument (Clang); empty where the attribute is unknown.
+#if defined(__has_cpp_attribute)
+#if __has_cpp_attribute(clang::lifetimebound)
+#define URD_LIFETIMEBOUND [[clang::lifetimebound]]
+#endif
+#endif
+#ifndef URD_LIFETIMEBOUND
+#define URD_LIFETIMEBOUND
+#endif
+// NOLINTEND(cppcoreguidelines-macro-usage)

pyurd/include/urd/cost.hpp

@@ -0,0 +1,313 @@
+#pragma once
+
+// What each operation costs a representation, and the memory it takes: how a cost grows, in which quantity, urd's
+// operations, and a container's table of costs, one entry per operation; its memory in words (urd/memory.hpp tells
+// what it holds). Stated in its declaration (operation_costs, words; urd/registry/declaration.hpp), from which
+// urd/registry/derived.hpp gives container_costs<R>, without defining R. Reading a representation's costs therefore
+// completes nothing and includes no implementation: the registry's own headers suffice. The docs' complexity tables
+// and the benchmarks' judgment of the registry (benchmarks/record.py) read these.
+
+#include "urd/traits.hpp"
+
+#include <concepts>
+#include <cstdint>
+#include <optional>
+#include <string_view>
+
+namespace urd
+{
+
+/// How a cost grows, in which quantity.
+enum class growth : std::uint8_t
+{
+    one,
+    log,
+    linear,
+    n_log_n,
+    n_times,  ///< n times the quantity: O(n changes)
+};
+
+/// A growth's name: one, log, linear, n_log_n, n_times.
+constexpr std::string_view name(growth of)
+{
+    switch (of)
+    {
+        case growth::one:
+            return "one";
+        case growth::log:
+            return "log";
+        case growth::linear:
+            return "linear";
+        case growth::n_log_n:
+            return "n_log_n";
+        case growth::n_times:
+            return "n_times";
+    }
+    return {};
+}
+
+/// What a cost grows in.
+enum class quantity : std::uint8_t
+{
+    n,         ///< the elements
+    keys,      ///< U, the key range (dense keys fill it: about n)
+    capacity,  ///< the slots held (about n over the load factor)
+    row,       ///< r, a row's length
+    delta,     ///< k, a delta's changes
+    changes,   ///< the changes since a scope began, or since the log was cleared
+};
+
+/// A quantity's name: n, keys, capacity, row, delta, changes.
+constexpr std::string_view name(quantity of)
+{
+    switch (of)
+    {
+        case quantity::n:
+            return "n";
+        case quantity::keys:
+            return "keys";
+        case quantity::capacity:
+            return "capacity";
+        case quantity::row:
+            return "row";
+        case quantity::delta:
+            return "delta";
+        case quantity::changes:
+            return "changes";
+    }
+    return {};
+}
+
+/// A quantity as a cost writes it: n, U, capacity, r, k, changes.
+constexpr std::string_view symbol(quantity of)
+{
+    switch (of)
+    {
+        case quantity::n:
+            return "n";
+        case quantity::keys:
+            return "U";
+        case quantity::capacity:
+            return "capacity";
+        case quantity::row:
+            return "r";
+        case quantity::delta:
+            return "k";
+        case quantity::changes:
+            return "changes";
+    }
+    return {};
+}
+
+/// Which quantities grow together: the elements, their key range and the capacity are one; a row's length, a delta's
+/// changes and the changes since a scope began each grow on their own.
+enum class scale : std::uint8_t
+{
+    n,
+    row,
+    delta,
+    changes,
+};
+/// A scale's name.
+constexpr std::string_view name(scale of)
+{
+    switch (of)
+    {
+        case scale::n:
+            return "n";
+        case scale::row:
+            return "row";
+        case scale::delta:
+            return "delta";
+        case scale::changes:
+            return "changes";
+    }
+    return {};
+}
+constexpr scale scale_of(quantity of)
+{
+    switch (of)
+    {
+        case quantity::n:
+        case quantity::keys:
+        case quantity::capacity:
+            return scale::n;
+        case quantity::row:
+            return scale::row;
+        case quantity::delta:
+            return scale::delta;
+        case quantity::changes:
+            return scale::changes;
+    }
+    return scale::n;
+}
+
+/// One operation's cost: its growth in a quantity, and whether it is amortized or expected.
+struct cost
+{
+    growth grows = growth::one;
+    quantity of = quantity::n;
+    bool amortized = false;
+    bool expected = false;
+};
+
+/// An operation's words (urd/property_set.hpp, words), and the operation Op (a struct with its name, its description,
+/// and how costs name it). A kind added outside urd adds its own, with costs its containers declare as members named
+/// for it.
+using operation_info = words<struct operation_words>;
+template<typename Op>
+inline constexpr const operation_info* operation_v = &words_of<struct operation_words, Op>;
+
+/// A list of operations: what a facet offers.
+template<typename... Ops>
+struct operation_list
+{
+};
+/// urd's operations: each its words, and the key of its entry in a container's costs (cost_table).
+namespace operation
+{
+
+struct insert
+{
+    static constexpr std::string_view name = "insert";
+    static constexpr std::string_view description = "a set's or map's insert, a sequence's push_back";
+};
+struct lookup
+{
+    static constexpr std::string_view name = "lookup";
+    static constexpr std::string_view description = "find, contains, a map's value by key";
+};
+struct ordered_lookup
+{
+    static constexpr std::string_view name = "ordered_lookup";
+    static constexpr std::string_view description = "lower_bound";
+};
+struct erase
+{
+    static constexpr std::string_view name = "erase";
+    static constexpr std::string_view description = "by key, or by position";
+};
+struct clear
+{
+    static constexpr std::string_view name = "clear";
+    static constexpr std::string_view description = "every element at once";
+};
+struct iterate
+{
+    static constexpr std::string_view name = "iterate";
+    static constexpr std::string_view description = "every element in turn";
+};
+struct access
+{
+    static constexpr std::string_view name = "access";
+    static constexpr std::string_view description = "by position or handle";
+};
+struct push
+{
+    static constexpr std::string_view name = "push";
+    static constexpr std::string_view description = "a queue's";
+};
+struct pop
+{
+    static constexpr std::string_view name = "pop";
+    static constexpr std::string_view description = "a queue's";
+};
+struct top
+{
+    static constexpr std::string_view name = "top";
+    static constexpr std::string_view description = "a queue's";
+};
+struct merge
+{
+    static constexpr std::string_view name = "merge";
+    static constexpr std::string_view description = "a partition's";
+};
+struct insert_row
+{
+    static constexpr std::string_view name = "insert_row";
+    static constexpr std::string_view description = "a pool's insert";
+};
+struct find_row
+{
+    static constexpr std::string_view name = "find_row";
+    static constexpr std::string_view description = "a pool's find";
+};
+struct scope
+{
+    static constexpr std::string_view name = "scope";
+    static constexpr std::string_view description = "push_scope, changes, pop_scope";
+};
+
+}  // namespace operation
+
+/// What operation Op costs in a container: one entry of its costs.
+template<typename Op, cost Cost>
+struct cost_entry
+{
+    using operation = Op;
+    static constexpr cost value = Cost;
+};
+
+/// A container's costs: one entry per operation it offers. `of<Op>()` is Op's cost, or none where it has no entry.
+template<typename... Entries>
+struct cost_table
+{
+    template<typename Op>
+    static constexpr std::optional<cost> of()
+    {
+        auto found = std::optional<cost>();
+        ((std::same_as<Op, typename Entries::operation> ? void(found = Entries::value) : void()), ...);
+        return found;
+    }
+    template<typename Op>
+    static constexpr bool passed_on()
+    { return false; }
+};
+
+/// A wrapper's costs: its own entries, and for every other operation its part's (Part, a declaration). An operation it
+/// has no entry for is passed on to its part.
+template<typename Part, typename... Entries>
+struct costs_over
+{
+    using part = Part;
+    template<typename Op>
+    static constexpr std::optional<cost> of()
+    {
+        const auto own = cost_table<Entries...>::template of<Op>();
+        return own ? own : Part::operation_costs::template of<Op>();
+    }
+    template<typename Op>
+    static constexpr bool passed_on()
+    { return !cost_table<Entries...>::template of<Op>() && Part::operation_costs::template of<Op>(); }
+};
+
+/// The costs of the operations of representation R: its declaration's operation_costs, a cost_table with an entry per
+/// operation R offers (a wrapper's, costs_over its part's declaration). Its memory is the declaration's `words`: at
+/// most so many words per element, or per unit of its `words_per` (a key of its range, a slot of its capacity), an
+/// upper bound the benchmarks judge (benchmarks/record.py); what that memory holds is in words in its synopsis
+/// (urd/registry/derived.hpp, container_synopsis). Declared for every registered representation, derived from its
+/// declaration (urd/registry/derived.hpp); none here.
+template<typename R>
+struct container_costs
+{
+};
+
+/// The costs, named: growth, then a for amortized, e for expected.
+namespace costs
+{
+inline constexpr cost one {};
+inline constexpr cost one_a { .amortized = true };
+inline constexpr cost one_e { .expected = true };
+inline constexpr cost one_ae { .amortized = true, .expected = true };
+inline constexpr cost log_n { .grows = growth::log };
+inline constexpr cost log_na { .grows = growth::log, .amortized = true };
+inline constexpr cost lin_n { .grows = growth::linear };
+inline constexpr cost lin_keys { .grows = growth::linear, .of = quantity::keys };
+inline constexpr cost lin_capacity { .grows = growth::linear, .of = quantity::capacity };
+inline constexpr cost lin_row { .grows = growth::linear, .of = quantity::row };
+inline constexpr cost lin_row_e { .grows = growth::linear, .of = quantity::row, .expected = true };
+inline constexpr cost lin_changes { .grows = growth::linear, .of = quantity::changes };
+inline constexpr cost nlog_changes { .grows = growth::n_log_n, .of = quantity::changes };
+}  // namespace costs
+
+}  // namespace urd

pyurd/include/urd/elements/builder.hpp

@@ -0,0 +1,12 @@
+#pragma once
+
+namespace urd
+{
+
+/// The mutable form of a T, filled in place before T is stored or read (a state while it is expanded, a denotation
+/// while it is computed). Specialize it per type; views read it as their record, urd::borrowed_view<T, C, builder<T>>
+/// (or owning_view, shared_view), with the accessors of view_mixin<builder<T>, V>.
+template<typename T>
+struct builder;
+
+}  // namespace urd

pyurd/include/urd/elements/children.hpp

@@ -0,0 +1,120 @@
+#pragma once
+
+#include "urd/elements/concepts.hpp"
+#include "urd/elements/flat.hpp"
+#include "urd/elements/index.hpp"
+
+#include <boost/mp11/algorithm.hpp>
+#include <concepts>
+#include <tuple>
+#include <type_traits>
+#include <utility>
+
+/// The children of a record of element type T: every index<U> with U in the type list Types (a boost::mp11 list),
+/// found anywhere in the record's cista members: directly, in (nested) flat vectors, as a variant's alternative, in an
+/// optional or a pair (std's or cista's, as urd::resolution reads them), or inside a member that names cista members
+/// itself (urd::Serializable). U may be T: an index<T> nested in any of these shapes is a child (an (and (and ...))).
+/// Only a direct member of type index<T> is not: that is the record's own handle. A direct index<T> member that links
+/// to another record of type T (a parent) is therefore not a child either; nest it (an optional, say) to make it one.
+/// They are handed out as the views their context makes, context.view(index) (urd::resolves), so callers never handle
+/// raw indices. urd::map_variant_children instead hands out each variant slot whole (urd::resolve of it), so that a
+/// callback may replace it by another alternative.
+namespace urd
+{
+namespace detail
+{
+/// Calls f with each member of a record whose cista_members() is a Members list.
+template<typename R, typename F>
+void for_each_cista_member(R& record, F f)
+{
+    [&]<auto... Ms>(Members<Ms...>) { (f(record.*Ms), ...); }(std::remove_const_t<R>::cista_members());
+}
+
+/// A slot of type S that is a child: an index of a type in the list Types.
+template<typename S, typename Types>
+concept child_of = is_index_type<std::remove_const_t<S>> && boost::mp11::mp_contains<Types, typename std::remove_const_t<S>::element_type>::value;
+template<typename Types, typename S>
+inline constexpr bool is_child = child_of<S, Types>;
+
+/// Walks member (const or not, as member is) in member order, calling f with each slot f takes (std::invocable) and
+/// not descending into it; any other slot is descended into where it is one of the flat containers a stored record
+/// holds (flat_vector, flat_variant, flat_optional, flat_pair) or a nested record, else skipped. An index f does not
+/// take is skipped too (its own cista member, value, is no slot).
+template<typename M, typename F>
+void walk(M& member, F& f)
+{
+    using V = std::remove_const_t<M>;
+    if constexpr (std::invocable<F&, M&>)
+        f(member);
+    else if constexpr (is_index_type<V>)
+        return;
+    else if constexpr (is_flat_vector<V>)
+        for (auto& element : member)
+            walk(element, f);
+    else if constexpr (is_flat_variant<V>)
+        member.apply([&](auto& alternative) { walk(alternative, f); });
+    else if constexpr (is_flat_optional<V>)
+    {
+        if (member.has_value())
+            walk(*member, f);
+    }
+    else if constexpr (is_flat_pair<V>)
+    {
+        walk(member.first, f);
+        walk(member.second, f);
+    }
+    else if constexpr (Serializable<V>)
+        for_each_cista_member(member, [&](auto& nested) { walk(nested, f); });
+}
+
+/// walk over record's members, but for its own handle: a direct member of type index<T>.
+template<typename T, typename R, typename F>
+void walk_members(R& record, F f)
+{
+    for_each_cista_member(record,
+                          [&]<typename M>(M& member)
+                          {
+                              if constexpr (!std::same_as<std::remove_const_t<M>, index<T>>)
+                                  walk(member, f);
+                          });
+}
+}  // namespace detail
+
+/// Calls f(context.view(child)) for every child of record, in member order.
+template<typename Types, typename T, typename R, typename C, typename F>
+void for_each_child(const R& record, const C& context, F f)
+{
+    detail::walk_members<T>(record,
+                            [&]<typename S>(S& child)
+                                requires detail::is_child<Types, S> { f(context.view(child)); });
+}
+
+/// record with every child c replaced by urd::to_stored(f(context.view(c))), in member order: f returns an index of
+/// c's type, or a view of one.
+template<typename Types, typename T, typename R, typename C, typename F>
+R map_children(R record, const C& context, F f)
+{
+    detail::walk_members<T>(record,
+                            [&]<typename S>(S& child)
+                                requires detail::is_child<Types, S> { child = urd::to_stored(f(context.view(child))); });
+    return record;
+}
+
+/// map_children, but every flat_variant slot (one not inside another variant; any alternatives, children or not) is
+/// replaced whole: by urd::to_stored(f(urd::resolve(slot, context))), f called with the std::variant of the slot's
+/// alternatives resolved (an empty slot throws std::bad_variant_access). f returns that variant, another of its
+/// alternatives (a view or index of another alternative type), or anything else to_stored makes into the slot's type or
+/// one of its alternatives. The walk does not descend into a slot: the children (and nested variants) inside it are
+/// f's to map. Children outside variants are replaced as map_children replaces them, so f is an overload set (or a
+/// generic callback) taking both the views and the resolved variants.
+template<typename Types, typename T, typename R, typename C, typename F>
+R map_variant_children(R record, const C& context, F f)
+{
+    detail::walk_members<T>(record,
+                            [&]<typename S>(S& slot)
+                                requires(detail::is_child<Types, S> || is_flat_variant<S>)
+                            { slot = urd::to_stored(f(urd::resolve(std::as_const(slot), context))); });
+    return record;
+}
+
+}  // namespace urd