nstd-sys 0.13.0

Cross platform general purpose C library written 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
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

#ifndef NSTD_HEAP_PTR_H
#define NSTD_HEAP_PTR_H
#include "core/alloc.h"
#include "core/optional.h"
#include "nstd.h"

/// A pointer type for single value heap allocation.
typedef struct {
    /// The memory allocator.
    const NSTDAllocator *allocator;
    /// A raw pointer to the value on the heap.
    NSTDAnyMut ptr;
    /// The heap object's memory layout.
    NSTDAllocLayout layout;
} NSTDHeapPtr;

/// Represents an optional value of type `NSTDHeapPtr`.
NSTDOptional(NSTDHeapPtr) NSTDOptionalHeapPtr;

/// Creates a new initialized heap allocated object.
///
/// # Parameters:
///
/// - `const NSTDAllocator *allocator` - The memory allocator.
///
/// - `NSTDAllocLayout layout` - The heap object's memory layout.
///
/// - `NSTDAny init` - A pointer to the object to initialize the heap object with.
///
/// # Returns
///
/// `NSTDOptionalHeapPtr hptr` - The new heap allocated object, or an uninitialized "none" variant
/// if allocating fails.
///
/// # Safety
///
/// `init` must be a pointer to a value that is valid for reads based on `layout`.
NSTDAPI NSTDOptionalHeapPtr
nstd_heap_ptr_new(const NSTDAllocator *allocator, NSTDAllocLayout layout, NSTDAny init);

/// Creates a new zero-initialized heap allocated object.
///
/// # Parameters:
///
/// - `const NSTDAllocator *allocator` - The memory allocator.
///
/// - `NSTDAllocLayout layout` - The heap object's memory layout.
///
/// # Returns
///
/// `NSTDOptionalHeapPtr hptr` - The new heap allocated object, or an uninitialized "none" variant
/// if allocating fails.
///
/// # Safety
///
/// The data to be stored in the heap pointer must be safely representable by an all-zero byte
/// pattern.
NSTDAPI NSTDOptionalHeapPtr
nstd_heap_ptr_new_zeroed(const NSTDAllocator *allocator, NSTDAllocLayout layout);

/// Creates a clone of a heap allocated object.
///
/// # Parameters:
///
/// - `const NSTDHeapPtr *hptr` - The heap pointer.
///
/// # Returns
///
/// `NSTDOptionalHeapPtr cloned` - A new clone of the original heap object, or an uninitialized
/// "none" variant if allocating fails.
NSTDAPI NSTDOptionalHeapPtr nstd_heap_ptr_clone(const NSTDHeapPtr *hptr);

/// Returns an immutable reference to a heap object's allocator.
///
/// # Parameters:
///
/// - `const NSTDHeapPtr *hptr` - The heap object.
///
/// # Returns
///
/// `const NSTDAllocator *allocator` - The heap object's allocator.
NSTDAPI const NSTDAllocator *nstd_heap_ptr_allocator(const NSTDHeapPtr *hptr);

/// Returns the size of the heap allocated object.
///
/// # Parameters:
///
/// - `const NSTDHeapPtr *hptr` - The heap pointer.
///
/// # Returns
///
/// `NSTDUInt size` - The size of the heap allocated object.
NSTDAPI NSTDUInt nstd_heap_ptr_size(const NSTDHeapPtr *hptr);

/// Returns an immutable raw pointer to the object on the heap.
///
/// # Note
///
/// This will always return null if the size of the object being stored on the heap is 0.
///
/// # Parameters:
///
/// - `const NSTDHeapPtr *hptr` - The heap pointer.
///
/// # Returns
///
/// `NSTDAny ptr` - A raw pointer to the object on the heap.
NSTDAPI NSTDAny nstd_heap_ptr_get(const NSTDHeapPtr *hptr);

/// Returns a raw pointer to the object on the heap.
///
/// # Note
///
/// This will always return null if the size of the object being stored on the heap is 0.
///
/// # Parameters:
///
/// - `NSTDHeapPtr *hptr` - The heap pointer.
///
/// # Returns
///
/// `NSTDAnyMut ptr` - A raw pointer to the object on the heap.
NSTDAPI NSTDAnyMut nstd_heap_ptr_get_mut(NSTDHeapPtr *hptr);

/// Frees an instance of `NSTDHeapPtr`.
///
/// # Parameters:
///
/// - `NSTDHeapPtr hptr` - A pointer to the heap object.
NSTDAPI void nstd_heap_ptr_free(NSTDHeapPtr hptr);

/// Frees an instance of `NSTDHeapPtr` after invoking `callback` with the heap object's data.
///
/// # Parameters:
///
/// - `NSTDHeapPtr hptr` - A pointer to the heap object.
///
/// - `void (*callback)(NSTDAnyMut)` - The heap object's destructor.
///
/// # Safety
///
/// This operation makes a direct call on a C function pointer (`callback`).
NSTDAPI void nstd_heap_ptr_drop(NSTDHeapPtr hptr, void (*callback)(NSTDAnyMut));

#endif