nushell icon indicating copy to clipboard operation
nushell copied to clipboard

Name the `Value` conversion functions more clearly

Open IanManske opened this issue 1 year ago • 2 comments

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 to type (e.g., i64 are converted to f64). This is the old behavior of some of the as_{type} functions -- these functions have simply been renamed to better reflect what they do.
  • The new as_{type} functions take a &Value and returns an Ok result only if the value is of type (no conversion is attempted). The returned value will be borrowed if type is non-Copy, otherwise an owned value is returned.
  • into_{type} exists for non-Copy types, but otherwise does not attempt conversion just like as_type. It takes an owned Value and always returns an owned result.
  • coerce_into_{type} has the same relationship with coerce_{type} as into_{type} does with as_{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, only to_path exists. (And to_string through Display.)

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.

IanManske avatar Feb 13 '24 22:02 IanManske

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?

sholderbach avatar Feb 14 '24 15:02 sholderbach

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.

IanManske avatar Feb 14 '24 17:02 IanManske

Nice! Thanks for implementing the elegant doctests as well!

sholderbach avatar Feb 17 '24 18:02 sholderbach