psltools 0.0.3

work with .psl files in Rust
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

// Copyright (c) 2026 Alejandro Gonzales-Irribarren <alejandrxgzi@gmail.com>
// Distributed under the terms of the Apache License, Version 2.0.

use std::ops::Range;
use std::sync::Arc;

use crate::PslError;

#[cfg(feature = "mmap")]
use memmap2::Mmap;

/// Shared byte storage for zero-copy parsing with lifetime safety.
///
/// Wraps either a memory-mapped file or owned bytes in an `Arc`, allowing
/// multiple zero-copy references to share the same underlying storage safely
/// without lifetime concerns.
///
/// # Variants
///
/// * `Mmap` - Memory-mapped file (requires the `mmap` feature)
/// * `Owned` - Owned buffer behind an `Arc`
#[derive(Debug, Clone)]
pub enum SharedBytes {
    #[cfg(feature = "mmap")]
    Mmap(Arc<Mmap>),
    Owned(Arc<Vec<u8>>),
}

impl SharedBytes {
    /// Returns the entire buffer as a byte slice.
    pub fn as_slice(&self) -> &[u8] {
        match self {
            #[cfg(feature = "mmap")]
            SharedBytes::Mmap(m) => &m[..],
            SharedBytes::Owned(buf) => buf.as_slice(),
        }
    }

    /// Creates a `SharedBytes` from a memory map (requires the `mmap` feature).
    #[cfg(feature = "mmap")]
    pub(crate) fn from_mmap(mmap: Mmap) -> Self {
        SharedBytes::Mmap(Arc::new(mmap))
    }

    /// Creates a `SharedBytes` from an owned `Vec<u8>`.
    pub fn from_owned(data: Vec<u8>) -> Self {
        SharedBytes::Owned(Arc::new(data))
    }
}

/// A lightweight, clonable view into a subsection of a `SharedBytes` buffer.
///
/// Holds a reference-counted pointer to the underlying storage plus a `Range`
/// describing the slice it represents, so cloning is cheap and never copies the
/// underlying bytes.
///
/// # Examples
///
/// ```
/// use psltools::io::storage::{ByteSlice, SharedBytes};
///
/// let storage = SharedBytes::from_owned(b"hello world".to_vec());
/// let slice = ByteSlice::new(storage, 6..11);
/// assert_eq!(slice.as_bytes(), b"world");
/// assert_eq!(slice.as_str(), Some("world"));
/// ```
#[derive(Debug, Clone)]
pub struct ByteSlice {
    storage: SharedBytes,
    range: Range<usize>,
}

impl ByteSlice {
    /// Creates a new `ByteSlice` over `range` within `storage`.
    pub fn new(storage: SharedBytes, range: Range<usize>) -> Self {
        ByteSlice { storage, range }
    }

    /// Returns the bytes represented by this slice.
    pub fn as_bytes(&self) -> &[u8] {
        &self.storage.as_slice()[self.range.clone()]
    }

    /// Attempts to interpret the slice as UTF-8, returning `None` if invalid.
    pub fn as_str(&self) -> Option<&str> {
        std::str::from_utf8(self.as_bytes()).ok()
    }

    /// Returns the number of bytes in the slice.
    pub fn len(&self) -> usize {
        self.range.len()
    }

    /// Returns `true` if the slice is empty.
    pub fn is_empty(&self) -> bool {
        self.range.is_empty()
    }
}

/// Checks if a file path has a `.gz` extension.
pub fn is_gz_path(path: &std::path::Path) -> bool {
    path.extension().is_some_and(|ext| ext == "gz")
}

/// Constructs a [`PslError::Unsupported`] for when the `gzip` feature is needed
/// but was not compiled in.
#[cfg_attr(feature = "gzip", allow(dead_code))]
pub fn gzip_feature_error() -> PslError {
    PslError::Unsupported {
        msg: "gzip support disabled; enable the `gzip` feature".into(),
    }
}