Add into_text_value() to PrimitiveValues

[techtenk]

Implements: ISSUE-88

This adds into_text_value() for PrimitiveValue as well as an impl From<Cow<'_, str>> for PrimitiveValue per the suggestion in the issue above.

Assumptions to check:

• All variants should be converted to PrimitiveValue::Str (including Empty and Strs)
• use to_raw_str() instead of to_str() to preserve the most information (no trimming of extra spaces, etc)
• both into_text_value() and impl From<Cow<'_, str>> for PrimitiveValue are useful for convenience/completeness, even though into_text_value() is just PrimitiveValue::from(self.to_raw_str())

Other things to check:

• I didn't write test cases for all variants, figuring it become redundant with the to_raw_str() tests. Let me know if I should.
• double check the correctness of the documentation. I tried to follow the pattern but I'm new to the project and might have mis-typed

[Enet4]

Thank you for your pull request. Please let me know if you are available to reiterate on it per the comments below.

The only major concern that makes me put this on hold is the fact that it can easily create invalid date-time values.

[Enet4]

It feels much too verbose to discuss when to use into_text_value() or some other method, frankly to the point of not being useful. The primary differences are also described in the type signature, through the receiving type (self vs &self) and the output type (PrimitiveValue vs one of Rust string types). Also, users are still much more likely to use to_str over to_raw_str or into_text_value.

I'd frame it like this:

Suggested change

	/// # When to use `into_text_value()` vs `to_raw_str()`
	///
	/// Use **`to_raw_str()`** when you need a string representation
	/// for display, comparison, or serialization:
	/// - Returns `Cow<'_, str>` (borrows when possible)
	/// - Does not consume the original value
	/// - Suitable for temporary string operations
	///
	/// Use **`into_text_value()`** when you need to store or manipulate
	/// the value as text within the `PrimitiveValue` enum:
	/// - Returns `PrimitiveValue::Str` (consumes the original)
	/// - Useful for normalizing values to text representation
	/// - Allows further processing as a `PrimitiveValue`
	///
	/// [`to_raw_str()`]: #method.to_raw_str
	/// # When to use `into_text_value()`
	///
	/// You can use `into_text_value` to
	/// turn an existing DICOM value into a textual DICOM value
	/// stored in a single string underneath,
	/// regardless of the value's original format.
	/// It is also an alternative to converting each number into strings
	/// before they are encased in `PrimitiveValue`.
	///
	/// The methods [`to_str`] or [`to_multi_str`]
	/// would be preferred when the intent is to
	/// retrieve the underlying values as a string type.
	///
	/// [`to_str`]: PrimitiveValue::to_str
	/// [`to_multi_str`]: PrimitiveValue::to_multi_str
	/// [`to_raw_str()`]: PrimitiveValue::to_raw_str

[techtenk]

I agree it's too verbose. It was a combination of me trying to emulate the other documentation in this file, which is fairly verbose and trying to actually understand the implications myself. I especially like the last point to call the string methods if the desired result is a string.

Accepted

[techtenk]

The description is still very verbose after these changes. Are we ok with the state of the documentation after this change or do you want me to make the examples more concise. Some of them are probably not required - we really just need two or so examples to convey that it's just .to_raw_str() underneath the covers.

[Enet4]

It will be a bit more than to_raw_str in the end (because of the date-time edge-case), but in any case I think its extensiveness is not a big issue at this point. Eventually we could get rid of the "When to use into_text_value" heading (keeping the contents below it), which will automatically give it a feeling of conciseness.

[Enet4]

This shows... an interesting caveat. Dates are only DICOM-encoded correctly when converted via to_encoded, but to_raw_str does not use it (which would be fine because to_str and to_raw_str are ill-advised for DICOM serialization anyway, so they are not expected to be pushed back into a DICOM value).

The current behavior of this method will come across as surprising, so we will have to adjust it accordingly.

• Date and date-time values in PrimitiveValue::Date and PrimitiveValue::DateTime are encoded to their standard DICOM textual form.
• Other binary variants are converted to strings via to_string.

[techtenk]

I can work on this. For clarification, is it as simple as calling to_encoded() when appropriate and updating the docs? Or am I missing some nuance?

[Enet4]

So yes, for the variants Da and Dt they should be converted to text via to_encoded(). The rule for concatenating multiple values into a single string would be the same (joined together with backslash as the separator).