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

@ -293,8 +293,8 @@ mod test {
);
} else {
assert_eq!(
actual.unwrap().into_string("", &config),
tc.expected.unwrap().into_string("", &config)
actual.unwrap().to_expanded_string("", &config),
tc.expected.unwrap().to_expanded_string("", &config)
);
}
}

View File

@ -119,7 +119,7 @@ fn to_string_tagged_value(
| Value::CustomValue { .. }
| Value::Filesize { .. }
| Value::CellPath { .. }
| Value::Float { .. } => Ok(v.clone().into_abbreviated_string(config)),
| Value::Float { .. } => Ok(v.clone().to_abbreviated_string(config)),
Value::Date { val, .. } => Ok(val.to_string()),
Value::Nothing { .. } => Ok(String::new()),
// Propagate existing errors

View File

@ -120,12 +120,12 @@ fn fragment(input: Value, pretty: bool, config: &Config) -> String {
};
out.push_str(&markup);
out.push_str(&data.into_string("|", config));
out.push_str(&data.to_expanded_string("|", config));
}
_ => out = table(input.into_pipeline_data(), pretty, config),
}
} else {
out = input.into_string("|", config)
out = input.to_expanded_string("|", config)
}
out.push('\n');
@ -168,7 +168,7 @@ fn table(input: PipelineData, pretty: bool, config: &Config) -> String {
.get(&headers[i])
.cloned()
.unwrap_or_else(|| Value::nothing(span))
.into_string(", ", config);
.to_expanded_string(", ", config);
let new_column_width = value_string.len();
escaped_row.push(value_string);
@ -180,7 +180,7 @@ fn table(input: PipelineData, pretty: bool, config: &Config) -> String {
}
p => {
let value_string =
v_htmlescape::escape(&p.into_abbreviated_string(config)).to_string();
v_htmlescape::escape(&p.to_abbreviated_string(config)).to_string();
escaped_row.push(value_string);
}
}
@ -215,7 +215,7 @@ pub fn group_by(values: PipelineData, head: Span, config: &Config) -> (PipelineD
.or_insert_with(|| vec![val.clone()]);
} else {
lists
.entry(val.into_string(",", config))
.entry(val.to_expanded_string(",", config))
.and_modify(|v: &mut Vec<Value>| v.push(val.clone()))
.or_insert_with(|| vec![val.clone()]);
}