http://fpcamigawiki.alb42.de/index.php?title=VarArgs&feed=atom&action=historyVarArgs - Revision history2024-03-29T09:09:58ZRevision history for this page on the wikiMediaWiki 1.35.1http://fpcamigawiki.alb42.de/index.php?title=VarArgs&diff=665&oldid=prevMolly: Typo's2016-03-19T12:28:59Z<p>Typo's</p>
<table class="diff diff-contentalign-left diff-editfont-monospace" data-mw="interface">
<col class="diff-marker" />
<col class="diff-content" />
<col class="diff-marker" />
<col class="diff-content" />
<tr class="diff-title" lang="en">
<td colspan="2" style="background-color: #fff; color: #202122; text-align: center;">← Older revision</td>
<td colspan="2" style="background-color: #fff; color: #202122; text-align: center;">Revision as of 12:28, 19 March 2016</td>
</tr><tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l10" >Line 10:</td>
<td colspan="2" class="diff-lineno">Line 10:</td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>Which, besides being inconsistent, resulted in quite some compiler related errors and/or warnings when attempting to write code that needs to be compiled for all these mentioned targets.</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>Which, besides being inconsistent, resulted in quite some compiler related errors and/or warnings when attempting to write code that needs to be compiled for all these mentioned targets.</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'>−</td><td style="color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div>First of all: the Tags (and respective values) as declared inside SDK (for all platforms) should be of type LongWord, which is a problem given that array of const does not support LongWord's and <del class="diffchange diffchange-inline">generated </del>compiler warnings because of that.</div></td><td class='diff-marker'>+</td><td style="color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div>First of all: the Tags (and respective values) as declared inside SDK (for all platforms) should be of type LongWord, which is a problem given that array of const does not support LongWord's and <ins class="diffchange diffchange-inline">generates </ins>compiler warnings because of that.</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>In order to workaround the array of const issues, all values stored in such array needed to be casted to LongInt.</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>In order to workaround the array of const issues, all values stored in such array needed to be casted to LongInt.</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'>−</td><td style="color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div>Secondly, the array of DWord declaration has the issue of generating compiler warnings when attempting to store signed integers without the stored values being casted to <del class="diffchange diffchange-inline">unassigned </del>integers.</div></td><td class='diff-marker'>+</td><td style="color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div>Secondly, the array of DWord declaration has the issue of generating compiler warnings when attempting to store signed integers without the stored values being casted to <ins class="diffchange diffchange-inline">unsigned </ins>integers.</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>When targeting all 3 platforms with the same source, this resulted in the need to cast both TagNames as well as TagValues to their corresponding underlying implementation (per platform).</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>When targeting all 3 platforms with the same source, this resulted in the need to cast both TagNames as well as TagValues to their corresponding underlying implementation (per platform).</div></td></tr>
<tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l27" >Line 27:</td>
<td colspan="2" class="diff-lineno">Line 27:</td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>* Array of const dragged in unit ObjPas and therefor added a fair amount to the size of the executable</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>* Array of const dragged in unit ObjPas and therefor added a fair amount to the size of the executable</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>* To have/create consistency amongst the platforms Amiga, AROS and MorphOS with regards to their VarArgs usage.</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>* To have/create consistency amongst the platforms Amiga, AROS and MorphOS with regards to their VarArgs usage.</div></td></tr>
<tr><td class='diff-marker'>−</td><td style="color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div>* The chosen type <del class="diffchange diffchange-inline">UIntPtr </del>is more future proof as it (automatically) takes f.e. 64 bit into consideration on compilation.</div></td><td class='diff-marker'>+</td><td style="color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div>* The chosen type <ins class="diffchange diffchange-inline">PtrUInt </ins>is more future proof as it (automatically) takes f.e. 64 bit into consideration on compilation.</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>* Functions and procedures which uses Array of const weren't allowed to be inlined (raised a compiler warning on certain targets and were not actually inlined), while array of PtrUInt allows this for the previously mentioned platforms.</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>* Functions and procedures which uses Array of const weren't allowed to be inlined (raised a compiler warning on certain targets and were not actually inlined), while array of PtrUInt allows this for the previously mentioned platforms.</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l35" >Line 35:</td>
<td colspan="2" class="diff-lineno">Line 35:</td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>== Type PtrUInt ==</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>== Type PtrUInt ==</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'>−</td><td style="color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div>Type PtrUInt is described in the Free Pascal Manual [http://www.freepascal.org/docs-html/rtl/system/ptruint.html here] and <del class="diffchange diffchange-inline">tells us </del>that this type is declared in <del class="diffchange diffchange-inline">the system Unit</del>.</div></td><td class='diff-marker'>+</td><td style="color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div>Type PtrUInt is described in the Free Pascal Manual [http://www.freepascal.org/docs-html/rtl/system/ptruint.html here] and <ins class="diffchange diffchange-inline">mentions </ins>that this type is declared in <ins class="diffchange diffchange-inline">unit System</ins>.</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>Furthermore, we can see that this type is declared as being a DWord(*), meaning it is an unsigned type.</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #202122; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>Furthermore, we can see that this type is declared as being a DWord(*), meaning it is an unsigned type.</div></td></tr>
<!-- diff cache key db624220369-ntdbjym2gu:diff::1.12:old-664:rev-665 -->
</table>Mollyhttp://fpcamigawiki.alb42.de/index.php?title=VarArgs&diff=664&oldid=prevMolly: Initial content2016-03-18T10:06:25Z<p>Initial content</p>
<p><b>New page</b></p><div>VarArgs are used in those functions (usually system api library calls), that accepts a variable amount of values for a single parameter.<br />
<br />
The SDK's of our beloved platforms usually declares two different functions when passing TagLists. One using a pointer to a taglist which contains a structure with (a variable amount of) values, and the other second declaration accepting the variable amount of values (directly) as single parameter.<br />
<br />
VarArgs were (previously) declared:<br />
* on Amiga as Array of DWORD<br />
* on AROS as Array of Const<br />
* on MorphOS as Array of DWORD<br />
<br />
Which, besides being inconsistent, resulted in quite some compiler related errors and/or warnings when attempting to write code that needs to be compiled for all these mentioned targets.<br />
<br />
First of all: the Tags (and respective values) as declared inside SDK (for all platforms) should be of type LongWord, which is a problem given that array of const does not support LongWord's and generated compiler warnings because of that.<br />
<br />
In order to workaround the array of const issues, all values stored in such array needed to be casted to LongInt.<br />
<br />
Secondly, the array of DWord declaration has the issue of generating compiler warnings when attempting to store signed integers without the stored values being casted to unassigned integers.<br />
<br />
When targeting all 3 platforms with the same source, this resulted in the need to cast both TagNames as well as TagValues to their corresponding underlying implementation (per platform).<br />
<br />
<br />
<br />
== Decision ==<br />
<br />
In march 2016 it was decided (and implemented in Free Pascal 3.1.1 trunk) to change the declarations of library functions which accept a variable amount of parameters (so called VarArgs) from "Array of const" to "array of PtrUInt".<br />
<br />
The reason behind that decision was fourfold:<br />
* Array of const dragged in unit ObjPas and therefor added a fair amount to the size of the executable<br />
* To have/create consistency amongst the platforms Amiga, AROS and MorphOS with regards to their VarArgs usage.<br />
* The chosen type UIntPtr is more future proof as it (automatically) takes f.e. 64 bit into consideration on compilation.<br />
* Functions and procedures which uses Array of const weren't allowed to be inlined (raised a compiler warning on certain targets and were not actually inlined), while array of PtrUInt allows this for the previously mentioned platforms.<br />
<br />
!! As of Free Pascal revision 33260 (march 17th 2016) thou shall not use array of const when declaring VarTag library functions !!<br />
<br />
<br />
== Type PtrUInt ==<br />
<br />
Type PtrUInt is described in the Free Pascal Manual [http://www.freepascal.org/docs-html/rtl/system/ptruint.html here] and tells us that this type is declared in the system Unit.<br />
<br />
Furthermore, we can see that this type is declared as being a DWord(*), meaning it is an unsigned type.<br />
<br />
(*) Dword, but with an exception: PtrUInt is an unsigned integer type which has always the same size as a pointer. When using integers which will be cast to pointers and vice versa, use this type, never the regular Cardinal type.<br />
<br />
Therefore, the size of variables declared as PtrUInt will have a different size depending on the target platform (16-bit vs 32-bit vs 64-bit).<br />
<br />
<br />
== Usage ==<br />
<br />
As for an example, let's take a look at the declaration of intuition library function OpenWindowTags().<br />
<br />
declaration:<br />
function OpenWindowTags(newWindow: PNewWindow; tagList: array of PtrUInt): PWindow;<br />
<br />
<br />
In order to call this function, we should use the following code:<br />
<br />
MyWindow := OpenWindowTags(nil, <br />
[<br />
WA_Title, 'Close the Window to Quit',<br />
WA_..tagname.., ..tagvalue..<br />
TAG_END<br />
])<br />
<br />
<br />
== Implications ==<br />
<br />
<br />
The change from Array of Const to Array of PtrUInt should not really have important impact on your existing sources, except when you explicitly (pre)declared your varargs/taglist with already filled variables and attempt to pass that along such a function.<br />
<br />
In that case, you should take note that such array declaration must now be of type PtrUInt (and not of type ULONG, SLONG or otherwise).<br />
<br />
Another issue that might perhaps be encountered is the fact that (provided) TagNames and actual TagValues are now being interpreted as PtrUInt. (depending on the platform the source targets, this can raise compiler warnings and/or hints).<br />
<br />
'''In case you were used to cast those tagnames/values as ULONG and/or SLONG, then now is the time to stop doing that''' (there is actually no need anymore), and '''instead use''' the special crafted (inline) '''function AsTag()''' (available inside unit Utility) that have overload versions for each type allowed inside such a taglist.<br />
<br />
With the introduction of Array of PtrUInt as VarArgs, '''it was also decided to declare unit SystemVarTags for Amiga as being obsolete'''. All varargs related functions (previously declared inside unit SystemVarTags) now resides in their own corresponding units.<br />
<br />
<br />
== Examples ==<br />
<br />
<br />
=== Calling a library function ===<br />
<br />
Insert code here<br />
<br />
<br />
=== (Pre)defining array values ===<br />
<br />
Insert code here<br />
<br />
<br />
=== Handling VarArgs manually ===<br />
<br />
Insert code here</div>Molly