|
| 1 | +# GL: Quick Start |
| 2 | + |
| 3 | +This guide provides a rapid introduction to the **GL** module. In just a few minutes, you will define a graph, populate it with vertices and weighted edges, and run Dijkstra's shortest path algorithm. |
| 4 | + |
| 5 | +## Basic Usage Example |
| 6 | + |
| 7 | +The following C++ program demonstrates the standard workflow of the CPP-GL library: |
| 8 | + |
| 9 | +1. **Defining Traits:** Selecting the memory layout, directionality, and payloads. |
| 10 | +2. **Building Topology:** Adding vertices and edges. |
| 11 | +3. **Execution:** Running a decoupled algorithm. |
| 12 | +4. **Reconstruction:** Extracting and formatting the results. |
| 13 | + |
| 14 | +```cpp |
| 15 | +#include <gl/graph.hpp> // (1)! |
| 16 | +#include <gl/algorithm.hpp> |
| 17 | +#include <gl/io.hpp> |
| 18 | + |
| 19 | +#include <iostream> |
| 20 | + |
| 21 | +int main() { |
| 22 | + using traits_t = gl::list_graph_traits< // (2)! |
| 23 | + gl::directed_t, |
| 24 | + gl::empty_properties, |
| 25 | + gl::weight_property<int>>; |
| 26 | + |
| 27 | + gl::graph<traits_t> graph(5); // (3)! |
| 28 | + |
| 29 | + graph.add_edge(0, 1)->weight = 10; // (4)! |
| 30 | + graph.add_edge(0, 2)->weight = 1; |
| 31 | + graph.add_edge(2, 3)->weight = 2; |
| 32 | + graph.add_edge(3, 1)->weight = 4; |
| 33 | + graph.add_edge(1, 4)->weight = 2; |
| 34 | + |
| 35 | + const auto source_id = 0u; |
| 36 | + auto paths = gl::algorithm::dijkstra_shortest_paths(graph, source_id); // (5)! |
| 37 | + |
| 38 | + const auto target_id = 4u; |
| 39 | + if (not gl::algorithm::is_reachable(paths.predecessors, target_id)) { // (6)! |
| 40 | + std::cerr << "Vertex " << target_id << " is unreachable.\n"; |
| 41 | + return 1; |
| 42 | + } |
| 43 | + |
| 44 | + auto path_to_target = gl::algorithm::reconstruct_path(paths.predecessors, target_id); // (7)! |
| 45 | + std::cout << "Shortest path distance to vertex " << target_id << ": " |
| 46 | + << paths.distances[target_id] << "\nPath: " |
| 47 | + << gl::io::range_formatter(path_to_target, " -> ", "", "") << '\n'; // (8)! |
| 48 | + |
| 49 | + return 0; |
| 50 | +} |
| 51 | +``` |
| 52 | + |
| 53 | +1. Include the necessary core graph, algorithm, and I/O headers. |
| 54 | +2. Define the graph's memory layout (adjacency list), directionality, and element payloads via a single traits structure. <br/> **NOTE:** Alternatively, you can use one of the provided [generic graph type aliases](../cpp-gl/group__GL-Core.md#public-types). |
| 55 | +3. Instantiate the generic `graph` class, pre-allocating it with 5 vertices (IDs 0 through 4). |
| 56 | +4. The `add_edge` method returns an `edge_descriptor`. Use the overloaded `->` operator to directly access and assign the attached `weight` payload in a type-safe manner. |
| 57 | +5. Execute the external algorithm on the instantiated graph. |
| 58 | +6. Use built-in utilities to verify if the target vertex was successfully reached during the pathfinding execution. |
| 59 | +7. Walk backward through the resulting predecessor map to reconstruct the exact sequence of vertices forming the shortest path. |
| 60 | +8. Stream the reconstructed path seamlessly using the library's built-in formatting utilities, customizing the delimiter to `" -> "`. |
| 61 | + |
| 62 | +**Output:** |
| 63 | +```text |
| 64 | +Shortest path distance to vertex 4: 9 |
| 65 | +Path: 0 -> 2 -> 3 -> 1 -> 4 |
| 66 | +``` |
| 67 | + |
| 68 | +### Understanding the Code |
| 69 | + |
| 70 | +- **Traits (`gl::list_graph_traits`):** CPP-GL relies heavily on template abstraction. Instead of passing multiple arguments to the `gl::graph` constructor, you pass a single *Traits* struct as its template parameter. This strictly dictates whether the graph uses an adjacency list or matrix, if it is directed, what custom properties (like `gl::weight_property`) exist on its elements and what id type is used for its elements. |
| 71 | +- **Property Access (`->weight`):** Adding an edge returns a descriptor handle. You access the specific payload fields associated with that edge by using the overloaded `->` operator, ensuring highly performant and type-safe data manipulation. |
| 72 | +- **Algorithm Separation:** Search engines and algorithms (like `dijkstra_shortest_paths`) exist entirely outside the graph class. They accept the graph as a `const` reference, mathematically guaranteeing that algorithms will never accidentally mutate your topology. |
| 73 | +- **Formatting (`gl::io::range_formatter`):** The library includes lightweight utility formatters so you can easily stream sequences, paths, and standard ranges directly to the console with complete control over delimiters and brackets. |
0 commit comments