Free Format Input and Output
Free format ASCII I/O is extremely easy to use. The main advantage of free formatted ASCII I/O is that you do not have to provide a format string to format the data, because you assume that adjacent values are separated by delimiters.
The routines for performing freely formatted ASCII I/O are listed in
"ASCII I/O—Free Format".
Free Format Input
Input is performed on scalar variables. In other words, array and structure variables are treated as collections of scalar variables. For example:
Z_hi = INTARR(5)
READ, Z_hi
causes PV-WAVE to read (from the standard input stream) five separate values to fill each element of the variable Z_hi.
Input data must be separated by commas or white space (tabs and blank spaces).
If the current input line is empty and there are variables left to be filled, another line is read. If the current input line is not empty but there are no variables left to be filled, the remainder of the line is ignored.
When reading into a variable with data type String, all characters remaining in the current input line are placed into the string.
When reading into numeric variables, PV-WAVE attempts to convert the input into a value of the expected type. Decimal points are optional and exponential (scientific) notation is allowed. If a floating-point value is provided for an integer variable, the value is truncated.
Importing String Data
When PV-WAVE reads strings using free formats, it reads to the end of the line. For this reason, it is usually convenient to place string variables at the end of the list of variables to be input. For example, if S is a string variable and I is an integer, do not do this:
; Read into the string first.
READ, S, I
; PV-WAVE prompts for input. The user enters a string value
; followed by an integer.
: hello world 34
; Because this is a freely formatted read statement, and the READ
; procedure doesn’t recognize delimiters inside strings, the
; entire previous line was placed into the string variable S, and
; PV-WAVE still expects a value to be entered for I. Consequently,
; PV-WAVE prompts for another line.
: 34
; Show the result of S.
PRINT, S
results in the output:
'Hello world 34'
Importing Data into Complex Variables
Complex scalar values are treated as two floating-point values. When reading into a variable of complex type, the real and imaginary parts must be separated by a comma and surrounded by parentheses. If only a single value is provided, it is taken as the real part of the variable, and the imaginary part is set to zero.
Here are some examples of how to enter complex data from the keyboard:
; Create a complex variable.
Z_lo = COMPLEX(0)
; PV‑WAVE prompts for input: Z_lo is set to COMPLEX(3,4).
READ, Z_lo
: (3,4)
; PV‑WAVE prompts for input: Z_lo is set to COMPLEX(50,0).
READ, Z_lo
: 50
Importing Data into a Structure
The following statements demonstrate how to load data into a complicated structure variable and then print the results:
; Create a structure named “alltypes” that contains all nine of
; the basic data types, as well as a floating-point array.
A = {alltypes, a:0b, b:0, c:0i, d:0l, e:1.0, f:1D, $
g:COMPLEX(0), h:DCOMPLEX(0), i:'string', j:fltarr(5)} ; Read freely formatted ASCII data from standard input; PV-WAVE
; prompts for input. Enter values for the first eight numeric
; fields of A. Hit <Return> to enter the string as each string
; needs to be entered on its own line. Notice that the complex
; values are specified as (7,8) and (9,10). If parentheses are
; omitted, the complex fields of A would receive the value
; COMPLEX(7,0) and DCOMPLEX(8), and the 9 and 10 would be used
; for the next fields.
; When reading into a string variable with the READ procedure,
; and no format string has been provided, PV-WAVE starts from the
; current point in the input and continues to the end of the line.
; Thus, values intended for the rest of the structure are entered
; on a separate line, as shown in the next step.
READ, A
: 1 2 3 4 5 6 (7,8) (9,10)
; Strings need to be entered on their own line
: eleven
; There are still fields of A that have not received data, so
; PV-WAVE prompts for another line of input.
: 12 13 14 15 16
; Show the result.
PRINT, A
Executing these statements results in the following output:
{ 1 2 3 4 5.00000 6.0000000( 7.00000, 8.00000)( 9.0000000, 10.000000) eleven
12.0000 13.0000 14.0000 15.0000 16.0000
}
When producing the output, PV-WAVE uses default formats for formatting the values, and attempts to place as many items as possible onto each line. Because the variable
A is a structure, curly braces, “{” and “}”, are placed around the output. The default formats are shown in
"Free Format Output".
Importing Date/Time Data
The following statements show how to read a file that contains some data values and also some chronological information about when those data values were recorded. The name of the file is events.dat:
01/01/92 05:45:12 10
02/01/92 10:10:10 15.89
05/15/92 02:02:02 14.2
This example shows how to use the DC_READ_FREE function to read this data. When using DC_READ_FREE, the date data and the time data can be placed into the same date/time structure using predefined templates. To see a complete list of the date/time templates, refer to
"Date/Time Templates".
To read the date/time from the first two columns into date/time variables and then read the third column of floating point data into another variable, use the following statements:
; The system structure definition of date/time is !DT. Date/time
; variables must be defined as !DT arrays before being used if the
; date/time data is to be read as such.
date1 = REPLICATE({!DT},3); The variable date1 is used twice, once to read the date data and
; once to read the time data.
status = DC_READ_FREE("events.dat", date1, date1, float1, $
/Column, Dt_Template=[1,-1])To see the values of the variables, you can use the PRINT command:
FOR I = 0,2 DO BEGIN
; Print one row at a time.
PRINT, date1(I), float1(I)
ENDFOR
Executing these statements results in the following output:
{ 1992 01 01 05 45 12.00 } 10.0000 { 1992 02 01 10 10 10.00 } 15.8900 { 1992 05 15 02 02 02.00 } 14.2000Because date1 is a structure, curly braces, “{” and “}”, are placed around the output. When displaying the values of date1 and float1, PV-WAVE uses default formats for formatting the values, and attempts to place as many items as possible onto each line.
For more information about the internal organization of the !DT system structure, refer to Working with Date/Time Data in the PV‑WAVE User’s Guide. For more information about using the DC_READ_FREE function with date/time data, refer to its description in the PV‑WAVE Reference.
Free Format Output
The format used to output numeric data is determined by the data type.
note | When writing string data, each string (or element of a string array) is written to the file, flanked with a delimiter on each side. This implies that the strings should not contain delimiter characters if you intend use free format input at a later time to read the file. |
The current output line is filled with characters until one of the following happens (in the following order):
1. There is no more data to output.
2. The output line is full. The line width is controlled by the device characteristics, as determined by the terminal characteristics (tty), or the file’s record characteristics (disk file).
3. An entire row is output in the case of multidimensional arrays.
When writing the contents of a structure variable to a file, its contents are bracketed with curly braces, “{” and “}”.
Version 2017.1
Copyright © 2019, Rogue Wave Software, Inc. All Rights Reserved.