nushell/crates/nu-protocol/src
Ian Manske 1c49ca503a
Name the Value conversion functions more clearly (#11851)
# Description
This PR renames the conversion functions on `Value` to be more consistent.
It follows the Rust [API guidelines](https://rust-lang.github.io/api-guidelines/naming.html#ad-hoc-conversions-follow-as_-to_-into_-conventions-c-conv) 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.
2024-02-17 18:14:16 +00:00
..
ast Support redirect stderr and stdout+stderr with a pipe (#11708) 2024-02-09 01:30:46 +08:00
config Name the Value conversion functions more clearly (#11851) 2024-02-17 18:14:16 +00:00
engine Name the Value conversion functions more clearly (#11851) 2024-02-17 18:14:16 +00:00
value Name the Value conversion functions more clearly (#11851) 2024-02-17 18:14:16 +00:00
alias.rs Refactor scope commands (#10023) 2023-08-17 11:58:38 +03:00
cli_error.rs Refactor and fix Config<->Value mechanism (#10896) 2023-11-08 20:31:30 +01:00
did_you_mean.rs Improve case insensitivity consistency (#10884) 2023-11-08 23:58:54 +01:00
eval_base.rs Name the Value conversion functions more clearly (#11851) 2024-02-17 18:14:16 +00:00
eval_const.rs Unify glob behavior on open, rm, cp-old, mv, umv, cp and du commands (#11621) 2024-01-26 21:57:35 +08:00
example.rs remove unused imports: Deserialize, Serialize compiler warning for nu-protocol/src/example.rs (#8514) 2023-03-18 11:45:12 -07:00
exportable.rs Module: support defining const and use const variables inside of function (#9773) 2023-08-01 07:09:52 +08:00
id.rs Add virtual path abstraction layer (#9245) 2023-05-23 23:48:50 +03:00
lev_distance.rs Suggest existing variables on not found (#8902) 2023-05-02 18:17:14 +03:00
lib.rs Deprecate --flag: bool in custom command (#11365) 2023-12-21 10:07:08 +01:00
module.rs Error on use path item1 item2, if item1 is not a module (#11183) 2023-12-05 11:38:45 +01:00
parse_error.rs Evaluate string interpolation at parse time (#11562) 2024-01-22 09:13:48 +02:00
parse_warning.rs Deprecate --flag: bool in custom command (#11365) 2023-12-21 10:07:08 +01:00
pipeline_data.rs Name the Value conversion functions more clearly (#11851) 2024-02-17 18:14:16 +00:00
plugin_signature.rs Rename main to script name when running scripts (#9948) 2023-08-12 05:58:49 +12:00
shell_error.rs Disallow spreading lists automatically when calling externals (#11857) 2024-02-14 18:16:19 -05:00
signature.rs Move history into their own module (#11308) 2023-12-15 13:17:12 +01:00
span.rs Bump miette from 5.10.0 to 7.0.0 (#11788) 2024-02-07 19:26:18 -06:00
syntax_shape.rs Unify glob behavior on open, rm, cp-old, mv, umv, cp and du commands (#11621) 2024-01-26 21:57:35 +08:00
ty.rs adjust some commansd input_output type (#11436) 2024-01-15 16:58:26 +08:00
util.rs Convert more ShellError variants to named fields (#11173) 2023-11-28 06:43:51 -06:00
variable.rs Fix broken constants in scopes (#9679) 2023-07-14 00:02:05 +03:00