[v4] Corrections & Améliorations de la doc FR

[Flype]

c'est clair ! chapeau bas, patience et courage...
en tout cas, tout ce que vous faites n'est pas vain, c'est réellement utile.

[comtois]

voila ce que ça donne

http://perso.orange.fr/comtois/Doc/memory.html

Pour ma part je simplifierais encore, notamment ce passage :

Dans cet exemple, la variable Point1 réside à l’adresse @point1en mémoire.
En écrivant *PointCourant.Point = @point1,la variable *PointCourant est une variable de type pointeur et sa valeur est égale à @point1. On dit que *PointCourant pointe sur Point1 car sa valeur représente l’adresse de la variable Point en mémoire.
Comme la structure Point est attachée à *PointCourant (car *PointCourant.Point) on peut accéder (lire ou écrire) le contenu de Point1\x en écrivant *PointCourant\x.
En écrivant *PointCourant.Point = @point2,on déplace *PointCourant pour qu’il pointe sur Point2.
En écrivant à nouveau *PointCourant\x, on accède cette fois ci au contenu de Point2\x.
Les pointeurs permettent donc de se déplacer, de lire et d’écrire facilement en mémoire. De plus ils permettent aux programmeurs d’accéder à de grandes quantités de données sans coût supplémentaire suite à une duplication de ces données. Copier un pointeur est beaucoup plus rapide.

A mon avis une bonne partie de ce passage pourrait être mis sous forme de commentaires dans le code exemple.
ça ne serait plus autant détaillé certes , mais est-ce que ça nuierait à la compréhension , tout est expliqué avant non ?

Par exemple

Code : Tout sélectionner

  Point1.Point
  Point2.Point
  *PointCourant.Point = @Point1 ; Récupère l'adresse de Point1
  *PointCourant\x = 10 ; 10 est affecté à Point1\x 
  *PointCourant.Point = @Point2 ; Récupère l'adresse  de Point2
  *PointCourant\x = 20 ; 20 est affecté à Point2\x
  Debug Point1\x
  Debug Point2\x

[Droopy]

Clair et précis. Nickel

[Jacobus]

Je pense aussi qu'en mode commentées les explications gagneront en clarté. Le lecteur fera immédiatement la liaison.

Autre sujet, un petit détail qui pourrait éviter des hésitations.
dans la série des "Write"

Extrait de la Doc :

Syntaxe

