String index doc

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

Re: String index doc

Postby fxm » Mar 02, 2021 19:27

With everything I added in this doc page, I think I'm listening a bit to comments and suggestions, even a little to the detriment of concision.
caseih
Posts: 1647
Joined: Feb 26, 2007 5:32

Re: String index doc

Postby caseih » Mar 02, 2021 19:35

EDIT. Delete post. I am no longer sure who claims to have insulted whom. I support fxm in locking threads that get out of hand. From what I can see fxm has tried to be civil.
jj2007
Posts: 2040
Joined: Oct 23, 2016 15:28
Location: Roma, Italia
Contact:

Re: String index doc

Postby jj2007 » Mar 02, 2021 20:51

speedfixer wrote:jj2007: again - if the other languages are so much better, if you don't like FB, why are you here?
I like BASIC, and FreeBasic is even better. I could pass back the question: if you are so fond of C++ concepts, why do you waste your time on a BASIC forum? Why are some people so eager to turn FreeBASIC into a caricature of C++? And no, I don't want to quote Dijkstra right now ;-)

The confusion comes IMHO from two potential uses of the [] operator:

Code: Select all

Dim a As String = "Hello world"
Dim Byref As ubyte r=a[6]
Dim As ubyte c

' asm int 3
c = a[6]   ' the operator [] returns a simple NUMBER (a ubyte in this case)
' asm int 3
r = a[6]   ' the operator [] returns a REFERENCE, which can be used e.g. as r=123
' asm int 3
print "c=";c
print "r=";r
c=88   ' uppercase "X"
print "The string: ";a
r=88
print "The string: ";a
Sleep
Output:

Code: Select all

The string: Hello world  ' no change from c=88, because c is not a reference
The string: Hello Xorld  ' string was modified
Under the hood:

Code: Select all

   int3                                     ; |
   mov eax, [local.4]                       ; |ptr to "Hello World"
   mov bl, [eax+6]                          ; |the char
   mov [local.6], bl                        ; |c=119="w"
   int3                                     ; |
   mov ebx, [local.4]                       ; |ptr to "Hello World"
   mov eax, [local.5]                       ; |ptr to "world"
   mov cl, [ebx+6]                          ; |the char: 119="w"
   mov [eax], cl                            ; |change ?orld
   int3                                     ; |
jj2007
Posts: 2040
Joined: Oct 23, 2016 15:28
Location: Roma, Italia
Contact:

Re: String index doc

Postby jj2007 » Mar 02, 2021 21:06

Now the other use - poke a new value into Hello World:

Code: Select all

asm int 3
r=&H77   ' use the reference to poke 77h into world
asm int 3
a[6]=&H77   ' use the pointer to poke 77h into world
asm int 3

Code: Select all

   int3
   mov ecx, [local.5]                       ; ecx is a pointer ("reference") to "world"
   mov byte ptr [ecx], 77                   ; replace the "w" with 77h
   int3
   mov ecx, [local.4]                       ; ecx is a pointer to "Hello world"
   mov byte ptr [ecx+6], 77                 ; replace the "w" with 77h
   int3
What a big difference, isn't it?
paul doe
Posts: 1374
Joined: Jul 25, 2017 17:22
Location: Argentina

Re: String index doc

Postby paul doe » Mar 03, 2021 1:36

fxm wrote:With everything I added in this doc page, I think I'm listening a bit to comments and suggestions, even a little to the detriment of concision.

I think you're overdoing it: it's a waste of valuable time, as you're probably aware by now. Just let this thread die if locking it is going to shatter some snowflakes.
speedfixer
Posts: 472
Joined: Nov 28, 2012 1:27
Location: California

Re: String index doc

Postby speedfixer » Mar 03, 2021 2:24

I have no problems with a locked thread. I do when it happens so fast it is locked in one day before many get to even notice it is there.

Personally, I already said I think the doc is fine.
No, I am not supporting the migration of FB to c/c++.
But that is not happening. The devs make choices. Sometimes there is not a good, existing syntax for the new feature. Better to choose something familiar than invent something will just MORE awkward, forever.

At this point, those that want to comment probably have. Pushing fxm this way and that is disrespecting his efforts. He didn't write the code, he is merely trying to make it understandable.

I am saying FB is what it is. These docs mostly cover it well. Always room for improvement.
If someone wants to keep forcing that FB is programmed wrong, then lock the thread: this is a DOCS forum, not development.
fxm
Posts: 10258
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Postby fxm » Mar 03, 2021 9:38

