/
File.txt
1342 lines (945 loc) · 42.6 KB
/
File.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
;
; File library documentation
;
; (c) 2024 - Fantaisie Software
;
@Library File
@Overview
Files are the main method for storing data on computers. PureBasic allows the programmer to create applications
in such a manner that the methods used to manage these files are simple to use, and yet still optimized.
Any number of files may be handled at the same time. This library uses buffered functions to increase the
reading/writing speed. All the file functions can handle huge files, all the way up to: 2^64 bytes,
(i.e. if the file-system supports it).
@LineBreak
@LineBreak
For large amounts of data it may be useful to load the data into an @ReferenceLink "dim" "array",
a @ReferenceLink "newlist" "list" or a @ReferenceLink "newmap" "Map",
using a @LibraryLink "memory" "memory block" may also be a good idea.
@LineBreak
@LineBreak
To get valid file paths for reading/saving data, take a look at
the @LibraryLink "filesystem" "FileSystem" and the @LibraryLink "requester" "Requester" libraries.
@CommandList
@ExampleFile All File.pb
@ExampleFile All FileSearch.pb
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function CloseFile(#File)
@Description
Close the specified file.
@Parameter "#File"
The file to close. If @#PB_All is specified, all the remaining files are closed.
@NoReturnValue
@Remarks
Once the file is closed, it may not be used anymore. Closing a file ensures the buffer will
effectively be put to the disk.
@LineBreak
@LineBreak
All remaining opened files are automatically closed when the program ends.
@LineBreak
@LineBreak
For an example see the @@ReadFile or the @@CreateFile functions.
@SeeAlso
@@CreateFile, @@OpenFile, @@ReadFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = CreateFile(#File, Filename$ [, Flags])
@Description
Create an empty file.
@Parameter "#File"
The number to identify the new file. @ReferenceLink "purebasic_objects" "#PB_Any" can be used to
auto-generate this number.
@Parameter "Filename$"
The filename and path to the new file. If the filename does not include a full path, it
is interpreted relative to the @Link "FileSystem/GetCurrentDirectory" "current directory".
@OptionalParameter "Flags"
It can be a combination (using the '| operand) of the following values:
@FixedFont
@#PB_File_SharedRead : the opened file can be read by another process (Windows only).
@#PB_File_SharedWrite: the opened file can be written by another process (Windows only).
@#PB_File_NoBuffering: the internal PureBasic file buffering system will be disabled for this file.
@@FileBuffersSize can not be used on this file.
@EndFixedFont
combined with one of the following values (the following flags affect the @@WriteString(), @@WriteStringN,
@@ReadString, @@ReadCharacter and @@WriteCharacter behaviour):
@FixedFont
@#PB_Ascii : all read/write string operation will use ASCII if not specified otherwise.
@#PB_UTF8 : all read/write string operation will use UTF-8 if not specified otherwise (default).
@#PB_Unicode: all read/write string operation will use Unicode if not specified otherwise.
@EndFixedFont
@ReturnValue
Returns nonzero if the file was created successfully and zero if there was an error.
If @#PB_Any was used as the #File parameter then the new generated number is returned on success.
@Remarks
If the file already exists, it will be overwritten by the new empty file.
The @@FileSize function can be used to determine whether a file exists so the
user can be prompted before overwriting a file.
@LineBreak
@LineBreak
To open an existing file for reading/writing, use the @@OpenFile function. To open a file for
reading only, use @@ReadFile.
@Example
@Code
If CreateFile(0, "Text.txt") ; we create a new text file...
For a=1 To 10
WriteStringN(0, "Line "+Str(a)) ; we write 10 lines (each with 'end of line' character)
Next
For a=1 To 10
WriteString(0, "String"+Str(a)) ; and now we add 10 more strings on the same line (because there is no 'end of line' character)
Next
CloseFile(0) ; close the previously opened file and store the written data this way
Else
MessageRequester("Information","may not create the file!")
EndIf
@EndCode
@SeeAlso
@@OpenFile, @@ReadFile, @@CloseFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = Eof(#File)
@Description
Checks whether the end of the file has been reached.
@Parameter "#File"
The file to use.
@ReturnValue
Returns nonzero if the read-pointer is at the end of the file or zero if not.
@Remarks
For an example see the @@ReadFile function.
@SeeAlso
@@Lof, @@Loc, @@CreateFile, @@OpenFile, @@ReadFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function FileBuffersSize(#File, Size)
@Description
Changes the size of the memory buffer used for file operations.
@Parameter "#File"
The file to change. If @#PB_Default is used as this parameter, then the
new buffer size will apply to all newly opened files with @@OpenFile,
@@CreateFile or @@ReadFile.
@Parameter "Size"
The new size (in bytes) for the memory buffer. A size of 0 disables memory buffering on the file.
@NoReturnValue
@Remarks
For performance reasons, the buffer size should be kept large enough (1028 seems
to be ok as a minimum). When buffers are used, the information is really written to the disk once the
cache buffer is full or when the file is closed. The @@FlushFileBuffers function
forces the cache buffer to be written at the time the function is called.
The default buffer size is 4096 bytes per file.
@SeeAlso
@@FlushFileBuffers
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = FileID(#File)
@Description
Returns the operating system handle of the file.
@Parameter "#File"
The file to use.
@ReturnValue
Returns the file handle.
@SeeAlso
@@CreateFile, @@OpenFile, @@ReadFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function FileSeek(#File, NewPosition.q [, Mode])
@Description
Change the read/write pointer position in the file.
@Parameter "#File"
The file to use.
@Parameter "NewPosition.q"
The new position relative to the beginning of the file in bytes.
@OptionalParameter "Mode"
The seek mode. It can be one of the following values:
@FixedFont
@#PB_Absolute: the 'NewPosition' parameter will be an absolute position with the file (default).
@#PB_Relative: the 'NewPosition' parameter will be an offset (positive or negative) relative to the current file pointer position.
@EndFixedFont
@NoReturnValue
@Example
@Code
File$ = OpenFileRequester("Select a file","","All files (*.*)|*.*",0)
If File$
If ReadFile(0, File$)
; Read length of file
Length = Lof(0)
Debug "File length: "+FormatNumber(Length, 0)+" bytes"
; Set the file pointer 10 bytes from end of file
FileSeek(0, Length - 10)
Debug "Position after seek: "+FormatNumber(Loc(0), 0)
CloseFile(0)
Else
Debug "Can't read the file: "+File$
EndIf
EndIf
@EndCode
@SeeAlso
@@Loc, @@Lof
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = FlushFileBuffers(#File)
@Description
Ensures that all buffered operations are written to disk.
@Parameter "#File"
The file to use.
@ReturnValue
Nonzero if the buffer has been successfully written the disk. If an error occurred (ie: disk full, disk error),
it will return zero.
@Remarks
See @@FileBuffersSize for more information about file buffer management.
@SeeAlso
@@FileBuffersSize
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = IsFile(#File)
@Description
Tests if the given #File number is a valid and correctly initialized file.
@Parameter "#File"
The file to use.
@ReturnValue
Returns nonzero if #File is a valid file and zero otherwise.
@Remarks
This function is bulletproof and may be used with any value. This is the correct way to ensure a file is ready to use.
@SeeAlso
@@CreateFile, @@OpenFile, @@ReadFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Position.q = Loc(#File)
@Description
Returns the read/write pointer position in the file.
@Parameter "#File"
The file to use.
@ReturnValue
Returns the file pointer position relative to the start of the file in bytes.
@Remarks
For an example look at the @@FileSeek function.
@SeeAlso
@@FileSeek, @@Lof
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Length.q = Lof(#File)
@Description
Returns the length of the specified file.
@Parameter "#File"
The file to use.
@ReturnValue
Returns the length of the file in bytes.
@Example
@Code
file$ = OpenFileRequester("Select a file","","Text (.txt)|*.txt|All files (*.*)|*.*",0)
If file$
If ReadFile(0, file$)
length = Lof(0) ; get the length of opened file
*MemoryID = AllocateMemory(length) ; allocate the needed memory
If *MemoryID
bytes = ReadData(0, *MemoryID, length) ; read all data into the memory block
Debug "Number of bytes read: " + Str(bytes)
EndIf
CloseFile(0)
EndIf
EndIf
@EndCode
@SeeAlso
@@Loc, @@FileSeek, @@FileSize
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = OpenFile(#File, Filename$ [, Flags])
@Description
Opens a file for reading/writing or creates a new file if it does not exist.
@Parameter "#File"
The number to identify the file. @ReferenceLink "purebasic_objects" "#PB_Any" can be used to
auto-generate this number.
@Parameter "Filename$"
The filename and path to the file. If the filename does not include a full path, it
is interpreted relative to the @Link "FileSystem/GetCurrentDirectory" "current directory".
@OptionalParameter "Flags"
It can be a combination (using the '| operand) of the following values:
@FixedFont
@#PB_File_SharedRead : the opened file can be read by another process (Windows only).
@#PB_File_SharedWrite: the opened file can be written by another process (Windows only).
@#PB_File_Append : the file pointer position will be set at the end of file.
@#PB_File_NoBuffering: the internal PureBasic file buffering system will be disabled for this file.
@@FileBuffersSize can not be used on this file.
@EndFixedFont
combined with one of the following values (the following flags affect the @@WriteString, @@WriteStringN,
@@ReadString, @@ReadCharacter and @@WriteCharacter behaviour):
@FixedFont
@#PB_Ascii : all read/write string operation will use ASCII if not specified otherwise.
@#PB_UTF8 : all read/write string operation will use UTF-8 if not specified otherwise (default).
@#PB_Unicode: all read/write string operation will use Unicode if not specified otherwise.
@EndFixedFont
@ReturnValue
Returns nonzero if the file was opened successfully and zero if there was an error.
If @#PB_Any was used as the #File parameter then the new generated number is returned on success.
@Remarks
This function fails if the file cannot be opened with write permission, for example if the file is located on a read-only
file-system like a CD. To open a file for reading only, use the @@ReadFile function. To overwrite an existing
file with a new and empty file, use the @@CreateFile function.
@LineBreak
@LineBreak
The file pointer will be positioned at the beginning of the file. To append data to the end of the file, use the
@#PB_File_Append flag to set the pointer to the end of the file.
@Example
@Code
If OpenFile(0, "Test.txt") ; opens an existing file or creates one, if it does not exist yet
FileSeek(0, Lof(0)) ; jump to the end of the file (result of Lof() is used)
WriteStringN(0, "... another line at the end.")
CloseFile(0)
EndIf
@EndCode
@SeeAlso
@@CreateFile, @@ReadFile, @@CloseFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function TruncateFile(#File)
@Description
Cuts the file at the current @Link "FileSeek" "file position" and discards all data that follows.
@Parameter "#File"
The file to use.
@NoReturnValue
@Remarks
This function may be used to shorten a file without the necessity of recreating it entirely. To make a file longer,
simply append more data with the write commands of this library.
@SeeAlso
@@FileSeek, @@Loc
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Number.a = ReadAsciiCharacter(#File)
@Description
Read an ASCII character (1 byte) from a file, starting at the current file position.
@Parameter "#File"
The file to read from.
@ReturnValue
Returns the read ASCII character or zero if there was an error.
@Remarks
For an example of how to read from a file, see the @@ReadFile function - with
ReadAsciiCharacter() only an ASCII character is read, instead of a complete line (string).
@SeeAlso
@@WriteAsciiCharacter, @@ReadUnicodeCharacter, @@ReadCharacter, @@OpenFile, @@ReadFile, @@Loc
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Number.b = ReadByte(#File)
@Description
Read a byte (1 byte) from a file, starting at the current file position.
@Parameter "#File"
The file to read from.
@ReturnValue
Returns the read byte or zero if there was an error.
@Remarks
For an example of how read from a file see the @@ReadFile function - with
ReadByte() only a byte value is read, instead of a complete line (string).
@SeeAlso
@@WriteByte, @@OpenFile, @@ReadFile, @@Loc
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result.c = ReadCharacter(#File [, Format])
@Description
Read a character from a file, starting at the current file position.
@Parameter "#File"
The file to read from.
@OptionalParameter "Format"
The format of the character to read. It can be one of the following value:
@FixedFont
@#PB_Ascii : 1 byte character.
@#PB_Unicode: 2 bytes character (default in @ReferenceLink "unicode" "unicode" mode).
@#PB_UTF8 : multi-bytes character (from 1 to 4 bytes).
@EndFixedFont
If this flag isn't set, then the format for reading the character depends on the related setting at
the previously used @@CreateFile, @@OpenFile or @@ReadFile command.
@ReturnValue
Returns the read character or zero if there was an error.
@Remarks
For an example of how to read from a file, see the @@ReadFile function - with
ReadCharacter() only a character is read, instead of a complete line (string).
@SeeAlso
@@WriteCharacter, @@ReadAsciiCharacter, @@ReadUnicodeCharacter, @@OpenFile, @@ReadFile, @@Loc
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Number.d = ReadDouble(#File)
@Description
Read a double (8 bytes) from a file, starting at the current file position.
@Parameter "#File"
The file to read from.
@ReturnValue
Returns the read double value or zero if there was an error.
@Remarks
For an example of how to read from a file, see the @@ReadFile function - with
ReadDouble() only a double value is read, instead of a complete line (string).
@SeeAlso
@@WriteDouble, @@OpenFile, @@ReadFile, @@Loc
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = ReadFile(#File, Filename$ [, Flags])
@Description
Open an existing file for read-only operations.
@Parameter "#File"
The number to identify the file. @ReferenceLink "purebasic_objects" "#PB_Any" can be used to
auto-generate this number.
@Parameter "Filename$"
The filename and path to the file. If the filename does not include a full path, it
is interpreted relative to the @Link "FileSystem/GetCurrentDirectory" "current directory".
@OptionalParameter "Flags"
It can be a combination (using the '| operand) of the following values:
@FixedFont
@#PB_File_SharedRead : if the file has been already opened by another process or thread for read operation,
this flag is needed to access it (Windows only).
@#PB_File_SharedWrite: if the file has been already opened by another process or thread for write operation,
this flag is needed to access it (Windows only).
@#PB_File_NoBuffering: the internal PureBasic file buffering system will be disabled for this file.
@@FileBuffersSize can not be used on this file.
@EndFixedFont
combined with one of the following values (the following flags affect the behaviour of @@ReadString
and @@ReadCharacter):
@FixedFont
@#PB_Ascii : all read string operation will use ASCII if not specified otherwise.
@#PB_UTF8 : all read string operation will use UTF-8 if not specified otherwise (default).
@#PB_Unicode: all read string operation will use Unicode if not specified otherwise.
@EndFixedFont
@ReturnValue
Returns nonzero if the file was opened successfully and zero if there was an error.
If @#PB_Any was used as the #File parameter then the new generated number is returned on success.
@Remarks
To open a file for reading and writing, use the @@OpenFile function.
To create a new and empty file, use the @@CreateFile function.
@Example
@Code
If ReadFile(0, "Text.txt") ; if the file could be read, we continue ...
Format = ReadStringFormat(0)
While Eof(0) = 0 ; loop as long the 'end of file' isn't reached
Debug ReadString(0, Format) ; display line by line in the debug window
Wend
CloseFile(0) ; close the previously opened file
Else
MessageRequester("Information", "Couldn't open the file!")
EndIf
@EndCode
@SeeAlso
@@OpenFile, @@CreateFile, @@CloseFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Number.f = ReadFloat(#File)
@Description
Read a float (4 bytes) from a file, starting at the current file position.
@Parameter "#File"
The file to read from.
@ReturnValue
Returns the read float value or zero if there was an error.
@Remarks
For an example of how to read from a file, see the @@ReadFile function - with
ReadFloat() only a float value is read, instead of a complete line (string).
@SeeAlso
@@WriteFloat, @@ReadDouble, @@OpenFile, @@ReadFile, @@Loc
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Number.i = ReadInteger(#File)
@Description
Read an integer (4 bytes in 32-bit executable, 8 bytes in 64-bit executable) from a file, starting at the current file position.
@Parameter "#File"
The file to read from.
@ReturnValue
Returns the read value or zero if there was an error.
@Remarks
For an example of how to read from a file, see the @@ReadFile function - with
ReadInteger() only a integer value is read, instead of a complete line (string).
@SeeAlso
@@WriteInteger, @@OpenFile, @@ReadFile, @@Loc
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Number.l = ReadLong(#File)
@Description
Read a long (4 bytes) from a file, starting at the current file position.
@Parameter "#File"
The file to read from.
@ReturnValue
Returns the read value or zero if there was an error.
@Remarks
For an example of how to read from a file, see the @@ReadFile function - with
ReadLong() only a long value is read, instead of a complete line (string).
@SeeAlso
@@WriteLong, @@OpenFile, @@ReadFile, @@Loc
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Number.q = ReadQuad(#File)
@Description
Read a quad (8 bytes) from a file, starting at the current file position.
@Parameter "#File"
The file to read from.
@ReturnValue
Returns the read number or zero if there was an error.
@Remarks
For an example of how to read from a file, see the @@ReadFile function - with
ReadQuad() only a quad value is read, instead of a complete line (string).
@SeeAlso
@@WriteQuad, @@OpenFile, @@ReadFile, @@Loc
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = ReadData(#File, *MemoryBuffer, LengthToRead)
@Description
Read the content from the file to the specified memory buffer, starting at the current file position.
@Parameter "#File"
The file to read from.
@Parameter "*MemoryBuffer"
The address to write the read data to.
@Parameter "LengthToRead"
The number of bytes to read. The maximum length is 2 GB.
@ReturnValue
Returns the number of bytes actually read from the file. If there is an error,
the return value is zero.
@Remarks
For a code example look at the @@Lof function.
@SeeAlso
@@WriteData, @@OpenFile, @@ReadFile, @@Loc
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Text$ = ReadString(#File [, Flags [, Length]])
@Description
Read a string from a file until an 'End Of Line' or a 'Null' character is found (Unix, DOS and Macintosh
file formats are supported).
@Parameter "#File"
The file to read from.
@OptionalParameter "Flags"
The flags to apply while reading the string. It may be one of the following values:
@FixedFont
@#PB_Ascii : reads the string as ASCII
@#PB_UTF8 : reads the string as UTF8
@#PB_Unicode: reads the string as UTF16
@EndFixedFont
combined with:
@FixedFont
@#PB_File_IgnoreEOL: ignores the end of line (but the resulting string will still contain them) until the specified
length or the end of file.
@EndFixedFont
If this flag isn't set, then the format for reading the string depends on the related setting at
the previously used @@CreateFile, @@OpenFile or @@ReadFile command.
@OptionalParameter "Length"
Read the file until the length (in characters) have been reached. If an end of line is encountered
before the length is reached, the read will stop (unless the flag @#PB_File_IgnoreEOL has been set).
@ReturnValue
Returns the read string, or an empty string if the read has failed.
@Remarks
For detecting the string encoding format (byte order mark) used in a file there is the
@@ReadStringFormat function available.
@LineBreak
@LineBreak
For an example see the @@ReadFile.
@SeeAlso
@@WriteString, @@ReadStringFormat, @@OpenFile, @@ReadFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = ReadStringFormat(#File)
@Description
Checks if the current file position contains a BOM (Byte Order Mark) and tries to identify the
String encoding used in the file.
@Parameter "#File"
The file to use.
@ReturnValue
Returns one of the following values:
@FixedFont
@#PB_Ascii : No BOM detected. This usually means a plain text file.
@#PB_UTF8 : UTF-8 BOM detected.
@#PB_Unicode: UTF-16 (little endian) BOM detected.
@#PB_UTF16BE: UTF-16 (big endian) BOM detected.
@#PB_UTF32 : UTF-32 (little endian) BOM detected.
@#PB_UTF32BE: UTF-32 (big endian) BOM detected.
@EndFixedFont
The @#PB_Ascii, @#PB_UTF8 and @#PB_Unicode results may be used directly
in further calls to @@ReadString to read the file. The other results represent string
formats that cannot be directly read with PureBasic string functions. They are included for completeness so that an
application can display a proper error-message.
@Remarks
If a BOM is detected, the @Link "FileSeek" "file pointer" will be placed
at the end of the BOM. If no BOM is detected, the file pointer remains unchanged.
@LineBreak
@LineBreak
The Byte Order Mark is a commonly used way to indicate the encoding for a textfile. It is usually placed
at the beginning of the file. It is however not a standard, just a commonly used practice. So if no BOM is
detected at the start of a file, it does not necessarily mean that it is a plain text file. It could also
just mean that the program that created the file did not use this practice.
@@WriteStringFormat may be used to place such a BOM in a file.
@LineBreak
@LineBreak
For more information, see this @InternetLink "http://en.wikipedia.org/wiki/Byte_Order_Mark" "Wikipedia Article."
@LineBreak
More information about using unicode in a PureBasic program can also be found @ReferenceLink "unicode" "here".
@SeeAlso
@@WriteStringFormat, @@ReadString, @@OpenFile, @@ReadFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Number.u = ReadUnicodeCharacter(#File)
@Description
Read a unicode character (2 bytes) from a file, starting at the current file position.
@Parameter "#File"
The file to read from.
@ReturnValue
Returns the read character or zero if there was an error.
@Remarks
For an example of how to read from a file, see the @@ReadFile function - with
ReadUnicodeCharacter() only a unicode character is read, instead of a complete line (string).
@SeeAlso
@@WriteUnicodeCharacter, @@ReadAsciiCharacter, @@ReadCharacter, @@OpenFile, @@ReadFile, @@Loc
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Number.w = ReadWord(#File)
@Description
Read a word (2 bytes) from a file, starting at the current file position.
@Parameter "#File"
The file to read from.
@ReturnValue
Returns the read number or zero if there was an error.
@Remarks
For an example of how to read from a file, see the @@ReadFile function - with
ReadWord() only a word value is read, instead of a complete line (string).
@SeeAlso
@@WriteWord, @@OpenFile, @@ReadFile, @@Loc
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = WriteAsciiCharacter(#File, Number.a)
@Description
Write an ASCII character (1 byte) to a file.
@Parameter "#File"
The file to write to.
@Parameter "Number"
The ASCII character value to write.
@ReturnValue
Returns nonzero if the operation was successful and zero if it failed.
@Remarks
Because of @Link "FileBuffersSize" "file buffering", this function may return successful even if there is not enough
space left on the output device for the write operation.
The file must be opened using a write-capable function (i.e. not with @@ReadFile).
@LineBreak
@LineBreak
For an example see the @@CreateFile function - with WriteAsciiCharacter() only an ASCII character is written, instead of a string.
@SeeAlso
@@ReadAsciiCharacter, @@WriteUnicodeCharacter, @@WriteCharacter, @@CreateFile, @@OpenFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = WriteByte(#File, Number.b)
@Description
Write a byte number (1 byte) to a file.
@Parameter "#File"
The file to write to.
@Parameter "Number"
The value to write.
@ReturnValue
Returns nonzero if the operation was successful and zero if it failed.
@Remarks
Because of @Link "FileBuffersSize" "file buffering", this function may return successful even if there is not enough
space left on the output device for the write operation.
The file must be opened using a write-capable function (i.e. not with @@ReadFile).
@LineBreak
@LineBreak
For an example see the @@CreateFile function - with WriteByte() only a byte number is written, instead of a string.
@SeeAlso
@@ReadByte, @@CreateFile, @@OpenFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = WriteCharacter(#File, Character.c [, Format])
@Description
Write a character number (1 byte in ASCII, 2 bytes in @ReferenceLink "unicode" "unicode") to a file.
@Parameter "#File"
The file to write to.
@Parameter "Character"
The character value to write.
@OptionalParameter "Format"
The format of the character to write. It can be one of the following value:
@FixedFont
@#PB_Ascii : 1 byte character.
@#PB_Unicode: 2 bytes character (default, see @ReferenceLink "unicode" "unicode" mode).
@#PB_UTF8 : multi-bytes character (from 1 to 4 bytes).
@EndFixedFont
If this flag isn't set, then the format for writing the character depends on the related setting at
the previously used @@CreateFile or @@OpenFile command.
@ReturnValue
Returns nonzero if the operation was successful or zero if it failed.
@Remarks
Because of @Link "FileBuffersSize" "file buffering", this function may return successful even if there is not enough
space left on the output device for the write operation.
The file must be opened using a write-capable function (i.e. not with @@ReadFile).
@LineBreak
@LineBreak
For an example see the @@CreateFile function - with WriteCharacter() only a character number is written, instead of a string.
@SeeAlso
@@ReadCharacter, @@writeAsciiCharacter, @@WriteUnicodeCharacter, @@CreateFile, @@OpenFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = WriteDouble(#File, Number.d)
@Description
Write a double number (8 bytes) to a file.
@Parameter "#File"
The file to write to.
@Parameter "Number.d"
The value to write.
@ReturnValue
Returns nonzero if the operation was successful and zero if it failed.
@Remarks
Because of @Link "FileBuffersSize" "file buffering", this function may return successful even if there is not enough
space left on the output device for the write operation.
The file must be opened using a write-capable function (i.e. not with @@ReadFile).
@LineBreak
@LineBreak
For an example see the @@CreateFile function - with WriteDouble() only a double number is written, instead of a string.
@SeeAlso
@@ReadDouble, @@WriteFloat, @@CreateFile, @@OpenFile
@SupportedOS
;--------------------------------------------------------------------------------------------------------
@Function Result = WriteFloat(#File, Number.f)
@Description
Write a float number (4 bytes) to a file.
@Parameter "#File"
The file to write to.
@Parameter "Number.f"
The float value to write.
@ReturnValue
Returns nonzero if the operation was successful and zero if it failed.
@Remarks
Because of @Link "FileBuffersSize" "file buffering", this function may return successful even if there is not enough
space left on the output device for the write operation.
The file must be opened using a write-capable function (i.e. not with @@ReadFile).
@LineBreak
@LineBreak
For an example see the @@CreateFile function - with WriteFloat() only a float number is written, instead of a string.
@SeeAlso
@@ReadFloat, @@WriteDouble, @@CreateFile, @@OpenFile