Wiki improvements

Forum for discussion about the documentation project.
coderJeff
Site Admin
Posts: 2680
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Aug 14, 2018 15:44

badidea wrote:I think I got another addition. There seems to be no .. page. Don't know if it has a name.


Indeed. To compare, in C++ there is '::' scope resolution operator, and '.' member access operator. In fbc we use '.' (dot) operator for both, for example:

Code: Select all

namespace N1
   dim X as integer
end namespace

namespace N2
   dim X as integer
end namespace

using N1 '' import namespace
using N2 '' import namespace

print N1.X  '' OK '.' operator resolves scope
print N2.X  '' OK '.' operator resolves scope

print X  '' error: abiguous symbol access


But, '.' operator on its own does not let us resolve scope to global namespace. To refer to the global namespace, we have '..' operator. For example:

Code: Select all

sub proc()
   print "global proc()"
end sub

namespace N
   const false as integer = 111
   const true as integer = 999
   
   sub proc()
      print "N.proc()"
   end sub
   
   sub test()
      proc()    '' call N.proc()   
      ..proc()  '' call global proc()

      '' N.false, N.true
      print false, true
      
      '' global false, true
      print ..false, ..true

   end sub
end namespace

N.test()


I suggest new page KeyPgOpScope for an additional page on '.', and KeyPgOpGlobalScope for undocumented '..', but whatever you guys think. The existing KeyPgOpMemberAccess is about an operator that works on expression, but '.' & '..' for scope resolution operates on symbol names.

Also, not sure if this is a bug or a side effect of shadowing, or just a bad example on my part:

Code: Select all

'' not quite the same for variables
dim y as integer = 1
scope
   dim y as integer = 2
   print y   '' prints 2
   print ..y '' prints 2
end scope
fxm
Posts: 8283
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 14, 2018 16:37

See this bug report:
#645 Access to global duplicated symbol is captured by local symbol