4 operators which return by reference have in their documentation page a single syntax of 'Usage', which can be misleading for a novice (suggesting the only feature "get").

Example for the Operator [] (String index):
Usage:
    result = lhs [ rhs ]

I propose to add a second syntax also suggesting the "set" feature:
Usage:
    result = lhs [ rhs ]
    or
    lhs [ rhs ] = value
marcov
Posts: 3116
Joined: Jun 16, 2005 9:45
Location: Eindhoven, NL
Contact:

Re: String index doc

Postby marcov » Mar 03, 2021 9:42

speedfixer wrote: Better to choose something familiar than invent something will just MORE awkward, forever.


Maybe, if all things are equal. But quite often foreign syntax is rooted in principles that are different, like C like languages habit of making everything an expression, or in block assignments with single = (leading to god-awful ugly and accidental bug-prone ==)
jj2007
Posts: 2040
Joined: Oct 23, 2016 15:28
Location: Roma, Italia
Contact:

Re: String index doc

Postby jj2007 » Mar 03, 2021 12:15

fxm wrote:4 operators which return by reference have in their documentation page a single syntax of 'Usage', which can be misleading for a novice (suggesting the only feature "get").
I know you all hate me by now, but I assure you that my intentions are good. A novice needs crystal clear examples, abstract explanations will not be understood. The problem here is that the operator [] can work, in get mode, in two different ways, and the only apparent difference lies in the Dim ByRef:

Code: Select all

Dim a As String = "Hello world"
Dim ByRef As ubyte r=a[6]    ' the operator [] returns a REFERENCE, which can be used e.g. as r=123
Dim As ubyte c=a[6]         ' the operator [] returns a simple NUMBER (a ubyte in this case)

' c = a[6]   ' assigning values may happen a hundred lines further down, at which
' r = a[6]   ' point the coder may have forgotten whether it was dim'ed byref or not

print "Get mode:"
print "returned char value=";c
print "returned  ref value=";r

print "Set mode:"

c=88   ' uppercase "X"
print "The string: ";a;" (no change, c is NOT a reference)"

r=88
print "The string: ";a; " (changed, r IS a reference)"

a[6]=89
print "The string: ";a; " (changed, a[6] is... what? a reference or a pointer?)"
Sleep
Output:

Code: Select all

Get mode:
returned char value=119
returned  ref value=119
Set mode:
The string: Hello world (no change, c is NOT a reference)
The string: Hello Xorld (changed, r IS a reference)
The string: Hello Yorld (changed, a[6] is... what? a reference or a pointer?)
Re the last example, a[6]=89:

Code: Select all

mov rax,qword ptr ss:[rsp+20]                             | [rsp+20]:"Hello Xorld"
mov byte ptr ds:[rax+6],59                                | 59:'Y'
I would call that a pointer, not a reference, but there is freedom of opinion ;-)
counting_pine
Site Admin
Posts: 6246
Joined: Jul 05, 2005 17:32
Location: Manchester, Lancs

Re: String index doc

Postby counting_pine » Mar 03, 2021 12:53

A reference is basically anything with an address attached to it, such that it can (in theory) be assigned a value. This might be - for example - a variable, array index, or dereferenced pointer.

To acknowledge the distinction from an expression without an address (e.g. '2+1'), you might call it an lvalue as opposed to an rvalue.
(lvalues can go on the left (or right) hand side of an 'lhs = rhs', while rvalues can only go on the right hand side.)

Code: Select all

