Next: , Up: SPV Detail facetLayout Element   [Contents][Index]


D.4.10.1 The format Element

Parent: sourceVariable, derivedVariable, formatMapping, labeling, formatMapping, setFormat
Contents: (affix+ | relabel+)?

This element appears only in schema version 2.7 (see SPV Detail visualization Element).

This element determines a format, equivalent to an SPSS print format.

Attributes for All Formats

These attributes apply to all kinds of formats. The most important of these attributes determines the high-level kind of formatting in use:

Optional: baseFormat

Either dateTime or elapsedTime. When this attribute is omitted, this element is a numeric or string format.

Whether, in the corpus, other attributes are always present (“yes”), never present (“no”), or sometimes present (“opt”) depends on baseFormat:

AttributedateTimeelapsedTimenumberstring
errorCharacteryesyesyesopt
 
separatorCharsyesnonono
 
mdyOrderyesnonono
 
showYearyesnonono
yearAbbreviationyesnonono
 
showMonthyesnonono
monthFormatyesnonono
 
showDayyesoptnono
dayPaddingyesoptnono
dayOfMonthPaddingyesnonono
dayTypeyesnonono
 
showHouryesoptnono
hourFormatyesoptnono
hourPaddingyesyesnono
 
showMinuteyesyesnono
minutePaddingyesyesnono
 
showSecondyesyesnono
secondPaddingnoyesnono
 
showMillisnoyesnono
 
minimumIntegerDigitsnonoyesno
maximumFractionDigitsnoyesyesno
minimumFractionDigitsnoyesyesno
useGroupingnooptyesno
scientificnonoyesno
smallnonooptno
suffixnonooptno
 
tryStringsAsNumbersnononoyes
 
Attribute: errorCharacter

A character that replaces the formatted value when it cannot otherwise be represented in the given format. Always ‘*’.

Date and Time Attributes

These attributes are used with dateTime and elapsedTime formats or both.

Attribute: separatorChars

Exactly four characters. In order, these are used for: decimal point, grouping, date separator, time separator. Always ‘.,-:’.

Attribute: mdyOrder

Within a date, the order of the days, months, and years. dayMonthYear is the only observed value, but one would expect that monthDayYear and yearMonthDay to be reasonable as well.

Attribute: showYear
Attribute: yearAbbreviation

Whether to include the year and, if so, whether the year should be shown abbreviated, that is, with only 2 digits. Each is true or false; only values of true and false, respectively, have been observed.

Attribute: showMonth
Attribute: monthFormat

Whether to include the month (true or false) and, if so, how to format it. monthFormat is one of the following:

long

The full name of the month, e.g. in an English locale, September.

short

The abbreviated name of the month, e.g. in an English locale, Sep.

number

The number representing the month, e.g. 9 for September.

paddedNumber

A two-digit number representing the month, e.g. 09 for September.

Only values of true and short, respectively, have been observed.

Attribute: dayPadding
Attribute: dayOfMonthPadding
Attribute: hourPadding
Attribute: minutePadding
Attribute: secondPadding

These attributes presumably control whether each field in the output is padded with spaces to its maximum width, but the details are not understood. The only observed value for any of these attributes is true.

Attribute: showDay
Attribute: showHour
Attribute: showMinute
Attribute: showSecond
Attribute: showMillis

These attributes presumably control whether each field is displayed in the output, but the details are not understood. The only observed value for any of these attributes is true.

Attribute: dayType

This attribute is always month in the corpus, specifying that the day of the month is to be displayed; a value of year is supposed to indicate that the day of the year, where 1 is January 1, is to be displayed instead.

Attribute: hourFormat

hourFormat, if present, is one of:

AMPM

The time is displayed with an am or pm suffix, e.g. 10:15pm.

AS_24

The time is displayed in a 24-hour format, e.g. 22:15.

This is the only value observed in the corpus.

AS_12

The time is displayed in a 12-hour format, without distinguishing morning or evening, e.g. 10;15.

hourFormat is sometimes present for elapsedTime formats, which is confusing since a time duration does not have a concept of AM or PM. This might indicate a bug in the code that generated the XML in the corpus, or it might indicate that elapsedTime is sometimes used to format a time of day.

Numeric Attributes

These attributes are used for formats when baseFormat is number. Attributes maximumFractionDigits, and minimumFractionDigits, and useGrouping are also used when baseFormat is elapsedTime.

Attribute: minimumIntegerDigits

Minimum number of digits to display before the decimal point. Always observed as 0.

Attribute: maximumFractionDigits
Attribute: maximumFractionDigits

Maximum or minimum, respectively, number of digits to display after the decimal point. The observed values of each attribute range from 0 to 9.

Attribute: useGrouping

Whether to use the grouping character to group digits in large numbers. It would make sense for the grouping character to come from the separatorChars attribute, but that attribute is only present when baseFormat is dateTime or elapsedTime, in the corpus at least. Perhaps that is because this attribute has only been observed as false.

Attribute: scientific

This attribute controls when and whether the number is formatted in scientific notation. It takes the following values:

onlyForSmall

Use scientific notation only when the number’s magnitude is smaller than the value of the small attribute.

whenNeeded

Use scientific notation when the number will not otherwise fit in the available space.

true

Always use scientific notation. Not observed in the corpus.

false

Never use scientific notation. A number that won’t otherwise fit will be replaced by an error indication (see the errorCharacter attribute). Not observed in the corpus.

Optional: small

Only present when the scientific attribute is onlyForSmall, this is a numeric magnitude below which the number will be formatted in scientific notation. The values 0 and 0.0001 have been observed. The value 0 seems like a pathological choice, since no real number has a magnitude less than 0; perhaps in practice such a choice is equivalent to setting scientific to false.

Optional: prefix
Optional: suffix

Specifies a prefix or a suffix to apply to the formatted number. Only suffix has been observed, with value ‘%’.

String Attributes

These attributes are used for formats when baseFormat is string.

Attribute: tryStringsAsNumbers

When this is true, it is supposed to indicate that string values should be parsed as numbers and then displayed according to numeric formatting rules. However, in the corpus it is always false.


Next: , Up: SPV Detail facetLayout Element   [Contents][Index]