llvm_lib/core/values/constants/
mod.rs

1//! This section contains APIs for interacting with `MValueRef` that
2//! correspond to `LLVM Constant` instances.
3
4pub mod composite;
5pub mod expressions;
6pub mod global_aliases;
7pub mod global_values;
8pub mod global_variables;
9pub mod scalar;
10
11use super::ValueRef;
12use crate::core::types::TypeRef;
13use crate::GetRef;
14use llvm_sys::core;
15
16/// Obtain a constant value referring to the null instance of a type.
17///
18/// # Details
19///
20/// Creates a constant 'null' value of the specified type.
21///
22/// This function wraps the `LLVMConstNull` function from the LLVM core library. It generates a constant
23/// 'null' value for the specified type (`ty`). This is typically used for pointer types, where the null value
24/// represents a pointer to no valid memory location, but it can also be used for other types where a zero-initialized
25/// constant is required.
26///
27/// # Parameters
28///
29/// - `ty`: A reference to the type (`TypeRef`) for which the null value should be created. This type determines the kind of null value that is generated (e.g., null pointer, zero-initialized struct).
30///
31/// # Returns
32///
33/// Returns an instance of `ValueRef`, which encapsulates the constant null value for the specified type.
34#[must_use]
35pub fn const_null(ty: &TypeRef) -> ValueRef {
36    unsafe { ValueRef(core::LLVMConstNull(ty.get_ref())) }
37}
38
39/// Obtain a constant value referring to the instance of a type
40/// consisting of all ones.
41///
42/// This is only valid for integer types.
43///
44/// # Details
45///
46/// Creates a constant value with all bits set to one for the specified type.
47///
48/// This function wraps the `LLVMConstAllOnes` function from the LLVM core library. It generates a constant value
49/// for the specified type (`ty`) where all the bits are set to one. This is often used to represent a value where
50/// all bits are enabled, such as `-1` for signed integers or the maximum possible value for unsigned integers.
51///
52/// # Parameters
53///
54/// - `ty`: A reference to the type (`TypeRef`) for which the all-ones value should be created. This type determines the size and nature of the value (e.g., integer, vector).
55///
56/// # Returns
57///
58/// Returns an instance of `ValueRef`, which encapsulates the constant all-ones value for the specified type.
59#[must_use]
60pub fn const_all_ones(ty: &TypeRef) -> ValueRef {
61    unsafe { ValueRef(core::LLVMConstAllOnes(ty.get_ref())) }
62}
63
64/// Obtain a constant value referring to an undefined value of a type.
65///
66/// # Details
67///
68/// Creates an 'undefined' value of the specified type.
69///
70/// This function wraps the `LLVMGetUndef` function from the LLVM core library. It generates a constant
71/// 'undefined' value for the specified type (`ty`). An undefined value is a placeholder that can take any value of the specified type
72/// during program execution, typically used in optimization phases or when a value does not need to be initialized.
73///
74/// # Parameters
75///
76/// - `ty`: A reference to the type (`TypeRef`) for which the undefined value should be created. This type determines the nature of the undefined value (e.g., integer, floating-point, vector).
77///
78/// # Returns
79///
80/// Returns an instance of `ValueRef`, which encapsulates the constant undefined value for the specified type.
81#[must_use]
82pub fn get_undef(ty: &TypeRef) -> ValueRef {
83    unsafe { ValueRef(core::LLVMGetUndef(ty.get_ref())) }
84}
85
86/// Obtain a constant value referring to a poison value of a type.
87///
88/// # Details
89///
90/// Creates a 'poison' value of the specified type.
91///
92/// This function wraps the `LLVMGetPoison` function from the LLVM core library. It generates a constant
93/// 'poison' value for the specified type (`ty`). A poison value is similar to an undefined value but more strict;
94/// it is used to represent a value that results from an operation with undefined behavior. Using a poison value in further
95/// operations can propagate the poison, potentially leading to further undefined behavior.
96///
97/// # Parameters
98///
99/// - `ty`: A reference to the type (`TypeRef`) for which the poison value should be created. This type determines the nature of the poison value (e.g., integer, floating-point, vector).
100///
101/// # Returns
102///
103/// Returns an instance of `ValueRef`, which encapsulates the constant poison value for the specified type.
104#[must_use]
105pub fn get_poison(ty: &TypeRef) -> ValueRef {
106    unsafe { ValueRef(core::LLVMGetPoison(ty.get_ref())) }
107}
108
109/// Determine whether a value instance is null.
110///
111/// # Details
112///
113/// Checks if the value is a constant 'null' value.
114///
115/// This function wraps the `LLVMIsNull` function from the LLVM core library. It determines whether
116/// the value represented by `ValueRef` is a constant 'null' value. This is typically used to check if a pointer
117/// or other nullable type is explicitly set to null within the LLVM IR.
118///
119/// # Returns
120///
121/// Returns `true` if the value is a constant null value, otherwise returns `false`.
122#[must_use]
123pub fn is_null(val: &ValueRef) -> bool {
124    unsafe { core::LLVMIsNull(val.get_ref()) != 0 }
125}
126
127/// Obtain a constant that is a constant pointer pointing to `NULL` for a
128/// specified type.
129///
130/// # Details
131///
132/// Creates a constant null pointer value of the specified pointer type.
133///
134/// This function wraps the `LLVMConstPointerNull` function from the LLVM core library. It generates a constant
135/// null pointer for the specified pointer type (`ty`). This is typically used to represent a pointer that does not
136/// point to any valid memory location within LLVM IR.
137///
138/// # Parameters
139///
140/// - `ty`: A reference to the pointer type (`TypeRef`) for which the null pointer value should be created. This type must be a pointer type.
141///
142/// # Returns
143///
144/// Returns an instance of `ValueRef`, which encapsulates the constant null pointer value for the specified type.
145#[must_use]
146pub fn const_pointer_null(ty: &TypeRef) -> ValueRef {
147    unsafe { ValueRef(core::LLVMConstPointerNull(ty.get_ref())) }
148}
llvm_lib/core/values/constants/mod.rs

llvm_lib/core/values/constants/
mod.rs