(I do not know if it's a good time to create new pages on these bugged features!)
coderJeff
Site Admin
Posts: 2680
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Aug 14, 2018 20:02

Hmm. No documentation at all? I dunno. If we wrote the documentation when the feature was added, we would have both documentation and a bug report. And at least we would have an expectation of what the feature should do.
fxm
Posts: 8283
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 14, 2018 20:30

Other subject: A potential new article #17 ?

About:
    How to use implicit / overload New([]) and Delete([]) operators in a polymorphic context
I already wrote a thread around that topic and I highlighted the cases of bad functioning when calling the Delete([]) operator in a subtype polymorphic context. I also wrote a bug report and a small note in documentation about that, proposing also a workaround.

Perhaps I could develop all this in an article, adding in a first part the normal and successful use of these operators in less complex cases (simpler UDT):
    17. How to Use Implicit / Overload New([]) and Delete([]) FB Operators with Simple UDT up to Subtype Polymorphism
    • implicit New ... implicit Delete,
    • Implicit New[] ... implicit Delete[],
    • placement New ... Destructor call on member,
    • overload New ... overload Delete,
    • overload New[] ... overload Delete[].
MrSwiss
Posts: 2728
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Postby MrSwiss » Aug 15, 2018 16:15

coderJeff wrote:Is it possible to discuss references without discussing pointers?
Well, there goes another one:
"Is it possible, to write about threading, without discussing pointers first?"
(or at least state: you have to be confident with pointers use, to understand the following ...)

There may be more, similar questions ...
Reason:
Pointers are a pre-condition for more, than just a single part of the FB language!

coderJeff wrote:Byref variables so much different?
I'd say yes "off hand", referring to the rather complex "handling" ...
They should first of all, be made usable in Type's (e.g. use byref, instead of properties).

Currently IMO badly missing (like Const arrays), are byref arrays, which would really start,
to make them "useful", in a more general context (than polymorpism and such like).
fxm
Posts: 8283
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 15, 2018 19:09

coderJeff wrote:@fxm, I noticed that the BYREF variable feature works great for some situations. In other situations, fbc might segfault, or the user program will segfault. I will follow up in what I think was original thread viewtopic.php?&t=23584

@MrSwiss,
The technical discussions (except concerning the documentation) on the Byref variables were reactivated by coderJeff and dkl in the thread cited above.
Please use it.
MrSwiss
Posts: 2728
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Postby MrSwiss » Aug 15, 2018 19:19

@fxm,
MrSwiss wrote:Pointers are a pre-condition for more, than just a single part of the FB language!
This definitely relates to doc. Actually meaning:
your introduction part about pointers, should be made a article "in itself",
because it applies to more cases, than just the "byref" stuff. (threads!)
fxm
Posts: 8283
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 15, 2018 20:35

MrSwiss wrote:@fxm,
your introduction part about pointers, should be made a article "in itself",
because it applies to more cases, than just the "byref" stuff.

It's just a reminder.
There are already several pages on pointers in documentation (see Programmer's Guide, Community Tutorials).
MrSwiss
Posts: 2728
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Postby MrSwiss » Aug 16, 2018 11:12

fxm wrote:There are already several pages on pointers in documentation (see Programmer's Guide, Community Tutorials).
Fine, if they where "up to standard", which especially "Inroduction to pointers ..." is clearly not.
Main issue is:
the permanent reference to "reference operator *", which is in fact "dereference operator *"!
Sorry to state but, that sort of thing is "very confusing", to say the least!
(Especially for beginners, which it is clearly aimed at. Should be replaced, IMO)
coderJeff
Site Admin
Posts: 2680
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Aug 16, 2018 14:02

MrSwiss wrote:Main issue is:
the permanent reference to "reference operator *", which is in fact "dereference operator *"!
Sorry to state but, that sort of thing is "very confusing", to say the least!
(Especially for beginners, which it is clearly aimed at. Should be replaced, IMO)


I think the most confusing part of the reference/dereference terminology is that "dereference" is misleading of what the operator actually does. "dereference" sounds like it is taking away a reference.

The "dereference" operator '*' actually returns a reference, i.e. *EXPR returns a reference to the value pointed to by EXPR. In otherwords, the '*' operator converts a pointer to a reference. '@' operator does the opposite and converts a reference to a pointer.

Here is some sample code with comments that steps through a comparison of accessing variables through references and pointers.

Code: Select all

sub ModifyInt( byref i as integer )
   i += 1
end sub

'' X is implicit reference to integer holding the value '3'
dim X as integer = 3
print "@X = " & @X,
print "X = " & X

'' Y is explicit reference to same integer as X
dim byref Y as integer = X
print "@Y = " & @Y,
print "Y = " & Y

'' Z is explicit reference to a pointer value containing memory location of X's value
'' Z is pointer to X, and *Z is reference to X
dim Z as integer ptr = @X
print "Z = " & Z,
print "*Z = " & *Z

'' dereference operator '*' on pointer RETURNS A REFERENCE
'' we can assign it, take the address of it, or pass to a
'' procedure's byref argument
*Z = 4
print "*Z = " & *Z
ModifyInt( *Z )
print "*Z = " & *Z
print "@*Z = " & @*Z

'' to get the actual value we use some other access on it, like in an expression
dim V as integer = cint(*Z)
print "V = " & V

'' we can't dereference a value, ever
'' print "*cint(Z) = " & *cint(Z) ' error

'' but we can take address of the expression, but it is now somewhere
'' else completely different than original X, Y, *Z
print "@cint(Z) = " & @cint(Z)

/' OUTPUT:

@X = 1638080   X = 3
@Y = 1638080  Y = 3
Z = 1638080   *Z = 3
*Z = 4
*Z = 5
@*Z = 1638080
V = 5
@cint(Z) = 1638024

'/
MrSwiss
Posts: 2728
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Postby MrSwiss » Aug 16, 2018 14:30

coderJeff wrote:"dereference" sounds like it is taking away a reference.
Well, I tend to look at it from the pointer itself, which is dereferenced,
to get/set the "value it points to" (debatable, for sure).
Personally, I've only understood pointers, after that sort of "explanation".
(IMPORTANT: not yet knowing anything about references, themselfs!)

Main problem from my point of view is exactly rooted in "terminology".
Because it tends to rely on not yet existing know-how ... (chicken/egg problem).

What I am trying to get at is something like doing it step by step (easy to heavy):
    1) Variables
    2) Pointers (explanations without referral to references, variables only)
    3) References (easily explained with pointers know-how)
