Skip to content

Commit

Permalink
align docs to spec terminology
Browse files Browse the repository at this point in the history
  • Loading branch information
@KodrAus
KodrAus committed Jul 14, 2023
1 parent e5a3fe4 commit ea40e7f
Show file tree
Hide file tree
Showing 3 changed files with 101 additions and 102 deletions.
79 changes: 28 additions & 51 deletions src/lib.rs
View file
Expand Up @@ -723,120 +723,116 @@ macro_rules! __impl_bitflags {
) => {
#[allow(dead_code, deprecated, unused_attributes)]
impl $PublicBitFlags {
/// Returns an empty set of flags.
/// Get a flags value with all bits unset.
#[inline]
pub const fn empty() -> Self {
$empty
}

/// Returns the set containing all flags.
/// Get a flags value with all known bits set.
#[inline]
pub const fn all() -> Self {
$all
}

/// Returns the raw value of the flags currently stored.
/// Get the underlying bits value.
///
/// The returned value is exactly the bits set in this flags value.
#[inline]
pub const fn bits(&self) -> $T {
let $bits0 = self;
$bits
}

/// Convert from underlying bit representation, unless that
/// representation contains bits that do not correspond to a flag.
/// Convert from a bits value, unless any unset bits are set.
#[inline]
pub const fn from_bits(bits: $T) -> $crate::__private::core::option::Option<Self> {
let $from_bits0 = bits;
$from_bits
}

/// Convert from underlying bit representation, dropping any bits
/// that do not correspond to flags.
/// Convert from a bits value, unsetting any unknown bits.
#[inline]
pub const fn from_bits_truncate(bits: $T) -> Self {
let $from_bits_truncate0 = bits;
$from_bits_truncate
}

/// Convert from underlying bit representation, preserving all
/// bits (even those not corresponding to a defined flag).
/// Convert from a bits value, without altering them in any way.
#[inline]
pub const fn from_bits_retain(bits: $T) -> Self {
let $from_bits_retain0 = bits;
$from_bits_retain
}

/// Get the value for a flag from its stringified name.
/// Get a flags value with the bits of a flag with the given name set.
///
/// Names are _case-sensitive_, so must correspond exactly to
/// the identifier given to the flag.
/// This method will return `None` if `name` is empty or doesn't
/// correspond to any named flag.
#[inline]
pub fn from_name(name: &str) -> $crate::__private::core::option::Option<Self> {
let $from_name0 = name;
$from_name
}

/// Returns `true` if no flags are currently stored.
/// Whether all bits in this flags value are unset.
#[inline]
pub const fn is_empty(&self) -> bool {
let $is_empty0 = self;
$is_empty
}

/// Returns `true` if all flags are currently set.
/// Whether all defined flags are contained in this flags value.
#[inline]
pub const fn is_all(&self) -> bool {
let $is_all0 = self;
$is_all
}

/// Returns `true` if there are flags common to both `self` and `other`.
/// Whether any set bits in a source flags value are also set in a target flags value.
#[inline]
pub const fn intersects(&self, other: Self) -> bool {
let $intersects0 = self;
let $intersects1 = other;
$intersects
}

/// Returns `true` if all of the flags in `other` are contained within `self`.
/// Whether all set bits in a source flags value are also set in a target flags value.
#[inline]
pub const fn contains(&self, other: Self) -> bool {
let $contains0 = self;
let $contains1 = other;
$contains
}

/// Inserts the specified flags in-place.
///
/// This method is equivalent to `union`.
/// The bitwise or (`|`) of the bits in two flags values.
#[inline]
pub fn insert(&mut self, other: Self) {
let $insert0 = self;
let $insert1 = other;
$insert
}

/// Removes the specified flags in-place.
/// The intersection of a source flags value with the complement of a target flags value (`&!`).
///
/// This method is equivalent to `difference`.
/// This method is not equivalent to `self & !other` when `other` has unknown bits set.
/// `remove` won't truncate `other`, but the `!` operator will.
#[inline]
pub fn remove(&mut self, other: Self) {
let $remove0 = self;
let $remove1 = other;
$remove
}

/// Toggles the specified flags in-place.
///
/// This method is equivalent to `symmetric_difference`.
/// The bitwise exclusive-or (`^`) of the bits in two flags values.
#[inline]
pub fn toggle(&mut self, other: Self) {
let $toggle0 = self;
let $toggle1 = other;
$toggle
}

/// Inserts or removes the specified flags depending on the passed value.
/// Call `insert` when `value` is `true` or `remove` when `value` is `false`.
#[inline]
pub fn set(&mut self, other: Self, value: bool) {
let $set0 = self;
Expand All @@ -845,11 +841,7 @@ macro_rules! __impl_bitflags {
$set
}

/// Returns the intersection between the flags in `self` and
/// `other`.
///
/// Calculating `self` bitwise and (`&`) other, including
/// any bits that don't correspond to a defined flag.
/// The bitwise and (`&`) of the bits in two flags values.
#[inline]
#[must_use]
pub const fn intersection(self, other: Self) -> Self {
Expand All @@ -858,10 +850,7 @@ macro_rules! __impl_bitflags {
$intersection
}

/// Returns the union of between the flags in `self` and `other`.
///
/// Calculates `self` bitwise or (`|`) `other`, including
/// any bits that don't correspond to a defined flag.
/// The bitwise or (`|`) of the bits in two flags values.
#[inline]
#[must_use]
pub const fn union(self, other: Self) -> Self {
Expand All @@ -870,15 +859,10 @@ macro_rules! __impl_bitflags {
$union
}

/// Returns the difference between the flags in `self` and `other`.
///
/// Calculates `self` bitwise and (`&!`) the bitwise negation of `other`,
/// including any bits that don't correspond to a defined flag.
/// The intersection of a source flags value with the complement of a target flags value (`&!`).
///
/// This method is _not_ equivalent to `a & !b` when there are bits set that
/// don't correspond to a defined flag. The `!` operator will unset any
/// bits that don't correspond to a flag, so they'll always be unset by `a &! b`,
/// but respected by `a.difference(b)`.
/// This method is not equivalent to `self & !other` when `other` has unknown bits set.
/// `difference` won't truncate `other`, but the `!` operator will.
#[inline]
#[must_use]
pub const fn difference(self, other: Self) -> Self {
Expand All @@ -887,11 +871,7 @@ macro_rules! __impl_bitflags {
$difference
}

/// Returns the symmetric difference between the flags
/// in `self` and `other`.
///
/// Calculates `self` bitwise exclusive or (`^`) `other`,
/// including any bits that don't correspond to a defined flag.
/// The bitwise exclusive-or (`^`) of the bits in two flags values.
#[inline]
#[must_use]
pub const fn symmetric_difference(self, other: Self) -> Self {
Expand All @@ -900,10 +880,7 @@ macro_rules! __impl_bitflags {
$symmetric_difference
}

/// Returns the complement of this set of flags.
///
/// Calculates the bitwise negation (`!`) of `self`,
/// **unsetting** any bits that don't correspond to a defined flag.
/// The bitwise negation (`!`) of the bits in a flags value, truncating the result.
#[inline]
#[must_use]
pub const fn complement(self) -> Self {
Expand Down
36 changes: 25 additions & 11 deletions src/public.rs
View file
Expand Up @@ -273,7 +273,10 @@ macro_rules! __impl_public_bitflags {
macro_rules! __impl_public_bitflags_iter {
($BitFlags:ident: $T:ty, $PublicBitFlags:ident) => {
impl $BitFlags {
/// Iterate over enabled flag values.
/// Yield a set of contained flags values.
///
/// Each yielded flags value will correspond to a defined named flag. Any unknown bits
/// will be yielded together as a final flags value.
#[inline]
pub const fn iter(&self) -> $crate::iter::Iter<$PublicBitFlags> {
$crate::iter::Iter::__private_const_new(
Expand All @@ -283,7 +286,10 @@ macro_rules! __impl_public_bitflags_iter {
)
}

/// Iterate over enabled flag values with their stringified names.
/// Yield a set of contained named flags values.
///
/// This method is like [`iter`], except only yields bits in contained named flags.
/// Any unknown bits, or bits not corresponding to a contained flag will not be yielded.
#[inline]
pub const fn iter_names(&self) -> $crate::iter::IterNames<$PublicBitFlags> {
$crate::iter::IterNames::__private_const_new(
Expand Down Expand Up @@ -349,15 +355,15 @@ macro_rules! __impl_public_bitflags_ops {
impl $crate::__private::core::ops::BitOr for $PublicBitFlags {
type Output = Self;

/// Returns the union of the two sets of flags.
/// The bitwise or (`|`) of the bits in two flags values.
#[inline]
fn bitor(self, other: $PublicBitFlags) -> Self {
self.union(other)
}
}

impl $crate::__private::core::ops::BitOrAssign for $PublicBitFlags {
/// Adds the set of flags.
/// The bitwise or (`|`) of the bits in two flags values.
#[inline]
fn bitor_assign(&mut self, other: Self) {
self.insert(other);
Expand All @@ -367,15 +373,15 @@ macro_rules! __impl_public_bitflags_ops {
impl $crate::__private::core::ops::BitXor for $PublicBitFlags {
type Output = Self;

/// Returns the left flags, but with all the right flags toggled.
/// The bitwise exclusive-or (`^`) of the bits in two flags values.
#[inline]
fn bitxor(self, other: Self) -> Self {
self.symmetric_difference(other)
}
}

impl $crate::__private::core::ops::BitXorAssign for $PublicBitFlags {
/// Toggles the set of flags.
/// The bitwise exclusive-or (`^`) of the bits in two flags values.
#[inline]
fn bitxor_assign(&mut self, other: Self) {
self.toggle(other);
Expand All @@ -385,15 +391,15 @@ macro_rules! __impl_public_bitflags_ops {
impl $crate::__private::core::ops::BitAnd for $PublicBitFlags {
type Output = Self;

/// Returns the intersection between the two sets of flags.
/// The bitwise and (`&`) of the bits in two flags values.
#[inline]
fn bitand(self, other: Self) -> Self {
self.intersection(other)
}
}

impl $crate::__private::core::ops::BitAndAssign for $PublicBitFlags {
/// Disables all flags disabled in the set.
/// The bitwise and (`&`) of the bits in two flags values.
#[inline]
fn bitand_assign(&mut self, other: Self) {
*self = Self::from_bits_retain(self.bits()).intersection(other);
Expand All @@ -403,15 +409,21 @@ macro_rules! __impl_public_bitflags_ops {
impl $crate::__private::core::ops::Sub for $PublicBitFlags {
type Output = Self;

/// Returns the set difference of the two sets of flags.
/// The intersection of a source flags value with the complement of a target flags value (`&!`).
///
/// This method is not equivalent to `self & !other` when `other` has unknown bits set.
/// `difference` won't truncate `other`, but the `!` operator will.
#[inline]
fn sub(self, other: Self) -> Self {
self.difference(other)
}
}

impl $crate::__private::core::ops::SubAssign for $PublicBitFlags {
/// Disables all flags enabled in the set.
/// The intersection of a source flags value with the complement of a target flags value (`&!`).
///
/// This method is not equivalent to `self & !other` when `other` has unknown bits set.
/// `difference` won't truncate `other`, but the `!` operator will.
#[inline]
fn sub_assign(&mut self, other: Self) {
self.remove(other);
Expand All @@ -421,14 +433,15 @@ macro_rules! __impl_public_bitflags_ops {
impl $crate::__private::core::ops::Not for $PublicBitFlags {
type Output = Self;

/// Returns the complement of this set of flags.
/// The bitwise negation (`!`) of the bits in a flags value, truncating the result.
#[inline]
fn not(self) -> Self {
self.complement()
}
}

impl $crate::__private::core::iter::Extend<$PublicBitFlags> for $PublicBitFlags {
/// The bitwise or (`|`) of the bits in each flags value.
fn extend<T: $crate::__private::core::iter::IntoIterator<Item = Self>>(
&mut self,
iterator: T,
Expand All @@ -440,6 +453,7 @@ macro_rules! __impl_public_bitflags_ops {
}

impl $crate::__private::core::iter::FromIterator<$PublicBitFlags> for $PublicBitFlags {
/// The bitwise or (`|`) of the bits in each flags value.
fn from_iter<T: $crate::__private::core::iter::IntoIterator<Item = Self>>(
iterator: T,
) -> Self {
Expand Down

0 comments on commit ea40e7f

Please sign in to comment.