• Home
  • Features
  • Pricing
  • Docs
  • Announcements
  • Sign In

vigna / webgraph-rs / 20017908129

08 Dec 2025 05:36AM UTC coverage: 62.065% (+0.4%) from 61.641%
20017908129

push

github

zommiommy
Fix doctests

5435 of 8757 relevant lines covered (62.06%)

46674689.93 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

82.88
/webgraph/src/graphs/bvgraph/sequential.rs
1
/*
2
 * SPDX-FileCopyrightText: 2023 Inria
3
 * SPDX-FileCopyrightText: 2023 Sebastiano Vigna
4
 *
5
 * SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
6
 */
7

8
use std::path::PathBuf;
9

10
use super::*;
11
use crate::utils::CircularBuffer;
12
use anyhow::Result;
13
use bitflags::Flags;
14
use dsi_bitstream::codes::ToInt;
15
use dsi_bitstream::traits::BE;
16
use dsi_bitstream::traits::BitSeek;
17
use lender::*;
18

19
/// A sequential BvGraph that can be read from a `codes_reader_builder`.
20
/// The builder is needed because we should be able to create multiple iterators
21
/// and this allows us to have a single place where to store the mmapped file.
22
#[derive(Debug, Clone)]
23
pub struct BvGraphSeq<F> {
24
    factory: F,
25
    number_of_nodes: usize,
26
    number_of_arcs: Option<u64>,
27
    compression_window: usize,
28
    min_interval_length: usize,
29
}
30

31
impl BvGraphSeq<()> {
32
    pub fn with_basename(
248,930✔
33
        basename: impl AsRef<std::path::Path>,
34
    ) -> LoadConfig<BE, Sequential, Dynamic, Mmap, Mmap> {
35
        LoadConfig {
36
            basename: PathBuf::from(basename.as_ref()),
995,720✔
37
            graph_load_flags: Flags::empty(),
497,860✔
38
            offsets_load_flags: Flags::empty(),
248,930✔
39
            _marker: std::marker::PhantomData,
40
        }
41
    }
42
}
43

44
impl<F: SequentialDecoderFactory> SplitLabeling for BvGraphSeq<F>
45
where
46
    for<'a> <F as SequentialDecoderFactory>::Decoder<'a>: Clone + Send + Sync,
47
{
48
    type SplitLender<'a>
49
        = split::seq::Lender<'a, BvGraphSeq<F>>
50
    where
51
        Self: 'a;
52
    type IntoIterator<'a>
53
        = split::seq::IntoIterator<'a, BvGraphSeq<F>>
54
    where
55
        Self: 'a;
56

57
    fn split_iter(&self, how_many: usize) -> Self::IntoIterator<'_> {
12✔
58
        split::seq::Iter::new(self.iter(), self.num_nodes(), how_many)
72✔
59
    }
60
}
61

62
impl<F: SequentialDecoderFactory> SequentialLabeling for BvGraphSeq<F> {
63
    type Label = usize;
64
    type Lender<'a>
65
        = Iter<F::Decoder<'a>>
66
    where
67
        Self: 'a;
68

69
    #[inline(always)]
70
    /// Returns the number of nodes in the graph
71
    fn num_nodes(&self) -> usize {
622,122✔
72
        self.number_of_nodes
622,122✔
73
    }
74

75
    #[inline(always)]
76
    fn num_arcs_hint(&self) -> Option<u64> {
×
77
        self.number_of_arcs
×
78
    }
79

80
    #[inline(always)]
81
    fn iter_from(&self, from: usize) -> Self::Lender<'_> {
629,220✔
82
        let mut iter = Iter::new(
83
            self.factory.new_decoder().unwrap(),
1,887,660✔
84
            self.number_of_nodes,
629,220✔
85
            self.compression_window,
629,220✔
86
            self.min_interval_length,
629,220✔
87
        );
88

89
        let _ = iter.advance_by(from);
1,258,440✔
90

91
        iter
629,220✔
92
    }
