builtin: document all functions in float.v (#7904)

pull/7912/head
Larpon 2021-01-05 23:01:10 +01:00 committed by GitHub
parent 5c4c4354b1
commit e219f954d8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 40 additions and 10 deletions

View File

@ -5,8 +5,11 @@ module builtin
import strconv import strconv
#include <float.h> #include <float.h>
// ----- f64 to string functions ----- /*
// str return a f64 as string in suitable notation -----------------------------------
----- f64 to string functions -----
*/
// str return a `f64` as `string` in suitable notation.
[inline] [inline]
pub fn (x f64) str() string { pub fn (x f64) str() string {
abs_x := f64_abs(x) abs_x := f64_abs(x)
@ -17,12 +20,14 @@ pub fn (x f64) str() string {
} }
} }
// str returns the value of the `any_float` as a `string`.
[inline] [inline]
pub fn (d any_float) str() string { pub fn (d any_float) str() string {
return f64(d).str() return f64(d).str()
} }
// return a string of the input f64 in scientific notation with digit_num deciamals displayed, max 17 digits // strsci returns the `f64` as a `string` in scientific notation with `digit_num` deciamals displayed, max 17 digits.
// Example: assert f64(1.234).strsci(3) == '1.234e+00'
[inline] [inline]
pub fn (x f64) strsci(digit_num int) string { pub fn (x f64) strsci(digit_num int) string {
mut n_digit := digit_num mut n_digit := digit_num
@ -34,14 +39,18 @@ pub fn (x f64) strsci(digit_num int) string {
return strconv.f64_to_str(x, n_digit) return strconv.f64_to_str(x, n_digit)
} }
// return a decimal notation of the input f64 // strlong returns a decimal notation of the `f64` as a `string`.
// Example: assert f64(1.23456).strlong() == '1.23456'
[inline] [inline]
pub fn (x f64) strlong() string { pub fn (x f64) strlong() string {
return strconv.f64_to_str_l(x) return strconv.f64_to_str_l(x)
} }
// ----- f32 to string functions ----- /*
// str return a f32 as string in suitable notation -----------------------------------
----- f32 to string functions -----
*/
// str returns a `f32` as `string` in suitable notation.
[inline] [inline]
pub fn (x f32) str() string { pub fn (x f32) str() string {
abs_x := f32_abs(x) abs_x := f32_abs(x)
@ -52,7 +61,8 @@ pub fn (x f32) str() string {
} }
} }
// return a string of the input f32 in scientific notation with digit_num deciamals displayed, max 8 digits // strsci returns the `f32` as a `string` in scientific notation with `digit_num` deciamals displayed, max 8 digits.
// Example: assert f32(1.234).strsci(3) == '1.234e+00'
[inline] [inline]
pub fn (x f32) strsci(digit_num int) string { pub fn (x f32) strsci(digit_num int) string {
mut n_digit := digit_num mut n_digit := digit_num
@ -64,13 +74,18 @@ pub fn (x f32) strsci(digit_num int) string {
return strconv.f32_to_str(x, n_digit) return strconv.f32_to_str(x, n_digit)
} }
// return a decimal notation of the input f32 // strlong returns a decimal notation of the `f32` as a `string`.
[inline] [inline]
pub fn (x f32) strlong() string { pub fn (x f32) strlong() string {
return strconv.f32_to_str_l(x) return strconv.f32_to_str_l(x)
} }
// ----- C functions ----- /*
-----------------------
----- C functions -----
*/
// f32_abs returns the absolute value of `a` as a `f32` value.
// Example: assert f32_abs(-2.0) == 2.0
[inline] [inline]
pub fn f32_abs(a f32) f32 { pub fn f32_abs(a f32) f32 {
return if a < 0 { return if a < 0 {
@ -80,6 +95,8 @@ pub fn f32_abs(a f32) f32 {
} }
} }
// f64_abs returns the absolute value of `a` as a `f64` value.
// Example: assert f64_abs(-2.0) == f64(2.0)
[inline] [inline]
fn f64_abs(a f64) f64 { fn f64_abs(a f64) f64 {
return if a < 0 { return if a < 0 {
@ -89,7 +106,8 @@ fn f64_abs(a f64) f64 {
} }
} }
// f32_max returns the largest `f32` of input `a` and `b`.
// Example: assert f32_max(2.0,3.0) == 3.0
[inline] [inline]
pub fn f32_max(a f32, b f32) f32 { pub fn f32_max(a f32, b f32) f32 {
return if a > b { return if a > b {
@ -99,6 +117,8 @@ pub fn f32_max(a f32, b f32) f32 {
} }
} }
// f32_min returns the smallest `f32` of input `a` and `b`.
// Example: assert f32_min(2.0,3.0) == 2.0
[inline] [inline]
pub fn f32_min(a f32, b f32) f32 { pub fn f32_min(a f32, b f32) f32 {
return if a < b { return if a < b {
@ -108,6 +128,8 @@ pub fn f32_min(a f32, b f32) f32 {
} }
} }
// f64_max returns the largest `f64` of input `a` and `b`.
// Example: assert f64_max(2.0,3.0) == 3.0
[inline] [inline]
pub fn f64_max(a f64, b f64) f64 { pub fn f64_max(a f64, b f64) f64 {
return if a > b { return if a > b {
@ -117,6 +139,8 @@ pub fn f64_max(a f64, b f64) f64 {
} }
} }
// f64_min returns the smallest `f64` of input `a` and `b`.
// Example: assert f64_min(2.0,3.0) == 2.0
[inline] [inline]
fn f64_min(a f64, b f64) f64 { fn f64_min(a f64, b f64) f64 {
return if a < b { return if a < b {
@ -126,6 +150,9 @@ fn f64_min(a f64, b f64) f64 {
} }
} }
// eq_epsilon returns true if the `f32` is equal to input `b`.
// using an epsilon of typically 1E-5 or higher (backend/compiler dependent).
// Example: assert f32(2.0).eq_epsilon(2.0)
[inline] [inline]
pub fn (a f32) eq_epsilon(b f32) bool { pub fn (a f32) eq_epsilon(b f32) bool {
hi := f32_max(f32_abs(a), f32_abs(b)) hi := f32_max(f32_abs(a), f32_abs(b))
@ -137,6 +164,9 @@ pub fn (a f32) eq_epsilon(b f32) bool {
} }
} }
// eq_epsilon returns true if the `f64` is equal to input `b`.
// using an epsilon of typically 1E-9 or higher (backend/compiler dependent).
// Example: assert f64(2.0).eq_epsilon(2.0)
[inline] [inline]
pub fn (a f64) eq_epsilon(b f64) bool { pub fn (a f64) eq_epsilon(b f64) bool {
hi := f64_max(f64_abs(a), f64_abs(b)) hi := f64_max(f64_abs(a), f64_abs(b))