CrystalXml.Scalar

Namespace: SnowBank.Data.Xml · class

Entry points for a document whose root is a bare scalar (a string, a number, a date, ...)

Remarks

Nested rather than overloaded on itself: a generic method taking a bare T? value would be a catch-all that captures every call the serializer overloads do not, and a mistyped argument must fail to compile rather than fail at write time.

Methods

ToBytes

static byte[] ToBytes<T>(T value, CrystalXmlSettings? settings = null, string rootName = null, Encoding encoding = null)

Serializes a scalar value to a Slice of XML, as a single root element

• value — Value to serialize, or null for the empty root element, marked nil when the settings ask for null members
• settings — Optional settings; the reference DataContract behavior is the default
• rootName — Optional name for the root element, in place of the type's xsd lexical name; the root stays in the Serialization namespace either way
• encoding — Encoding of the returned bytes, defaulting to UTF-8 with no byte-order mark. The writer always produces UTF-8 internally; a non-default encoding transcodes the finished buffer once, so the UTF-8 path stays untouched. When WriteXmlDeclaration is set, the declaration names this encoding.

ToSlice

static Slice ToSlice<T>(T value, CrystalXmlSettings? settings = null, string rootName = null, Encoding encoding = null)

Serializes a scalar value to a Slice of XML, as a single root element

• value — Value to serialize, or null for the empty root element, marked nil when the settings ask for null members
• settings — Optional settings; the reference DataContract behavior is the default
• rootName — Optional name for the root element, in place of the type's xsd lexical name; the root stays in the Serialization namespace either way
• encoding — Encoding of the returned bytes, defaulting to UTF-8 with no byte-order mark. The writer always produces UTF-8 internally; a non-default encoding transcodes the finished buffer once, so the UTF-8 path stays untouched. When WriteXmlDeclaration is set, the declaration names this encoding.

ToText

static string ToText<T>(T value, CrystalXmlSettings? settings = null, string rootName = null)

Serializes a scalar value to a String of XML text, as a single root element

• value — Value to serialize, or null for the empty root element, marked nil when the settings ask for null members
• settings — Optional settings; the reference DataContract behavior is the default
• rootName — Optional name for the root element, in place of the type's xsd lexical name; the root stays in the Serialization namespace either way

These entry points write the output the reference DataContractSerializer writes for the same declared type: the xsd lexical name in the built-in Serialization namespace, as pinned by the root facts of DcsNamespaceReferenceFacts. A type outside the lexical set has no scalar output and is rejected.

ToXDocument

static XDocument ToXDocument<T>(T value, CrystalXmlSettings? settings = null, string rootName = null)

Serializes a scalar value to a String of XML text, as a single root element

• value — Value to serialize, or null for the empty root element, marked nil when the settings ask for null members
• settings — Optional settings; the reference DataContract behavior is the default
• rootName — Optional name for the root element, in place of the type's xsd lexical name; the root stays in the Serialization namespace either way

These entry points write the output the reference DataContractSerializer writes for the same declared type: the xsd lexical name in the built-in Serialization namespace, as pinned by the root facts of DcsNamespaceReferenceFacts. A type outside the lexical set has no scalar output and is rejected.

WriteTo

static void WriteTo<T>(TextWriter destination, T value, CrystalXmlSettings? settings = null, string rootName = null)

Serializes a scalar value as XML text into destination, as a single root element

• destination — Destination writer; ownership stays with the caller, who is responsible for flushing and disposing it
• value — Value to serialize, or null for the empty root element, marked nil when the settings ask for null members
• settings — Optional settings; the reference DataContract behavior is the default
• rootName — Optional name for the root element, in place of the type's xsd lexical name; the root stays in the Serialization namespace either way

Same buffering and failure-path contract as .

static void WriteTo<T>(IBufferWriter<byte> destination, T value, CrystalXmlSettings? settings = null, string rootName = null)

Serializes a scalar value as UTF-8 encoded XML into destination, as a single root element

• destination — Destination buffer writer
• value — Value to serialize, or null for the empty root element, marked nil when the settings ask for null members
• settings — Optional settings; the reference DataContract behavior is the default
• rootName — Optional name for the root element, in place of the type's xsd lexical name; the root stays in the Serialization namespace either way

Same ownership contract as : this overload owns no pooled resource of its own.

static void WriteTo<T>(XmlWriter destination, T value, CrystalXmlSettings? settings = null, string rootName = null)

Serializes a scalar value into destination, as a single root element

• destination — Destination writer, not owned: the caller flushes and disposes it, and configures its XmlWriterSettings
• value — Value to serialize, or null for the empty root element, marked nil when the settings ask for null members
• settings — Optional settings; the reference DataContract behavior is the default
• rootName — Optional name for the root element, in place of the type's xsd lexical name; the root stays in the Serialization namespace either way

Only infoset equivalence with the byte-exact output is guaranteed here: see the remarks on .

static void WriteTo<T>(Stream destination, T value, CrystalXmlSettings? settings = null, string rootName = null, Encoding encoding = null)

Serializes a scalar value as XML into destination, as a single root element

• destination — Destination stream; ownership stays with the caller, who is responsible for flushing and disposing it
• value — Value to serialize, or null for the empty root element, marked nil when the settings ask for null members
• settings — Optional settings; the reference DataContract behavior is the default
• rootName — Optional name for the root element, in place of the type's xsd lexical name; the root stays in the Serialization namespace either way
• encoding — Encoding of the returned bytes, defaulting to UTF-8 with no byte-order mark. The writer always produces UTF-8 internally; a non-default encoding transcodes the finished buffer once, so the UTF-8 path stays untouched. When WriteXmlDeclaration is set, the declaration names this encoding.

Same buffering and failure-path contract as . A non-default takes the simpler path instead, building the whole buffer before writing it out in one call.