Skip to content

Commit

Permalink
Mark function without side effects as must_use (#228)
Browse files Browse the repository at this point in the history 
This hint will make the compiler warn consumers of this library if they
ever call one of these functions without using its return value.
  • Loading branch information
@WhyNotHugo
WhyNotHugo authored Oct 5, 2023
1 parent 078f8e8 commit 98669b2
Show file tree
Hide file tree
Showing 35 changed files with 188 additions and 0 deletions.
8 changes: 8 additions & 0 deletions src/base/charstr.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ impl CharStr<()> {

impl<Octs: ?Sized> CharStr<Octs> {
/// Creates a new empty character string.
#[must_use]
pub fn empty() -> Self
where
Octs: From<&'static [u8]>,
Expand Down Expand Up @@ -103,6 +104,7 @@ impl CharStr<[u8]> {
}

/// Creates a new empty character string on an octets slice.
#[must_use]
pub fn empty_slice() -> &'static Self {
unsafe { Self::from_slice_unchecked(b"".as_ref()) }
}
Expand All @@ -113,6 +115,7 @@ impl CharStr<[u8]> {
///
/// The caller has to make sure that `octets` is at most 255 octets
/// long. Otherwise, the behaviour is undefined.
#[must_use]
pub unsafe fn from_slice_unchecked(slice: &[u8]) -> &Self {
&*(slice as *const [u8] as *const Self)
}
Expand All @@ -139,6 +142,7 @@ impl CharStr<[u8]> {

impl<Octs: ?Sized> CharStr<Octs> {
/// Creates a new empty builder for this character string type.
#[must_use]
pub fn builder() -> CharStrBuilder<Octs::Builder>
where
Octs: IntoBuilder,
Expand Down Expand Up @@ -592,11 +596,13 @@ pub struct CharStrBuilder<Builder>(Builder);

impl<Builder: EmptyBuilder> CharStrBuilder<Builder> {
/// Creates a new empty builder with default capacity.
#[must_use]
pub fn new() -> Self {
CharStrBuilder(Builder::empty())
}

/// Creates a new empty builder with the given capacity.
#[must_use]
pub fn with_capacity(capacity: usize) -> Self {
CharStrBuilder(Builder::with_capacity(capacity))
}
Expand Down Expand Up @@ -627,11 +633,13 @@ impl<Builder: OctetsBuilder + AsRef<[u8]>> CharStrBuilder<Builder> {
#[cfg(feature = "std")]
impl CharStrBuilder<Vec<u8>> {
/// Creates a new empty characater string builder atop an octets vec.
#[must_use]
pub fn new_vec() -> Self {
Self::new()
}

/// Creates a new empty builder atop an octets vec with a given capacity.
#[must_use]
pub fn vec_with_capacity(capacity: usize) -> Self {
Self::with_capacity(capacity)
}
Expand Down
32 changes: 32 additions & 0 deletions src/base/header.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ impl Header {
/// The new header has all fields as either zero or false. Thus, the
/// opcode will be [`Opcode::Query`] and the response code will be
/// [`Rcode::NoError`].
#[must_use]
pub fn new() -> Self {
Self::default()
}
Expand All @@ -83,6 +84,7 @@ impl Header {
/// # Panics
///
/// This function panics if the slice is less than four octets long.
#[must_use]
pub fn for_message_slice(s: &[u8]) -> &Header {
assert!(s.len() >= mem::size_of::<Header>());
unsafe { &*(s.as_ptr() as *const Header) }
Expand All @@ -99,6 +101,7 @@ impl Header {
}

/// Returns a reference to the underlying octets slice.
#[must_use]
pub fn as_slice(&self) -> &[u8] {
&self.inner
}
Expand All @@ -122,6 +125,7 @@ impl Header {
)]
#[cfg_attr(not(feature = "std"), doc = "`set_random_id`")]
/// can be used for this purpose.
#[must_use]
pub fn id(self) -> u16 {
u16::from_be_bytes(self.inner[..2].try_into().unwrap())
}
Expand All @@ -138,6 +142,7 @@ impl Header {
}

/// Returns whether the [QR](Flags::qr) bit is set.
#[must_use]
pub fn qr(self) -> bool {
self.get_bit(2, 7)
}
Expand All @@ -153,6 +158,7 @@ impl Header {
/// the [`Opcode`] type for more information on the possible values and
/// their meaning. Normal queries have the variant [`Opcode::Query`]
/// which is also the default value when creating a new header.
#[must_use]
pub fn opcode(self) -> Opcode {
Opcode::from_int((self.inner[2] >> 3) & 0x0F)
}
Expand All @@ -168,6 +174,7 @@ impl Header {
/// in the header. The returned [`Flags`] type can be useful when you're
/// working with all flags, rather than a single one, which can be easily
/// obtained from the header directly.
#[must_use]
pub fn flags(self) -> Flags {
Flags {
qr: self.qr(),
Expand All @@ -192,6 +199,7 @@ impl Header {
}

/// Returns whether the [AA](Flags::aa) bit is set.
#[must_use]
pub fn aa(self) -> bool {
self.get_bit(2, 2)
}
Expand All @@ -202,6 +210,7 @@ impl Header {
}

/// Returns whether the [TC](Flags::tc) bit is set.
#[must_use]
pub fn tc(self) -> bool {
self.get_bit(2, 1)
}
Expand All @@ -212,6 +221,7 @@ impl Header {
}

/// Returns whether the [RD](Flags::rd) bit is set.
#[must_use]
pub fn rd(self) -> bool {
self.get_bit(2, 0)
}
Expand All @@ -222,6 +232,7 @@ impl Header {
}

/// Returns whether the [RA](Flags::ra) bit is set.
#[must_use]
pub fn ra(self) -> bool {
self.get_bit(3, 7)
}
Expand All @@ -234,6 +245,7 @@ impl Header {
/// Returns whether the reserved bit is set.
///
/// This bit must be `false` in all queries and responses.
#[must_use]
pub fn z(self) -> bool {
self.get_bit(3, 6)
}
Expand All @@ -244,6 +256,7 @@ impl Header {
}

/// Returns whether the [AD](Flags::ad) bit is set.
#[must_use]
pub fn ad(self) -> bool {
self.get_bit(3, 5)
}
Expand All @@ -254,6 +267,7 @@ impl Header {
}

/// Returns whether the [CD](Flags::cd) bit is set.
#[must_use]
pub fn cd(self) -> bool {
self.get_bit(3, 4)
}
Expand All @@ -270,6 +284,7 @@ impl Header {
/// possible values and their meaning.
///
/// [`Rcode`]: ../../iana/rcode/enum.Rcode.html
#[must_use]
pub fn rcode(self) -> Rcode {
Rcode::from_int(self.inner[3] & 0x0F)
}
Expand Down Expand Up @@ -368,6 +383,7 @@ impl Flags {
/// Creates new flags.
///
/// All flags will be unset.
#[must_use]
pub fn new() -> Self {
Self::default()
}
Expand Down Expand Up @@ -473,6 +489,7 @@ pub struct HeaderCounts {
///
impl HeaderCounts {
/// Creates a new value with all counters set to zero.
#[must_use]
pub fn new() -> Self {
Self::default()
}
Expand All @@ -485,6 +502,7 @@ impl HeaderCounts {
/// # Panics
///
/// This function panics if the octets slice is shorter than 24 octets.
#[must_use]
pub fn for_message_slice(message: &[u8]) -> &Self {
assert!(message.len() >= mem::size_of::<HeaderSection>());
unsafe {
Expand All @@ -510,6 +528,7 @@ impl HeaderCounts {
}

/// Returns a reference to the raw octets slice of the header counts.
#[must_use]
pub fn as_slice(&self) -> &[u8] {
&self.inner
}
Expand All @@ -534,6 +553,7 @@ impl HeaderCounts {
///
/// This field contains the number of questions in the first
/// section of the message, normally the question section.
#[must_use]
pub fn qdcount(self) -> u16 {
self.get_u16(0)
}
Expand Down Expand Up @@ -572,6 +592,7 @@ impl HeaderCounts {
///
/// This field contains the number of resource records in the second
/// section of the message, normally the answer section.
#[must_use]
pub fn ancount(self) -> u16 {
self.get_u16(2)
}
Expand Down Expand Up @@ -610,6 +631,7 @@ impl HeaderCounts {
///
/// This field contains the number of resource records in the third
/// section of the message, normally the authority section.
#[must_use]
pub fn nscount(self) -> u16 {
self.get_u16(4)
}
Expand Down Expand Up @@ -648,6 +670,7 @@ impl HeaderCounts {
///
/// This field contains the number of resource records in the fourth
/// section of the message, normally the additional section.
#[must_use]
pub fn arcount(self) -> u16 {
self.get_u16(6)
}
Expand Down Expand Up @@ -688,6 +711,7 @@ impl HeaderCounts {
///
/// This is the same as the `qdcount()`. It is used in UPDATE queries
/// where the first section is the zone section.
#[must_use]
pub fn zocount(self) -> u16 {
self.qdcount()
}
Expand All @@ -701,6 +725,7 @@ impl HeaderCounts {
///
/// This is the same as the `ancount()`. It is used in UPDATE queries
/// where the first section is the prerequisite section.
#[must_use]
pub fn prcount(self) -> u16 {
self.ancount()
}
Expand All @@ -714,6 +739,7 @@ impl HeaderCounts {
///
/// This is the same as the `nscount()`. It is used in UPDATE queries
/// where the first section is the update section.
#[must_use]
pub fn upcount(self) -> u16 {
self.nscount()
}
Expand All @@ -727,6 +753,7 @@ impl HeaderCounts {
///
/// This is the same as the `arcount()`. It is used in UPDATE queries
/// where the first section is the additional section.
#[must_use]
pub fn adcount(self) -> u16 {
self.arcount()
}
Expand Down Expand Up @@ -773,6 +800,7 @@ impl HeaderSection {
///
/// The value will have all header and header counts fields set to zero
/// or false.
#[must_use]
pub fn new() -> Self {
Self::default()
}
Expand All @@ -782,6 +810,7 @@ impl HeaderSection {
/// # Panics
///
/// This function panics if the octets slice is shorter than 12 octets.
#[must_use]
pub fn for_message_slice(s: &[u8]) -> &HeaderSection {
assert!(s.len() >= mem::size_of::<HeaderSection>());
unsafe { &*(s.as_ptr() as *const HeaderSection) }
Expand All @@ -798,6 +827,7 @@ impl HeaderSection {
}

/// Returns a reference to the underlying octets slice.
#[must_use]
pub fn as_slice(&self) -> &[u8] {
&self.inner
}
Expand All @@ -807,6 +837,7 @@ impl HeaderSection {
///
impl HeaderSection {
/// Returns a reference to the header.
#[must_use]
pub fn header(&self) -> &Header {
Header::for_message_slice(&self.inner)
}
Expand All @@ -817,6 +848,7 @@ impl HeaderSection {
}

/// Returns a reference to the header counts.
#[must_use]
pub fn counts(&self) -> &HeaderCounts {
HeaderCounts::for_message_slice(&self.inner)
}
Expand Down
7 changes: 7 additions & 0 deletions src/base/iana/macros.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ macro_rules! int_enum {

impl $ianatype {
/// Returns a value from its raw integer value.
#[must_use]
pub const fn from_int(value: $inttype) -> Self {
match value {
$( $value => $ianatype::$variant ),*,
Expand All @@ -30,6 +31,7 @@ macro_rules! int_enum {
}

/// Returns the raw integer value for a value.
#[must_use]
pub const fn to_int(self) -> $inttype {
match self {
$( $ianatype::$variant => $value ),*,
Expand All @@ -38,6 +40,7 @@ macro_rules! int_enum {
}

/// Returns a value from a well-defined mnemonic.
#[must_use]
pub fn from_mnemonic(m: &[u8]) -> Option<Self> {
$(
if m.eq_ignore_ascii_case($mnemonic) {
Expand All @@ -51,6 +54,7 @@ macro_rules! int_enum {
///
/// This will also return a mnemonic if a well-defined variant
/// is hidden in a `Int` variant.
#[must_use]
pub const fn to_mnemonic(self) -> Option<&'static [u8]> {
match self {
$( $ianatype::$variant => Some($mnemonic) ),*,
Expand Down Expand Up @@ -224,6 +228,7 @@ macro_rules! int_enum_str_mnemonics_only {
macro_rules! int_enum_str_decimal {
($ianatype:ident, $inttype:ident) => {
impl $ianatype {
#[must_use]
pub fn from_bytes(bytes: &[u8]) -> Option<Self> {
core::str::from_utf8(bytes)
.ok()
Expand Down Expand Up @@ -284,6 +289,7 @@ macro_rules! int_enum_str_decimal {
macro_rules! int_enum_str_with_decimal {
($ianatype:ident, $inttype:ident, $error:expr) => {
impl $ianatype {
#[must_use]
pub fn from_bytes(bytes: &[u8]) -> Option<Self> {
$ianatype::from_mnemonic(bytes).or_else(|| {
core::str::from_utf8(bytes)
Expand Down Expand Up @@ -379,6 +385,7 @@ macro_rules! int_enum_str_with_prefix {
($ianatype:ident, $str_prefix:expr, $u8_prefix:expr, $inttype:ident,
$error:expr) => {
impl $ianatype {
#[must_use]
pub fn from_bytes(bytes: &[u8]) -> Option<Self> {
$ianatype::from_mnemonic(bytes).or_else(|| {
if bytes.len() <= $u8_prefix.len() {
Expand Down
Loading

0 comments on commit 98669b2

Please sign in to comment.