How to use this library? [integer literal is too large]

[MeRahulAhire]

Hi, I've looking to assign a big number to an integer in rust with this lib. The docs doesn't clearly mentions how to initialise it.

Following is my code

use num_bigint::BigInt;
fn main (){
    let int: BigInt  = 99999999999999999999999999999999999999999999999999;
print!("integer is {}", int)
}

but it returns this error

error: integer literal is too large
 --> src\main.rs:3:24
  |
3 |     let int: BigInt  = 99999999999999999999999999999999999999999999999999;
  |                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

error: could not compile `rust` due to previous error

I'm new to rust I wanna know how to use it properly. Can you please help?

[cuviper]

You can't directly write that as a numeric literal because we're not integrated in the language or compiler, but you can parse that number from a string:

    let int: BigInt = "99999999999999999999999999999999999999999999999999"
        .parse()
        .unwrap(); // for unknown input, might want to handle errors better here

[MeRahulAhire]

Do you know any resource/guide that could help me to understand doing arithmetic operations like add, sub, mul, etc with big numbers in rust.

I want to know more about this library but there's nothing in README.md.

[cuviper]

I don't know any better resources, and no doubt we could use more documentation if someone has the time and skill for writing that. But generally, once you get over this hurdle of creating big numbers, the rest of the normal Rust operators should work fine. Another difference from primitive integers is that BigInt and BigUint are not Copy-able, so they must be explicitly Cloned (by calling .clone()) to duplicate them. Many operators also work on references so you can avoid excessive clones, like:

let x: BigInt = ...;

// Multiply by reference to create a new `BigInt`, and `x` will still be usable afterward.
let square = &x * &x;

Another tip: for numbers that are initially small enough for a primitive integer type, you can also convert them using the From trait, like BigInt::from(42_i32).

[MeRahulAhire]

Thanks I'll try that 👍🏻

[Rudxain]

I want to help with the docs. Where do I start?

[cuviper]

That's an open-ended question! Find something that's confusing and try to clear it up from your perspective as a newer user, or add documentation that you think is completely absent. For this particular issue, the main documentation on struct BigInt and struct BigUint is very minimal right now, and could at least use some examples of different ways to construct them.

[Rudxain]

Thanks for the advice! But should I add stuff to the READMEs, a new folder named "docs", or should I edit in docs.rs?

If it's in docs.rs, I need to create an account there (I don't have one, currently). And even after I create an account, I don't know where to "post" my edits (it seems similar to a wiki, so maybe the "edit" button only shows up after login?)

[cuviper]

It would be most visible on docs.rs, but the way you do that is by editing the inline doc comments, here in the code.

See https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments
and https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html

[Rudxain]

Thanks again! While reading some more docs, I noticed that cargo test can use doc-comment examples as tests! This, and the fact that cargo doc and docs.rs auto-generate HTML documentation from doc-comments is a blessing. I've fallen in love with a CLI tool, lol.

(The following is a tangent topic) When I first searched my xorsum crate on docs.rs, I didn't find it, so my conjecture that "docs.rs may be automatic, and not a manually edited wiki" was droped from my brain. But I searched it again and found it! It seems like it has finally got out of the queue.

(The following is on-topic again) So if I understood correctly, to edit docs, I just need to open PRs where I edit doc-comments of any rust-num repo (then await approval and possible merge)? It's that easy?! Then I'm going to start right now!

Should I open a monolithic PR? (these usually have big diffs) Or should I open multiple small PRs (1 for each file edited)?

[cuviper]

Note that docs.rs only builds after you publish a new version, and you can see that queue here: https://docs.rs/releases/queue

I just need to open PRs where I edit doc-comments of any rust-num repo (then await approval and possible merge)?

Yes.

Should I open a monolithic PR? (these usually have big diffs) Or should I open multiple small PRs (1 for each file edited)?

Well, I want to caution you that I'm the only active maintainer on rust-num right now, and I don't have a lot of time to spend reviewing here. So while I appreciate your enthusiasm, please don't flood me with changes too quickly. Let's start with a few small areas that you feel will have large impact, and go from there.

[Rudxain]

Ok, understood :)