fuchsia / third_party / github.com / petgraph / petgraph / refs/heads/upstream/next / . / crates / core / src / lib.rs

//! # `petgraph-core`: Core Capabilities for Graph Manipulation | |

//! | |

//! Welcome to `petgraph-core`, a Rust library that serves as the bedrock for the petgraph | |

//! ecosystem. | |

//! The library is by default `no-std` and `no-alloc` and is focused on providing core | |

//! functionalities for graph operations, while abstracting over any specific graph implementation. | |

//! This means to fully utilize this library you need to either provide your own graph | |

//! implementation or use one of the many existing graph implementations. | |

//! | |

//! Within `petgraph-core` you'll discover the fundamental types crucial to working with graphs, | |

//! such as [`Node`] and [`Edge`]. | |

//! The central [`Graph`] type which is the main entry point for working with graphs. | |

//! The [`GraphStorage`] and [`DirectedGraphStorage`] traits which define the storage requirements | |

//! for a graph. | |

//! | |

//! ## Key Features | |

//! | |

//! - **Graph Storage Agnostic**: `petgraph-core` is designed to be agnostic to the underlying | |

//! storage of the graph. This means that you can use any graph implementation that implements the | |

//! [`GraphStorage`] and [`DirectedGraphStorage`] traits. | |

//! - **Graph Manipulation**: `petgraph-core` provides the core types and traits for working with | |

//! graphs. This includes the [`Graph`] type which is the main entry point for working with | |

//! graphs. | |

//! - **Node and Edge Types**: `petgraph-core` provides the [`Node`] and [`Edge`] types which are | |

//! used to access specific nodes and edges in a graph, as well as provide a way to explore the | |

//! graph in a more ergonomic way. | |

//! - **Graph Ids**: `petgraph-core` provides the [`GraphId`] trait which is used to identify a | |

//! graph. | |

//! - **Graph Directionality**: `petgraph-core` provides the [`GraphDirectionality`] trait which can | |

//! be used by graph implementations to indicate whether the graph is directed or undirected. | |

//! | |

//! The focus of `petgraph-core` is to provide the core types and traits for working with graphs. | |

//! While preserving flexibility and increasing usability. | |

//! | |

//! ## Usage | |

//! | |

//! To use `petgraph-core` you need to add it as a dependency in your `Cargo.toml` file: | |

//! | |

//! ```toml | |

//! [dependencies] | |

//! petgraph-core = "0.1.0" | |

//! ``` | |

//! | |

//! ## Deprecated | |

//! | |

//! `petgraph` 0.7.0 signaled a major change in the library, with the introduction of a new paradigm | |

//! and all new traits. To make conversion of code easier the old traits are deprecated but | |

//! preserved in the `deprecated` module. | |

//! | |

//! This module will be removed in `petgraph` 0.8.0. | |

//! | |

//! ## Examples | |

//! | |

//! The following example demonstrates how to create a graph and add nodes and edges to it. | |

//! The chosen implementation in this example (and all other examples of the crate) use | |

//! `petgraph-dino`, a graph implementation that is based on a generational arena and fast lookup | |

//! through compressed bitsets. | |

//! | |

//! ```rust | |

//! use petgraph_core::{edge::marker::Directed, Graph}; | |

//! use petgraph_dino::DinoStorage; | |

//! | |

//! let mut graph = Graph::<DinoStorage<_, _, Directed>>::new(); | |

//! // ^ a more convenient alias `DiDinoGraph` exists. | |

//! | |

//! // Add some nodes to the graph. | |

//! // `insert_node` returns the `NodeMut` of the inserted node. | |

//! let a = *graph.insert_node("A").id(); | |

//! let b = *graph.insert_node("B").id(); | |

//! let c = *graph.insert_node("C").id(); | |

//! | |

//! // Add some edges to the graph. | |

//! // `insert_edge` returns the `EdgeMut` of the inserted edge. | |

//! let ab = *graph.insert_edge("A → A", &a, &b).id(); | |

//! let bc = *graph.insert_edge("B → C", &b, &c).id(); | |

//! let ca = *graph.insert_edge("C → A", &c, &a).id(); | |

//! | |

//! // We can now access the nodes and edges in the graph. | |

//! assert_eq!(graph.node(&a).map(|node| node.weight()), Some(&"A")); | |

//! assert_eq!(graph.node(&b).map(|node| node.weight()), Some(&"B")); | |

//! assert_eq!(graph.node(&c).map(|node| node.weight()), Some(&"C")); | |

//! | |

//! assert_eq!(graph.edge(&ab).map(|edge| edge.weight()), Some(&"A → A")); | |

//! assert_eq!(graph.edge(&bc).map(|edge| edge.weight()), Some(&"B → C")); | |

//! assert_eq!(graph.edge(&ca).map(|edge| edge.weight()), Some(&"C → A")); | |

//! | |

//! // We can even mutate the nodes and edges in the graph. | |

//! if let Some(mut node) = graph.node_mut(&a) { | |

//! *node.weight_mut() = "A'"; | |

//! } | |

//! | |

//! assert_eq!(graph.node(&a).map(|node| node.weight()), Some(&"A'")); | |

//! ``` | |

//! | |

//! ## Feature Flags | |

//! | |

//! | Feature | Description | Default | | |

//! |---------------|---------------------------------------------------------------------------------------------------|----------| | |

//! | `alloc` | Enables [`DataMap`] on [`NodeFiltered`], enables [`ContinuousIndexMapper`] | enabled | | |

//! | `std` | Enables [`VisitMap`] and [`FilterNode`] and on [`HashSet`] | enabled | | |

//! | `fixedbitset` | Enables [`GetAdjacencyMatrix`] for [`Graph`], [`VisitMap`] and [`FilterNode`] for [`FixedBitSet`] | disabled | | |

//! | `indexmap` | Enables [`VisitMap`] for [`IndexMap`] | disabled | | |

//! | |

//! `std`, `fixedbitset` and `indexmap` only exist for the `deprecated` module and will be removed | |

//! in `petgraph` 0.8.0. | |

//! | |

//! [`GetAdjacencyMatrix`]: deprecated::visit::GetAdjacencyMatrix | |

//! [`VisitMap`]: deprecated::visit::VisitMap | |

//! [`FilterNode`]: deprecated::visit::FilterNode | |

//! [`DataMap`]: deprecated::data::DataMap | |

//! [`NodeFiltered`]: deprecated::visit::NodeFiltered | |

//! [`ContinuousIndexMapper`]: id::ContinuousIndexMapper | |

//! [`FixedBitSet`]: fixedbitset::FixedBitSet | |

//! [`IndexMap`]: indexmap::IndexMap | |

//! [`HashSet`]: std::collections::HashSet | |

#![feature(impl_trait_in_assoc_type)] | |

#![cfg_attr(not(feature = "std"), no_std)] | |

#![warn(missing_docs)] | |

#[cfg(feature = "alloc")] | |

extern crate alloc; | |

#[deprecated(since = "0.1.0")] | |

pub mod deprecated; | |

pub mod edge; | |

mod error; | |

pub(crate) mod graph; | |

pub mod node; | |

pub mod storage; | |

pub use crate::{ | |

edge::{DetachedEdge, Edge, EdgeMut, GraphDirectionality}, | |

error::Error, | |

graph::Graph, | |

node::{DetachedNode, Node, NodeMut}, | |

storage::{DirectedGraphStorage, GraphStorage}, | |

}; |