Write

WRITE scrive in un file i dati-byte previsti, cominciando dall'inizio del file. ^{[nota 1]}

Di norma alla funzione Write seguono almeno due membri separati da una virgola:

• il primo, immediatamente preceduto, come prefisso, dal simbolo #, rappresenta la variabile di tipo File o Stream, ottenuta di solito con l'apertura in scrittura mediante la funzione Open. Se non viene specificata la variabile di tipo file, sulla quale scrivere, allora i dati verranno scritti nello Standard Output.
• il secondo rappresenta il dato o i dati, espressi in forma esplicita o contenuti in apposita variabile, da scrivere nel file.

Pertanto la sua sintassi base è la seguente:

Write #variabile_tipo_file, variabile_contenente_i_dati [, quantità_dei_dati_da_scrivere]

Il file, se già esistente, dovrà essere ovviamente aperto con l'istruzione Open in Scrittura mediante le parole-chiave "FOR WRITE":

Public Sub Main()
 
 Dim fl As File
 Dim s As String
 
 fl = Open "/percorso/del/file/esistente/nel/quale/scrivere" For Write
 s = "Testo qualsiasi"
  
' Scrive nella variabile di tipo "File" il contenuto della variabile di tipo Stringa "s":
 Write #fl, s
  
' Al termine della scrittura il file va chiuso, per liberare la memoria allocata durante la creazione dell'Oggetto di tipo "File":
 fl.Close
  
End

altrimenti (se non già esistente) andrà creato ed aperto mediante le parole-chiave "For Create":

fl = Open "/percorso/del/nuovo/file/da/creare" For Create

Alternativa alla parola-chiave "CREATE" per creare un file

Un'alternativa alla parola-chiave "CREATE" per creare un file, è l'uso del Metodo ".Save()" della Classe File, passando il valore predefinito Null nel secondo argomento. Il file, così creato, può poi essere normalmente aperto ed essere scritto con i dati previsti mediante la funzione Open e le parole-chiave "For Write":

File.Save("/percorso/del/file/da/creare", Null)

fl = Open "/percorso/del/file/creato/nel/quale/scrivere/dati" For Write

Scrivere in un file una stringa di caratteri

La scrittura di una stringa di caratteri in un file può avvenire in due forme: con o senza l'indicazione del tipo di dato String a seguire nel secondo membro della funzione Write mediante l'espressione delle parole-chiave "AS STRING".
A seconda della forma scelta, si avrà nel file un effetto diverso.

Specificazione del tipo Stringa mediante l'uso delle parole-chive "As String"

Qualora vengano impiegate le parole-chiave "As String":

Public Sub Main()
 
 Dim fl As File
 
 fl = Open "/tmp/prova" For Create
 
 Write #fl, "Testo qualsiasi" As String
 
 fl.Close
  
End

nel file si avrà - prima dei dati attinenti ai caratteri - uno o più byte che rappresentano numericamente la quantità di dati salvata nel file.
Alla fine dei dati dei caratteri memorizzati nel file non sarà presente il valore relativo al "fine linea e a capo " (&h0A).

Senza uso delle parole "As String"

Se nella riga di comando dell'istruzione "Write " non saranno impiegate le parole-chiave "As String", allora nei dati memorizzati non sarà presente all'inizio il valore relativo alla quantità di caratteri memorizzati, né il valore relativo al "fine linea e a capo " (&h0A).

Scrivere una quantità definita di dati di una stringa

In un file è possibile scrivere una quantità definita di dati di tipo Stringa, specificando con un terzo elemento sintattico la quantità di dati da scrivere:

Write #variabile_file, stringa, n

laddove n rappresenta la quantità di dati-byte che della variabile stringa si intende scrivere. Esempio pratico:

Public Sub Main()
 
 Dim fl As File
 Dim s As String
  
 s = "testo qualsiasi"
   
 fl = Open "/tmp/prova" For Write Create
   
' Scrive nel file solo otto dati-byte, a cominciare dal primo, di quelli contenuti nella variabile di tipo stringa "s":
 Write #fl, s, 8
   
' Chiude il file, liberando la memoria precedentemente allocata per la creazione dell'Oggetto di tipo "File":
 fl.Close
  
End

Scrivere una quantità inferiore ai dati in possesso

Se di un insieme di dati di tipo stringa si vuole scrivere soltanto una quantità inferiore, tale quantità andrà dunque specificata:

