Wiki improvements

Forum for discussion about the documentation project.
fxm
Posts: 9083
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 12, 2019 19:48

I consider that:
  • For simple variables (including fix-len arrays) declared anywhere, as follows:
    Dim [Byref] [Shared] As datatype [Ptr] variablename
    or
    Static [Byref] Shared As datatype [Ptr] variablename
    they always have a lifetime related to their scope.
  • For simple variables (including fix-len arrays) declared as follows:
    Static [Byref] As datatype [Ptr] variablename
    they always have a lifetime equal to the program duration, so irrelevant to their scope if there are declared in scope blocks (including procedure scopes).
For the other keywords used to declare a dynamic allocation ([Re]Allocate, New, Imagecreate), they create an unnamed entity whose the lifetime depends on other commands of user (Deallocate, Delete, Imagedestroy):
  • Generally, these allocation keywords are included in expressions used to assign or initialize a simple variable as above.
  • Therefore, in this case, there are two distinct entities: a named pointer (or a reference) the first entity, pointing (or referring) to an allocated memory the second entity (unnamed).
  • Do not confuse the two entities, each has its own lifetime (Deallocate, Delete, Imagedestroy deallocating only the second entity, not the first).
In the same way, one can consider a var-len string or var-len array as a predefined assembly of two entities: a descriptor associated to the variable-name, and referring to a dynamic allocation in memory (the string data or the array data).
The string data being [re|de]allocated by string assignment, and array data being [re]allocated by Redim and deallocated by Erase (Erase does not destroy the descriptor but just re-initializes it).

Note:
Var [Byref] [Shared] variablename = expression
is equivalent to:
Dim [Byref] [Shared] As Typeof(expression) variablename = expression
coderJeff
Site Admin
Posts: 2964
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Aug 13, 2019 1:09

fxm, overall, a good summary. I would like to focus on a couple of points:

fxm wrote:1) Do not confuse the two entities, each has its own lifetime (Deallocate, Delete, Imagedestroy deallocating only the second entity, not the first)
2) In the same way, one can consider a var-len string or var-len array as a predefined assembly of two entities: a descriptor associated to the variable-name, and referring to a dynamic allocation in memory (the string data or the array data).


I don't know, maybe it would make sense to have two topics.
1) "Variable Scope and Lifetime" - beginner, most common use cases
2) "Object and Data Lifetime" - advanced, more detailed mechanics of allocation/deallocation, pointers & references

For example:

Code: Select all

scope
   dim a as string = "first"
   dim p as zstring ptr = strptr(a)
   print a, *p '' OK
   a += ", second, reallocated if quite a bit longer"
   print a, *p '' Not OK
end scope


Scope and lifetime of "a" and "p" entities are essentially the same. But, the lifetime of data entity to which "a" and "p" refers (may) change within the scope due to reassignment of the string
- when referring to the data by "a", lifetime of the data is irrelevant
- when referring to the data by "*p", lifetime of data is relevant
fxm
Posts: 9083
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 13, 2019 5:26

And so to make well the difference between a pointer or a reference to a var-len string (by the address of its descriptor) and a pointer or a reference to its data only (by the address of these ones):

Code: Select all

scope
   dim s as string = "first"
   dim ps as string ptr = @s
   dim byref rs as string = s
   dim pz as zstring ptr = strptr(s)
   dim byref rz as Zstring = *strptr(s)
   print s
   print *ps '' OK
   print rs  '' OK
   print *pz '' OK
   print rz  '' OK
   s &= ", second, reallocated if quite a bit longer"
   print s
   print *ps '' OK
   print rs  '' OK
   print *pz '' Not OK
   print rz  '' Not OK
end scope
fxm
Posts: 9083
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 13, 2019 14:24

coderJeff wrote:maybe it would make sense to have two topics.
1) "Variable Scope and Lifetime" - beginner, most common use cases
2) "Object and Data Lifetime" - advanced, more detailed mechanics of allocation/deallocation, pointers & references

Therefore, I propose for the "Programmer's Guide / Declarationns" section:
  • Keeping the existing page "Variable Scope" for the moment (but suppressing the empty page "Variable Lifetime").
  • Filling in 2 new pages (after "Variable Scope") rather focused on the lifetime:
      - "Variable Lifetime versus Scope" - predefined simple variables, excluding var-len strings and var-len arrays, static simple UDT instances.
      - "Object and Data Lifetime" - all dynamic objects, including var-len strings and var-len arrays.
Declarations
    Implicit Declarations
    Initialization
    Storage Classes
    Variable Scope
    Variable Lifetime versus Scope
    Object and Data Lifetime
    Namespaces
    Variable and Procedure Linkage
fxm
Posts: 9083
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 19, 2019 5:27

'Namespaces' page filled in the Programmer's Guide / Declarations:
- ProPgNamespaces → fxm [new page created]
- CatPgProgrammer → fxm [added link to "Namespaces" page]
- PrintToc → fxm [added link to "Namespaces" page]
fxm
Posts: 9083
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Aug 19, 2019 12:04

fxm wrote:
coderJeff wrote:maybe it would make sense to have two topics.
1) "Variable Scope and Lifetime" - beginner, most common use cases
2) "Object and Data Lifetime" - advanced, more detailed mechanics of allocation/deallocation, pointers & references

Therefore, I propose for the "Programmer's Guide / Declarationns" section:
  • Keeping the existing page "Variable Scope" for the moment (but suppressing the empty page "Variable Lifetime").
  • Filling in 2 new pages (after "Variable Scope") rather focused on the lifetime:
      - "Variable Lifetime versus Scope" - predefined simple variables, excluding var-len strings and var-len arrays, static simple UDT instances.
      - "Object and Data Lifetime" - all dynamic objects, including var-len strings and var-len arrays.
Declarations
    Implicit Declarations
    Initialization
    Storage Classes
    Variable Scope
    Variable Lifetime versus Scope
    Object and Data Lifetime
    Namespaces
    Variable and Procedure Linkage

Jeff,

What do you think of this cutting?
Can I start this way?

FX
coderJeff
Site Admin
Posts: 2964
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Aug 22, 2019 13:17

fxm, yes, go for it. Thank you. It's good to have your expertise added to the programmer's guide. You should feel free to cut and rearrange topics as needed. Also, if it makes sense to rename or delete pages, just go ahead as needed because if we really had to get an old version, the pages are also stored in the repo. Besides, I don't think we would need to go back to old versions because of your thoroughness of content. :)

Return to “Documentation”

Who is online

Users browsing this forum: No registered users and 14 guests