Language Change Specification for String representation of values of composite types

Summary

LCS Number: LCS-2016-012
Version: 3
Date: 16 Mar 2017
Status: Voting
Author: Ryan Hinton
Email: Main.RyanHinton
Source Doc: String representation of values of composite types
History Doc: History
Summary: Provide simple built-in facility for converting the value of a composite type to/from a string.

Details of Language Change

Changes are shown in red font. Deletions are crossed out. Editing notes in green font.

Section 5.3.2.4 Predefined operations on array types

Edit 12.1: Last paragraph on page 50 (pdf 64), flowing to the top of page 51

Given a type declaration that declares a one-dimensional array type T whose element type is a character type that contains only character literals a representable array type T (see 5.7), the following operation is implicitly declared immediately following the type declaration:

function TO_STRING (VALUE: T) return STRING;

The TO_STRING operation returns the string representation (see 5.7) of the value of its actual parameter. The result type of the operation is the type STRING defined in package STANDARD.

Edit 12.2: New section 5.3.3.2 Predefined operations on record types

Given a type declaration that declares a representable record type T (see 5.7), the following operation is implicitly declared immediately following the type declaration:

function TO_STRING (VALUE: T) return STRING;

The TO_STRING operation returns the string representation (see 5.7) of the value of its actual parameter. The result type of the operation is the type STRING defined in package STANDARD.

NOTE -- The TO_STRING function can be overridden to customize the returned string for a particular application. The format described in 5.7 is reasonably compact and simple for a machine to produce and parse. However, it would be challenging for a person to interpret from a simulation transcript.

Section 5.7 String representations

Edit 12.3: Second-to-last bullet, near the end of page 61 (pdf page 75):

  • A value of type STRING is its own string representation.
  • For a given value that is of a composite type other than described by the preceding paragraphs, the string representation consists of the concatenation of a left parenthesis, the string representations of the elements of the type separated by commas, and a right parenthesis. The string representations of the elements occur in left-to-right order for arrays and in element declaration order for records. A composite type is representable if the base type of each of its elements is a scalar type or a representable composite type.
  • For a given value that is of a composite type other than described by that is not representable according to the preceding paragraph, there is no string representation.
  • For a value of an access type, a file type, or a protected type, there is no string representation.

["Representable" is defined positively in terms of allowed element types instead of disallowed types (currently only access types) to avoid possible conflict with the proposed change to allow protected types in composites.]

Section 16.2.2 Predefined attributes of types and objects

Edit 12.4: T'IMAGE(X), middle of page 240 (pdf page 254):

