String index doc
String index doc
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
Operator [] (String index)
Returns a reference to a character in a string
Re: String index doc
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.
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.
Re: String index doc
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.
<<is there since the creation of this page in 2008.>>
... I guess I'm the only dummy - so no rush, but Tnx.
Re: String index doc
'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]
"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]
Re: String index doc
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.
"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.
Re: String index doc
Maybe it would be better like this?
Anyway, if it's the term 'reference' that bothers you, we can't escape it because it's the appropriate term!Returns a numeric reference to a character value in a string
Re: String index doc
I beg to differ, how it is returned is only a secondary priority.fxm wrote:Maybe it would be better like this?Anyway, if it's the term 'reference' that bothers you, we can't escape it because it's the appropriate term!Returns a numeric reference to a character value in a string
Ordinary users want to know, what they get:
A UByte containing the ASCII value of a string-character (byref return).
Re: String index doc
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.
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.
Re: String index doc
I definitely don't: its more compact (yes) but far less simple to understand.fxm wrote:I prefer mine which is more compact and precise IMHO.
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 ...
Re: String index doc
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.
The keyword manual should be the reference for the language, not a tutorial or beginner's documentation.
Re: String index doc
We agree on that but only as long as that doesn't make it "incomprehensible" for most.fxm wrote:UShort or ULong or ..... for WStrings, depending on platform!<-- metioned already!
The keyword manual should be the reference for the language.
Re: String index doc
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.
Re: String index doc
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:fxm wrote:'Returns a reference' is the right term because the 'Operator [] (String Index)' really returns by reference (see Syntax).
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
Re: String index doc
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'.
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'.
Re: String index doc
Precisely.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