Module api_classify

Expand description

Standard-library API call classification helpers.

Each classifier answers “what kind of operation is this call?” (pointer arithmetic, raw memory access, ownership transfer, …). Callers — the VM, the alias/hazard scanner, and the call-summary registry — use these to pick a modelling strategy or discharge a safety obligation.

§Matching mechanism

Every classifier takes a DefId — fn(Option<DefId>) -> bool for callee matching, or fn(DefId) -> bool for ADT type matching — and answers via exact set membership in crate::def_id rather than substring-matching a def_path_str. crate::def_id resolves the well-known std/core/alloc items (by lang/diagnostic item, explicit path, or — for the open-ended groups and the std-challenge suites’ local re-implementations — by name-scanning fn_defs() at init), so a call site is matched by identity without the false positives of per-call-site name matching.

Functions§

any_fn 🔒: Whether callee is Some and matches any resolved DefId in the slice.
any_of 🔒: Whether callee is Some and matches any item in the (Option) list.
is_abs
is_align_offset: Whether callee is ptr::align_offset / NonNull::align_offset / *const T::align_offset / *mut T::align_offset.
is_align_to_local
is_as_ptr: Whether callee produces a raw pointer (or NonNull) alias of its first argument: as_ptr/as_mut_ptr, into_raw, and pointer cast (incl. cast_mut/cast_const). as_ptr_range/as_mut_ptr_range are excluded because they return a Range of two pointers rather than a single pointer; NonNull::new_unchecked/as_ref/as_mut are excluded because they do not produce a raw pointer (and new_unchecked must not mark its result non-null, or it would hide new_unchecked(null) unsoundness).
is_as_ptr_valid: is_as_ptr restricted to the pointer-validity-establishing subset: as_ptr/as_mut_ptr, into_raw, and NonNull::cast — which expose a non-null, aligned, initialized backing pointer. Raw-pointer cast/ cast_mut/cast_const are excluded because they only reinterpret the address (preserving null-ness) and are left to MIR inlining.
is_benign_origin_use: Whether callee is a benign, read-only use of a raw-pointer origin (len, is_empty, is_null, addr, as_ptr/as_mut_ptr, cast).
is_bit_preserving_nz
is_box_alloc_ctor: Box::new / new_in / new_uninit / new_uninit_in (and try_ variants) — fresh heap allocation constructors.
is_byte_ptr_add 🔒: Byte-granular byte_add/wrapping_byte_add and signed byte_offset/wrapping_byte_offset (stride 1).
is_byte_ptr_arith: Any byte-granular pointer arithmetic (stride 1), regardless of direction.
is_byte_ptr_sub 🔒: Byte-granular byte_sub/wrapping_byte_sub (stride 1).
is_capacity: Whether callee is a capacity query method.
is_checked_add
is_checked_mul
is_checked_next_pow2
is_checked_nonzero_iff
is_clamp
is_container_as_ptr: Whether callee is an as_ptr/as_mut_ptr method on a recognized pointer-container ADT (Vec/NonNull/Box/MaybeUninit/CString).
is_cstr_from_ptr
is_cstr_unchecked_constructor: _unchecked C-string constructors whose caller must guarantee NUL termination (CStr::from_bytes_with_nul_unchecked, CString::from_vec_with_nul_unchecked).
is_drop_in_place: Whether callee is drop_in_place::<T> — the MIR drop shim that drops the pointee in place and (for an owning pointee like Box/Vec) frees its heap allocation.
is_element_ptr_add 🔒: Element-strided add/wrapping_add and signed offset/wrapping_offset (stride = size_of::<T>()). offset_from/offset_from_unsigned are not matched (they subtract two pointers into an isize).
is_element_ptr_sub 🔒: Element-strided sub/wrapping_sub (stride = size_of::<T>()).
is_exchange_malloc: alloc::alloc::exchange_malloc (Box::new’s allocator on some toolchains).
is_from_raw_parts: Whether callee is a from_raw_parts constructor (slice/str/ptr/ String/Vec/NonNull). Matched by DefId via crate::def_id::from_raw_parts_fns (resolved from fn_defs(), including local re-implementations), instead of substring-matching def_path_str.
is_from_raw_parts_mut: Whether callee is a from_raw_parts_mut constructor.
is_into_boxed_slice
is_iter_position
is_layout_align
is_layout_constant: Whether callee is the compile-time layout constant size_of::<T>() or align_of::<T>(). The runtime intrinsics (size_of_val, align_of_val, pref_align_of, *_val_raw, …) are not classified here.
is_len: Whether callee is a len query method. Matched by DefId via crate::def_id::len_fns, which resolves every ::len fn_def in the std crates and the local crate — so the std-challenge suites’ re-implemented len methods are modelled too, without substring-matching a def_path_str.
is_manually_drop_drop: Whether callee is ManuallyDrop::<T>::drop — the manual drop that frees the pointee’s allocation without the ManuallyDrop wrapper’s own (no-op) drop glue.
is_max
is_maybe_uninit_assume_init: Whether callee is a MaybeUninit “assume initialized” accessor (assume_init, assume_init_read, assume_init_ref, assume_init_mut).
is_maybe_uninit_ty: Whether ty (peeling through & / *mut / *const / [T] / [T; N]) is MaybeUninit<...>, i.e. carries no validity invariant (any bit pattern is a valid value). Shared by the VM (init_parameters) and the Typed checker.
is_maybe_uninit_type
is_maybe_uninit_uninit: Whether callee is MaybeUninit::uninit (a new uninitialized slot).
is_maybe_uninit_write: Whether callee is MaybeUninit::write, which initializes the slot (unlike raw ptr::write, handled by is_mem_copy_or_write).
is_mem_copy_or_write: Memory copy/write intrinsics that legitimately write through a raw pointer without requiring the target bytes to be pre-initialized (e.g. ptr::write, write_bytes, copy_nonoverlapping, ptr::copy). Used by the checker to discharge Init/Typed obligations on MaybeUninit targets.
is_mem_replace: Whether callee is mem::replace(dest, src) — returns *dest (the old value), so the summary must deref the reference argument.
is_min_like
is_neg
is_nonnull_as_mut: Whether callee is NonNull::as_mut (produces an exclusive &mut).
is_nonnull_as_ref_as_mut: Whether callee is NonNull::as_ref or NonNull::as_mut.
is_nonnull_checked_new 🔒: Whether callee is NonNull::new (the null-checked constructor).
is_nonnull_new_unchecked 🔒: Whether callee is NonNull::new_unchecked (the unchecked transparent wrapper). Modeled as a provenance-preserving alias so the pointer’s element offset survives inlined iterator bodies (post_inc_start’s new_unchecked(ptr.add(1))); non-nullness is inherited from the source, not asserted, so new_unchecked(null) unsoundness is still caught.
is_overflowing_abs_neg
is_ownership_reconstruction: Whether callee reconstructs an owned value, taking ownership of the pointed-to memory: from a single raw pointer (Box::from_raw, CString::from_raw, Arc::from_raw, Rc::from_raw) or from a Vec<u8> (CString::from_vec_with_nul_unchecked). Distinct from is_from_raw_parts, which builds a slice/Vec from (ptr, len[, cap]).
is_ownership_return: Whether callee returns ownership of an allocation as a raw pointer (Box::into_raw, CString::into_raw, Arc::into_raw, Rc::into_raw, …).
is_ownership_transfer
is_pointer_add: Any pointer add (element or byte). offset/byte_offset take a signed isize, so a negative offset is still classified here (the sign lives in the argument); see is_pointer_sub for the positive-count sub family.
is_pointer_sub: Any pointer sub (element or byte): a positive count, base - count * stride.
is_ptr_read: Whether callee reads through a raw pointer or copies memory (ptr::read/read_unaligned/read_volatile, copy_to/copy_from, MaybeUninit::assume_init_read, and intrinsics copy/copy_nonoverlapping).
is_ptr_write: Whether callee writes through a raw pointer to its first argument (ptr::write, write_bytes, write_unaligned, write_volatile).
is_raw_ptr_cast 🔒: Whether callee is a raw-pointer cast/cast_mut/cast_const. These only reinterpret the address — they preserve null-ness and provenance, but do not establish that the result is non-null, aligned, or points at initialized memory. Distinguished from is_as_ptr so is_as_ptr_valid can keep them on the MIR-inlining path rather than the ReturnPointerFromArg model (which asserts those facts).
is_sat_unchecked_add
is_sat_unchecked_mul
is_select_unpredictable 🔒: Whether callee is select_unpredictable (the intrinsic or its hint::/intrinsics:: wrappers): returns one of two candidate values.
is_slice_get_unchecked
is_slice_range: Whether callee is slice::range(range, bounds) — the range normalizer that returns Range { start, end } with 0 <= start <= end <= bounds.end.
is_slice_to_vec: slice::to_vec (<[T]>::to_vec via to_vec_in::ConvertVec::to_vec) — allocates a fresh buffer and copies the slice’s elements.
is_sliceindex_get_unchecked: Whether callee is SliceIndex::get_unchecked/get_unchecked_mut (the trait method, whose receiver is the index and whose first argument is the slice pointer). Distinct from is_slice_get_unchecked (the slice-side methods whose receiver is the slice): the result aliases argument 1, not argument 0.
is_split_at
is_std_box
is_std_cstring
is_std_drop: Whether callee is std::mem::drop / core::mem::drop — the value drop that frees the argument’s heap allocation.
is_std_iter_or_itermut
is_std_nonnull
is_std_ordering
is_std_vec
is_str_as_bytes: str::as_bytes: reinterprets &str as &[u8] — same data pointer and byte length, so the result aliases the argument.
is_strlen
is_unwrap
is_vec_alloc_constructor
is_vec_from_box
is_vec_invalidating_method: Whether callee is a Vec method that may reallocate (invalidating any outstanding raw pointers derived from it).
is_vec_ownership_transfer
is_vec_push_or_reserve
is_vec_with_capacity: Vec::with_capacity — matched by DefId via crate::def_id::with_capacity_fns.