builtin: document all functions in int.v (#7896)

vlib/builtin/int.v

@@ -43,6 +43,7 @@ pub fn ptr_str(ptr voidptr) string {
 	return tos(buf, vstrlen(buf))
 }
 */
+// ptr_str returns the address of `ptr` as a `string`.
 pub fn ptr_str(ptr voidptr) string {
 	buf1 := u64(ptr).hex()
 	return buf1
@@ -53,8 +54,9 @@ const (
 )
 
 // This implementation is the quickest with gcc -O2
+// str_l returns the string representation of the integer `max`.
 [inline]
-pub fn (nn int) str_l(max int) string {
+fn (nn int) str_l(max int) string {
 	mut n := i64(nn)
 	mut d := 0
 	if n == 0 {
@@ -98,22 +100,32 @@ pub fn (nn int) str_l(max int) string {
 	// return tos(buf + index, (max-index))
 }
 
+// str returns the value of the `i8` as a `string`.
+// Example: assert i8(-2).str() == '-2'
 pub fn (n i8) str() string {
 	return int(n).str_l(5)
 }
 
+// str returns the value of the `i16` as a `string`.
+// Example: assert i16(-20).str() == '-20'
 pub fn (n i16) str() string {
 	return int(n).str_l(7)
 }
 
+// str returns the value of the `u16` as a `string`.
+// Example: assert u16(20).str() == '20'
 pub fn (n u16) str() string {
 	return int(n).str_l(7)
 }
 
+// str returns the value of the `int` as a `string`.
+// Example: assert int(-2020).str() == '-2020'
 pub fn (n int) str() string {
 	return n.str_l(12)
 }
 
+// str returns the value of the `u32` as a `string`.
+// Example: assert u32(20000).str() == '20000'
 pub fn (nn u32) str() string {
 	mut n := nn
 	mut d := u32(0)
@@ -147,11 +159,14 @@ pub fn (nn u32) str() string {
 	// return tos(buf + index, (max-index))
 }
 
+// str returns the value of the `any_int` as a `string`.
 [inline]
 pub fn (n any_int) str() string {
 	return i64(n).str()
 }
 
+// str returns the value of the `i64` as a `string`.
+// Example: assert i64(-200000).str() == '-200000'
 pub fn (nn i64) str() string {
 	mut n := nn
 	mut d := i64(0)
@@ -197,6 +212,8 @@ pub fn (nn i64) str() string {
 	// return tos(buf + index, (max-index))
 }
 
+// str returns the value of the `u64` as a `string`.
+// Example: assert u64(2000000).str() == '2000000'
 pub fn (nn u64) str() string {
 	mut n := nn
 	mut d := u64(0)
@@ -230,6 +247,8 @@ pub fn (nn u64) str() string {
 	// return tos(buf + index, (max-index))
 }
 
+// str returns the value of the `bool` as a `string`.
+// Example: assert (2 > 1).str() == 'true'
 pub fn (b bool) str() string {
 	if b {
 		return 'true'
@@ -247,6 +266,7 @@ pub fn (n int) hex1() string {
 	return tos(hex, count)
 }
 */
+// u64_to_hex converts the number `nn` to a (zero padded if necessary) hexadecimal `string`.
 [inline]
 fn u64_to_hex(nn u64, len byte) string {
 	mut n := nn
@@ -265,6 +285,7 @@ fn u64_to_hex(nn u64, len byte) string {
 	}
 }
 
+// u64_to_hex_no_leading_zeros converts the number `nn` to hexadecimal `string`.
 [inline]
 fn u64_to_hex_no_leading_zeros(nn u64, len byte) string {
 	mut n := nn
@@ -287,6 +308,11 @@ fn u64_to_hex_no_leading_zeros(nn u64, len byte) string {
 	}
 }
 
+// hex returns the value of the `byte` as a hexadecimal `string`.
+// Note that the output is zero padded for values below 16.
+// Example: assert byte(2).hex() == '02'
+// Example: assert byte(15).hex() == '0f'
+// Example: assert byte(255).hex() == 'ff'
 pub fn (nn byte) hex() string {
 	if nn == 0 {
 		return '00'
@@ -294,10 +320,19 @@ pub fn (nn byte) hex() string {
 	return u64_to_hex(nn, 2)
 }
 
+// hex returns the value of the `i8` as a hexadecimal `string`.
+// Note that the output is zero padded for values below 16.
+// Example: assert i8(8).hex() == '08'
+// Example: assert i8(10).hex() == '0a'
+// Example: assert i8(15).hex() == '0f'
 pub fn (nn i8) hex() string {
 	return byte(nn).hex()
 }
 
+// hex returns the value of the `u16` as a hexadecimal `string`.
+// Note that the output is ***not*** zero padded.
+// Example: assert u16(2).hex() == '2'
+// Example: assert u16(200).hex() == 'c8'
 pub fn (nn u16) hex() string {
 	if nn == 0 {
 		return '0'
@@ -305,10 +340,18 @@ pub fn (nn u16) hex() string {
 	return u64_to_hex_no_leading_zeros(nn, 4)
 }
 
+// hex returns the value of the `i16` as a hexadecimal `string`.
+// Note that the output is ***not*** zero padded.
+// Example: assert i16(2).hex() == '2'
+// Example: assert i16(200).hex() == 'c8'
 pub fn (nn i16) hex() string {
 	return u16(nn).hex()
 }
 
+// hex returns the value of the `u32` as a hexadecimal `string`.
+// Note that the output is ***not*** zero padded.
+// Example: assert u32(2).hex() == '2'
+// Example: assert u32(200).hex() == 'c8'
 pub fn (nn u32) hex() string {
 	if nn == 0 {
 		return '0'
@@ -316,14 +359,27 @@ pub fn (nn u32) hex() string {
 	return u64_to_hex_no_leading_zeros(nn, 8)
 }
 
+// hex returns the value of the `int` as a hexadecimal `string`.
+// Note that the output is ***not*** zero padded.
+// Example: assert int(2).hex() == '2'
+// Example: assert int(200).hex() == 'c8'
 pub fn (nn int) hex() string {
 	return u32(nn).hex()
 }
 
+// hex2 returns the value of the `int` as a `0x`-prefixed hexadecimal `string`.
+// Note that the output after `0x` is ***not*** zero padded.
+// Example: assert int(8).hex2() == '0x8'
+// Example: assert int(15).hex2() == '0xf'
+// Example: assert int(18).hex2() == '0x12'
 pub fn (n int) hex2() string {
 	return '0x' + n.hex()
 }
 
+// hex returns the value of the `u64` as a hexadecimal `string`.
+// Note that the output is ***not*** zero padded.
+// Example: assert u64(2).hex() == '2'
+// Example: assert u64(2000).hex() == '7d0'
 pub fn (nn u64) hex() string {
 	if nn == 0 {
 		return '0'
@@ -331,36 +387,56 @@ pub fn (nn u64) hex() string {
 	return u64_to_hex_no_leading_zeros(nn, 16)
 }
 
+// hex returns the value of the `i64` as a hexadecimal `string`.
+// Note that the output is ***not*** zero padded.
+// Example: assert i64(2).hex() == '2'
+// Example: assert i64(-200).hex() == 'ffffffffffffff38'
+// Example: assert i64(2021).hex() == '7e5'
 pub fn (nn i64) hex() string {
 	return u64(nn).hex()
 }
 
+// hex returns the value of the `any_int` as a hexadecimal `string`.
+// Note that the output is ***not*** zero padded.
 pub fn (nn any_int) hex() string {
 	return u64(nn).hex()
 }
 
+// hex returns the value of the `voidptr` as a hexadecimal `string`.
+// Note that the output is ***not*** zero padded.
 pub fn (nn voidptr) str() string {
 	return u64(nn).hex()
 }
 
+// hex returns the value of the `byteptr` as a hexadecimal `string`.
+// Note that the output is ***not*** zero padded.
 pub fn (nn byteptr) str() string {
 	return u64(nn).hex()
 }
 
-// pub fn (nn byte) hex_full() string { return u64_to_hex(nn, 2) }
+/*
-// pub fn (nn i8)  hex_full() string { return u64_to_hex(byte(nn), 2) }
+pub fn (nn byte) hex_full() string { return u64_to_hex(nn, 2) }
-// pub fn (nn u16) hex_full() string { return u64_to_hex(nn, 4) }
+pub fn (nn i8)  hex_full() string { return u64_to_hex(byte(nn), 2) }
-// pub fn (nn i16) hex_full() string { return u64_to_hex(u16(nn), 4) }
+pub fn (nn u16) hex_full() string { return u64_to_hex(nn, 4) }
-// pub fn (nn u32) hex_full() string { return u64_to_hex(nn, 8) }
+pub fn (nn i16) hex_full() string { return u64_to_hex(u16(nn), 4) }
-// pub fn (nn int) hex_full() string { return u64_to_hex(u32(nn), 8) }
+pub fn (nn u32) hex_full() string { return u64_to_hex(nn, 8) }
+pub fn (nn int) hex_full() string { return u64_to_hex(u32(nn), 8) }
+*/
+// hex_full returns the value of the `u64` as a *full* 16-digit hexadecimal `string`.
+// Example: assert u64(2).hex_full() == '0000000000000002'
+// Example: assert u64(255).hex_full() == '00000000000000ff'
 pub fn (nn u64) hex_full() string {
 	return u64_to_hex(nn, 16)
 }
 
-// pub fn (nn i64) hex_full() string { return u64_to_hex(u64(nn), 16) }
+/*
-// pub fn (nn any_int) hex_full() string { return u64_to_hex(nn, 16) }
+pub fn (nn i64) hex_full() string { return u64_to_hex(u64(nn), 16) }
-// pub fn (nn voidptr) hex_full() string { return u64_to_hex(nn, 16) }
+pub fn (nn any_int) hex_full() string { return u64_to_hex(nn, 16) }
-// pub fn (nn byteptr) hex_full() string { return u64_to_hex(nn, 16) }
+pub fn (nn voidptr) hex_full() string { return u64_to_hex(nn, 16) }
+pub fn (nn byteptr) hex_full() string { return u64_to_hex(nn, 16) }
+*/
+// str returns the contents of `byte` as a zero terminated `string`.
+// Example: assert byte(111).str() == 'o'
 pub fn (b byte) str() string {
 	// TODO
 	// return int(b).str_l(7)
@@ -376,9 +452,11 @@ pub fn (b byte) str() string {
 	return str
 }
 
+// TODO make an actual example for the docs: Example: assert byte(0).str_escaped() == `\0` // <- but this fails?
+// str_escaped returns the contents of `byte` as an escaped `string`.
 pub fn (b byte) str_escaped() string {
 	str := match b {
-		0 { '`\\' + '0`' } // Bug is preventing \\0 in a literal
+		0 { '`\\' + '0`' } // TODO BUG is preventing \\0 in a literal
 		7 { '`\\a`' }
 		8 { '`\\b`' }
 		9 { '`\\t`' }