View Issue Details

IDProjectCategoryView StatusLast Update
0033566FPCDocumentationpublic2018-04-14 12:09
ReporterOndrej PokornyAssigned ToMichael Van Canneyt 
PrioritynormalSeverityminorReproducibilityN/A
Status closedResolutionfixed 
Product Version3.1.1Product Build38675 
Target Version3.2.0Fixed in Version3.1.1 
Summary0033566: Storage information docs are outdated
Descriptionhttps://www.freepascal.org/docs-html/ref/refsu38.html#x90-1120006.6.6 is outdated.

This is wrong:

- "The default specifier can be specified for ordinal types and sets. It serves the same purpose as the stored specifier: properties that have as value their default value, will not be written to the stream by the streaming system."

- "The nodefault specifier (nodefault) must be used to indicate that a property has no default value. The effect is that the value of this property is always written to the stream when streaming the property.

- "The value 2147483648 cannot be used as a default value, as it is used internally to denote nodefault"

Correct is:

- The stored and (no)default modifiers are independent on each other.
- The property value is saved only if it is different from its default value (or if there is no default value) and the stored specifier is True.
- If the stored specifier is not specified, an implicit "stored True" is used.
- The value -2147483648 cannot be used as a default value, as it is used internally to denote nodefault.
Additional InformationRelated bug reports: 0031985, 0033563, 0033564
TagsNo tags attached.
Fixed in Revision1476
FPCOldBugId
FPCTarget
Attached Files
  • property-storage-01.patch (1,833 bytes)
    Index: ref.tex
    ===================================================================
    --- ref.tex	(revision 1477)
    +++ ref.tex	(working copy)
    @@ -5203,7 +5203,7 @@
     The compiler offers 2 mechanisms to control whether a property is streamed
     using a streaming mechanism, such as the one implemented in the classes
     unit. These mechanisms write extra information to the generated RTTI, which
    -is later on in the streaming system:
    +is later used in the streaming system:
     
     \begin{enumerate}
     \item The {\em stored} specifier.
    @@ -5229,6 +5229,10 @@
     the stream by the streaming system, even if \var{Stored} was \var{True}.
     The default value is stored in the RTTI that is generated for the class. 
     
    +String, floating-point and pointer properties have implicit \var{default}
    +value of empty string, 0 or nil, respectively.
    +Ordinal and set properties have no implicit \var{default} value.
    +
     The {\em nodefault specifier} (\var{nodefault}) must be used to indicate 
     that a property has no default value. The effect is that the value of this
     property is always written to the stream when streaming the property, if
    @@ -5243,6 +5247,12 @@
     internally to denote \var{nodefault}.
     \item It is not possible to specify a default for array properties.
     \item It is not possible to specify the \var{Stored} directive for array properties.
    +\item All storage specifiers can be overriden in descendent classes.
    +\begin{verbatim}
    +property Test stored False;
    +\end{verbatim}
    +\item The {\em nodefault specifier} can be used to override the implicit
    +{\em nodefault specifier} of string, floating-point and pointer properties.
     \item The streaming mechanism described here is the one implemented in the
     \file{classes} unit of the RTL. Other streaming mechanisms can be
     implemented, and they can use the RTTI information in a different way.
    
  • property-storage-02.patch (1,831 bytes)
    Index: ref.tex
    ===================================================================
    --- ref.tex	(revision 1477)
    +++ ref.tex	(working copy)
    @@ -5203,7 +5203,7 @@
     The compiler offers 2 mechanisms to control whether a property is streamed
     using a streaming mechanism, such as the one implemented in the classes
     unit. These mechanisms write extra information to the generated RTTI, which
    -is later on in the streaming system:
    +is later used in the streaming system:
     
     \begin{enumerate}
     \item The {\em stored} specifier.
    @@ -5229,6 +5229,10 @@
     the stream by the streaming system, even if \var{Stored} was \var{True}.
     The default value is stored in the RTTI that is generated for the class. 
     
    +String, floating-point and pointer properties have implicit \var{default}
    +value of empty string, 0 or nil, respectively.
    +Ordinal and set properties have no implicit \var{default} value.
    +
     The {\em nodefault specifier} (\var{nodefault}) must be used to indicate 
     that a property has no default value. The effect is that the value of this
     property is always written to the stream when streaming the property, if
    @@ -5243,6 +5247,12 @@
     internally to denote \var{nodefault}.
     \item It is not possible to specify a default for array properties.
     \item It is not possible to specify the \var{Stored} directive for array properties.
    +\item All storage specifiers can be overriden in descendent classes.
    +\begin{verbatim}
    +property Test stored False;
    +\end{verbatim}
    +\item The {\em nodefault specifier} can be used to override the implicit
    +{\em default specifier} of string, floating-point and pointer properties.
     \item The streaming mechanism described here is the one implemented in the
     \file{classes} unit of the RTL. Other streaming mechanisms can be
     implemented, and they can use the RTTI information in a different way.
    

