Struct VaList

#[repr(transparent)]
pub struct VaList<'a> { pub(in ::ffi::va_list) inner: VaListInner, pub(in ::ffi::va_list) _marker: PhantomCovariantLifetime<'a> }

A variable argument list, ABI-compatible with va_list in C.

This type is created in c-variadic functions when ... is desugared. A VaList is automatically initialized (equivalent to calling va_start in C).

use std::ffi::VaList;

/// # Safety
/// Must be passed at least `count` arguments of type `i32`.
unsafe extern "C" fn my_func(count: u32, ap: ...) -> i32 {
    unsafe { vmy_func(count, ap) }
}

/// # Safety
/// Must be passed at least `count` arguments of type `i32`.
unsafe fn vmy_func(count: u32, mut ap: VaList<'_>) -> i32 {
    let mut sum = 0;
    for _ in 0..count {
        sum += unsafe { ap.next_arg::<i32>() };
    }
    sum
}

assert_eq!(unsafe { my_func(1, 42i32) }, 42);
assert_eq!(unsafe { my_func(3, 42i32, -7i32, 20i32) }, 55);

The VaList::next_arg method reads the next argument from the variable argument list, and is equivalent to C va_arg.

Cloning a VaList performs the equivalent of C va_copy, producing an independent cursor that arguments can be read from without affecting the original. Dropping a VaList performs the equivalent of C va_end.

A VaList can be used across an FFI boundary, and fully matches the platform's va_list in terms of layout and ABI.

Fields

inner: VaListInner
_marker: PhantomCovariantLifetime<'a>

Implementations

impl VaList<'_>

const fn duplicate(&self) -> Self

impl<'f> VaList<'f>

const unsafe fn next_arg<T: VaArgSafe>(&mut self) -> T

Read the next argument from the variable argument list.

Only types that implement VaArgSafe can be read from a variable argument list.

Safety

This function is safe to call only if all of the following conditions are satisfied:

  • There is another c-variadic argument to read.
  • The actual type of the argument U is compatible with T (as defined below).
  • If U and T are both integer types, then the value passed by the caller must be representable in both types.
  • If T is not Copy, then it must not have already been read using next_arg on a [clone][VaList::clone]d copy of this VaList. (Currently, all types implementing VaArgSafe also implement Copy, but this may change in the future.)

Types T and U are compatible when:

  • T and U are the same type.
  • T and U are integer types of the same size.
  • T and U are both pointers, and their target types are compatible.
  • T is a pointer to c_void and U is a pointer to i8 or u8, or vice versa.

Trait Implementations

impl Debug for VaList<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl<'f> Clone for VaList<'f>

fn clone(&self) -> Self

Clone the VaList, producing a second independent cursor into the variable argument list.

Corresponds to va_copy in C.

impl<'f> Drop for VaList<'f>

fn drop(&mut self)

Drop the VaList.

Corresponds to va_end in C.

Auto Trait Implementations

impl<'a> !Send for VaList<'a>

impl<'a> !Sync for VaList<'a>

impl<'a> Freeze for VaList<'a>

impl<'a> RefUnwindSafe for VaList<'a>

impl<'a> Unpin for VaList<'a>

impl<'a> UnsafeUnpin for VaList<'a>

impl<'a> UnwindSafe for VaList<'a>

Blanket Implementations

impl<T> Any for VaList<'a> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for VaList<'a> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for VaList<'a> where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> CloneToUninit for VaList<'a> where T: Clone,

unsafe fn clone_to_uninit(&self, dest: *mut u8)

impl<T> From<T> for VaList<'a>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> SizeHint for VaList<'a> where T: ?Sized,

fn lower_bound(&self) -> usize
fn upper_bound(&self) -> Option<usize>

impl<T> SizedTypeProperties for VaList<'a>

impl<T, U> Into<U> for VaList<'a> where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for VaList<'a> where U: Into<T>,

type Error = never;
fn try_from(value: U) -> Result<T, never>

impl<T, U> TryInto<U> for VaList<'a> where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>