From 68758f3f90a31ca8ee019d6af7d3b980c2217cee Mon Sep 17 00:00:00 2001 From: auronandace Date: Mon, 15 Jun 2026 15:09:18 +0100 Subject: [PATCH] add descriptions to inttypes header and related functions --- src/header/inttypes/mod.rs | 77 +++++++++++++++++++++++++++----------- src/header/stdlib/mod.rs | 40 ++++++++++++++++---- src/header/wchar/mod.rs | 72 +++++++++++++++++++++++------------ 3 files changed, 136 insertions(+), 53 deletions(-) diff --git a/src/header/inttypes/mod.rs b/src/header/inttypes/mod.rs index 252a02e47c..8aad0f9200 100644 --- a/src/header/inttypes/mod.rs +++ b/src/header/inttypes/mod.rs @@ -15,31 +15,48 @@ use crate::{ }; /// See . +/// +/// Computes the absolute value of the integer `j`. #[unsafe(no_mangle)] -pub extern "C" fn imaxabs(i: intmax_t) -> intmax_t { - i.abs() +pub extern "C" fn imaxabs(j: intmax_t) -> intmax_t { + j.abs() } /// See . +/// +/// Structure type that is the type of the value returned by the `imaxdiv()` +/// function. #[repr(C)] pub struct imaxdiv_t { + /// The quotient. quot: intmax_t, + /// The remainder. rem: intmax_t, } /// See . +/// +/// Computes `numer` / `denom` and `numer` % `denom` in a single operation. +/// +/// Returns the struct `imaxdiv_t`, comprising both the quotient and remainder. #[unsafe(no_mangle)] -pub extern "C" fn imaxdiv(i: intmax_t, j: intmax_t) -> imaxdiv_t { +pub extern "C" fn imaxdiv(numer: intmax_t, denom: intmax_t) -> imaxdiv_t { imaxdiv_t { - quot: i / j, - rem: i % j, + quot: numer / denom, + rem: numer % denom, } } /// See . +/// +/// Equivalent to `strtol()` and `strtoll()`, except that the initial portion +/// of the string shall be converted to `intmax_t`. +/// +/// Upon success, returns the converted value. If no conversion could be +/// performed or the value of `base` is not supported, returns `0`. #[unsafe(no_mangle)] pub unsafe extern "C" fn strtoimax( - s: *const c_char, + nptr: *const c_char, endptr: *mut *mut c_char, base: c_int, ) -> intmax_t { @@ -48,16 +65,22 @@ pub unsafe extern "C" fn strtoimax( false, intmax_t::MAX, intmax_t::MIN, - s, + nptr, endptr, base ) } /// See . +/// +/// Equivalent to `strtoul()` and `strtoull()`, except that the initial portion +/// of the string shall be converted to `uintmax_t`. +/// +/// Upon success, returns the converted value. If no conversion could be +/// performed or the value of `base` is not supported, returns `0`. #[unsafe(no_mangle)] pub unsafe extern "C" fn strtoumax( - s: *const c_char, + nptr: *const c_char, endptr: *mut *mut c_char, base: c_int, ) -> uintmax_t { @@ -66,39 +89,51 @@ pub unsafe extern "C" fn strtoumax( false, uintmax_t::MAX, uintmax_t::MIN, - s, + nptr, endptr, base ) } /// See . +/// +/// Equivalent to `wctol()` and `wctoll()`, except that the initial portion +/// of the wide string shall be converted to `intmax_t`. +/// +/// Upon success, returns the converted value. If no conversion could be +/// performed, returns `0`. #[expect(clippy::cast_lossless)] // not all users of `wcsto_impl!` are lossless #[unsafe(no_mangle)] pub unsafe extern "C" fn wcstoimax( - mut ptr: *const wchar_t, - end: *mut *mut wchar_t, + mut nptr: *const wchar_t, + endptr: *mut *mut wchar_t, base: c_int, ) -> intmax_t { - skipws!(ptr); - let result = wcsto_impl!(intmax_t, ptr, base); - if !end.is_null() { - unsafe { *end = ptr.cast_mut() }; + skipws!(nptr); + let result = wcsto_impl!(intmax_t, nptr, base); + if !endptr.is_null() { + unsafe { *endptr = nptr.cast_mut() }; } result } /// See . +/// +/// Equivalent to `wctoul()` and `wctoull()`, except that the initial portion +/// of the wide string shall be converted to `uintmax_t`. +/// +/// Upon success, returns the converted value. If no conversion could be +/// performed, returns `0`. #[unsafe(no_mangle)] pub unsafe extern "C" fn wcstoumax( - mut ptr: *const wchar_t, - end: *mut *mut wchar_t, + mut nptr: *const wchar_t, + endptr: *mut *mut wchar_t, base: c_int, ) -> uintmax_t { - skipws!(ptr); - let result = wcsto_impl!(uintmax_t, ptr, base); - if !end.is_null() { - unsafe { *end = ptr.cast_mut() }; + skipws!(nptr); + let result = wcsto_impl!(uintmax_t, nptr, base); + if !endptr.is_null() { + unsafe { *endptr = nptr.cast_mut() }; } result } diff --git a/src/header/stdlib/mod.rs b/src/header/stdlib/mod.rs index d6b3a2d944..3949c81135 100644 --- a/src/header/stdlib/mod.rs +++ b/src/header/stdlib/mod.rs @@ -1488,17 +1488,29 @@ pub unsafe extern "C" fn strtof(s: *const c_char, endptr: *mut *mut c_char) -> c } /// See . +/// +/// Converts the initial portion of the string pointed to by `nptr` to a type +/// `long`. +/// +/// Upon success, returns the converted value. If no conversion could be +/// performed or the value of `base` is not supported, returns `0`. #[unsafe(no_mangle)] -pub unsafe extern "C" fn strtol(s: *const c_char, endptr: *mut *mut c_char, base: c_int) -> c_long { - strto_impl!(c_long, true, c_long::MAX, c_long::MIN, s, endptr, base) +pub unsafe extern "C" fn strtol(nptr: *const c_char, endptr: *mut *mut c_char, base: c_int) -> c_long { + strto_impl!(c_long, true, c_long::MAX, c_long::MIN, nptr, endptr, base) } // TODO: strtold(), when long double is available /// See . +/// +/// Converts the initial portion of the string pointed to by `nptr` to a type +/// `long long`. +/// +/// Upon success, returns the converted value. If no conversion could be +/// performed or the value of `base` is not supported, returns `0`. #[unsafe(no_mangle)] pub unsafe extern "C" fn strtoll( - s: *const c_char, + nptr: *const c_char, endptr: *mut *mut c_char, base: c_int, ) -> c_longlong { @@ -1507,26 +1519,38 @@ pub unsafe extern "C" fn strtoll( true, c_longlong::MAX, c_longlong::MIN, - s, + nptr, endptr, base ) } /// See . +/// +/// Converts the initial portion of the string pointed to by `str` to a type +/// `unsigned long`. +/// +/// Upon success, returns the converted value. If no conversion could be +/// performed or the value of `base` is not supported, returns `0`. #[unsafe(no_mangle)] pub unsafe extern "C" fn strtoul( - s: *const c_char, + str: *const c_char, endptr: *mut *mut c_char, base: c_int, ) -> c_ulong { - strto_impl!(c_ulong, false, c_ulong::MAX, c_ulong::MIN, s, endptr, base) + strto_impl!(c_ulong, false, c_ulong::MAX, c_ulong::MIN, str, endptr, base) } /// See . +/// +/// Converts the initial portion of the string pointed to by `str` to a type +/// `unsigned long long`. +/// +/// Upon success, returns the converted value. If no conversion could be +/// performed or the value of `base` is not supported, returns `0`. #[unsafe(no_mangle)] pub unsafe extern "C" fn strtoull( - s: *const c_char, + str: *const c_char, endptr: *mut *mut c_char, base: c_int, ) -> c_ulonglong { @@ -1535,7 +1559,7 @@ pub unsafe extern "C" fn strtoull( false, c_ulonglong::MAX, c_ulonglong::MIN, - s, + str, endptr, base ) diff --git a/src/header/wchar/mod.rs b/src/header/wchar/mod.rs index 31fe7e291d..a23ba14e2f 100644 --- a/src/header/wchar/mod.rs +++ b/src/header/wchar/mod.rs @@ -848,62 +848,86 @@ pub unsafe extern "C" fn wcstok( } /// See . +/// +/// Converts the initial portion of the wide-character string pointed to by +/// `nptr` to a type `long`. +/// +/// Upon success, returns the converted value. If no conversion could be +/// performed, returns `0`. #[unsafe(no_mangle)] pub unsafe extern "C" fn wcstol( - mut ptr: *const wchar_t, - end: *mut *mut wchar_t, + mut nptr: *const wchar_t, + endptr: *mut *mut wchar_t, base: c_int, ) -> c_long { - skipws!(ptr); - let result = wcsto_impl!(c_long, ptr, base); - if !end.is_null() { - unsafe { *end = ptr.cast_mut() }; + skipws!(nptr); + let result = wcsto_impl!(c_long, nptr, base); + if !endptr.is_null() { + unsafe { *endptr = nptr.cast_mut() }; } result } /// See . +/// +/// Converts the initial portion of the wide-character string pointed to by +/// `nptr` to a type `long long`. +/// +/// Upon success, returns the converted value. If no conversion could be +/// performed, returns `0`. #[expect(clippy::cast_lossless)] // not all users of `wcsto_impl!` are lossless #[unsafe(no_mangle)] pub unsafe extern "C" fn wcstoll( - mut ptr: *const wchar_t, - end: *mut *mut wchar_t, + mut nptr: *const wchar_t, + endptr: *mut *mut wchar_t, base: c_int, ) -> c_longlong { - skipws!(ptr); - let result = wcsto_impl!(c_longlong, ptr, base); - if !end.is_null() { - unsafe { *end = ptr.cast_mut() }; + skipws!(nptr); + let result = wcsto_impl!(c_longlong, nptr, base); + if !endptr.is_null() { + unsafe { *endptr = nptr.cast_mut() }; } result } /// See . +/// +/// Converts the initial portion of the wide-character string pointed to by +/// `nptr` to a type `unsigned long`. +/// +/// Upon success, returns the converted value. If no conversion could be +/// performed, returns `0`. #[unsafe(no_mangle)] pub unsafe extern "C" fn wcstoul( - mut ptr: *const wchar_t, - end: *mut *mut wchar_t, + mut nptr: *const wchar_t, + endptr: *mut *mut wchar_t, base: c_int, ) -> c_ulong { - skipws!(ptr); - let result = wcsto_impl!(c_ulong, ptr, base); - if !end.is_null() { - unsafe { *end = ptr.cast_mut() }; + skipws!(nptr); + let result = wcsto_impl!(c_ulong, nptr, base); + if !endptr.is_null() { + unsafe { *endptr = nptr.cast_mut() }; } result } /// See . +/// +/// Converts the initial portion of the wide-character string pointed to by +/// `nptr` to a type `unsigned long long`. +/// +/// Upon success, returns the converted value. If no conversion could be +/// performed, returns `0`. #[unsafe(no_mangle)] pub unsafe extern "C" fn wcstoull( - mut ptr: *const wchar_t, - end: *mut *mut wchar_t, + mut nptr: *const wchar_t, + endptr: *mut *mut wchar_t, base: c_int, ) -> c_ulonglong { - skipws!(ptr); - let result = wcsto_impl!(c_ulonglong, ptr, base); - if !end.is_null() { - unsafe { *end = ptr.cast_mut() }; + skipws!(nptr); + let result = wcsto_impl!(c_ulonglong, nptr, base); + if !endptr.is_null() { + unsafe { *endptr = nptr.cast_mut() }; } result }