Operator [] (Pointer Index) - Wiki

Forum for discussion about the documentation project.
MrSwiss
Posts: 1738
Joined: Jun 02, 2013 9:27
Location: Switzerland

Operator [] (Pointer Index) - Wiki

Postby MrSwiss » Jun 27, 2017 12:30

IMHO, not very clear about the automatic "dereferencing", taking place ...

There is only: in the second sentence, "It is essentially shorthand for "*(lhs + rhs)"; both do exactly the same thing."
While this might be sufficient for people with some experience, a beginner is unlikely to understand: *(lhs + rhs) without,
some textual explanation (step by step) of what exactly is happening. The term "dereference" isn't anywhwere to be found.

The very terse first explanation, is therefore actually wrong, because it says:
"Returns a reference to memory offset from an address", which it doesn't, otherwise, we'd still have to "dereference" it!
(to get at the value)
should be:
"Returns a dereferenced value, from a reference to memory offset from an address"

It also appears to break the pointer rule #1:
to get at the value (it points to), dereference it.
It introduces a "inconsistency".
fxm
Posts: 6993
Joined: Apr 22, 2009 12:46
Location: Paris suburb, FRANCE

Re: Operator [] (Pointer Index) - Wiki

Postby fxm » Jun 27, 2017 18:24

The operator [] (Pointer Index) actually returns a reference and not only a value:
    Declare Operator [] ( ByRef lhs As T Pointer, ByRef rhs As Integer ) ByRef As T
A reference is an entity that is a way to access (in read and in write) data located in memory. A reference can be thought of as a pointer that is implicitly dereferenced.
So a reference does not need of any dereferencing by user to access the data value.

Usage of pointer indexing is not advisable to beginners, but they can find more information in the following tutorials:
MrSwiss
Posts: 1738
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Operator [] (Pointer Index) - Wiki

Postby MrSwiss » Jun 27, 2017 19:38

fxm wrote:A reference can be thought of as a pointer that is implicitly dereferenced.
In this case, why isn't this explained (this way) in the reference?
This would definitely explain the behaviour, far clearer, than the current explanation, does ...

fxm wrote:Usage of pointer indexing is not advisable to beginners, but they can find more information in the following tutorials
How are they supposed, to find them?
The cited manuals, tutorials etc., should also be added as: further information, can be found in ...
(with links)
Last edited by MrSwiss on Jun 27, 2017 20:00, edited 1 time in total.
fxm
Posts: 6993
Joined: Apr 22, 2009 12:46
Location: Paris suburb, FRANCE

Re: Operator [] (Pointer Index) - Wiki

Postby fxm » Jun 27, 2017 20:00

This explanation is extracted from what I wrote in the recent page BYREF (variables)

KeyPgOpPtrIndex → fxm [Added a very small explanation]
MrSwiss
Posts: 1738
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Operator [] (Pointer Index) - Wiki

Postby MrSwiss » Jun 27, 2017 21:07

Thanks fxm, far better explanation (than before).
speedfixer
Posts: 195
Joined: Nov 28, 2012 1:27

Re: Operator [] (Pointer Index) - Wiki

Postby speedfixer » Jun 28, 2017 15:01

It is better, but:

fxm wrote:

Postby fxm » Jun 27, 2017 20:00
This explanation is extracted from what I wrote in the recent page BYREF (variables)

KeyPgOpPtrIndex → fxm [Added a very small explanation]


How do we get from any place in

http://www.freebasic.net/wiki/wikka.php ... OpPtrIndex

to byref?

Are you asking a newbie click on every blue text on any page to **hopefully** find an explanation? This will give a lot of frustration.

lhs and rhs are used everywhere, for example, but no entry in the glossary where you would expect. SOMEWHERE I'm sure they are defined, but how would one search for this?

A great many terms are missing in that glossary that a newbie needs.
How about a tiny change, something that educates and explains at the same time:

from:

" This operator returns a reference to a value some distance in memory from a base address. "

to:

" This operator returns a memory location (reference) to a value some distance in memory from a base address. "

No question or doubt about what is returned, even for a newbie.

David


BTW: rhs and lhs are NOT explained in either tutorial referenced in this discussion.
fxm
Posts: 6993
Joined: Apr 22, 2009 12:46
Location: Paris suburb, FRANCE

Re: Operator [] (Pointer Index) - Wiki

Postby fxm » Jun 28, 2017 16:58

Very well known acronyms:
    RHS = Right Hand Side
    LHS = Left Hand Side
speedfixer
Posts: 195
Joined: Nov 28, 2012 1:27

Re: Operator [] (Pointer Index) - Wiki

Postby speedfixer » Jun 28, 2017 17:59

Assuming one isn't new to all this, true.

The topic is clarity and helping a NEW programmer, not catering to old guys.
MrSwiss
Posts: 1738
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Operator [] (Pointer Index) - Wiki

Postby MrSwiss » Jun 28, 2017 19:19

