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.
This commit is contained in:
Ian Manske
2024-02-17 18:14:16 +00:00
committed by GitHub
parent 360ebeb0bc
commit 1c49ca503a
117 changed files with 903 additions and 745 deletions

View File

@@ -70,7 +70,7 @@ fn to_url(input: PipelineData, head: Span) -> Result<PipelineData, ShellError> {
Value::Record { ref val, .. } => {
let mut row_vec = vec![];
for (k, v) in val {
match v.as_string() {
match v.coerce_string() {
Ok(s) => {
row_vec.push((k.clone(), s.to_string()));
}

View File

@@ -181,10 +181,10 @@ impl UrlComponents {
if key == "params" {
return match value {
Value::Record { ref val, .. } => {
Value::Record { val, .. } => {
let mut qs = val
.iter()
.map(|(k, v)| match v.as_string() {
.into_iter()
.map(|(k, v)| match v.coerce_into_string() {
Ok(val) => Ok(format!("{k}={val}")),
Err(err) => Err(err),
})
@@ -202,7 +202,7 @@ impl UrlComponents {
// if query is present it means that also query_span is set.
return Err(ShellError::IncompatibleParameters {
left_message: format!("Mismatch, qs from params is: {qs}"),
left_span: value.span(),
left_span: value_span,
right_message: format!("instead query is: {q}"),
right_span: self.query_span.unwrap_or(Span::unknown()),
});
@@ -224,7 +224,7 @@ impl UrlComponents {
}
// apart from port and params all other keys are strings.
let s = value.as_string()?; // If value fails String conversion, just output this ShellError
let s = value.coerce_into_string()?; // If value fails String conversion, just output this ShellError
if !Self::check_empty_string_ok(&key, &s, value_span)? {
return Ok(self);
}
@@ -259,7 +259,7 @@ impl UrlComponents {
// if query is present it means that also params_span is set.
return Err(ShellError::IncompatibleParameters {
left_message: format!("Mismatch, query param is: {s}"),
left_span: value.span(),
left_span: value_span,
right_message: format!("instead qs from params is: {q}"),
right_span: self.params_span.unwrap_or(Span::unknown()),
});
@@ -268,7 +268,7 @@ impl UrlComponents {
Ok(Self {
query: Some(format!("?{s}")),
query_span: Some(value.span()),
query_span: Some(value_span),
..self
})
}

View File

@@ -75,7 +75,7 @@ impl Command for SubCommand {
}
fn get_url_string(value: &Value, engine_state: &EngineState) -> String {
value.into_string("", engine_state.get_config())
value.to_expanded_string("", engine_state.get_config())
}
fn parse(value: Value, head: Span, engine_state: &EngineState) -> Result<PipelineData, ShellError> {