Dim a As String = "Hello world"
Dim Byref As ubyte r=a[6] '' create a reference pointing to a reference (i.e. set r's underlying address to the address of a[6])
Dim As ubyte ptr p=@a[6]  '' assign a pointer to a pointer (internally, the same as the previous line, except nothing's dereferenced)
Dim As ubyte c=a[6]       '' assign a reference's value to a variable (i.e. copy its value)


(In all three cases, you could use an array index or pointer index instead of a string index.)
fxm
Posts: 10258
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Postby fxm » Mar 03, 2021 13:42

jj2007 wrote:The problem here is that the operator [] can work, in get mode, in two different ways, and the only apparent difference lies in the Dim ByRef:

Dim a As String = "Hello world"
Dim ByRef As ubyte r=a[6] ' the operator [] returns a REFERENCE, which can be used e.g. as r=123
Dim As ubyte c=a[6] ' the operator [] returns a simple NUMBER (a ubyte in this case)

In all cases (whatever its use) the 'a[6]' expression is similar to the differentiation of a pointer.
In the case of 'a' is a string:
'a[6]' is equivalent to '*Cptr(Ubyte Ptr, Strptr(a) + 6)'

So your code line:
Dim As ubyte c = a[6]
is equivalent to:
Dim As ubyte c = *Cptr(Ubyte Ptr, Strptr(a) + 6) ' the operator [] "returns" a dereferenced Ubyte pointer

When a reference variable is created, an internal pointer 'p' is created with its value equal to the address of the initializer.
Dim ByRef As ubyte r = a[6]
is equivalent to:
Dim As Ubyte Ptr p = @a[6]
i.e.:
Dim As Ubyte Ptr p = Cptr(Ubyte Ptr, Strptr(a) + 6)
with:
r = (*p)

So:
r = 123
becomes:
*p = 123
or:
*Cptr(Ubyte Ptr, Strptr(a) + 6) = 123
fxm
Posts: 10258
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Postby fxm » Mar 03, 2021 13:47

Otherwise, I think the example I complemented in the docs is pretty straightforward:

Code: Select all

Dim a As String = "Hello, world!"
Dim i As Integer

For i = 0 To Len(a) - 1
    Print Chr(a[i]) & " ";
Next i
Print
Print

For i = 1 To 4
    a[i] = a[i] - 32  ' converting lowercase alphabetic characters to uppercase
Next i
For i = 7 To 11
    a[i] = a[i] - 32  ' converting lowercase alphabetic characters to uppercase
Next i
Print a

Code: Select all

H e l l o ,   w o r l d !

HELLO, WORLD!
fxm
Posts: 10258
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Postby fxm » Mar 03, 2021 14:11

fxm wrote:4 operators which return by reference have in their documentation page a single syntax of 'Usage', which can be misleading for a novice (suggesting the only feature "get").

Example for the Operator [] (String index):
Usage:
    result = lhs [ rhs ]

I propose to add a second syntax also suggesting the "set" feature:
Usage:
    result = lhs [ rhs ]
    or
    lhs [ rhs ] = value

Done:
- KeyPgOpStringIndex → fxm [added a 'Usage' syntax corresponding to a 'set' feature]
- KeyPgOpValueOf → fxm [added a 'Usage' syntax corresponding to a 'set' feature]
- KeyPgOpPtrIndex → fxm [added a 'Usage' syntax corresponding to a 'set' feature]
- KeyPgOpArrayIndex → fxm [added a 'Usage' syntax corresponding to a 'set' feature]
speedfixer
Posts: 472
Joined: Nov 28, 2012 1:27
Location: California

Re: String index doc

Postby speedfixer » Mar 04, 2021 19:13

@jj2007:
A novice needs crystal clear examples, abstract explanations will not be understood.

Sometimes you need both, or the explanation just isn't complete. And that last part makes assumptions that are not valid.

Simple first, then clarification after. Several other keywords have that pattern.
Leaving the technical and abstract out for some of the complex keywords obviously won't work.
jj2007
Posts: 2040
Joined: Oct 23, 2016 15:28
Location: Roma, Italia
Contact:

Re: String index doc

Postby jj2007 » Mar 04, 2021 20:19

speedfixer wrote:@jj2007:
A novice needs crystal clear examples, abstract explanations will not be understood.

Sometimes you need both, or the explanation just isn't complete. And that last part makes assumptions that are not valid.

Simple first, then clarification after. Several other keywords have that pattern.
Leaving the technical and abstract out for some of the complex keywords obviously won't work.
I fully agree. However, the point of this thread is that the operator [] has several faces, as demonstrated above:
jj2007 wrote:The problem here is that the operator [] can work, in get mode, in two different ways, and the only apparent difference lies in the Dim ByRef:[code]Dim a As String = "Hello world"
Dim ByRef As ubyte r=a[6] ' the operator [] returns a REFERENCE, which can be used e.g. as r=123
Dim As ubyte c=a[6] ' the operator [] returns a simple NUMBER (a ubyte in this case)
Now check the brand new manual page and tell me if everything is as clear as it should be.

Return to “Documentation”

Who is online

Users browsing this forum: No registered users and 1 guest