Activities

Michael Van Canneyt

2018-04-05 08:08

administrator   ~0107624

"The stored and (no)default modifiers are independent on each other."

The docs do not claim otherwise. They state that these constructs save the same purpose: control whether a property is written to stream or not.

I will rephrase it.

Ondrej Pokorny

2018-04-05 08:41

developer   ~0107626

Yes and no - feel free to change it.

The docs say "The nodefault specifier (nodefault) must be used to indicate that a property has no default value. The effect is that the value of this property is always written to the stream when streaming the property." - which is not true. The stored modifier is taken into account as well, so nodefault isn't streamed when "Stored False" is used.

With "The stored and (no)default modifiers are independent on each other." I wanted to stress that always both "Stored" and "Default" modifiers are evaluated. And not that nodefault implies "Stored True" and vice versa - which is now the case and it is a bug (0033564).

Again, feel free to make the docs clearer. People are really confused about the storage modifiers. Delphi has nice and clear docs for this purpose: http://docwiki.embarcadero.com/RADStudio/Tokyo/en/Properties_(Delphi)#Storage_Specifiers

Michael Van Canneyt

2018-04-14 11:17

administrator   ~0107774

Reworked that section.

Also made it clear that this is how the classes unit processes the RTTI.

Ondrej Pokorny

2018-04-14 11:57

developer   ~0107778

Very good, thank you. Now it is clear.

Just a small remark: you forgot to include information about the implicit default value for strings/floating point numbers/pointers.

I also added a note about overriding storage properties.

See the patch. I hope it's valid TeX, it's been a while when I used it the last time.

Ondrej Pokorny

2018-04-14 11:57

developer  

property-storage-01.patch (1,833 bytes)
Index: ref.tex
===================================================================
--- ref.tex	(revision 1477)
+++ ref.tex	(working copy)
@@ -5203,7 +5203,7 @@
 The compiler offers 2 mechanisms to control whether a property is streamed
 using a streaming mechanism, such as the one implemented in the classes
 unit. These mechanisms write extra information to the generated RTTI, which
-is later on in the streaming system:
+is later used in the streaming system:
 
 \begin{enumerate}
 \item The {\em stored} specifier.
@@ -5229,6 +5229,10 @@
 the stream by the streaming system, even if \var{Stored} was \var{True}.
 The default value is stored in the RTTI that is generated for the class. 
 
+String, floating-point and pointer properties have implicit \var{default}
+value of empty string, 0 or nil, respectively.
+Ordinal and set properties have no implicit \var{default} value.
+
 The {\em nodefault specifier} (\var{nodefault}) must be used to indicate 
 that a property has no default value. The effect is that the value of this
 property is always written to the stream when streaming the property, if
@@ -5243,6 +5247,12 @@
 internally to denote \var{nodefault}.
 \item It is not possible to specify a default for array properties.
 \item It is not possible to specify the \var{Stored} directive for array properties.
+\item All storage specifiers can be overriden in descendent classes.
+\begin{verbatim}
+property Test stored False;
+\end{verbatim}
+\item The {\em nodefault specifier} can be used to override the implicit
+{\em nodefault specifier} of string, floating-point and pointer properties.
 \item The streaming mechanism described here is the one implemented in the
 \file{classes} unit of the RTL. Other streaming mechanisms can be
 implemented, and they can use the RTTI information in a different way.