Prefix: Any scalar type or subtype or representable composite type or subtype T.
Parameter: An expression whose type is the base type of T.
Result type: Type STRING.
Result: The string representation of the parameter value as defined in 5.7, but with the following differences. If T is an enumeration type or subtype and the parameter value is either an extended identifier or a character literal, the result is expressed with both a leading and trailing reverse solidus (backslash) (in the case of an extended identifier) or apostrophe (in the case of a character literal); in the case of an extended identifier that has a backslash, the backslash is doubled in the string representation. If T is an enumeration type or subtype and the parameter value is a basic identifier, then the result is expressed in lowercase characters. If T is a numeric type or subtype, the result is expressed as the decimal representation of the parameter value without underlines or leading or trailing zeros (except as necessary to form the image of a legal literal with the proper value); moreover, an exponent may (but is not required to) be present and the language does not define under what conditions it is or is not present. If the exponent is present, the e is expressed as a lowercase character. If T is a physical type or subtype, the result is expressed in terms of the primary unit of T unless the base type of T is TIME, in which case the result is expressed in terms of the resolution limit (see 5.2.4.2); in either case, if the unit is a basic identifier, the image of the unit is expressed in lowercase characters. If T is a floating-point type or subtype, the number of digits to the right of the decimal point corresponds to the standard form generated when the DIGITS parameter to TEXTIO.WRITE for type REAL is set to 0 (see 16.4). (The text up to this point is the complete, unmodified text from the VHDL-2008 description of the 'image result.) If T is a one-dimensional array type or subtype whose element type is enumeration type that contains only character literals (This covers the important cases of bit_vector and std_logic_vector as well as types from numeric_std, fixed_pkg, and float_pkg.) , the result consists of the string representation of the given value with leading and trailing double quotes. Any double quotes in the string representation are doubled. If T is any other representable composite type or subtype (see 5.7), the result is the concatenation of a left parenthesis, the images of the elements of T separated by commas, and a right parenthesis. The image of an element Y of X is the result of calling Y'SUBTYPE'IMAGE(Y). If T is a one-dimensional array type or subtype whose elements are a mixture of character literals and identifiers and all of the elements of X are character literals, the result may follow the rule for character literal-only types, or it may follow the general rule for composites. (This allows for typical STRING values to be represented as "bob" instead of ('b','o','b').) The language does not define under what conditions which representation is used in this case. (Implementations can support only the general rule if they like for simplicity and because it requires an extra pass to check the values. I hope my simulator supports the optimized output. 'value has to decode both, but each format is already needed, and it's easy to decide which encoding is being used by the first character.)
Restrictions: It is an error if the parameter value does not belong to the subtype implied by the prefix. It is an error if the prefix is a composite type that is not representable according to 5.7. Implementations may limit generated string length.

Edit 12.5: T'VALUE(X), middle of page 241 (pdf page 255):

Prefix: Any scalar type or subtype or representable composite type or subtype T.
Parameter: An expression of type STRING
Result type: The base type of T.
Result: The value of T whose string representation (as defined in 5.7) is given by the parameter. Leading and trailing whitespace is allowed and ignored. If T is a numeric type or subtype, the parameter shall be expressed either as a decimal literal or as a based literal, with the addition of an optional leading sign. If the sign is present, whitespace shall not occur between the sign and the remainder of the value. If T is a physical type or subtype, the parameter shall be expressed using a string representation of any of the unit names of T, with or without a leading abstract literal. The parameter shall have whitespace between any abstract literal and the unit name. For the representation of a composite type, extra spaces are allowed and ignored around the enclosing parentheses and around the commas delimiting the element representations.
Restrictions: It is an error if the parameter is not a valid string representation of a literal of type T or if the result does not belong to the subtype implied by T.
(With the more verbose 'image representation relative to the "string representation", spaces around commas and parentheses shouldn't interfere with unambiguously parsing the string to a value of the given type.)

Edit 12.6: Notes, page 242 (pdf 256):

NOTE 2 -- For all values V of any scalar type T any representable type T except a real type or a composite containing a real type, the following relation holds:

V = T'Value(T'Image(V))

Note 3 -- Calling STRING'IMAGE("two") will return one of two possible results: either the length-5 string "two" (the quotes are part of the result) following the special-case rule, or ('t','w','o') following the general rule for aggregates.

16.3 Package STANDARD

Edit 12.7: Page 268 (pdf 282):
-- Predefined TO_STRING operations on scalar types

-- function TO_STRING (VALUE: BOOLEAN) return STRING;
-- function TO_STRING (VALUE: BIT) return STRING;
-- function TO_STRING (VALUE: CHARACTER) return STRING;
-- function TO_STRING (VALUE: SEVERITY_LEVEL) return STRING;
-- function TO_STRING (VALUE: universal_integer) return STRING;
-- function TO_STRING (VALUE: universal_real) return STRING;
-- function TO_STRING (VALUE: INTEGER) return STRING;
-- function TO_STRING (VALUE: REAL) return STRING;
-- function TO_STRING (VALUE: TIME) return STRING;
-- function TO_STRING (VALUE: STRING) return STRING;
-- function TO_STRING (VALUE: BOOLEAN_VECTOR) return STRING;
-- function TO_STRING (VALUE: INTEGER_VECTOR) return STRING;
-- function TO_STRING (VALUE: REAL_VECTOR) return STRING;
-- function TO_STRING (VALUE: TIME_VECTOR) return STRING;
-- function TO_STRING (VALUE: FILE_OPEN_KIND) return STRING;
-- function TO_STRING (VALUE: FILE_OPEN_STATUS) return STRING;

-- Predefined overloaded TO_STRING operations

Annex I Glossary

Edit 12.8: Page 580 (pdf 594)

string representation: A string that represents the value of a given type. A string representation of a value is returned by the TO_STRING operation. (5.7)

Comments

Topic revision: r23 - 2017-07-22 - 21:38:52 - JimLewis
 
Copyright © 2008-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback