Standard File I/O

Here, we'll discuss system functions for straightforward file input and output in VCSSL.

Standard File Output

Let's start with an example that writes a string to a file named "world.txt":

Executing this code creates a file named "world.txt" in the same directory as the program, containing the text "Hello world!".

In the "open" function, the first argument is the file name "world.txt", and the second argument is the text writing mode "w" (alternatively, you can use the constant WRITE). There are various other modes available for file operations.

The open function returns a unique identifier for the opened file, referred to as the "file ID". In the example above, it's stored in an integer variable named "fileID".

To perform file write/read operations or to close the file, you use this file ID, allowing you to manage multiple files simultaneously.

Writing Line by Line

In scenarios where you need to write content line by line, users familiar with C language might write:

However, while this works, it's discouraged in VCSSL due to potential confusion caused by environment-dependent newline characters. Instead, use the "writeln" function, which automatically appends the correct newline character based on the operating environment:

This approach ensures that each string is correctly followed by a newline, simplifying the writing process and avoiding cross-platform issues.

Standard File Input

Let's now try reading the file we previously wrote:

In the open function above, the "r" argument specifies the text reading mode. The "read" function retrieves the file's contents (alternatively, you can use the constant READ).

The return value of the "read" function is typically a string array. However, in text reading mode ("r"), it returns an array containing a single element. In VCSSL, you can directly assign an array with one element to a scalar variable. Thus, in the example above, the return value of the read function is stored in the scalar variable "text".

In binary reading mode ("rb"), the returned array from the "read" function contains bytes. In TSV reading mode ("rtsv"), the returned array contains contents separated by tabs or spaces. In CSV reading mode ("rcsv"), the returned array contains contents separated by commas. This means you need to handle the results differently depending on the mode used.

Reading Line By Line

To read the file line by line, follow these steps:

Here, we first ascertain the number of lines using the "countln" function. Then, we read through the file one line at a time using the readln function. Unlike the read function, which retrieves the entire file's contents at once, readln extracts content line by line, but otherwise it's the same.

Specification of Standard File I/O Functions

The functions used in the examples above, such as "open" and "readln", are called standard file I/O functions, provided by the "System" library.

List of Standard File I/O Functions

List of File I/O Modes

The modes specified as the second argument of the "open" function are outlined below.

Writing Modes

Reading Modes

Details and Notes for Each Mode

Text Writing/Reading Modes

These modes are intended for regular text files. In writing mode, the specified strings or values are written directly to the file as text. If multiple arguments are specified, they are written sequentially without any separators. In reading mode, the entire contents of a file or a line are returned as a string array with one element.

Binary Writing/Reading Modes

These modes allow for the direct reading and writing of byte values. Since VCSSL lacks a type specifically for handling single-byte values, reading and writing are performed using int type values. For example, writing a sequence of int values 1, 2, and 3 will directly write them as a sequence of unsigned byte values 1, 2, and 3 (represented in binary as 00000001, 00000010, and 00000011). Note that the maximum value that can be written in one byte is 255 (11111111).

TSV Writing/Reading Modes

These modes are designed for handling tab- or space-separated numerical data files. They are optimized for handling numerical data and perform simple operations without additional processing such as quoting or escaping values that contain delimiter characters or newlines.

CSV Writing/Reading Modes

Similar to TSV modes, these are for comma-separated numerical data files. Like TSV modes, no complex processing is performed for values that include delimiters or newlines.

For both TSV and CSV modes, if you require handling of files that need more sophisticated processing (such as escaping delimiters within values), you should use the open.file.TextFile library.

Writing Values of y = x^2 to a CSV Numerical Data File

Let's demonstrate writing to a CSV numerical data file. We'll calculate y = x^2 and output the results to a file:

Executing this code will generate a file named "x2.csv" in the same directory as the program. The content of the file will look like this:

Files in this format can be graphed using general graphing software or VCSSL's graph plotting functionality.

Reading a CSV Numerical Data File of y = x^2

Next, we'll read from the file we just created:

This program reads the "x2.csv" file, storing the separated values into x and y arrays, and then displays their contents on the console.

The "readln" function, when called for the first time, retrieves the first line of the file, separates it by the comma symbol ",", and stores it in a string array, then returns it. In the above code, this array is received in the integer array "line". Here implicit type conversion casts the strings to integers.

The line[0] represents the first value (x-value) described in the line, so it's stored in the integer array x, and similarly, the nexe value line[1] is stored in y. This completes the reading of one line.

Since "readln" is within a for loop, it's called repeatedly 10 times. When called for the second time, it reads the 2nd line of the file. This way, it reads up to the 10th line, and the program exits.

Specifying Character Encoding

When exchanging files created on different operating systems, issues like character encoding differences can lead to "mojibake" or garbled text. To address this, you can specify the character encoding in the "open" function by adding an encoding parameter.

Here are the character encodings you can use:

It's crucial to use the correct formal notation for each encoding. For example, "Shift_JIS" instead of "Shift-JIS" (using an underscore instead of a hyphen) is required to avoid errors. Similarly, "UTF-8" must be used instead of "UTF_8". Adherence to these formats is essential to ensure correct function usage.