But I may be wrong on that ...
Last edited by MrSwiss on Aug 16, 2018 15:26, edited 1 time in total.
fxm
Posts: 8283
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 16, 2018 15:22

I think each one has his own understanding.
Mine is this:
- "Referencing a variable" means accessing the memory address of the variable (this address is often used to initialize a pointer value).
- "Dereferencing a variable" means accessing the variable stored at a memory address (this address is often given from a pointer value).

So, in everyday language, we outright speak (with a little abuse) of:
- "Referencing a pointer" means initialize the pointer value with the memory address of a variable (using the @ operator with the variable name). The variable type must be compatible with the type of the pointer.
- "Dereferencing a pointer" means access (in read and in write) a variable stored at the memory address given from the pointer value (using the * operator with the pointer name). The variable type is deduced from the type of the pointer.
coderJeff
Site Admin
Posts: 2680
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Aug 16, 2018 21:08

MrSwiss wrote:But I may be wrong on that ...

I don't think you are wrong. It's a good point. I think either perspective is valid. If a programmer was familiar with PHP or LISP, the reverse might be a better approach. They probably already have good understanding of references, and could explain pointers in terms of references. As best we can should try to approach pointers vs references separately, and still compare them at some point, because the implementation allows us to do so. Hopefully the beginner will get it somehow.

fxm, well put. referencing/dereferencing in the context of pointer use. I have this feeling that even with the wiki cleaned up with consistent use of terminology, this just going to be a tough concept to get.

OK, I'm just playing with words now, so don't take too seriously... note the "reference" vs "Reference" ...

reference = refer to something
indirection = synonym for reference
pointer = indirection exposed to programmer
Reference = indirection hidden from programmer
dereference = convert indirection exposed to programmer to indirection hidden from programmer
'@' reference operator = convert Reference to reference
'*' dereference operator = convert reference to Reference

Kind of highlights the overuse of "reference" in this concept/topic, lol.
MrSwiss
Posts: 2728
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Postby MrSwiss » Aug 16, 2018 22:08

coderJeff wrote:Kind of highlights the overuse of "reference" in this concept/topic, lol.
Yes, the "level of indirection" could be a different approach, to stated dilemma. Aka:
    first level = Pointer (exposed indirection)
    second level = Reference (hidden indiretion/*ptr)
Maybe?!?
fxm
Posts: 8283
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 22, 2018 12:51

fxm wrote:Other subject: A potential new article #17 ?

About:
    How to use implicit / overload New([]) and Delete([]) operators in a polymorphic context
I already wrote a thread around that topic and I highlighted the cases of bad functioning when calling the Delete([]) operator in a subtype polymorphic context. I also wrote a bug report and a small note in documentation about that, proposing also a workaround.

Perhaps I could develop all this in an article, adding in a first part the normal and successful use of these operators in less complex cases (simpler UDT):
    17. How to Use Implicit / Overload New([]) and Delete([]) FB Operators with Simple UDT up to Subtype Polymorphism
    • implicit New ... implicit Delete,
    • Implicit New[] ... implicit Delete[],
    • placement New ... Destructor call on member,
    • overload New ... overload Delete,
    • overload New[] ... overload Delete[].

Maybe this article is a bit too technical (especially in its second part) to interest a significant number of people.
For my own person, the only interest I see there is to reorder on paper (and therefore in my mind) all the information that I have accumulated by doing lots of tests in this area (from the simplest configurations to the most complex).

Return to “Documentation”

Who is online

Users browsing this forum: No registered users and 1 guest