XTCE12 — toString/NumberFormat needs default settings

Description Kevin Rice 2008-03-20 19:13:40 GMT
toString/NumberFormat - element is required if toString is in use. Almost all
attributes are optional but defaults should be

provided for "most common" likely format...

Propose to accept that default and annotations are a good idea

Beginning work from the schema up to date with ballot 7 from Brad.

The complexType NumberToStringType had a typo in that it did not close one of the <element> elements. This type below corrects that and also adds annotation for the NumberFormat element.

<complexType name="NumberToStringType" abstract="true">
<annotation>
<documentation xml:lang="en">There are two ways numeric data can be changed to string data: using a Java style NumberFormat, or using an enumerated list. Enumerated lists can be assigned to a single value or a value range.</documentation>
</annotation>
<complexContent>
<extension base="xtce:OptionalNameDescriptionType">
<choice>
<choice maxOccurs="unbounded">
<element name="ValueEnumeration" type="xtce:ValueEnumerationType">
<annotation>
<documentation xml:lang="en">A number or range assigned to a string.</documentation>
</annotation>
</element>
<element name="RangeEnumeration" type="xtce:RangeEnumerationType"/>
</choice>
<element name="NumberFormat" type="xtce:NumberFormatType">
<annotation>
<documentation xml:lang="en">This element describes how a numeric value should be represented in engineering/calibrated form. The defaults reflect the most common form.</documentation>
</annotation>
</element>
</choice>
</extension>
</complexContent>
</complexType>

The complexType NumberFormatType needed an update to assign the default values and also to add descriptive annotation to the attributes. The previous definition first:

<complexType name="NumberFormatType">
<attribute name="numberBase" type="xtce:RadixType" use="optional"/>
<attribute name="minimumFractionDigits" type="nonNegativeInteger" use="optional"/>
<attribute name="maximumFractionDigits" type="nonNegativeInteger" use="optional"/>
<attribute name="minimumIntegerDigits" type="nonNegativeInteger" use="optional"/>
<attribute name="maximumIntegerDigits" type="nonNegativeInteger" use="optional"/>
<attribute name="negativeSuffix" type="string" use="optional"/>
<attribute name="positiveSuffix" type="string" use="optional"/>
<attribute name="negativePrefix" type="string" use="optional" default="-"/>
<attribute name="positivePrefix" type="string" use="optional"/>
<attribute name="showThousandsGrouping" type="boolean" use="optional" default="true"/>
<attribute name="notation" type="xtce:FloatingPointNotationType" use="optional" default="normal"/>
</complexType>

Now, the updated definition of the type:

<complexType name="NumberFormatType">
<annotation>
<documentation xml:lang="en">This type describes how a numeric value should be represented in engineering/calibrated form. The defaults reflect the most common form.</documentation>
</annotation>
<attribute name="numberBase" type="xtce:RadixType" use="optional" default="decimal">
<annotation>
<documentation xml:lang="en">Describes how the engineering/calibrated value of this number should be displayed with respect to the radix. Default is base 10.</documentation>
</annotation>
</attribute>
<attribute name="minimumFractionDigits" type="xtce:NonNegativeLongType" use="optional" default="0">
<annotation>
<documentation xml:lang="en">Describes how the engineering/calibrated value of this number should be displayed with respect to the minimum number of fractional digits. The default is 0.</documentation>
</annotation>
</attribute>
<attribute name="maximumFractionDigits" type="xtce:NonNegativeLongType" use="optional">
<annotation>
<documentation xml:lang="en">Describes how the engineering/calibrated value of this number should be displayed with respect to the maximum or upper bound of the number of digits. There is no default. No value specified should be interpreted as no upper bound such that all requires digits are used to fully characterize the value.</documentation>
</annotation>
</attribute>
<attribute name="minimumIntegerDigits" type="xtce:NonNegativeLongType" use="optional" default="1">
<annotation>
<documentation xml:lang="en">Describes how the engineering/calibrated value of this number should be displayed with respect to the minimum number of integer digits. The default is 1.</documentation>
</annotation>
</attribute>
<attribute name="maximumIntegerDigits" type="xtce:NonNegativeLongType" use="optional">
<annotation>
<documentation xml:lang="en">Describes how the engineering/calibrated value of this number should be displayed with respect to the maximum or upper bound of the integer digits. There is no default. No value specified should be interpreted as no upper bound such that all requires digits are used to fully characterize the value.</documentation>
</annotation>
</attribute>
<attribute name="negativeSuffix" type="string" use="optional" default="">
<annotation>
<documentation xml:lang="en">Describes how the engineering/calibrated value of this number should be displayed with respect to negative values. This attribute specifies the character or characters that should be appended to the numeric value to indicate negative values. The default is none.</documentation>
</annotation>
</attribute>
<attribute name="positiveSuffix" type="string" use="optional" default="">
<annotation>
<documentation xml:lang="en">Describes how the engineering/calibrated value of this number should be displayed with respect to positive values. This attribute specifies the character or characters that should be appended to the numeric value to indicate positive values. The default is none. Zero is considered to be specific to the implementation/platform and is not implied here.</documentation>
</annotation>
</attribute>
<attribute name="negativePrefix" type="string" use="optional" default="-">
<annotation>
<documentation xml:lang="en">Describes how the engineering/calibrated value of this number should be displayed with respect to negative values. This attribute specifies the character or characters that should be prepended to the numeric value to indicate negative values. The default is a minus character "-".</documentation>
</annotation>
</attribute>
<attribute name="positivePrefix" type="string" use="optional" default="">
<annotation>
<documentation xml:lang="en">Describes how the engineering/calibrated value of this number should be displayed with respect to positive values. This attribute specifies the character or characters that should be prepended to the numeric value to indicate positive values. The default is none. Zero is considered to be specific to the implementation/platform and is not implied here.</documentation>
</annotation>
</attribute>
<attribute name="showThousandsGrouping" type="boolean" use="optional" default="false">
<annotation>
<documentation xml:lang="en">Describes how the engineering/calibrated value of this number should be displayed with respect to larger values. Groupings by thousand are specific to locale, so the schema only specifies whether they will be present and not which character separators are used. The default is false.</documentation>
</annotation>
</attribute>
<attribute name="notation" type="xtce:FloatingPointNotationType" use="optional" default="normal">
<annotation>
<documentation xml:lang="en">Describes how the engineering/calibrated value of this number should be displayed with respect to notation. Engineering, scientific, or traditional decimal notation may be specified. The precise characters used is locale specific for the implementation/platform. The default is "normal" for the traditional notation.</documentation>
</annotation>
</attribute>
</complexType>

This proposal should add significant new clarity to this element. Not using this element in an XTCE document will imply the most common numeric formats that platforms tend to default to.