webgraph 0.6.1

A Rust port of the WebGraph framework (http://webgraph.di.unimi.it/).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

/*
 * SPDX-FileCopyrightText: 2023 Inria
 * SPDX-FileCopyrightText: 2024 Sebastiano Vigna
 *
 * SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
 */

use crate::utils::{ArcMmapHelper, MmapHelper};
use anyhow::Result;
use mmap_rs::{MmapFlags, MmapMut};
use std::path::Path;
use std::sync::Arc;
use sux::traits::*;
use value_traits::slices::{SliceByValue, SliceByValueMut};

/// Maps into memory a file of big-endian 64-bit values, making it accessible as
/// a [`BitFieldSlice<usize>`](sux::traits::BitFieldSlice).
///
/// The purpose of this helper class is to make interoperability with the big
/// version of the Java implementation of WebGraph easier. It is a thin wrapper
/// around [`MmapHelper`], and its methods are named accordingly.
///
/// Note that this class is only available on 64-bit platforms.
///
/// By default it uses an `Arc<Mmap>` so that it can be cloned.
#[cfg(target_pointer_width = "64")]
#[derive(Clone)]
pub struct JavaPermutation<M = ArcMmapHelper<u64>> {
    pub perm: M,
}

#[cfg(target_pointer_width = "64")]
impl JavaPermutation<MmapHelper<u64, MmapMut>> {
    /// Creates and map a permutation into memory (read/write), overwriting it if it exists.
    ///
    /// # Arguments
    /// - `path` - The path to the permutation.
    /// - `flags` - The flags to use for the memory mapping.
    /// - `len` - The length of the permutation (number of 64-bit unsigned values).
    pub fn new(path: impl AsRef<Path>, flags: MmapFlags, len: usize) -> Result<Self> {
        Ok(Self {
            perm: MmapHelper::new(path, flags, len)?,
        })
    }

    /// Maps a permutation into memory (read/write).
    ///
    /// # Arguments
    /// - `path` - The path to the permutation.
    /// - `flags` - The flags to use for the memory mapping.
    pub fn mmap_mut(path: impl AsRef<Path>, flags: MmapFlags) -> Result<Self> {
        Ok(Self {
            perm: MmapHelper::mmap_mut(path, flags)?,
        })
    }
}

impl JavaPermutation {
    /// Maps a permutation into memory (read-only).
    ///
    /// # Arguments
    /// - `path` - The path to the permutation.
    /// - `flags` - The flags to use for the memory mapping.
    pub fn mmap(path: impl AsRef<Path>, flags: MmapFlags) -> Result<Self> {
        Ok(Self {
            perm: ArcMmapHelper(Arc::new(MmapHelper::mmap(path, flags)?)),
        })
    }
}

impl BitWidth<usize> for JavaPermutation {
    fn bit_width(&self) -> usize {
        64
    }
}

impl BitWidth<usize> for JavaPermutation<MmapHelper<u64, MmapMut>> {
    fn bit_width(&self) -> usize {
        64
    }
}

impl SliceByValue for JavaPermutation {
    type Value = usize;
    #[inline(always)]
    fn len(&self) -> usize {
        self.perm.as_ref().len()
    }
    #[inline(always)]
    unsafe fn get_value_unchecked(&self, index: usize) -> usize {
        u64::from_be_bytes(unsafe { self.perm.as_ref().get_unchecked(index).to_ne_bytes() })
            as usize
    }
}

impl SliceByValue for JavaPermutation<MmapHelper<u64, MmapMut>> {
    type Value = usize;
    #[inline(always)]
    fn len(&self) -> usize {
        self.perm.as_ref().len()
    }
    #[inline(always)]
    unsafe fn get_value_unchecked(&self, index: usize) -> usize {
        u64::from_be_bytes(unsafe { self.perm.as_ref().get_unchecked(index).to_ne_bytes() })
            as usize
    }
}

impl SliceByValueMut for JavaPermutation<MmapHelper<u64, MmapMut>> {
    #[inline(always)]
    unsafe fn set_value_unchecked(&mut self, index: usize, value: usize) {
        unsafe {
            *self.perm.as_mut().get_unchecked_mut(index) =
                u64::from_ne_bytes((value as u64).to_be_bytes());
        }
    }

    type ChunksMut<'a>
        = std::slice::ChunksMut<'a, usize>
    where
        Self: 'a;

    type ChunksMutError = std::convert::Infallible;

    fn try_chunks_mut(
        &mut self,
        _chunk_size: usize,
    ) -> Result<Self::ChunksMut<'_>, std::convert::Infallible> {
        unimplemented!(
            "This method is not implemented for JavaPermutation<MmapHelper<u64, MmapMut>>"
        );
    }
}

impl AsRef<[u64]> for JavaPermutation {
    fn as_ref(&self) -> &[u64] {
        self.perm.as_ref()
    }
}

impl AsRef<[u64]> for JavaPermutation<MmapHelper<u64, MmapMut>> {
    fn as_ref(&self) -> &[u64] {
        self.perm.as_ref()
    }
}