From 578ea85a3e224784298312dcadb98d5aac24c044 Mon Sep 17 00:00:00 2001 From: mertcandav Date: Wed, 23 Oct 2024 14:24:51 +0300 Subject: [PATCH] std/math/big: improve documentation of the Int --- std/math/big/int.jule | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/std/math/big/int.jule b/std/math/big/int.jule index 7397fc26..b022e7ea 100644 --- a/std/math/big/int.jule +++ b/std/math/big/int.jule @@ -7,7 +7,27 @@ use "std/unsafe" static mut intZero = Int{} static mut intOne = Int{abs: wordOne} -// Arbitrary big integer. +// An Int represents a signed multi-precision integer. +// The zero value for an Int represents the value 0. +// +// Copying is completely safe and there is no additional allocation cost. +// A common buffer is used within the scope of interior mutability. +// The value returned as a result of any calculation must be independent of the +// parameters taken or must not change it. Therefore, even a simple addition or +// subtraction operation can realize a new internal allocation. +// Some methods may continue to use common allocation without any changes +// if possible, but this is not a guarantee. This implementation cares adhering to +// Jule's mechanics, such as immutability, and keeping side effects on common buffers +// as minimal as possible. If more control over common allocations is required at +// the expense of ignoring that points, this implementation may not be a good choice. +// +// Note that methods may leak the Int's value through timing side-channels. +// Because of this and because of the scope and complexity of the +// implementation, Int is not well-suited to implement cryptographic operations. +// The standard library avoids exposing non-trivial Int methods to +// attacker-controlled inputs and the determination of whether a bug in std/math/big +// is considered a security vulnerability might depend on the impact on the +// standard library. struct Int { mut abs: []Word mut neg: bool