String index doc

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

Re: String index doc

Post by fxm »

Flyzone wrote:
jj2007 wrote:it returns the numeric value of the char inside the string a at position n
Precisely.
Not just that.
It also allows you to modify the value of the character at position n (which a simple copy cannot do).

This entity (a kind of alias) which makes it possible to read and modify the value of a variable (the character at position n in this case), this is what is called a reference.
(see the example that I completed in documentation page)
Flyzone
Posts: 109
Joined: Nov 17, 2017 17:39

Re: String index doc

Post by Flyzone »

At the risk of making things murkier I think we should take a step back. The doc is now overwrought and it the word REFERENCE that is making the understanding of this operator a bit opaque.

I suggest that the concept of “reference” be deferred until the last line in the doc. After all, it is “under the covers” and not the primary point of the string operator so why is it the 4th word in the explanation and repeated several times?

I do not think I am going to be successful here since I think you believe that the “reference” explanation aspect of this piece is essential and overriding and counter to what I believe should be the main point. Therein lies the problem. The focus needs to be on the returned values and back off on the “reference” reference.

Perhaps there should be a documentation piece on REFERENCE. I suspect there already is, but I dare not go there.

If this doesn’t go anywhere I will excuse myself so as not to be repetitious. I mean, it probably won’t hurt this this doc has probably not been well understood since 2008.

Having said all that, this was still fun.
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Post by fxm »

Flyzone wrote:Perhaps there should be a documentation piece on REFERENCE. I suspect there already is, but I dare not go there.
  • fxm wrote:Under the hood, its returns a pointer by value, which is implicitly dereferenced.
    It is exactly the definition of a reference in FreeBASIC (an internal pointer implicitly dereferenced).

    See in the Programmer's Guide my two articles in the topic 'Variables and Datatypes / References'.
Flyzone wrote:Having said all that, this was still fun.
  • Not for me, continuing this discussion is fruitless.
badidea
Posts: 2586
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: String index doc

Post by badidea »

Does the confusion come form the ability that the the string [] operator can be used in 2 directions?

Code: Select all

dim as string text = "Hello, world!"
'dereferenced pointer to 'o'
var char = text[4]
'pointer to 'o' so we can change the memory to 'X'
text[4] = asc("X")
I think that automatic deferencing in (Free)basic was a unwise decision. It makes the subject of pointers unnecessary complicated.

Example with deferencing undone:

Code: Select all

dim as string text = "Hello, world!"
var pChar = @text[4]
#print typeof(pChar)
*pChar = asc("?")
print text
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Post by fxm »

fxm wrote: continuing this discussion is fruitless.
I locked this topic.
speedfixer
Posts: 606
Joined: Nov 28, 2012 1:27
Location: CA, USA moving to WA, USA
Contact:

re: String Index Doc: wtf!

Post by speedfixer »

Lock the topic when YOU don't want to discuss it anymore? So quick!

The clearest example of Code Police!


(Though I agree with you, fxm. It is very valuable as a REFERENCE - used to extract and change - and that is what the [] symbols are used for in FB. The fact that it is a pointer to a <type> should be explained.)

david
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Post by fxm »

I have unlocked the topic, but please, for those who are not quite sure what a REFERENCE is, read these two articles:
- From Pointers to References
- Using References
before arguing about the need to specify it at the beginning of the page, or only at the end of the description (as a detail).

The difference between a COPY and a REFERENCE is fundamental and this should be highlighted at the start of the description:
  • 'Returns the value of a character in a string' implicitly suggests that the returned value is only a copy of the character's value, and therefore that character cannot be changed by using the keyword.
  • 'Returns a reference to a character in a string' specifies that what is returned is not a simple copy, but on the contrary an entity (a dereferenced pointer to the character) which allows both to read and to modify the value of the character by using the keyword.
Example between a copy and a reference:

Code: Select all

Dim As Integer variable(0 To 2) = {0, 123, 0}

Dim As Integer copy1 = variable(1)
Dim Byref As Integer reference1 = variable(1)

Print copy1, variable(1)
copy1 = 456
Print copy1, variable(1)
Print

Print reference1, variable(1)
reference1 = 456
Print reference1, variable(1)
Print

Code: Select all

 123           123
 456           123

 123           123
 456           456
 
For me the difference is fundamental and deserves to be pointed out at the highest level of description.
counting_pine
Site Admin
Posts: 6323
Joined: Jul 05, 2005 17:32
Location: Manchester, Lancs

Re: String index doc

Post by counting_pine »

I think putting the words "numeric" and "reference" together can be confusing.
The word "numeric" is presumably there to indicate that the value of a character is a number (rather than, say, a 1-character string). But this is unclear because it's in a different part of the sentence.
Maybe it would be best to say: "This operator returns a reference to the numeric value of a specific character in a string".
Slightly wordier, but clearer I think.

It's perhaps worth saying the the fact that it returns a reference is one of its most noteworthy features, because Asc performs provides similar functionality without returning a reference.
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Post by fxm »

I wanted to clarify that the reference is of numeric type and not of type string for example, but ok for your proposal.
jj2007
Posts: 2326
Joined: Oct 23, 2016 15:28
Location: Roma, Italia
Contact:

Re: String index doc

Post by jj2007 »

Dim c As Integer=a[6] does not "return a reference", it returns a number (ubyte or ushort); and of course, it does so internally without making a copy. This is trivial, only a horribly inefficient compiler would create a copy to extract the byte...

What bothers me here is not only the incoherent (and IMHO plain wrong) language but also the attempt to use C/C++ jargon for something that has been used in BASIC, successfully and without any ambiguity, for half a century or so:

Code: Select all

Dim a As String = "Hello world!"
Dim c As Integer=a[6]
Dim ref as any ptr=@a[6]
print "ref=[";@a[6];"][";ref;"]"	' return a pointer to the memory where the number is stored

print "char=["; a[6]; "] ["; c; "] ["; Asc(Mid(a, 7));"]"	' 3 ways to return a number (byte for Ansi, short for Utf-16)

a[6]=120	' assign "x" using the reference (i.e. not a copy)
c=a[6]
print "char=["; a[6]; "] ["; c; "] ["; Asc(Mid(a, 7));"]"	' return the new number

Mid(a, 7)="z"  ' assign "x" using the reference (i.e. not a copy)
c=a[6]
print "char=["; a[6]; "] ["; c; "] ["; Asc(Mid(a, 7));"]"	' return the new number

print "ref=[";@a[6];"][";ref;"]"	' return a pointer to the memory where the number is stored

Sleep

Code: Select all

ref=[5973878][5973878]
char=[119] [ 119] [119]
char=[120] [ 120] [120]
char=[122] [ 122] [122]
ref=[5973878][5973878]
counting_pine wrote:It's perhaps worth saying the the fact that it returns a reference is one of its most noteworthy features, because Asc performs provides similar functionality without returning a reference.
Why should Asc return a reference when you ask for a number? Also, Mid(a, 7)="z" does not "return a reference", but it inserts the z right there, in the original string, and that's what we asked for, right? Btw it does exactly the same thing as a[6]=122, as demonstrated above.
paul doe
Moderator
Posts: 1730
Joined: Jul 25, 2017 17:22
Location: Argentina

Re: String index doc

Post by paul doe »

jj2007 wrote:...
What bothers me here is not only the incoherent (and IMHO plain wrong) language but also the attempt to use C/C++ jargon for something that has been used in BASIC, successfully and without any ambiguity, for half a century or so:
...
The [] operator (which alas, wasn't available half a century ago) returns a reference to the char at the specified position in the string:

Code: Select all

dim as string t = "This is a test"

var byref ch = t[ 0 ]

ch = asc( "t" )

? t

ch = asc( "F" )

? t

sleep()
There is no ambiguity here, only a bunch of people that can't grasp what a reference is. So much discussion over such a trivial matter...
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Post by fxm »

Give its opinion on the merit of underlining that this operator returns a reference by adjudging that it is rather a detail to be reported at the end of the description, and at the same time admit not knowing what is actually a reference and even not being interested in that (even if I offered some formative readings) seems to me quite contradictory.

As for those who think they know very well what a reference is, but who say that this operator does not return a reference .....
jj2007
Posts: 2326
Joined: Oct 23, 2016 15:28
Location: Roma, Italia
Contact:

Re: String index doc

Post by jj2007 »

paul doe wrote:a bunch of people that can't grasp what a reference is. So much discussion over such a trivial matter...
Interesting that you start insulting other members of this forum - you've run out of arguments?

As to "trivial matter": the first Google hit for reference pointer difference is a SOF post with 40 answers, and hundreds of comments. Trivial, of course, but it's amazing how many different opinions can be derived from a "binary" reference vs pointer question.

Fact is that x=a[6] (where a is an Ansi string) returns an 8-bit number in x. One of the characteristics of references, btw, is that they are an alias to an existing variable, i.e. a different name for the same variable. Which is clearly not the case for number=a[6].

What is indeed trivial is what happens under the hood for c=a[6] (and it demonstrates that a[6] uses a pointer, not a reference variable):

Dim a As String = "Hello world!"
Dim c As Integer
c=a[6]

Code: Select all

mov eax, [local.37]                      ; ptr to "Hello World"
movzx ebx, byte ptr [eax+6]              ; extract a byte
mov [local.38], ebx                      ; move it to c
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Post by fxm »

'Dim As Integer c = a[6]' only copies 'a[6]' in the variable 'c', therefore 'c' is not created as reference.

But 'Dim Byref As Integer r = a[6]' creates a reference 'r' to 'a[6]' which is already a reference to the 7th character of the string, therefore 'r' is a second reference to the 7th character of the string.
('r = ...' modifies the value of the 7th character of the string)

Compare your above code (asm code result) with:

Code: Select all

Dim a As String = "Hello world!"
Dim Byref r As Integer = a[6]
jj2007 wrote:and it demonstrates that a[6] uses a pointer, not a reference variable
But under the hood, an FB reference variable is nothing more than an internal pointer dereferenced (I am repeating it over and over)!
speedfixer
Posts: 606
Joined: Nov 28, 2012 1:27
Location: CA, USA moving to WA, USA
Contact:

Re: String index doc

Post by speedfixer »

jj2007: again - if the other languages are so much better, if you don't like FB, why are you here?

This should be a discussion about the docs.
The programming of the syntax is what it is.


The docs as they were was not so bad.
An addition that basically a pointer is passed around would help some others for clarity, perhaps.

Some language explanations will always present difficulty for some people at different times. I have had this problem. That doesn't make the current docs terrible. They are simply not perfect.

That's OK. No one else gets to be perfect because I am not perfect.

@fxm:
I prefer mine which is more compact and precise IMHO.
Anyone can disagree with that. Then they make suggestions.
Otherwise, I agree with you, mostly.

In this case, I see no problem. I am not everyone.
Generally, I think too much effort is given to that "compact" and "precise".

BUT

Generally, I appreciate your efforts and work you obviously give to support FB. I respect your deep insights you have worked so hard to get.
And unless someone else is saying they will do a more thorough and complete job, I much prefer you continue.
Just, sometimes, remember that you are a person like anyone else and not always right. And you don't need to be a defender of the Bible of FreeBASIC.
Post Reply