String index doc

Forum for discussion about the documentation project.
Flyzone
Posts: 109
Joined: Nov 17, 2017 17:39

String index doc

Post by Flyzone »

The String index ( [ ] ) documentation is entirely too vague in describing the operator's return value. It specifies a "reference" which apparently is an ASCII value for the selected character. It should state this. This return value is not further elaborated on in the Description either. One might infer this return value from the example but that's just poor. My own notion of a "reference" is usually an address pointer.

Operator [] (String index)
Returns a reference to a character in a string
badidea
Posts: 2586
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: String index doc

Post by badidea »

You mean this page: https://freebasic.net/wiki/KeyPgOpStringIndex
I agree that it is confusing. The term 'reference' is there since the creation of this page in 2008.
I'll wait for fxm to fix/improve it, else I will try tomorrow.
Flyzone
Posts: 109
Joined: Nov 17, 2017 17:39

Re: String index doc

Post by Flyzone »

Yes. That is the page. Sorry I didn't post the link.

<<is there since the creation of this page in 2008.>>

... I guess I'm the only dummy - so no rush, but Tnx.
fxm
Moderator
Posts: 12082
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Post by fxm »

'Returns a reference' is the right term because the 'Operator [] (String Index)' really returns by reference (see Syntax).

"Returns a reference" is very precise, and this is an important term that one needs to know well (see Reference in Glossary):
- 'Return by reference' is the opposite of 'return by value' where only a copy is returned. When a variable is returned by reference, you can modify it.
- 'Return by reference' is implemented under the hood as a pointer implicitly dereferenced.

- In case of a 'String' or a 'ZString' 's':
s[n]
is equivalent to:
*Cptr(Ubyte Ptr, Strptr(s) + n)

- In case of a 'WString' 's':
s[n]
is equivalent to:
*Cptr(T Ptr, Strptr(s) + n)

The text 'Returns a reference to a character in a string' could also be improved with roughly:
'Returns a reference to a numeric character in a string':
- for a 'String' or a 'ZString': a 'Ubyte' (containing the ASCII value of the character),
- for a 'WString': a numeric type depending on platform, for example 'UShort' for Windows or 'ULong' for Linux (containing the numeric value of the character).

This afternoon, I will update the documentation page as per everything stated above.


[edit]
Done:
KeyPgOpStringIndex → fxm [complemented description and example]
Flyzone
Posts: 109
Joined: Nov 17, 2017 17:39

Re: String index doc

Post by Flyzone »

Though you've solved the original problem with an explanation of the return values, I still find the statement:
"Returns a reference to a numeric character in a string"
at best obscure, and perhaps even misleading to those who might actually need the documentation.
But Thanks for the fix.
fxm
Moderator
Posts: 12082
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Post by fxm »

Maybe it would be better like this?
Returns a numeric reference to a character value in a string
Anyway, if it's the term 'reference' that bothers you, we can't escape it because it's the appropriate term!
MrSwiss
Posts: 3910
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: String index doc

Post by MrSwiss »

fxm wrote:Maybe it would be better like this?
Returns a numeric reference to a character value in a string
Anyway, if it's the term 'reference' that bothers you, we can't escape it because it's the appropriate term!
I beg to differ, how it is returned is only a secondary priority.
Ordinary users want to know, what they get:

A UByte containing the ASCII value of a string-character (byref return).
fxm
Moderator
Posts: 12082
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Post by fxm »

First, one should extend your proposition to WStrings:
A numeric type containing the value of a string-character (byref return)
to compare to:
Returns a numeric reference to a character value in a string

I prefer mine which is more compact and precise IMHO.
MrSwiss
Posts: 3910
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: String index doc

Post by MrSwiss »

fxm wrote:I prefer mine which is more compact and precise IMHO.
I definitely don't: its more compact (yes) but far less simple to understand.
This is, what should have TOP PRIORITY. Secondly, users must like it (not you or me).

in its first form:
A UByte containing the ASCII value of a string-character (byref return).
in its second form:
A UShort containing the numeric value of a wstring-character (Windows).
or:
A ULong containing the numeric value of a wstring-character (Linux).

Btw: you've done that type of explanation yourself, many times over ...
fxm
Moderator
Posts: 12082
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Post by fxm »

UShort or ULong or ..... for WStrings, depending on platform!

The keyword manual should be the reference for the language, not a tutorial or beginner's documentation.
MrSwiss
Posts: 3910
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: String index doc

Post by MrSwiss »

fxm wrote:UShort or ULong or ..... for WStrings, depending on platform! <-- metioned already!
The keyword manual should be the reference for the language.
We agree on that but only as long as that doesn't make it "incomprehensible" for most.
Flyzone
Posts: 109
Joined: Nov 17, 2017 17:39

Re: String index doc

Post by Flyzone »

I think MrSwiss is much closer to understanding the real problem as well as the audience. That is an understandable definition upon which the rest of the explanation builds. We have the classic chicken and egg problem, or which comes first - the WHAT or the HOW.
jj2007
Posts: 2326
Joined: Oct 23, 2016 15:28
Location: Roma, Italia
Contact:

Re: String index doc

Post by jj2007 »

fxm wrote:'Returns a reference' is the right term because the 'Operator [] (String Index)' really returns by reference (see Syntax).
Maybe it returns (arguably) something by reference, but it does not return a reference; it returns the numeric value of the char inside the string a at position n:

Code: Select all

Dim a As String = "Hello, world!"
Dim c As Integer=a[6]
print "char=[";a[6];"][";c;"]"

Dim ref as any ptr=@a[6]
print "ref=[";@a[6];"][";ref;"]"
Sleep
The BASIC syntax, btw, is c=Asc(Mid$(a, 6, 1)).
fxm
Moderator
Posts: 12082
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: String index doc

Post by fxm »

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
Posts: 109
Joined: Nov 17, 2017 17:39

Re: String index doc

Post by Flyzone »

jj2007 wrote:it returns (arguably) something by reference, but it does not return a reference; it returns the numeric value of the char inside the string a at position n
Precisely.
Post Reply