Public Sub Main()

 Dim fl As File

 fl = Open "/percorso/del/file/sul/quale/scrivere" For Write

 Write #fl, "testo qualsiasi", 4

 fl.Close

End

Si scriveranno solo i primi quattro byte.
Se si intende scrivere la quantità di byte prevista, però cominciando da un byte diverso dal primo, si utilizzerà ovviamente l'istruzione SEEK.

Scrivere una quantità superiore ai dati in possesso

Se si indicherà nel terzo elemento, invece, una quantità superiore ai dati da scrivere, allora i dati in eccesso saranno scritti automaticamente con valore pari a zero:
Esempio:

Public Sub Main()

 Dim fl As File
 
 fl = Open "/percorso/del/file/sul/quale/scrivere" For Write Create

 Write #fl, "testo qualsiasi", 20

 fl.Close

End

Nel file avremo i seguenti byte:
74 65 73 74 6F 20 71 75 61 6C 73 69 61 73 69 00 00 00 00 00

Per evitare tale effetto di aggiunta automatica di valori zero, prodotto dalla impostazione nel terzo parametro di un valore di dati-byte da voler scrivere superiore a quelli realmente esistenti, si attribuirà al terzo parametro un segno "negativo".
Il segno negativo, assegnato al valore del terzo parametro della riga di comando di "Write", consente quindi di scrivere una quantità di dati byte sino al numero espresso dal valore medesimo e di riconoscere nel contempo la fine dei dati-byte da scrivere.
Se dunque ad esempio si devono scrivere quindici dati-byte e viene impostato nel terzo argomento il valore -24, la riga di comando di "Write" ha teoricamente la capacità di scrivere sino a 24 dati-byte, ma, qualora essi fossero in realtà di un numero inferiore, "Write" scriverebbe sino e non oltre l'ultimo dato-byte, non aggiungendo così alcun valore zero per raggiungere il numero complessivo di 24, come accadrebbe invece se il terzo argomento non fosse un valore negativo.

Mostriamo un esempio:

Public Sub Main()

 Dim fl As File
 
 fl = Open "/percorso/del/file/sul/quale/scrivere" For Write Create

 Write #fl, "testo qualsiasi", -20

 fl.Close

End

Nel file avremo ora soltanto i seguenti byte:
74 65 73 74 6F 20 71 75 61 6C 73 69 61 73 69

Indicare un valore zero nel terzo elemento della sintassi

Se il terzo elemento è pari a zero:

write #fl, "testo qualsiasi", 0

allora con Gambas 3 non viene scritto alcun dato.

Scrivere dati per i quali è necessario specificare il "tipo"

Se il valore da scrivere nel file, non è di tipo String, allora va necessariamente specificato il "tipo" di dato attraverso la parola-chiave "AS":

Write #variabile_file, dati AS tipo_di_dato

In tal modo si specifica quanti byte di memoria si dovranno occupare nel file per memorizzare il valore che si intende salvare.

Nel seguente esempio pratico scriveremo nel file un valore esplicito di tipo Byte e poi un altro di tipo Integer contenuto in una variabile:

 Public Sub Main()
 
 Dim fl As File
 Dim i As Integer = 1000000
 
 fl = Open "/percorso/del/file/nel/quale/scrivere" For Write
  
' Scrive nella variabile di tipo "File" il valore decimale 64, specificando che il suo tipo di valore è un "Byte":
 Write #fl, 64 As Byte

' Poi scrive un valore di tipo "Intero", e anche in questo caso lo deve specificare, se vuole che avvenga ciò:
 Write #fl, i As Integer
  
 fl.Close
  
End

Scrivere una quantità di byte inferiore alla quantità di byte già presenti nel file

Se il file già esistente è costituito da una quantità di byte superiore alla quantità dei nuovi byte da scrivere, i restanti ultimi vecchi byte (ossia quelli che non saranno sovrascritti dai nuovi byte) saranno conservati.

Dalla documentazione:
« Diversamente da altri dialetti BASIC, Gambas non cancellerà mai un file quando esso viene aperto con la parola chiave WRITE. Quindi se il nuovo contenuto è più piccolo di quello vecchio, una parte del file non desiderata resterà in coda al file modificato. Per evitare questa situazione (che non è un difetto in quanto può far comodo in altri contesti), bisogna aprire il file includendo la parola chiave CREATE. »
Usando la parola-chiave CREATE in sostanza il vecchio file esistente, sarà distrutto e rimpiazzato da un nuovo file, creato con il suo medesimo nome.
Esempio:

