(r14) LCS2016_012 < P1076

P1076 Web>VHDL2017>LCS2016_012 (revision 14) (raw view)~~EditAttach~~
---+ Language Change Specification for String representation of values of composite types

---++ Summary

| <sticky><b>LCS Number:</b></sticky> | LCS-2016-012 |
| <sticky><b>Version:</b></sticky>  | 3 |
| <sticky><b>Date:</b></sticky>  | 16 Mar 2017  |
| <sticky><b>Status:</b></sticky>  | Voting |
| <sticky><b>Author:</b></sticky>  | Ryan Hinton |
| <sticky><b>Email:</b></sticky>  | [[Main.RyanHinton]] |
| <sticky><b>Source Doc:</b></sticky> | [[CompositeValueString][String representation of values of composite types]] |
| <sticky><b>History Doc:</b></sticky> | [[LCS2016_012_History][History]] |
| <sticky><b>Summary:</b></sticky>  | 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%red font%ENDCOLOR%.  Deletions are %RED%<del>crossed out</del>%ENDCOLOR%. Editing notes in %GREEN%green font%ENDCOLOR%.

---++++ 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 %RED%<del>a one-dimensional array type T whose element type is a character type that contains only character literals</del> a representable array type T (see 5.7)%ENDCOLOR%, the following operation is implicitly declared immediately following the type declaration:
<pre><b>function</b> TO_STRING (VALUE: T) <b>return</b> STRING;
</pre>

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

%RED%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:%ENDCOLOR%
<pre><b>function</b> TO_STRING (VALUE: T) <b>return</b> STRING;
</pre>

%RED%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.%ENDCOLOR%

%RED%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.%ENDCOLOR%

---++++ Section 5.7 String representations
---+++++ Edit 12.3:   Second-to-last bullet, near the end of page 61 (pdf page 75):

   * %RED%A value of type STRING is its own string representation.%ENDCOLOR%
   * %RED%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.%ENDCOLOR%
   * For a given value that is of a composite type %RED%<del>other than described by</del> that is not representable according to%ENDCOLOR% 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.

%GREEN%["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.]%ENDCOLOR%

---++++ 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 %RED%or representable composite type or subtype%ENDCOLOR% 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). %GREEN% _(The text up to this point is the complete, unmodified text from the VHDL-2008 description of the ='image= result.)_ %ENDCOLOR% %RED% If T is a one-dimensional array type or subtype whose element type is enumeration type that contains only character literals %ENDCOLOR% %GREEN% _(This covers the important cases of =bit_vector= and =std_logic_vector= as well as types from =numeric_std=, =fixed_pkg=, and =float_pkg=.)_ %ENDCOLOR% %RED%, 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. %ENDCOLOR% %GREEN% _(This allows for typical STRING values to be represented as ="bob"= instead of =('b','o','b')=.)_ %ENDCOLOR% %RED% The language does not define under what conditions which representation is used in this case.%ENDCOLOR% %GREEN% _(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.)_ %ENDCOLOR% <span data-mce-mark="1">%RED%</span> |
| Restrictions: | It is an error if the parameter value does not belong to the subtype implied by the prefix. %RED%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.%ENDCOLOR% |

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

| Prefix: | Any scalar type or subtype %RED%or representable composite type or subtype%ENDCOLOR% 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. <span data-mce-mark="1"><!-- ... %GREEN%[No changes to this paragraph.]%ENDCOLOR% --></span> %RED% 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. %ENDCOLOR% |
| 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. <span data-mce-mark="1"><!-- OLD: %RED%Extra spaces are not allowed in the string representation of a composite type, particularly around commas and parentheses.%ENDCOLOR% --></span> |
  <span data-mce-mark="1"><!--OLD: %GREEN%(It is tempting to allow spaces around the commas separating the field strings of a composite.  However, in the case of an array of CHARACTER (STRING), it may be impossible to tell where the value starts and ends if it has spaces at the beginning and/or end.  The exception to allowing spaces around commas would have to include at least arrays of type CHARACTER or a CHARACTER-based enumerated type that includes the space character.  To simplify specification and implementation, the current draft does not allow spaces around separators for composite representations.)%ENDCOLOR% --></span>
  %GREEN% _(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.)_ %ENDCOLOR%

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

NOTE 2 -- For all values V of %RED%<del>any scalar type T</del> any representable type T%ENDCOLOR% except a real type %RED%or a composite containing a real type%ENDCOLOR%, the following relation holds:

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

%RED% 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. %ENDCOLOR%

---++++ 16.3 Package STANDARD
---+++++ Edit 12.7:   Page 268 (pdf 282):
<pre>-- 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;
%RED%-- 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;%ENDCOLOR%
-- function TO_STRING (VALUE: FILE_OPEN_KIND) return STRING;
-- function TO_STRING (VALUE: FILE_OPEN_STATUS) return STRING;

-- Predefined overloaded TO_STRING operations
</pre>

---++++ 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<span data-mce-mark="1"><!-- %RED%and the 'IMAGE attribute, and is accepted as an argument to the 'VALUE attribute%ENDCOLOR% --></span>. (5.7)

---++ Comments

%COMMENT%
Topic revision: r1 - 2017-07-22 - 21:38:52 - TWikiGuest
P1076