93
}
94

95
impl<F: SequentialDecoderFactory> SequentialGraph for BvGraphSeq<F> {}
96

97
/// Convenience implementation that makes it possible to iterate
98
/// over the graph using the [`for_`] macro
99
/// (see the [crate documentation](crate)).
100
impl<'a, F: SequentialDecoderFactory> IntoLender for &'a BvGraphSeq<F> {
101
    type Lender = <BvGraphSeq<F> as SequentialLabeling>::Lender<'a>;
102

103
    #[inline(always)]
104
    fn into_lender(self) -> Self::Lender {
×
105
        self.iter()
×
106
    }
107
}
108

109
impl<F: SequentialDecoderFactory> BvGraphSeq<F> {
110
    /// Creates a new sequential graph from a codes reader builder
111
    /// and the number of nodes.
112
    pub fn new(
629,142✔
113
        codes_reader_builder: F,
114
        number_of_nodes: usize,
115
        number_of_arcs: Option<u64>,
116
        compression_window: usize,
117
        min_interval_length: usize,
118
    ) -> Self {
119
        Self {
120
            factory: codes_reader_builder,
121
            number_of_nodes,
122
            number_of_arcs,
123
            compression_window,
124
            min_interval_length,
125
        }
126
    }
127

128
    #[inline(always)]
129
    pub fn map_factory<F1, F0>(self, map_func: F0) -> BvGraphSeq<F1>
×
130
    where
131
        F0: FnOnce(F) -> F1,
132
        F1: SequentialDecoderFactory,
133
    {
134
        BvGraphSeq {
135
            factory: map_func(self.factory),
×
136
            number_of_nodes: self.number_of_nodes,
×
137
            number_of_arcs: self.number_of_arcs,
×
138
            compression_window: self.compression_window,
×
139
            min_interval_length: self.min_interval_length,
×
140
        }
141
    }
142

143
    #[inline(always)]
144
    /// Consume self and return the factory
145
    pub fn into_inner(self) -> F {
×
146
        self.factory
×
147
    }
148
}
149

150
impl<F: SequentialDecoderFactory> BvGraphSeq<F> {
151
    #[inline(always)]
152
    /// Creates an iterator specialized in the degrees of the nodes.
153
    /// This is slightly faster because it can avoid decoding some of the nodes
154
    /// and completely skip the merging step.
155
    pub fn offset_deg_iter(&self) -> OffsetDegIter<F::Decoder<'_>> {
255,793✔
156
        OffsetDegIter::new(
157
            self.factory.new_decoder().unwrap(),
767,379✔
158
            self.number_of_nodes,
255,793✔
159
            self.compression_window,
255,793✔
160
            self.min_interval_length,
255,793✔
161
        )
162
    }
163
}
164

165
/// A fast sequential iterator over the nodes of the graph and their successors.
166
/// This iterator does not require to know the offsets of each node in the graph.
167
#[derive(Debug, Clone)]
168
pub struct Iter<D: Decode> {
169
    pub(crate) number_of_nodes: usize,
170
    pub(crate) compression_window: usize,
171
    pub(crate) min_interval_length: usize,
172
    pub(crate) decoder: D,
173
    pub(crate) backrefs: CircularBuffer<Vec<usize>>,
174
    pub(crate) current_node: usize,
175
}
176

177
impl<D: Decode + BitSeek> Iter<D> {
178
    #[inline(always)]
179
    /// Forward the call of `get_pos` to the inner `codes_reader`.
180
    /// This returns the current bits offset in the bitstream.
181
    pub fn bit_pos(&mut self) -> Result<u64, <D as BitSeek>::Error> {
1,175,880✔
182
        self.decoder.bit_pos()
2,351,760✔
183
    }
184
}
185

186
impl<D: Decode> Iter<D> {
187
    /// Creates a new iterator from a codes reader
188
    pub fn new(
1,002,474✔
189
        decoder: D,
190
        number_of_nodes: usize,
191
        compression_window: usize,
192
        min_interval_length: usize,
193
    ) -> Self {
194
        Self {
195
            number_of_nodes,
196
            compression_window,
197
            min_interval_length,
198
            decoder,
199
            backrefs: CircularBuffer::new(compression_window + 1),
1,002,474✔
200
            current_node: 0,
201
        }
202
    }
203

204
    /// Get the successors of the next node in the stream
205
    pub fn next_successors(&mut self) -> Result<&[usize]> {
×
206
        let mut res = self.backrefs.take(self.current_node);
×
207
        res.clear();
×
208
        self.get_successors_iter_priv(self.current_node, &mut res)?;
×
209
        let res = self.backrefs.replace(self.current_node, res);
×
210
        self.current_node += 1;
×
211
        Ok(res)
×
212
    }
213

214
    #[inline(always)]
215
    /// Inner method called by `next_successors` and the iterator `next` method
216
    fn get_successors_iter_priv(&mut self, node_id: usize, results: &mut Vec<usize>) -> Result<()> {
221,000,654✔
217
        let degree = self.decoder.read_outdegree() as usize;
442,001,308✔
218
        // no edges, we are done!
219
        if degree == 0 {
221,000,654✔
220
            return Ok(());
26,179,186✔
221
        }
222

223
        // ensure that we have enough capacity in the vector for not reallocating
224
        results.reserve(degree.saturating_sub(results.capacity()));
1,168,928,808✔
225
        // read the reference offset
226
        let ref_delta = if self.compression_window != 0 {
389,642,936✔
227
            self.decoder.read_reference_offset() as usize
168,452,966✔
228
        } else {
229
            0
26,368,502✔
230
        };
231
        // if we copy nodes from a previous one
232
        if ref_delta != 0 {
194,821,468✔
233
            // compute the node id of the reference
234
            let reference_node_id = node_id - ref_delta;
144,259,560✔
235
            // retrieve the data
236
            let neighbours = &self.backrefs[reference_node_id];
144,259,560✔
237
            //debug_assert!(!neighbours.is_empty());
238
            // get the info on which destinations to copy
239
            let number_of_blocks = self.decoder.read_block_count() as usize;
144,259,560✔
240
            // no blocks, we copy everything
241
            if number_of_blocks == 0 {
96,834,878✔
242
                results.extend_from_slice(neighbours);
49,410,196✔
243
            } else {
244
                // otherwise we copy only the blocks of even index
245
                // the first block could be zero
246
                let mut idx = self.decoder.read_block() as usize;
94,849,364✔
247
                results.extend_from_slice(&neighbours[..idx]);
142,274,046✔
248

249
                // while the other can't
250
                for block_id in 1..number_of_blocks {
124,169,499✔
251
                    let block = self.decoder.read_block() as usize;
153,489,634✔
252
                    let end = idx + block + 1;
153,489,634✔
253
                    if block_id % 2 == 0 {
101,281,109✔
254
                        results.extend_from_slice(&neighbours[idx..end]);
98,145,168✔
255
                    }
256
                    idx = end;
76,744,817✔
257
                }
258
                if number_of_blocks & 1 == 0 {
75,096,915✔
259
                    results.extend_from_slice(&neighbours[idx..]);
83,016,699✔
260
                }
261
            }
262
        };
263

264
        // if we still have to read nodes
265
        let nodes_left_to_decode = degree - results.len();
584,464,404✔
266
        if nodes_left_to_decode != 0 && self.min_interval_length != 0 {
366,698,074✔
267
            // read the number of intervals
268
            let number_of_intervals = self.decoder.read_interval_count() as usize;
274,795,144✔
269
            if number_of_intervals != 0 {
137,397,572✔
270
                // pre-allocate with capacity for efficiency
271
                let node_id_offset = self.decoder.read_interval_start().to_int();
139,061,148✔
272
                let mut start = (node_id as i64 + node_id_offset) as usize;
69,530,574✔
273
                let mut delta = self.decoder.read_interval_len() as usize;
69,530,574✔
274
                delta += self.min_interval_length;
34,765,287✔
275
                // save the first interval
276
                results.extend(start..(start + delta));
139,061,148✔
277
                start += delta;
34,765,287✔
278
                // decode the intervals
279
                for _ in 1..number_of_intervals {
55,749,788✔
280
                    start += 1 + self.decoder.read_interval_start() as usize;
41,969,002✔
281
                    delta = self.decoder.read_interval_len() as usize;
41,969,002✔
282
                    delta += self.min_interval_length;
41,969,002✔
283

284
                    results.extend(start..(start + delta));
83,938,004✔
285

286
                    start += delta;
20,984,501✔
287
                }
288
            }
289
        }
290

291
        // decode the extra nodes if needed
292
        let nodes_left_to_decode = degree - results.len();
584,464,404✔
293
        self.decoder.num_of_residuals(nodes_left_to_decode);
584,464,404✔
294
        if nodes_left_to_decode != 0 {
194,821,468✔
295
            // pre-allocate with capacity for efficiency
296
            let node_id_offset = self.decoder.read_first_residual().to_int();
680,578,100✔
297
            let mut extra = (node_id as i64 + node_id_offset) as usize;
340,289,050✔
298
            results.push(extra);
510,433,575✔
299
            // decode the successive extra nodes
300
            for _ in 1..nodes_left_to_decode {
1,149,065,849✔
301
                extra += 1 + self.decoder.read_residual() as usize;
1,957,842,648✔
302
                results.push(extra);
1,957,842,648✔
303
            }
304
        }
305

306
        results.sort();
194,821,468✔
307
        Ok(())
194,821,468✔
308
    }
309
}
310

311
impl<'succ, D: Decode> NodeLabelsLender<'succ> for Iter<D> {
312
    type Label = usize;
313
    type IntoIterator = crate::traits::labels::AssumeSortedIterator<
314
        std::iter::Copied<std::slice::Iter<'succ, Self::Label>>,
315
    >;
316
}
317

318
impl<'succ, D: Decode> Lending<'succ> for Iter<D> {
319
    type Lend = (usize, <Self as NodeLabelsLender<'succ>>::IntoIterator);
320
}
321

322
impl<D: Decode> Lender for Iter<D> {
323
    fn next(&mut self) -> Option<Lend<'_, Self>> {
221,000,998✔
324
        if self.current_node >= self.number_of_nodes {
221,000,998✔
325
            return None;
344✔
326
        }
327
        let mut res = self.backrefs.take(self.current_node);
884,002,616✔
328
        res.clear();
442,001,308✔
329
        self.get_successors_iter_priv(self.current_node, &mut res)
884,002,616✔
330
            .unwrap();
331

332
        let res = self.backrefs.replace(self.current_node, res);
1,105,003,270✔
333
        let node_id = self.current_node;
442,001,308✔
334
        self.current_node += 1;
221,000,654✔
335
        Some((node_id, unsafe {
442,001,308✔
336
            crate::traits::labels::AssumeSortedIterator::new(res.iter().copied())
442,001,308✔
337
        }))
338
    }
339

340
    fn size_hint(&self) -> (usize, Option<usize>) {
3,581,262✔
341
        let len = self.len();
10,743,786✔
342
        (len, Some(len))
3,581,262✔
343
    }
344
}
345

346
unsafe impl<D: Decode> SortedLender for Iter<D> {}
347

348
impl<D: Decode> ExactSizeLender for Iter<D> {
349
    fn len(&self) -> usize {
3,906,830✔
350
        self.number_of_nodes - self.current_node
3,906,830✔
351
    }
352
}
STATUS · Troubleshooting · Open an Issue · Sales · Support · CAREERS · ENTERPRISE · START FREE · SCHEDULE DEMO
ANNOUNCEMENTS · TWITTER · TOS & SLA · Supported CI Services · What's a CI service? · Automated Testing

© 2026 Coveralls, Inc