From 5e5d62ed4c4ca3943a6d0f50ca635fa0bb4912dc Mon Sep 17 00:00:00 2001 From: jeffmikels Date: Sun, 9 Jan 2022 09:12:33 -0500 Subject: [PATCH] arrays,docs: remove arrays.zip; improve docs (#13082) --- vlib/arrays/arrays.v | 39 ++++++++++----------------------------- vlib/builtin/README.md | 4 ++++ vlib/builtin/js/builtin.v | 8 +++++--- vlib/sokol/audio/audio.v | 30 +++++++++++++++--------------- 4 files changed, 34 insertions(+), 47 deletions(-) diff --git a/vlib/arrays/arrays.v b/vlib/arrays/arrays.v index d63d08497e..905b6fcce4 100644 --- a/vlib/arrays/arrays.v +++ b/vlib/arrays/arrays.v @@ -6,7 +6,8 @@ module arrays // - merge - combine two sorted arrays and maintain sorted order // - chunk - chunk array to arrays with n elements // - window - get snapshots of the window of the given size sliding along array with the given step, where each snapshot is an array -// - TODO: zip - merge two arrays by interleaving e.g. arrays.zip([1,3,5], [2,4,6]) => [1,2,3,4,5,6] +// - group - merge two arrays by interleaving e.g. arrays.group([1,3,5], [2,4,6]) => [[1,2],[3,4],[5,6]] +// - flatten - reduce dimensionality of array by one. e.g. arrays.flatten([[1,2],[3,4],[5,6]]) => [1,2,3,4,5,6] // min returns the minimum value in the array // Example: arrays.min([1,2,3,0,9]) // => 0 @@ -107,7 +108,11 @@ pub fn merge(a []T, b []T) []T { } // group n arrays into a single array of arrays with n elements -// (an error will be generated if the type annotation is omitted) +// +// This function is analogous to the "zip" function of other languages. +// To fully interleave two arrays, follow this function with a call to `flatten`. +// +// NOTE: An error will be generated if the type annotation is omitted. // Example: arrays.group([1,2,3],[4,5,6]) // => [[1, 4], [2, 5], [3, 6]] pub fn group(lists ...[]T) [][]T { mut length := if lists.len > 0 { lists[0].len } else { 0 } @@ -122,12 +127,12 @@ pub fn group(lists ...[]T) [][]T { mut arr := [][]T{cap: length} // append all combined arrays into the resultant array for ndx in 0 .. length { - mut zipped := []T{cap: lists.len} + mut grouped := []T{cap: lists.len} // combine each list item for the ndx position into one array for list_ndx in 0 .. lists.len { - zipped << lists[list_ndx][ndx] + grouped << lists[list_ndx][ndx] } - arr << zipped + arr << grouped } return arr } @@ -305,30 +310,6 @@ pub fn concat(a []T, b ...T) []T { return m } -// zip returns a new array by interleaving the source arrays. -// -// NOTE: The two arrays do not need to be equal sizes -// Example: arrays.zip([1, 3, 5, 7], [2, 4, 6, 8, 10]) // => [1, 2, 3, 4, 5, 6, 7, 8, 10] -pub fn zip(a []T, b []T) []T { - mut m := []T{cap: a.len + b.len} - mut i := 0 - for i < m.cap { - // short-circuit the rest of the loop as soon as we can - if i >= a.len { - m << b[i..] - break - } - if i >= b.len { - m << a[i..] - break - } - m << a[i] - m << b[i] - i++ - } - return m -} - // returns the smallest element >= val, requires `arr` to be sorted // Example: arrays.lower_bound([2, 4, 6, 8], 3)? // => 4 pub fn lower_bound(arr []T, val T) ?T { diff --git a/vlib/builtin/README.md b/vlib/builtin/README.md index 09af131bd5..df08b80abf 100644 --- a/vlib/builtin/README.md +++ b/vlib/builtin/README.md @@ -4,3 +4,7 @@ It implements the builtin V types `array`, `string`, `map`. It also implements builtin functions like `println`, `eprintln`, `malloc`, `panic`, `print_backtrace`. + +The autogenerated documentation for builtin functions is lacking, +so for these functions, please refer to the +[official V documentation](https://github.com/vlang/v/blob/master/doc/docs.md). diff --git a/vlib/builtin/js/builtin.v b/vlib/builtin/js/builtin.v index d0c7a28c75..843c515d92 100644 --- a/vlib/builtin/js/builtin.v +++ b/vlib/builtin/js/builtin.v @@ -59,12 +59,13 @@ pub fn (o Option) str() string { return 'Option{ error: "$o.err" }' } +// trace_error prints to stderr a string and a backtrace of the error fn trace_error(x string) { eprintln('> ${@FN} | $x') } // error returns a default error instance containing the error given in `message`. -// Example: `if ouch { return error('an error occurred') }` +// Example: if ouch { return error('an error occurred') } [inline] pub fn error(message string) IError { // trace_error(message) @@ -74,7 +75,7 @@ pub fn error(message string) IError { } // error_with_code returns a default error instance containing the given `message` and error `code`. -// `if ouch { return error_with_code('an error occurred', 1) }` +// Example: if ouch { return error_with_code('an error occurred', 1) } [inline] pub fn error_with_code(message string, code int) IError { // trace_error('$message | code: $code') @@ -84,7 +85,8 @@ pub fn error_with_code(message string, code int) IError { } } -// free allows for manually freeing memory allocated at the address `ptr`. no-op on JS backend +// free allows for manually freeing memory allocated at the address `ptr`. +// However, this is a no-op on JS backend [unsafe] pub fn free(ptr voidptr) { _ := ptr diff --git a/vlib/sokol/audio/audio.v b/vlib/sokol/audio/audio.v index 86dfad7fe9..700ff21a55 100644 --- a/vlib/sokol/audio/audio.v +++ b/vlib/sokol/audio/audio.v @@ -97,42 +97,42 @@ fn C.saudio_expect() int fn C.saudio_push(frames &f32, num_frames int) int -// audio.setup - setup sokol-audio +// setup - setup sokol-audio pub fn setup(desc C.saudio_desc) { C.saudio_setup(&desc) } -// audio.shutdown - shutdown sokol-audio +// shutdown - shutdown sokol-audio pub fn shutdown() { C.saudio_shutdown() } -// audio.is_valid - true after setup if audio backend was successfully initialized +// is_valid - true after setup if audio backend was successfully initialized pub fn is_valid() bool { return C.saudio_isvalid() } -// audio.userdata - return the saudio_desc.user_data pointer +// userdata - return the saudio_desc.user_data pointer pub fn user_data() voidptr { return C.saudio_userdata() } -// audio.query - return a copy of the original saudio_desc struct +// query - return a copy of the original saudio_desc struct pub fn query() C.saudio_desc { return C.saudio_query_desc() } -// audio.sample_rate - return the actual sample rate +// sample_rate - return the actual sample rate pub fn sample_rate() int { return C.saudio_sample_rate() } -// audio.buffer_frames - return the actual backend buffer size in number of frames +// buffer_frames - return the actual backend buffer size in number of frames pub fn buffer_frames() int { return C.saudio_buffer_frames() } -// audio.channels - return the actual number of channels +// channels - return the actual number of channels pub fn channels() int { return C.saudio_channels() } @@ -143,17 +143,17 @@ pub fn suspended() bool { return C.saudio_suspended() } -// audio.expect - get current number of frames to fill packet queue; use in combination with audio.push +// expect - get current number of frames to fill packet queue; use in combination with audio.push pub fn expect() int { return C.saudio_expect() } -// audio.push - push sample frames from main thread, returns number of frames actually pushed +// push - push sample frames from main thread, returns number of frames actually pushed pub fn push(frames &f32, num_frames int) int { return C.saudio_push(frames, num_frames) } -// audio.fclamp - helper function to 'clamp' a number to a certain range +// fclamp - helper function to 'clamp' a number to a certain range // Example: realsample := audio.fclamp(sample, -1.0, 1.0) [inline] pub fn fclamp(x f32, flo f32, fhi f32) f32 { @@ -166,9 +166,9 @@ pub fn fclamp(x f32, flo f32, fhi f32) f32 { return x } -// audio.min - helper function to return the smaller of two numbers +// min - helper function to return the smaller of two numbers // -// math.min returns `f32` values, this returns `int` values +// NOTE: math.min returns `f32` values, this returns `int` values // Example: smaller := audio.min(1, 5) // smaller == 1 pub fn min(x int, y int) int { if x < y { @@ -177,9 +177,9 @@ pub fn min(x int, y int) int { return y } -// audio.max - helper function to return the larger of two numbers +// max - helper function to return the larger of two numbers // -// math.max returns `f32` values, this returns `int` values +// NOTE: math.max returns `f32` values, this returns `int` values // Example: larger := audio.max(1, 5) // larger == 5 pub fn max(x int, y int) int { if x < y {