Ondrej Pokorny

2018-04-14 11:59

developer  

property-storage-02.patch (1,831 bytes)
Index: ref.tex
===================================================================
--- ref.tex	(revision 1477)
+++ ref.tex	(working copy)
@@ -5203,7 +5203,7 @@
 The compiler offers 2 mechanisms to control whether a property is streamed
 using a streaming mechanism, such as the one implemented in the classes
 unit. These mechanisms write extra information to the generated RTTI, which
-is later on in the streaming system:
+is later used in the streaming system:
 
 \begin{enumerate}
 \item The {\em stored} specifier.
@@ -5229,6 +5229,10 @@
 the stream by the streaming system, even if \var{Stored} was \var{True}.
 The default value is stored in the RTTI that is generated for the class. 
 
+String, floating-point and pointer properties have implicit \var{default}
+value of empty string, 0 or nil, respectively.
+Ordinal and set properties have no implicit \var{default} value.
+
 The {\em nodefault specifier} (\var{nodefault}) must be used to indicate 
 that a property has no default value. The effect is that the value of this
 property is always written to the stream when streaming the property, if
@@ -5243,6 +5247,12 @@
 internally to denote \var{nodefault}.
 \item It is not possible to specify a default for array properties.
 \item It is not possible to specify the \var{Stored} directive for array properties.
+\item All storage specifiers can be overriden in descendent classes.
+\begin{verbatim}
+property Test stored False;
+\end{verbatim}
+\item The {\em nodefault specifier} can be used to override the implicit
+{\em default specifier} of string, floating-point and pointer properties.
 \item The streaming mechanism described here is the one implemented in the
 \file{classes} unit of the RTL. Other streaming mechanisms can be
 implemented, and they can use the RTTI information in a different way.

Michael Van Canneyt

2018-04-14 12:03

administrator   ~0107780

Additional patch applied in 1480. Thanks !

Ondrej Pokorny

2018-04-14 12:09

developer   ~0107781

Thank you!

Now, we only need the streaming bugs 0033563, 0033564 and 0033035 get fixed so that the compiler corresponds with the docs and everything is perfect :)

Issue History

Date Modified Username Field Change
2018-04-05 01:31 Ondrej Pokorny New Issue
2018-04-05 01:31 Ondrej Pokorny Status new => assigned
2018-04-05 01:31 Ondrej Pokorny Assigned To => Michael Van Canneyt
2018-04-05 08:08 Michael Van Canneyt Note Added: 0107624
2018-04-05 08:41 Ondrej Pokorny Note Added: 0107626
2018-04-14 11:17 Michael Van Canneyt Fixed in Revision => 1476
2018-04-14 11:17 Michael Van Canneyt Note Added: 0107774
2018-04-14 11:17 Michael Van Canneyt Status assigned => resolved
2018-04-14 11:17 Michael Van Canneyt Fixed in Version => 3.1.1
2018-04-14 11:17 Michael Van Canneyt Resolution open => fixed
2018-04-14 11:17 Michael Van Canneyt Target Version => 3.2.0
2018-04-14 11:57 Ondrej Pokorny Note Added: 0107778
2018-04-14 11:57 Ondrej Pokorny Status resolved => feedback
2018-04-14 11:57 Ondrej Pokorny Resolution fixed => reopened
2018-04-14 11:57 Ondrej Pokorny File Added: property-storage-01.patch
2018-04-14 11:59 Ondrej Pokorny File Added: property-storage-02.patch
2018-04-14 12:03 Michael Van Canneyt Note Added: 0107780
2018-04-14 12:03 Michael Van Canneyt Status feedback => resolved
2018-04-14 12:03 Michael Van Canneyt Resolution reopened => fixed
2018-04-14 12:09 Ondrej Pokorny Note Added: 0107781
2018-04-14 12:09 Ondrej Pokorny Status resolved => closed