Improve documentation and tests, add From impl

Author: alamb

src/ast/value.rs

@@ -30,7 +30,40 @@ use crate::{ast::Ident, tokenizer::Span};
 #[cfg(feature = "visitor")]
 use sqlparser_derive::{Visit, VisitMut};
 
-/// Primitive SQL values such as number and string
+/// Wraps a primitive SQL [`Value`]  with its [`Span`] location
+///
+/// # Example: create a `ValueWithSpan` from a `Value`
+/// ```
+/// # use sqlparser::ast::{Value, ValueWithSpan};
+/// # use sqlparser::tokenizer::{Location, Span};
+/// let value = Value::SingleQuotedString(String::from("endpoint"));
+/// // from line 1, column 1 to line 1, column 7
+/// let span = Span::new(Location::new(1, 1), Location::new(1, 7));
+/// let value_with_span = value.with_span(span);
+/// ```
+///
+/// # Example: create a `ValueWithSpan` from a `Value` with an empty span
+///
+/// You can call [`Value::with_empty_span`] to create a `ValueWithSpan` with an empty span
+/// ```
+/// # use sqlparser::ast::{Value, ValueWithSpan};
+/// # use sqlparser::tokenizer::{Location, Span};
+/// let value = Value::SingleQuotedString(String::from("endpoint"));
+/// let value_with_span = value.with_empty_span();
+/// assert_eq!(value_with_span.span, Span::empty());
+/// ```
+///
+/// You can also use the [`From`] trait to convert  `ValueWithSpan` to/from `Value`s
+/// ```
+/// # use sqlparser::ast::{Value, ValueWithSpan};
+/// # use sqlparser::tokenizer::{Location, Span};
+/// let value = Value::SingleQuotedString(String::from("endpoint"));
+/// // converting `Value` to `ValueWithSpan` results in an empty span
+/// let value_with_span: ValueWithSpan = value.into();
+/// assert_eq!(value_with_span.span, Span::empty());
+/// // convert back to `Value`
+/// let value: Value = value_with_span.into();
+/// ```
 #[derive(Debug, Clone, Eq, Ord)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(feature = "visitor", derive(Visit, VisitMut))]
@@ -63,6 +96,12 @@ impl From<ValueWithSpan> for Value {
     }
 }
 
+impl From<Value> for ValueWithSpan {
+    fn from(value: Value) -> Self {
+        value.with_empty_span()
+    }
+}
+
 /// Primitive SQL values such as number and string
 #[derive(Debug, Clone, PartialEq, PartialOrd, Eq, Ord, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]

tests/sqlparser_clickhouse.rs

@@ -55,7 +55,7 @@ fn parse_map_access_expr() {
                         "indexOf",
                         [
                             Expr::Identifier(Ident::new("string_names")),
-                            Expr::Value(Value::SingleQuotedString("endpoint".to_string()))
+                            Expr::Value(Value::SingleQuotedString("endpoint".to_string()).into())
                         ]
                     ),
                 })],