Merge rust-bitcoin/rust-secp256k1#399: Clarified conversions between `Parity` and integers

705c9cfbc1 Clarified conversions between `Parity` and integers (Martin Habovstiak)

Pull request description:

  This was discussed in https://github.com/rust-bitcoin/rust-secp256k1/pull/390#issuecomment-1033018430

ACKs for top commit:
  apoelstra:
    ACK 705c9cfbc1

Tree-SHA512: 3ba2ec566099c3c6d1c6f830e4959312b818b8766d924e3d995e6b23bd196ab747cc03d46f494ef451569188b0163f53e3236cacd20bfae9118ee76bcdbc9c02
This commit is contained in:
Andrew Poelstra 2022-02-09 18:36:09 +00:00
commit 8bf29271de
No known key found for this signature in database
GPG Key ID: C588D63CE41B97C1
1 changed files with 20 additions and 4 deletions

View File

@ -1201,22 +1201,32 @@ pub enum Parity {
} }
impl Parity { impl Parity {
/// Converts parity into a integer (byte) value. /// Converts parity into an integer (byte) value.
///
/// This returns `0` for even parity and `1` for odd parity.
pub fn to_u8(self) -> u8 { pub fn to_u8(self) -> u8 {
self as u8 self as u8
} }
/// Converts parity into a integer value. /// Converts parity into an integer value.
///
/// This returns `0` for even parity and `1` for odd parity.
pub fn to_i32(self) -> i32 { pub fn to_i32(self) -> i32 {
self as i32 self as i32
} }
/// Constructs a [`Parity`] from a byte. /// Constructs a [`Parity`] from a byte.
///
/// The only allowed values are `0` meaning even parity and `1` meaning odd.
/// Other values result in error being returned.
pub fn from_u8(parity: u8) -> Result<Parity, Error> { pub fn from_u8(parity: u8) -> Result<Parity, Error> {
Parity::from_i32(parity as i32) Parity::from_i32(parity.into())
} }
/// Constructs a [`Parity`] from a signed integer. /// Constructs a [`Parity`] from a signed integer.
///
/// The only allowed values are `0` meaning even parity and `1` meaning odd.
/// Other values result in error being returned.
pub fn from_i32(parity: i32) -> Result<Parity, Error> { pub fn from_i32(parity: i32) -> Result<Parity, Error> {
match parity { match parity {
0 => Ok(Parity::Even), 0 => Ok(Parity::Even),
@ -1228,7 +1238,9 @@ impl Parity {
impl From<i32> for Parity { impl From<i32> for Parity {
/// Please note, this method is deprecated and will be removed in an upcoming release, it /// Please note, this method is deprecated and will be removed in an upcoming release, it
/// is not equivalent to `from_u32()`, it is better to use `Parity::from_u32`. /// is **not** equivalent to `from_u32()`, it is better to use `Parity::from_u32`.
///
/// This method returns same parity as the parity of input integer.
fn from(parity: i32) -> Parity { fn from(parity: i32) -> Parity {
if parity % 2 == 0 { if parity % 2 == 0 {
Parity::Even Parity::Even
@ -1238,12 +1250,14 @@ impl From<i32> for Parity {
} }
} }
/// The conversion returns `0` for even parity and `1` for odd.
impl From<Parity> for i32 { impl From<Parity> for i32 {
fn from(parity: Parity) -> i32 { fn from(parity: Parity) -> i32 {
parity.to_i32() parity.to_i32()
} }
} }
/// Returns even parity if the operands are equal, odd otherwise.
impl BitXor for Parity { impl BitXor for Parity {
type Output = Parity; type Output = Parity;
@ -1257,6 +1271,7 @@ impl BitXor for Parity {
} }
} }
/// The parity is serialized as `i32` - `0` for even, `1` for odd.
#[cfg(feature = "serde")] #[cfg(feature = "serde")]
#[cfg_attr(docsrs, doc(cfg(feature = "serde")))] #[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
impl ::serde::Serialize for Parity { impl ::serde::Serialize for Parity {
@ -1265,6 +1280,7 @@ impl ::serde::Serialize for Parity {
} }
} }
/// The parity is deserialized as `i32` - `0` for even, `1` for odd.
#[cfg(feature = "serde")] #[cfg(feature = "serde")]
#[cfg_attr(docsrs, doc(cfg(feature = "serde")))] #[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
impl<'de> ::serde::Deserialize<'de> for Parity { impl<'de> ::serde::Deserialize<'de> for Parity {