Skip to content

Commit

Permalink
Merge pull request serde-rs#82 from nham/improve_bigint_docs
Browse files Browse the repository at this point in the history 
Improve bigint docs.
  • Loading branch information
@alexcrichton
alexcrichton committed Apr 15, 2015
2 parents 44dfed3 + 82aa7c7 commit eeeaaf2
Showing 1 changed file with 59 additions and 23 deletions.
82 changes: 59 additions & 23 deletions src/bigint.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

//! A Big integer (signed version: `BigInt`, unsigned version: `BigUint`).
//!
//! A `BigUint` is represented as an array of `BigDigit`s.
//! A `BigUint` is represented as a vector of `BigDigit`s.
//! A `BigInt` is a combination of `BigUint` and `Sign`.
//!
//! Common numerical operations are overloaded, so we can treat them
Expand Down Expand Up @@ -938,14 +938,14 @@ impl BigUint {
/// ```
/// use num::bigint::BigUint;
///
/// assert_eq!(BigUint::from_bytes_be("A".as_bytes()),
/// BigUint::parse_bytes("65".as_bytes(), 10).unwrap());
/// assert_eq!(BigUint::from_bytes_be("AA".as_bytes()),
/// BigUint::parse_bytes("16705".as_bytes(), 10).unwrap());
/// assert_eq!(BigUint::from_bytes_be("AB".as_bytes()),
/// BigUint::parse_bytes("16706".as_bytes(), 10).unwrap());
/// assert_eq!(BigUint::from_bytes_be("Hello world!".as_bytes()),
/// BigUint::parse_bytes("22405534230753963835153736737".as_bytes(), 10).unwrap());
/// assert_eq!(BigUint::from_bytes_be(b"A"),
/// BigUint::parse_bytes(b"65", 10).unwrap());
/// assert_eq!(BigUint::from_bytes_be(b"AA"),
/// BigUint::parse_bytes(b"16705", 10).unwrap());
/// assert_eq!(BigUint::from_bytes_be(b"AB"),
/// BigUint::parse_bytes(b"16706", 10).unwrap());
/// assert_eq!(BigUint::from_bytes_be(b"Hello world!"),
/// BigUint::parse_bytes(b"22405534230753963835153736737", 10).unwrap());
/// ```
#[inline]
pub fn from_bytes_be(bytes: &[u8]) -> BigUint {
Expand All @@ -967,6 +967,15 @@ impl BigUint {
}

/// Returns the byte representation of the `BigUint` in little-endian byte order.
///
/// # Examples
///
/// ```
/// use num::bigint::BigUint;
///
/// let i = BigUint::parse_bytes(b"1125", 10).unwrap();
/// assert_eq!(i.to_bytes_le(), vec![101, 4]);
/// ```
#[inline]
pub fn to_bytes_le(&self) -> Vec<u8> {
let mut result = Vec::new();
Expand All @@ -991,6 +1000,15 @@ impl BigUint {
}

/// Returns the byte representation of the `BigUint` in big-endian byte order.
///
/// # Examples
///
/// ```
/// use num::bigint::BigUint;
///
/// let i = BigUint::parse_bytes(b"1125", 10).unwrap();
/// assert_eq!(i.to_bytes_be(), vec![4, 101]);
/// ```
#[inline]
pub fn to_bytes_be(&self) -> Vec<u8> {
let mut v = self.to_bytes_le();
Expand All @@ -1005,9 +1023,9 @@ impl BigUint {
/// ```
/// use num::bigint::{BigUint, ToBigUint};
///
/// assert_eq!(BigUint::parse_bytes("1234".as_bytes(), 10), ToBigUint::to_biguint(&1234));
/// assert_eq!(BigUint::parse_bytes("ABCD".as_bytes(), 16), ToBigUint::to_biguint(&0xABCD));
/// assert_eq!(BigUint::parse_bytes("G".as_bytes(), 16), None);
/// assert_eq!(BigUint::parse_bytes(b"1234", 10), ToBigUint::to_biguint(&1234));
/// assert_eq!(BigUint::parse_bytes(b"ABCD", 16), ToBigUint::to_biguint(&0xABCD));
/// assert_eq!(BigUint::parse_bytes(b"G", 16), None);
/// ```
#[inline]
pub fn parse_bytes(buf: &[u8], radix: u32) -> Option<BigUint> {
Expand Down Expand Up @@ -1713,14 +1731,14 @@ impl BigInt {
/// ```
/// use num::bigint::{BigInt, Sign};
///
/// assert_eq!(BigInt::from_bytes_be(Sign::Plus, "A".as_bytes()),
/// BigInt::parse_bytes("65".as_bytes(), 10).unwrap());
/// assert_eq!(BigInt::from_bytes_be(Sign::Plus, "AA".as_bytes()),
/// BigInt::parse_bytes("16705".as_bytes(), 10).unwrap());
/// assert_eq!(BigInt::from_bytes_be(Sign::Plus, "AB".as_bytes()),
/// BigInt::parse_bytes("16706".as_bytes(), 10).unwrap());
/// assert_eq!(BigInt::from_bytes_be(Sign::Plus, "Hello world!".as_bytes()),
/// BigInt::parse_bytes("22405534230753963835153736737".as_bytes(), 10).unwrap());
/// assert_eq!(BigInt::from_bytes_be(Sign::Plus, b"A"),
/// BigInt::parse_bytes(b"65", 10).unwrap());
/// assert_eq!(BigInt::from_bytes_be(Sign::Plus, b"AA"),
/// BigInt::parse_bytes(b"16705", 10).unwrap());
/// assert_eq!(BigInt::from_bytes_be(Sign::Plus, b"AB"),
/// BigInt::parse_bytes(b"16706", 10).unwrap());
/// assert_eq!(BigInt::from_bytes_be(Sign::Plus, b"Hello world!"),
/// BigInt::parse_bytes(b"22405534230753963835153736737", 10).unwrap());
/// ```
#[inline]
pub fn from_bytes_be(sign: Sign, bytes: &[u8]) -> BigInt {
Expand All @@ -1736,12 +1754,30 @@ impl BigInt {
}

/// Returns the sign and the byte representation of the `BigInt` in little-endian byte order.
///
/// # Examples
///
/// ```
/// use num::bigint::{ToBigInt, Sign};
///
/// let i = -1125.to_bigint().unwrap();
/// assert_eq!(i.to_bytes_le(), (Sign::Minus, vec![101, 4]));
/// ```
#[inline]
pub fn to_bytes_le(&self) -> (Sign, Vec<u8>) {
(self.sign, self.data.to_bytes_le())
}

/// Returns the sign and the byte representation of the `BigInt` in big-endian byte order.
///
/// # Examples
///
/// ```
/// use num::bigint::{ToBigInt, Sign};
///
/// let i = -1125.to_bigint().unwrap();
/// assert_eq!(i.to_bytes_be(), (Sign::Minus, vec![4, 101]));
/// ```
#[inline]
pub fn to_bytes_be(&self) -> (Sign, Vec<u8>) {
(self.sign, self.data.to_bytes_be())
Expand All @@ -1754,9 +1790,9 @@ impl BigInt {
/// ```
/// use num::bigint::{BigInt, ToBigInt};
///
/// assert_eq!(BigInt::parse_bytes("1234".as_bytes(), 10), ToBigInt::to_bigint(&1234));
/// assert_eq!(BigInt::parse_bytes("ABCD".as_bytes(), 16), ToBigInt::to_bigint(&0xABCD));
/// assert_eq!(BigInt::parse_bytes("G".as_bytes(), 16), None);
/// assert_eq!(BigInt::parse_bytes(b"1234", 10), ToBigInt::to_bigint(&1234));
/// assert_eq!(BigInt::parse_bytes(b"ABCD", 16), ToBigInt::to_bigint(&0xABCD));
/// assert_eq!(BigInt::parse_bytes(b"G", 16), None);
/// ```
#[inline]
pub fn parse_bytes(buf: &[u8], radix: u32) -> Option<BigInt> {
Expand Down

0 comments on commit eeeaaf2

Please sign in to comment.