xmloxide 0.4.3

A pure Rust reimplementation of libxml2 — memory-safe XML/HTML parsing
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

//! XML Catalog FFI functions.
#![allow(unsafe_code, clippy::missing_safety_doc)]

use std::ffi::CStr;
use std::os::raw::c_char;

use crate::catalog::Catalog;

use super::strings::to_c_string;
use super::{clear_last_error, set_last_error};

/// Parses an XML Catalog from a null-terminated UTF-8 XML string.
///
/// Returns a pointer to the catalog on success, or null on failure.
/// The returned catalog must be freed with [`xmloxide_free_catalog`].
///
/// # Safety
///
/// `input` must be a valid null-terminated UTF-8 string.
#[no_mangle]
pub unsafe extern "C" fn xmloxide_parse_catalog(input: *const c_char) -> *mut Catalog {
    clear_last_error();
    if input.is_null() {
        set_last_error("null input pointer");
        return std::ptr::null_mut();
    }
    // SAFETY: Null check above.
    let c_str = unsafe { CStr::from_ptr(input) };
    let Ok(s) = c_str.to_str() else {
        set_last_error("invalid UTF-8");
        return std::ptr::null_mut();
    };
    match Catalog::parse(s) {
        Ok(cat) => Box::into_raw(Box::new(cat)),
        Err(e) => {
            set_last_error(&e.message);
            std::ptr::null_mut()
        }
    }
}

/// Frees a catalog previously returned by `xmloxide_parse_catalog`.
///
/// Passing null is safe and does nothing.
///
/// # Safety
///
/// `catalog` must have been returned by `xmloxide_parse_catalog`, or be null.
#[no_mangle]
pub unsafe extern "C" fn xmloxide_free_catalog(catalog: *mut Catalog) {
    if !catalog.is_null() {
        // SAFETY: `catalog` was created by `Box::into_raw`, and is non-null.
        unsafe {
            drop(Box::from_raw(catalog));
        }
    }
}

/// Resolves a system identifier using the catalog.
///
/// Returns a caller-owned C string with the resolved URI, or null if not found.
/// The returned string must be freed with `xmloxide_free_string`.
///
/// # Safety
///
/// `catalog` must be a valid catalog pointer. `system_id` must be a valid
/// null-terminated UTF-8 string.
#[no_mangle]
pub unsafe extern "C" fn xmloxide_catalog_resolve_system(
    catalog: *const Catalog,
    system_id: *const c_char,
) -> *mut c_char {
    if catalog.is_null() || system_id.is_null() {
        return std::ptr::null_mut();
    }
    // SAFETY: Null checks above.
    let catalog = unsafe { &*catalog };
    let c_id = unsafe { CStr::from_ptr(system_id) };
    let Ok(id_str) = c_id.to_str() else {
        return std::ptr::null_mut();
    };
    match catalog.resolve_system(id_str) {
        Some(resolved) => to_c_string(&resolved),
        None => std::ptr::null_mut(),
    }
}

/// Resolves a public identifier using the catalog.
///
/// Returns a caller-owned C string with the resolved URI, or null if not found.
/// The returned string must be freed with `xmloxide_free_string`.
///
/// # Safety
///
/// `catalog` must be a valid catalog pointer. `public_id` must be a valid
/// null-terminated UTF-8 string.
#[no_mangle]
pub unsafe extern "C" fn xmloxide_catalog_resolve_public(
    catalog: *const Catalog,
    public_id: *const c_char,
) -> *mut c_char {
    if catalog.is_null() || public_id.is_null() {
        return std::ptr::null_mut();
    }
    // SAFETY: Null checks above.
    let catalog = unsafe { &*catalog };
    let c_id = unsafe { CStr::from_ptr(public_id) };
    let Ok(id_str) = c_id.to_str() else {
        return std::ptr::null_mut();
    };
    match catalog.resolve_public(id_str) {
        Some(resolved) => to_c_string(&resolved),
        None => std::ptr::null_mut(),
    }
}

/// Resolves a URI using the catalog.
///
/// Returns a caller-owned C string with the resolved URI, or null if not found.
/// The returned string must be freed with `xmloxide_free_string`.
///
/// # Safety
///
/// `catalog` must be a valid catalog pointer. `uri` must be a valid
/// null-terminated UTF-8 string.
#[no_mangle]
pub unsafe extern "C" fn xmloxide_catalog_resolve_uri(
    catalog: *const Catalog,
    uri: *const c_char,
) -> *mut c_char {
    if catalog.is_null() || uri.is_null() {
        return std::ptr::null_mut();
    }
    // SAFETY: Null checks above.
    let catalog = unsafe { &*catalog };
    let c_uri = unsafe { CStr::from_ptr(uri) };
    let Ok(uri_str) = c_uri.to_str() else {
        return std::ptr::null_mut();
    };
    match catalog.resolve_uri(uri_str) {
        Some(resolved) => to_c_string(&resolved),
        None => std::ptr::null_mut(),
    }
}