nushell
nushell copied to clipboard
Name the `Value` conversion functions more clearly
Description
This PR renames the conversion functions on Value
to be more consistent. It follows the Rust API guidelines for ad-hoc conversions. The conversion functions on Value
now come in a few forms:
-
coerce_{type}
takes a&Value
and attempts to convert the value totype
(e.g.,i64
are converted tof64
). This is the old behavior of some of theas_{type}
functions -- these functions have simply been renamed to better reflect what they do. - The new
as_{type}
functions take a&Value
and returns anOk
result only if the value is oftype
(no conversion is attempted). The returned value will be borrowed iftype
is non-Copy
, otherwise an owned value is returned. -
into_{type}
exists for non-Copy
types, but otherwise does not attempt conversion just likeas_type
. It takes an ownedValue
and always returns an owned result. -
coerce_into_{type}
has the same relationship withcoerce_{type}
asinto_{type}
does withas_{type}
. -
to_{kind}_string
: conversion to different string formats (debug, abbreviated, etc.). Only two of the old string conversion functions were removed, the rest have been renamed only. -
to_{type}
: other conversion functions. Currently, onlyto_path
exists. (Andto_string
throughDisplay
.)
This table summaries the above:
Form | Cost | Input Ownership | Output Ownership | Converts Value case/type |
---|---|---|---|---|
as_{type} |
Cheap | Borrowed | Borrowed/Owned | No |
into_{type} |
Cheap | Owned | Owned | No |
coerce_{type} |
Cheap | Borrowed | Borrowed/Owned | Yes |
coerce_into_{type} |
Cheap | Owned | Owned | Yes |
to_{kind}_string |
Expensive | Borrowed | Owned | Yes |
to_{type} |
Expensive | Borrowed | Owned | Yes |
User-Facing Changes
Breaking API change for Value
in nu-protocol
which is exposed as part of the plugin API.
Thank you so much for tackling the weird coercions under a wrong name.
Can we provide some recommendations on the plethora of munch_it_somehow_into_a_string
methods, when to use what?
Can we provide some recommendations on the plethora of
munch_it_somehow_into_a_string
methods, when to use what?
I was able to remove yet another one of the to_{kind}_string
functions. Otherwise, I added docs for the remaining four. The docs describe what each function does, but they don't say when to use each (except for to_debug_string
). I'm not sure when to use each of the other three.
Nice! Thanks for implementing the elegant doctests as well!