WriteData(#Fichier, *Buffer, Longueur)
Description

Ecrit dans le #Fichier la zone de mémoire qui commence à l'adresse contenue dans le pointeur *Buffer. Le paramètre 'Longueur' précise le nombre d'octets en mémoire à écrire.


Exemple:

*MemoryID = AllocateMemory(1000) ; Alloue un bloc mémoire de 1000 octets
If *MemoryID
PokeS(*MemoryID, "Enregistre ce texte dans le bloc mémoire") ; Ecriture d'une chaîne de caractères dans le bloc mémoire
EndIf
If CreateFile(0, "Texte.txt") ; Création d'un nouveau fichier...
WriteData(0, *MemoryID, 10) ; On écrit les 10 premiers caractères du bloc mémoire dans le fichier
CloseFile(0) ; Ferme le fichier précédemment ouvert et enregistre les données
Else
Debug "Impossible de créer le fichier!"
EndIf

Il me semble qu'il faudrait préciser quelque part les définitions de base de l'octet et des unités généralement utilisées. Dans l'exemple ci-dessus on peut lire " Alloue un bloc mémoire de 1000 octets" et "On écrit les 10 premiers caractères du bloc mémoire dans le fichier"
Sachant qu'il y a plusieurs types de codage (ASCII; UTF8; Unicode)
Quelle est la bonne formule? Octet ou caractère, l'un pouvant être égal à l'autre mais pas toujours.
Suis-je clair? à côté de la plaque? ou bien est-ce pertinent?

[comtois]

c'est vrai que l'exemple date d'avant l'unicode dans Purebasic.

Il faudrait peut-être corriger l'exemple ainsi Pour s'affranchir du mode ?

Code : Tout sélectionner

WriteData(0, *MemoryID, SizeOf(Character)*10) ; On écrit les 10 premiers caractères du bloc mémoire dans le fichier

ou

Code : Tout sélectionner

PokeS(*MemoryID, "Enregistre ce texte dans le bloc mémoire",#PB_Default, #PB_Ascii) ; Ecriture d'une chaîne

[Jacobus]

En effet, bien vu, ça me paraît plus parlant désormais.

Il te suffit de rajouter un lien vers SizeOf() dans la doc de WriteData() et ça roule.

Bon courage!

[Dräc]

voila ce que ça donne

http://perso.orange.fr/comtois/Doc/memory.html

Pour ma part je simplifierais encore, notamment ce passage :

Dans cet exemple, la variable Point1 réside à l’adresse @point1en mémoire.
En écrivant *PointCourant.Point = @point1,la variable *PointCourant est une variable de type pointeur et sa valeur est égale à @point1. On dit que *PointCourant pointe sur Point1 car sa valeur représente l’adresse de la variable Point en mémoire.
Comme la structure Point est attachée à *PointCourant (car *PointCourant.Point) on peut accéder (lire ou écrire) le contenu de Point1\x en écrivant *PointCourant\x.
En écrivant *PointCourant.Point = @point2,on déplace *PointCourant pour qu’il pointe sur Point2.
En écrivant à nouveau *PointCourant\x, on accède cette fois ci au contenu de Point2\x.
Les pointeurs permettent donc de se déplacer, de lire et d’écrire facilement en mémoire. De plus ils permettent aux programmeurs d’accéder à de grandes quantités de données sans coût supplémentaire suite à une duplication de ces données. Copier un pointeur est beaucoup plus rapide.

A mon avis une bonne partie de ce passage pourrait être mis sous forme de commentaires dans le code exemple.
ça ne serait plus autant détaillé certes , mais est-ce que ça nuierait à la compréhension , tout est expliqué avant non ?

Par exemple

Code : Tout sélectionner

  Point1.Point
  Point2.Point
  *PointCourant.Point = @Point1 ; Récupère l'adresse de Point1
  *PointCourant\x = 10 ; 10 est affecté à Point1\x 
  *PointCourant.Point = @Point2 ; Récupère l'adresse  de Point2
  *PointCourant\x = 20 ; 20 est affecté à Point2\x
  Debug Point1\x
  Debug Point2\x

Je suis d'accord pour dire qu'il y a redondance, mais cela s’appelle « expliquer un exemple ».
Puisque l’opportunité est donnée d’ajouter des compléments sur les pointeurs, je trouve qu’il est intéressant d’y trouver une explication pour bien démystifier.

Pour tous ceux qui utilisent les pointeurs, cela peut sembler excessif, mais je ne suis pas sur qu’un débutant le perçoive ainsi.

Maintenant, le question est : quel est le rôle/l’esprit de la Doc officielle ? Il est vrai qu’en général, la Doc est succincte et précise.
Il existe très peu d’exemples « expliqués » car plutôt commentés. (mais ca existe : voir 1er exemple de Define)

Pour respecter cet esprit, on peut tout à fait supprimer l’explication au profit de commentaires

Pour clarifier, j’ai fait une passe sur la rubrique entière que Comtois a compulsé pour vous livrer ma vision à la lumière des différents réclamations.

Pointeurs et accès mémoire

Plusieurs simplifications ont été opérées et entre autre:

- Suppression de la phrase « Cela permet d'accéder à la structure via le pointeur. »
Non explicite et explicité plus loin

- Suppression du titre « Notion sur les pointeurs en PureBasic » au profit des titres :
Pointeurs et taille mémoire
Pointeurs et structures
Pointeurs et chaînes de caractères

- Les remarques sont regroupées dans « Pointeurs et taille mémoire »

- Le passage sur l’arithmétique des pointeurs est bien trouvé : j’ai cependant changé « en utilisant » par « en s'aidant de » car on peut ajouter tout nombre à un pointeur, simplement SizeOf() facilite la détermination d’adresses valides.

Voila, j’espère que cela satisfera tout le monde, du moins je ne vois pas ce que je pourrais y apporter de plus.
Aussi, pour la suite, je laisse le soin à Comtois de valider quitte à ajuster.

[comtois]

j’ai cependant changé « en utilisant » par « en s'aidant de » car on peut ajouter tout nombre à un pointeur, simplement SizeOf() facilite la détermination d’adresses valides.

Merci c'est exactement ça , je cherchais encore comment arranger cette phrase, tu as trouvé

Je viens de relire tes modifications, je crois qu'on s'approche de l'esprit de la doc officielle , je ne vais pas tarder à valider la page

Merci pour ton exposé.

[Jacobus]

Belle aide sur les pointeurs (on voudrait que ce soit pour tout pareil)
C'est clair, bien expliqué, un débutant devrait s'en sortir.
Merci à vous deux

[flaith]

A Noter : A l’inverse du C/C++, en PureBasic l'* fait partie intégrante du nom de la variable. Aussi ptr et *ptr sont deux variables bien distinctes.
ptr est une variable (régulière) contenant une valeur, *ptr est une autre variable de type pointeur contenant une adresse.

c'est dingue, je savais pas ca, j'ai toujours utilisé les pointeurs comme en C
Merci beaucoup pour l'info

[comtois]

la nouvelle doc est en ligne (premier lien de ma signature)

et elle inclut la page sur les pointeurs

http://perso.orange.fr/comtois/Doc/memory.html

[flaith]

Merci les gars, c'est vraiment du bon boulot

[Anonyme2]

J'ai utilisé ce code avec la commande Not

Code : Tout sélectionner

If Not(CountList(Structures()))
        Etat | 1
EndIf

et j'ai fait F1 pour l'aide dessus mais rien ni dans l'onglet rechercher de la doc

Ce code fonctionne correctement

Il faudrait l'ajouter

[nico]

Une duplication sur AddElement()

...
Structure Element
*Next.Element ; Pointeur vers l'élément suivant de la liste ou zéro si c'est le dernier élément
*Previous.Element ; Pointeur vers l'élément précédent de la liste ou zéro si c'est le premier élément

; La structure utilisée par la liste suit directement ces 2 variables (ce qui implique que les
; données utilisateurs se situent à l'adresse du nouvel élément + 8 octets.
EndStructure

Vous ne devriez pas changer les pointeurs du début de la liste, car ça casserait la structure interne de la liste.
Exemple:

Structure Element
*Next.Element ; Pointeur vers l'élément suivant de la liste ou zéro si c'est le dernier élément
*Previous.Element ; Pointeur vers l'élément précédent de la liste ou zéro si c'est le premier élément

; La structure utilisée par la liste suit directement ces 2 variables (ce qui implique que les
; données utilisateurs se situent à l'adresse du nouvel élément + 8 octets.
EndStructure

Vous ne devriez pas changer les pointeurs du début de la liste, car ça casserait la structure interne de la liste.
...

[Anonyme2]

Bon boulot Comtois (And co )


Une remarque sur la page pointeur

C’est pour cette raison qu’un pointeur est une variable dite de type pointeur car son encombrement en mémoire sera lié à la capacité d’adressage mémoire du processeur.
Il en découle qu’affecter un type à un pointeur (*Pointeur.l, *Pointeur.b…) n’a aucun sens puisque l’encombrement mémoire d’un pointeur est imposé par celui d’une adresse et non par celui d’un type.

La phrase devrait être corrigé (et le compilateur aussi pour ne pas permettre cette écriture). Un pointeur a forcément un type qui est soit une Structure soit une Interface, cela permet au compilateur de s'y retrouver.

La phrase devrait être corrigé comme ceci (ou quelque chose dans ce goût là)

Il en découle qu’il faut affecter à un pointeur, un type basé sur une Structure ou une Interface. L'écriture suivante
*Pointeur.w, *Pointeur.b etc est une erreur , il faut écrire *Pointeur.[long] , *Pointeur.[byte] , *Pointeur.[Character] etc.
L'écriture *Pointeur.l peut-être utilisée pour avoir un pointeur sans type.

Les structures Double, Quad sont apparues avec PB 4. Pour la version Unicode du Char, je ne vois pas de Structure.

D'ailleurs, l'exemple quelques lignes plus loin montre bien que les pointeur sont typés.

Attacher une Structure à un pointeur (par exemple *MonPoint.Point) permet d’accéder au contenu mémoire de chaque membre de la Structure avec le caractère \ .

Exemple:

Define Point1.Point, Point2.Point
*PointCourant.Point = @Point1 ; Déclare le pointeur, l'associe a une structure et l'initialise avec l'adresse de Point1
*PointCourant\x = 10 ; Assigne la valeur 10 à Point1\x
*PointCourant.Point = @Point2 ; Récupère l'adresse de Point2
*PointCourant\x = 20 ; Assigne la valeur 20 à Point2\x
Debug Point1\x
Debug Point2\x