fl = Open "/percorso/del/file/esistente" For Write Create   ' oppure solo Create

Write #fl, "Questa è una prova."

fl.Close

Scrivere in un file i dati contenuti in un'area di memoria puntata da un Puntatore

Per scrivere in un file i dati contenuti in un'area di memoria riservata, puntata da una variabile di tipo Puntatore, si dovrà indicare la quantità di dati-byte da scrivere. ^{[nota 2] [nota 3] [nota 4]}
Va precisato che questa modalità prevede comunque l'indicazione di un numero positivo qualsiasi di valori-byte da scrivere nel file. In assenza di detto numero, non verrà scritto alcun valore-byte nel file.

Write #file, puntatore, quantità_di_byte_da_scrivere

Esempio pratico:

Public Sub Main()
 
 Dim p As Pointer
 Dim fl As File
 
 p = Alloc("testo qualsiasi")
   
 fl = Open "/tmp/prova" For Create
   
' Scrive nel file solo otto valori-byte, a cominciare dal primo, di quelli contenuti nell'area di memoria allocata e puntata dal Puntatore "p":
 Write #fl, p, 8
   
' Va in chiusura liberando la memoria precedentemente comunque allocata:
 fl.Close
 Free(p)
  
End

Scrivere in un file i dati contenuti da un Vettore

Anche nel caso dell'uso di un Puntatore a un'area dei dati contenuti da un Vettore (array) va specificato il numero di byte-dati che si vogliono scrivere.
Nell'esempio, che segue, si scriveranno nel file tutti i dati presenti nel Vettore di tipo "Integer[]":

Public Sub Main()

 Dim ii As Integer[] = [100, 200, 300, 400]
 Dim fl As File
 
 fl = Open "/tmp/prova" For Create 
 Write #fl, ii.Data, ii.Count * SizeOf(gb.Integer)
 fl.Close

End

Scrivere in un file i dati contenuti in una Struttura

Per scrivere in un file i dati contenuti in una Struttura, bisognerà passare all'istruzione WRITE come secondo parametro la variabile della Struttura contenente quei dati, specificandone anche il tipo (Struttura). ^{[nota 5]}
Esempio pratico:

Public Struct STRUTTURA
  b As Byte
  c As Short
  i As Integer
End Struct


Public Sub Main()

 Dim fl As File
 Dim st As New STRUTTURA

 fl = Open "/percorso/del/file/da/creare" For Create

 With st
   .b = 1
   .c = 1000
   .i = 100000
 End With

 Write #fl, st As STRUTTURA

 fl.Close

End

Note

[1] La parola Write è utilizzata anche per scrivere in un Processo:

Private pr As Process


Public Sub Form_Open()

 pr = Shell "programma_da_lanciare" For Write

End 

Public Sub Button1_Click()

 Dim s As String = "Prova"
 
 Write #pr, s   ' o anche: Print #pr, s

End

[2] Questa modalità ricorda molto quella esperibile con il Metodo ".Write()" degli Oggetti array di Gambas.
Pertanto, possiamo dire che:

Write #flusso, puntatore, numero_dati_da_scrivere

corrisponde sostanzialmente a:

vettore.Write(flusso, 0, numero_dati_da_scrivere)

Altresì, se si tratta di un vettore, oltre ad utilizzare il predetto Metodo ".Write()", si potrà usare nuovamente la funzione "WRITE", purché con la Proprietà ".Data" dell'Oggetto vettore:

Write #flusso, vettore.Data, numero_dati_da_scrivere

[3] Vedere anche: Scrivere in un file i dati presenti in un vettore di tipo Byte

[4] Quest'uso dell'istruzione "WRITE" con una variabile di tipo Puntatore e il numero specificato di dati da scrivere può emulare il comportamento della funzione "fwrite()" del linguaggio C. Ciò risulta utile soprattutto nel caso di traduzione di un codice dal C a Gambas.
A tal riguardo vedere la seguente pagina: Emulare in Gambas la funzione fwrite() di C

[5] A tal riguardo vedere la seguente pagina: Scrivere i dati dei membri di una Struttura in un file direttamente

Riferimenti

• https://gambaswiki.org/wiki/lang/write?l=it