From 1c48a8d760379788a902491fd856188e3a9ca701 Mon Sep 17 00:00:00 2001 From: Larpon Date: Tue, 26 Apr 2022 17:09:36 +0200 Subject: [PATCH] strconv: add missing doc strings (#14164) --- vlib/strconv/f32_str.c.v | 4 ++-- vlib/strconv/f64_str.c.v | 4 ++-- vlib/strconv/format.v | 1 + vlib/strconv/format_mem.c.v | 11 +++++++---- vlib/strconv/ftoa.c.v | 12 ++++++++++++ vlib/strconv/utilities.c.v | 26 +++++++++++++++++++++++--- vlib/strconv/vprintf.c.v | 12 ++++++++++-- 7 files changed, 57 insertions(+), 13 deletions(-) diff --git a/vlib/strconv/f32_str.c.v b/vlib/strconv/f32_str.c.v index 918eb3377..ac498a47d 100644 --- a/vlib/strconv/f32_str.c.v +++ b/vlib/strconv/f32_str.c.v @@ -322,7 +322,7 @@ fn f32_to_decimal(mant u32, exp u32) Dec32 { // String Functions //============================================================================= -// f32_to_str return a string in scientific notation with max n_digit after the dot +// f32_to_str returns a `string` in scientific notation with max `n_digit` after the dot. pub fn f32_to_str(f f32, n_digit int) string { mut u1 := Uf32{} u1.f = f @@ -349,7 +349,7 @@ pub fn f32_to_str(f f32, n_digit int) string { return d.get_string_32(neg, n_digit, 0) } -// f32_to_str return a string in scientific notation with max n_digit after the dot +// f32_to_str_pad returns a `string` in scientific notation with max `n_digit` after the dot. pub fn f32_to_str_pad(f f32, n_digit int) string { mut u1 := Uf32{} u1.f = f diff --git a/vlib/strconv/f64_str.c.v b/vlib/strconv/f64_str.c.v index 91acdbb13..b9495dc54 100644 --- a/vlib/strconv/f64_str.c.v +++ b/vlib/strconv/f64_str.c.v @@ -331,7 +331,7 @@ fn f64_to_decimal(mant u64, exp u64) Dec64 { // String Functions //============================================================================= -// f64_to_str return a string in scientific notation with max n_digit after the dot +// f64_to_str returns `f` as a `string` in scientific notation with max `n_digit` digits after the dot. pub fn f64_to_str(f f64, n_digit int) string { mut u1 := Uf64{} u1.f = f @@ -356,7 +356,7 @@ pub fn f64_to_str(f f64, n_digit int) string { return d.get_string_64(neg, n_digit, 0) } -// f64_to_str return a string in scientific notation with max n_digit after the dot +// f64_to_str returns `f` as a `string` in scientific notation with max `n_digit` digits after the dot. pub fn f64_to_str_pad(f f64, n_digit int) string { mut u1 := Uf64{} u1.f = f diff --git a/vlib/strconv/format.v b/vlib/strconv/format.v index 39eae1266..f48ad290a 100644 --- a/vlib/strconv/format.v +++ b/vlib/strconv/format.v @@ -89,6 +89,7 @@ pub mut: rm_tail_zero bool // remove the tail zeros from floats } +// format_str returns a `string` formatted according to the options set in `p`. [manualfree] pub fn format_str(s string, p BF_param) string { if p.len0 <= 0 { diff --git a/vlib/strconv/format_mem.c.v b/vlib/strconv/format_mem.c.v index 44c9be8f2..edb215e8f 100644 --- a/vlib/strconv/format_mem.c.v +++ b/vlib/strconv/format_mem.c.v @@ -9,7 +9,7 @@ module strconv import strings -// strings.Builder version of format_str +// format_str_sb is a `strings.Builder` version of `format_str`. pub fn format_str_sb(s string, p BF_param, mut sb strings.Builder) { if p.len0 <= 0 { sb.write_string(s) @@ -40,7 +40,7 @@ const ( digit_pairs = '00102030405060708090011121314151617181910212223242526272829203132333435363738393041424344454647484940515253545556575859506162636465666768696071727374757677787970818283848586878889809192939495969798999' ) -// format_dec_sb format a u64 +// format_dec_sb formats an u64 using a `strings.Builder`. [direct_array_access] pub fn format_dec_sb(d u64, p BF_param, mut res strings.Builder) { mut n_char := dec_digits(d) @@ -135,8 +135,9 @@ pub fn format_dec_sb(d u64, p BF_param, mut res strings.Builder) { return } +// f64_to_str_lnd1 formats a f64 to a `string` with `dec_digit` digits after the dot. [direct_array_access; manualfree] -pub fn f64_to_str_lnd1(f f64, dec_digit int) string { +fn f64_to_str_lnd1(f f64, dec_digit int) string { unsafe { // we add the rounding value s := f64_to_str(f + dec_round[dec_digit], 18) @@ -311,7 +312,7 @@ pub fn f64_to_str_lnd1(f f64, dec_digit int) string { } } -// strings.Builder version of format_fl +// format_fl is a `strings.Builder` version of format_fl. [direct_array_access; manualfree] pub fn format_fl(f f64, p BF_param) string { unsafe { @@ -388,6 +389,7 @@ pub fn format_fl(f f64, p BF_param) string { } } +// format_es returns a f64 as a `string` formatted according to the options set in `p`. [direct_array_access; manualfree] pub fn format_es(f f64, p BF_param) string { unsafe { @@ -458,6 +460,7 @@ pub fn format_es(f f64, p BF_param) string { } } +// remove_tail_zeros strips traling zeros from `s` and return the resulting `string`. [direct_array_access] pub fn remove_tail_zeros(s string) string { unsafe { diff --git a/vlib/strconv/ftoa.c.v b/vlib/strconv/ftoa.c.v index 6efd60942..2cc61edd4 100644 --- a/vlib/strconv/ftoa.c.v +++ b/vlib/strconv/ftoa.c.v @@ -18,21 +18,33 @@ inspired by the Go version here: https://github.com/cespare/ryu/tree/ba56a33f39e3bbbfa409095d0f9ae168a595feea */ +// ftoa_64 returns a string in scientific notation with max 17 digits after the dot. +// +// Example: assert strconv.ftoa_64(123.1234567891011121) == '1.2312345678910111e+02' [inline] pub fn ftoa_64(f f64) string { return f64_to_str(f, 17) } +// ftoa_long_64 returns `f` as a `string` in decimal notation with a maximum of 17 digits after the dot. +// +// Example: assert strconv.f64_to_str_l(123.1234567891011121) == '123.12345678910111' [inline] pub fn ftoa_long_64(f f64) string { return f64_to_str_l(f) } +// ftoa_32 returns a `string` in scientific notation with max 8 digits after the dot. +// +// Example: assert strconv.ftoa_32(34.1234567) == '3.4123455e+01' [inline] pub fn ftoa_32(f f32) string { return f32_to_str(f, 8) } +// ftoa_long_32 returns `f` as a `string` in decimal notation with a maximum of 6 digits after the dot. +// +// Example: assert strconv.ftoa_long_32(34.1234567) == '34.12346' [inline] pub fn ftoa_long_32(f f32) string { return f32_to_str_l(f) diff --git a/vlib/strconv/utilities.c.v b/vlib/strconv/utilities.c.v index 0c2e1ed63..5cdfbf153 100644 --- a/vlib/strconv/utilities.c.v +++ b/vlib/strconv/utilities.c.v @@ -25,7 +25,9 @@ f64 to string with string format */ // TODO: Investigate precision issues -// f32_to_str_l return a string with the f32 converted in a string in decimal notation +// f32_to_str_l returns `f` as a `string` in decimal notation with a maximum of 6 digits after the dot. +// +// Example: assert strconv.f32_to_str_l(34.1234567) == '34.12346' [manualfree] pub fn f32_to_str_l(f f32) string { s := f32_to_str(f, 6) @@ -34,6 +36,10 @@ pub fn f32_to_str_l(f f32) string { return res } +// f32_to_str_l_no_dot returns `f` as a `string` in decimal notation with a maximum of 6 digits after the dot. +// The decimal digits after the dot can be omitted. +// +// Example: assert strconv.f32_to_str_l_no_dot(34.) == '34' [manualfree] pub fn f32_to_str_l_no_dot(f f32) string { s := f32_to_str(f, 6) @@ -42,6 +48,9 @@ pub fn f32_to_str_l_no_dot(f f32) string { return res } +// f64_to_str_l returns `f` as a `string` in decimal notation with a maximum of 18 digits after the dot. +// +// Example: assert strconv.f64_to_str_l(123.1234567891011121) == '123.12345678910111' [manualfree] pub fn f64_to_str_l(f f64) string { s := f64_to_str(f, 18) @@ -50,6 +59,10 @@ pub fn f64_to_str_l(f f64) string { return res } +// f64_to_str_l_no_dot returns `f` as a `string` in decimal notation with a maximum of 18 digits after the dot. +// The decimal digits after the dot can be omitted. +// +// Example: assert strconv.f64_to_str_l_no_dot (34.) == '34' [manualfree] pub fn f64_to_str_l_no_dot(f f64) string { s := f64_to_str(f, 18) @@ -58,7 +71,10 @@ pub fn f64_to_str_l_no_dot(f f64) string { return res } -// f64_to_str_l return a string with the f64 converted in a string in decimal notation +// fxx_to_str_l_parse returns a `string` in decimal notation converted from a +// floating-point `string` in scientific notation. +// +// Example: assert strconv.fxx_to_str_l_parse('34.22e+00') == '34.22' [manualfree] pub fn fxx_to_str_l_parse(s string) string { // check for +inf -inf Nan @@ -181,7 +197,11 @@ pub fn fxx_to_str_l_parse(s string) string { return unsafe { tos(res.data, r_i) } } -// f64_to_str_l return a string with the f64 converted in a string in decimal notation +// fxx_to_str_l_parse_no_dot returns a `string` in decimal notation converted from a +// floating-point `string` in scientific notation. +// The decimal digits after the dot can be omitted. +// +// Example: assert strconv.fxx_to_str_l_parse_no_dot ('34.e+01') == '340' [manualfree] pub fn fxx_to_str_l_parse_no_dot(s string) string { // check for +inf -inf Nan diff --git a/vlib/strconv/vprintf.c.v b/vlib/strconv/vprintf.c.v index 073dc8ee8..ec8d5f078 100644 --- a/vlib/strconv/vprintf.c.v +++ b/vlib/strconv/vprintf.c.v @@ -22,10 +22,18 @@ enum Char_parse_state { reset_params } +// v_printf prints a sprintf-like formated `string` to the terminal. pub fn v_printf(str string, pt ...voidptr) { print(v_sprintf(str, ...pt)) } +// v_sprintf returns a sprintf-like formated `string`. +// +// Example: +// ```v +// x := 3.141516 +// assert strconv.v_sprintf('aaa %G', x) == 'aaa 3.141516' +// ``` [manualfree] pub fn v_sprintf(str string, pt ...voidptr) string { mut res := strings.new_builder(pt.len * 16) @@ -628,7 +636,7 @@ pub fn format_fl_old(f f64, p BF_param) string { } [manualfree] -pub fn format_es_old(f f64, p BF_param) string { +fn format_es_old(f f64, p BF_param) string { unsafe { mut s := '' mut fs := f64_to_str_pad(if f > 0 { f } else { -f }, p.len1) @@ -692,7 +700,7 @@ pub fn format_es_old(f f64, p BF_param) string { } } -pub fn remove_tail_zeros_old(s string) string { +fn remove_tail_zeros_old(s string) string { mut i := 0 mut last_zero_start := -1 mut dot_pos := -1 -- 2.30.2