builtin: improve docs for array methods that take an `it` expression, like .map, .filter etc (#13836)
Move explanation about boolean `it` expressions to `filter`, as `sort` doesn't take a boolean expression. Also move `any` example. Add 2 filter examples. Add map example from docs.md.pull/13839/head
parent
dc9fd2bd7e
commit
02f72c8230
|
@ -667,7 +667,17 @@ pub fn (a &array) free() {
|
||||||
// Ignore the function signature. `filter` does not take an actual callback. Rather, it
|
// Ignore the function signature. `filter` does not take an actual callback. Rather, it
|
||||||
// takes an `it` expression.
|
// takes an `it` expression.
|
||||||
//
|
//
|
||||||
// Example: array.filter(it % 2 == 1) // will yield a new array of only odd elements
|
// Certain array functions (`filter` `any` `all`) support a simplified
|
||||||
|
// domain-specific-language by the backend compiler to make these operations
|
||||||
|
// more idiomatic to V. These functions are described here, but their implementation
|
||||||
|
// is compiler specific.
|
||||||
|
//
|
||||||
|
// Each function takes a boolean test expression as its single argument.
|
||||||
|
// These test expressions may use `it` as a pointer to a single element at a time.
|
||||||
|
//
|
||||||
|
// Example: array.filter(it < 5) // create an array of elements less than 5
|
||||||
|
// Example: array.filter(it % 2 == 1) // create an array of only odd elements
|
||||||
|
// Example: array.filter(it.name[0] == `A`) // create an array of elements whose `name` field starts with 'A'
|
||||||
pub fn (a array) filter(predicate fn (voidptr) bool) array
|
pub fn (a array) filter(predicate fn (voidptr) bool) array
|
||||||
|
|
||||||
// any tests whether at least one element in the array passes the test.
|
// any tests whether at least one element in the array passes the test.
|
||||||
|
@ -677,6 +687,7 @@ pub fn (a array) filter(predicate fn (voidptr) bool) array
|
||||||
// it returns `false`. It doesn't modify the array.
|
// it returns `false`. It doesn't modify the array.
|
||||||
//
|
//
|
||||||
// Example: array.any(it % 2 == 1) // will return true if any element is odd
|
// Example: array.any(it % 2 == 1) // will return true if any element is odd
|
||||||
|
// Example: array.any(it.name == 'Bob') // will yield `true` if any element has `.name == 'Bob'`
|
||||||
pub fn (a array) any(predicate fn (voidptr) bool) bool
|
pub fn (a array) any(predicate fn (voidptr) bool) bool
|
||||||
|
|
||||||
// all tests whether all elements in the array pass the test
|
// all tests whether all elements in the array pass the test
|
||||||
|
@ -689,34 +700,37 @@ pub fn (a array) any(predicate fn (voidptr) bool) bool
|
||||||
pub fn (a array) all(predicate fn (voidptr) bool) bool
|
pub fn (a array) all(predicate fn (voidptr) bool) bool
|
||||||
|
|
||||||
// map creates a new array populated with the results of calling a provided function
|
// map creates a new array populated with the results of calling a provided function
|
||||||
// on every element in the calling array
|
// on every element in the calling array.
|
||||||
|
// It also accepts an `it` expression.
|
||||||
|
//
|
||||||
|
// Example:
|
||||||
|
// ```v
|
||||||
|
// words := ['hello', 'world']
|
||||||
|
// r1 := words.map(it.to_upper())
|
||||||
|
// assert r1 == ['HELLO', 'WORLD']
|
||||||
|
//
|
||||||
|
// // map can also accept anonymous functions
|
||||||
|
// r2 := words.map(fn (w string) string {
|
||||||
|
// return w.to_upper()
|
||||||
|
// })
|
||||||
|
// assert r2 == ['HELLO', 'WORLD']
|
||||||
|
// ```
|
||||||
pub fn (a array) map(callback fn (voidptr) voidptr) array
|
pub fn (a array) map(callback fn (voidptr) voidptr) array
|
||||||
|
|
||||||
// sort sorts an array in place.
|
// sort sorts the array in place.
|
||||||
// Ignore the function signature. Passing a callback to `.sort` is not supported
|
// Ignore the function signature. Passing a callback to `.sort` is not supported
|
||||||
// for now. Consider using the `.sort_with_compare` method if you need it.
|
// for now. Consider using the `.sort_with_compare` method if you need it.
|
||||||
//
|
//
|
||||||
// Instead, a very simple syntax is available to you for custom sorting and more.
|
// sort can take a boolean test expression as its single argument.
|
||||||
//
|
// The expression uses 2 'magic' variables `a` and `b` as pointers to the two elements
|
||||||
// Certain array functions (`filter` `any` `all` and `sort`) support a simplified
|
// being compared.
|
||||||
// domain-specific-language by the backend compiler to make these operations
|
|
||||||
// more idiomatic to V. These functions are described here, but their implementation
|
|
||||||
// is compiler specific.
|
|
||||||
//
|
|
||||||
// Each function takes a boolean test expression as its single argument.
|
|
||||||
// These test expressions may use certain 'magic' variables depending on their context:
|
|
||||||
// - `sort` may use `a` and `b` as pointers to two elements
|
|
||||||
// giving you direct access to those objects
|
|
||||||
// - `filter`, `any`, and `all` may use `it` as a pointer to a single element at a time.
|
|
||||||
//
|
//
|
||||||
// Example: array.sort() // will sort the array in ascending order
|
// Example: array.sort() // will sort the array in ascending order
|
||||||
// Example: array.sort(b < a) // will sort the array in decending order
|
// Example: array.sort(b < a) // will sort the array in decending order
|
||||||
// Example: array.sort(b.name < a.name) // will sort descending by the .name field
|
// Example: array.sort(b.name < a.name) // will sort descending by the .name field
|
||||||
// Example: array.filter(it % 2 == 1) // will yield a new array of only odd elements
|
|
||||||
// Example: array.any(it.name == 'Bob') // will yield `true` if any element has `.name == 'Bob'`
|
|
||||||
pub fn (mut a array) sort(callback fn (voidptr, voidptr) int)
|
pub fn (mut a array) sort(callback fn (voidptr, voidptr) int)
|
||||||
|
|
||||||
// sort_with_compare sorts array in-place using the results of the
|
// sort_with_compare sorts the array in-place using the results of the
|
||||||
// given function to determine sort order.
|
// given function to determine sort order.
|
||||||
//
|
//
|
||||||
// The function should return one of three values:
|
// The function should return one of three values:
|
||||||
|
@ -724,7 +738,7 @@ pub fn (mut a array) sort(callback fn (voidptr, voidptr) int)
|
||||||
// - `1` when `b` should come before `a` ( `b < a` )
|
// - `1` when `b` should come before `a` ( `b < a` )
|
||||||
// - `0` when the order cannot be determined ( `a == b` )
|
// - `0` when the order cannot be determined ( `a == b` )
|
||||||
//
|
//
|
||||||
// ### Example:
|
// Example:
|
||||||
// ```v
|
// ```v
|
||||||
// fn main() {
|
// fn main() {
|
||||||
// mut a := ['hi', '1', '5', '3']
|
// mut a := ['hi', '1', '5', '3']
|
||||||
|
|
Loading…
Reference in New Issue