speedfixer wrote:The topic is clarity and helping a NEW programmer, not catering to old guys.
I'm 100% with speedfixer, on the issue.
MrSwiss wrote:
fxm wrote:Usage of pointer indexing is not advisable to beginners, but they can find more information in the following tutorials
How are they supposed, to find them?
As well as, how are they supposed, to ever learn it?
MrSwiss wrote:The cited manuals, tutorials etc., should also be added as: further information, can be found in ... (with links)
St_W
Posts: 852
Joined: Feb 11, 2009 14:24
Location: Austria
Contact:

Re: Operator [] (Pointer Index) - Wiki

Postby St_W » Jun 28, 2017 19:29

That sounds like well known problem: Either we explain it in a very detailed level, which will result in lots of text (bloat), which is bad for readability and overview, but may be better for beginners. Or we do the opposite an assume a lot of prior knowledge, which will allow compact and yet precise descriptions, but will be probably hard to understand for beginners. Neither is ideal and no solution will make everybody happy. So the best solution will be something in between the two extremes that won't cause bloat but explains non-obvious things.
Same for the "related" links: if there are too many of them you won't find the interesting things, otherwise you might cannot reach some related information directly.
However, there are beginner tutorials and different ways to find content (search, index, table of contents, context pages, ...), so I don't think we need to add that many links. Yet, it won't hurt that much if a link is placed on existing text.
fxm
Posts: 6993
Joined: Apr 22, 2009 12:46
Location: Paris suburb, FRANCE

Re: Operator [] (Pointer Index) - Wiki

Postby fxm » Jun 28, 2017 20:16

speedfixer wrote:How about a tiny change, something that educates and explains at the same time:

from:

" This operator returns a reference to a value some distance in memory from a base address. "

to:

" This operator returns a memory location (reference) to a value some distance in memory from a base address. "

No question or doubt about what is returned, even for a newbie.

A reference is not a memory location but an entity that is a way to access data at a memory location (under the hood a pointer having as value the memory location, and which is implicitly dereferenced):
    @reference = memory_location_value
speedfixer
Posts: 195
Joined: Nov 28, 2012 1:27

Re: Operator [] (Pointer Index) - Wiki

Postby speedfixer » Jun 28, 2017 21:38

I know the difference between a memory location and a reference, but a newbie doesn't, and I don't think it should be covered in this keyword page.

If someone doesn't already know, you haven't made it more clear and are not likely to make it better.

AND

the fact remains:

NOT in glossary, and from search on forum:
Information

The following words in your search query were ignored because they are too common words: +lhs.
You must specify at least one word to search for. Each word must consist of at least 4 characters and must not contain more than 84 characters excluding wildcards.


reference: Glossary:

R

ragged array (container)
A ragged array is an array having rows of differing lengths.

real number
Any positive or negative number including fractions, irrational and transcendental numbers (like pi or e) and zero. Variables containing a real number have a limited range and precision depending on the number of bits used to represent the number. See: Single and Double.

registers
Places inside the CPU for data storage. 80386 and compatible 32-bit models have EAX, EBX, ECX, EDX, ESI, EDI, EBP and ESP, plus some special (control/test/debug) registers. NOT related to "Windows registry".


no 'reference' here

I don't expect that FB forums or the wiki will answer all questions anyone may have, but if anyone really has a desire of furthering FB and helping the new people, some other better effort and attitude must exist. The beginner's learning curve is already steep - don't try to make it worse.

The keyword entries in the wiki should be like dictionary listings:

brief
cover USUAL possible meanings
HINT at more if needed.

NOT an encyclopedic entry that explains every facet of the word.
New, modern tutorials and advanced topic explanations would be more helpful than changes to the keyword entries, in most cases.

fxm, you have terrific and broad knowledge about programming and programming topics. You more than most make a special effort to try to get the explanations in the wiki correct. Most of the keyword pages are very acceptable. Clearly, you have tested each keyword against your knowledge before you answer the tough questions some people ask.

Don't waste your time on tiny semantics with me: write good and more technical articles on subjects as a tutorials for those that are ready and want to know more.
fxm
Posts: 6993
Joined: Apr 22, 2009 12:46
Location: Paris suburb, FRANCE

Re: Operator [] (Pointer Index) - Wiki

Postby fxm » Jun 29, 2017 11:44

GlossaryIndex → fxm [Added some definitions (LHS, RHS, reference)]
xlucas
Posts: 201
Joined: May 09, 2014 21:19
Location: Argentina

Re: Operator [] (Pointer Index) - Wiki

Postby xlucas » Jun 29, 2017 19:33

I agree with Mr Swiss and Speedfixer. Pointers, in general, is a topic that very difficult to digest for the first time. I believe that formal definitions and details for users who already know the topic are indeed important, but simple descriptions for users who have no idea of what a pointer is are probably more important, because these are more likely to look up this information.
Anyway, it doesn't have to be just one or the other. I have to say I don't know much about how the documentation is maintained, so this is just a humble opinion of mine. But I reckon that, upon searching for the topic, one might get to the simple explanation and get a link to the formal definitions and details if they're interested. I remember the first time I had to face pointers, when I started working in C. From that moment, to the one when I understood what "dereferencing" means, a long time elapsed.
So this is just to support what the guys are saying. In general, FB's help has so far been very, very helpful to me :)

Return to “Documentation”

Who is online

Users browsing this forum: No registered users and 2 guests