Wiki improvements

Forum for discussion about the documentation project.
Tourist Trap
Posts: 2383
Joined: Jun 02, 2015 16:24

Re: Wiki improvements

Postby Tourist Trap » Jun 22, 2018 10:20

fxm wrote:It is not any counter of access or download, completely impersonal, that interests me, but it is rather the exchanges with the users, at any level whatsoever.
As for diverting/hacking the FreeBASIC language, I see it more as a game than as a finality in itself.

Anyway you are skilled enough to end here:
https://www.oreilly.com/work-with-us.html
coderJeff
Site Admin
Posts: 2693
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Jun 22, 2018 17:27

fxm wrote:New proposed title:
How FB supports References (pass and return byref, byref variables), and How to Use them


The simplest definitions I can think of:
POINTERS: pointers let you work with storage locations as though they were values
BYREF: byref types let you work with the contents of a storage location as a value of a specific type

fxm, I think you understand exactly what I mean. I think many here would not, and could benefit from a lesson.

Pointers get interesting only when you add * dereference operator and @ address operator.
Byref is kind of interesting all on it's own. fbc has had byref parameters since beginning. Byref variables so different?

Challenge!: Is it possible to discuss references without discussing pointers? Write an article and find out... :)
fxm
Posts: 8351
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 12, 2018 9:20

About the article: How FB supports References (pass and return byref, byref variables), and How to Use them

Since its publication (June 26), I am surprised to have had no feedback on the text of the article or even more generally on the subject itself addressing the concepts of pointers and references.
Does this mean that such an article is irrelevant to users' expectations, or that all these notions are already well known and mastered?
(I do not dare to think that the article is perfect and that there is nothing more to say)
dodicat
Posts: 5161
Joined: Jan 10, 2006 20:30
Location: Scotland

Re: Wiki improvements

Postby dodicat » Aug 12, 2018 14:10

I have only one critique.
In a simplified resize you may see it.
But it seems now that a normal everyday function seems as fast as an inline macro.
Strange?

Code: Select all

 

dim byref as zstring  z=*Cptr(Zstring Ptr, 0)

''#define resize(p,size)  reallocate(p,size) 'alternative

function resize(p as any ptr,size as long) as any ptr
    return reallocate(p,size)
end function

const as string d="Finished this part"

dim as ulong counter
dim as double t=timer
do
    counter+=1
    locate 3,1,0
dim as string s="fb"
@z=resize(@z,len(s))
z=s
print z

s="FreeBASIC 1.05.0"
@z=resize(@z,len(s))
z=s
print z

s=""
@z=resize(@z,len(s))
z=s
print z

@z=resize(@z,len(d))
z=d

print z

print
dim as zstring ptr p

 s="fb"
p=resize(p,len(s))
*p=s
print *p

s="FreeBASIC 1.05.0"
p=resize(p,len(s))
*p=s
print *p

s=""
p=resize(p,len(s))
*p=s
print *p
p=resize(p,len(d))
*p=d
print *p
print

print "mem left  ";fre,"loops per second ";
if timer-t>1 then print tab(60); counter:t=timer:counter=0
loop until len(inkey)


sleep
 

Tested for leaks over a cup of tea.
grindstone
Posts: 556
Joined: May 05, 2015 5:35
Location: Germany

Re: Wiki improvements

Postby grindstone » Aug 12, 2018 14:24

coderJeff wrote:Is it possible to discuss references without discussing pointers?
That depends. If you only want to know how to use it, it's enough to know that changing a paramter submitted BYREF will affect the value outside of the procedure, while the changes made to a BYVAL parameter are limited to the inside of the procedure. But if you want to know how it works, it's essential to understand the pointer stuff.
fxm
Posts: 8351
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 12, 2018 14:48

dodicat wrote:I have only one critique...

Me, I have 2 critics:

1) Correct your bug:
When allocating memory for a zstring, you must also allocate one supplementary byte for the terminal character ('0') that is written when assigning.
Everywhere (6 times), correct the call to 'resize()':
@z=resize(@z,len(s)+1)
and
p=resize(p,len(s)+1)

2) About your execution time measurement:
You mainly measure the print time on the screen because the execution time of 'resize()' is negligible compared to this one.
dodicat
Posts: 5161
Joined: Jan 10, 2006 20:30
Location: Scotland

Re: Wiki improvements

Postby dodicat » Aug 12, 2018 15:39

Thank you fxm.
forgot that point.
My gripe was of course "FreeBASIC 1.06.0" as a string.
Who has this version, is it easy to get and easy to install?
fxm
Posts: 8351
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 12, 2018 15:56

A daily zip is available here:
http://users.freebasic-portal.de/stw/builds/
fxm
Posts: 8351
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 12, 2018 16:06

coderJeff wrote:Is it possible to discuss references without discussing pointers?

I think that for the particular case of the FreeBASIC language, it is very useful to do parallel with the pointers when the references are explained:
- Under the hood, references are implemented using pointers auto-dereferenced by the compiler.
- Some FreeBASIC error messages on references involve the associated pointers under the hood.
- The FreeBASIC language leaves the user free to reassign a reference to another variable (of the same type or a compatible type):
@reference = @other_variable
(The operator '@' appears in the syntax).
- The address of the associated pointer under the hood can even be retrieved by:
@@reference

For the C language, the question may arise because the use of references is much less open and lax than for the FreeBASIC language.
For other languages that do not offer pointers to the user, the question obviously does not arise!
coderJeff
Site Admin
Posts: 2693
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Aug 13, 2018 4:59

fxm, I think you did a great job with the article. Very good explanations. I think you did well explaining difference between reference and pointer. I've read many bad explanations that make references sound like they are same as pointers. And they are not the same thing at all, but, because of the implementation like in fbc, can compare them.
badidea
Posts: 975
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Wiki improvements

Postby badidea » Aug 13, 2018 20:35

Something else, I was looking for the manual on the new operator. The first place where I looked was the CatPgMemory. That was incorrect apparently. Via CatPgOpIndex I found it.

But there is also a page called CatPgOpMemory. If I check what links to this page, I get " There are no backlinks to this page". But there is a page that links to here: CatPgOperators. Weird?

Also, a good idea to link to CatPgOpMemory from CatPgMemory?
fxm
Posts: 8351
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 13, 2018 21:00

Done:
CatPgMemory → fxm [Added "See also" link to CatPgOpMemory (Memory Operators)]
badidea
Posts: 975
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Wiki improvements

Postby badidea » Aug 13, 2018 21:27

I think I got another addition. There seems to be no .. page. Don't know if it has a name.

Example, line 39:

Code: Select all

const as integer MAX_DES_LEN = 63

type dbItem_type field = 1
   dim as longint id 'identifier
   dim as string * MAX_DES_LEN des 'description
   dim as long qty 'quantity
end type

const as integer MAX_DB_ITEMS = 10

type dbItems_type
   private:
   dim as integer numItems
   dim as dbItem_type dbItems(MAX_DB_ITEMS-1)
   public:
   declare function add(id as longint, des as string, qty as long) as integer
   declare function print(index as integer) as integer
end type

function dbItems_type.add(id as longint, des as string, qty as long) as integer
   'todo: check if id not in list
   if id < 0 then return -1
   if len(des) > MAX_DES_LEN then return -2
   if qty < 0 then return -3
   if numItems >= MAX_DB_ITEMS then return -4
   with dbItems(numItems)
      .id = id
      .des = des
      .qty = qty
   end with
   numItems += 1
   return numItems
end function

function dbItems_type.print(index as integer) as integer
   if index < 0 then return -1
   if index >= MAX_DB_ITEMS then return -2
   with dbItems(index)
      ..print str(.id), trim(.des), str(.qty)
   end with
   return 0
end function

dim as dbItems_type dbItems

dbItems.add(1234, "FreeBASIC", 1)
dbItems.print(0)
fxm
Posts: 8351
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 13, 2018 21:34

'With' documentation page wrote:.....
Note for With block used inside member procedure:
To access duplicated symbols defined outside the Type, add two dots as prefix: "..SomeSymbol" (inside a With...End With block).


'Member Procedures', 'Function (Member)', 'Sub (Member)', and 'Namespace' documentation pages wrote:.....
To access duplicated symbols defined outside the Type, add one (or two) dot(s) as prefix: .SomeSymbol (or ..SomeSymbol if inside a With..End With block).
fxm
Posts: 8351
Joined: Apr 22, 2009 12:46
Location: Paris (suburb), FRANCE

Re: Wiki improvements

Postby fxm » Aug 14, 2018 6:11

About the "How and Why to Define Constructors, Assignment-Operators, and Destructor, for UDTs in FB" article:

I completed the "2) Conversion-constructors" paragraph to show (with example) that implicit conversion by compiler (using the single-parameter constructor if exists) can induce subtle but serious errors in the code if we define a multi-parameter constructor, but with these ones optional.
The compiler can interpret one of its forms as a conversion-constructor (with a single parameter), and so construct unexpected objects.
I also recalled a feature request around this problem of implicit conversion by compiler but not wished by user.

Return to “Documentation”

Who is online

Users browsing this forum: No registered users and 1 guest