Modelica.Utilities.Streams

Information

Library content

Package Streams contains functions to input and output strings to a message window or on files. Note that a string is interpreted and displayed as html text (e.g., with print(..) or error(..)) if it is enclosed with the Modelica html quotation, e.g.,

It is a quality of implementation, whether (a) all tags of html are supported or only a subset, (b) how html tags are interpreted if the output device does not allow to display formatted text.

In the table below an example call to every function is given:

Use functions scanXXX from package Strings to parse a string.

If Real, Integer or Boolean values shall be printed or used in an error message, they have to be first converted to strings with the builtin operator String(...). Example:

  if x < 0 or x > 1 then
     Streams.error("x (= " + String(x) + ") has to be in the range 0 .. 1");
  end if;

Extends from Modelica.Icons.Package (Icon for standard packages).

Package Content

Name	Description
print	Print string to terminal or file
readFile	Read content of a file and return it in a vector of strings
readLine	Reads a line of text from a file and returns it in a string
countLines	Returns the number of lines in a file
error	Print error message and cancel all actions
close	Close file

Modelica.Utilities.Streams.print

Information

Syntax

Streams.print(string);
Streams.print(string,fileName);

Description

Function print(..) opens automatically the given file, if it is not yet open. If the file does not exist, it is created. If the file does exist, the given string is appended to the file. If this is not desired, call "Files.remove(fileName)" before calling print ("remove(..)" is silent, if the file does not exist). The Modelica environment may close the file whenever appropriate. This can be enforced by calling Streams.close(fileName). After every call of "print(..)" a "new line" is printed automatically.

Example

  Streams.print("x = " + String(x));
  Streams.print("y = " + String(y));
  Streams.print("x = " + String(y), "mytestfile.txt");

See also

Streams, Streams.error, String

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

Type	Name	Default	Description
String	string	""	String to be printed
String	fileName	""	File where to print (empty string is the terminal)

Modelica definition

function print "Print string to terminal or file"
  extends Modelica.Icons.Function;
  input String string="" "String to be printed";
  input String fileName="" "File where to print (empty string is the terminal)";
external "C" ModelicaInternal_print(string, fileName);
end print;

Modelica.Utilities.Streams.readFile

Information

Syntax

stringVector = Streams.readFile(fileName)

Description

Function readFile(..) opens the given file, reads the complete content, closes the file and returns the content as a vector of strings. Lines are separated by LF or CR-LF; the returned strings do not contain the line separators.

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

Type	Name	Default	Description
String	fileName		Name of the file that shall be read

Outputs

Type	Name	Description
String	stringVector[countLines(fileName)]	Content of file

Modelica definition

function readFile 
  "Read content of a file and return it in a vector of strings"
  extends Modelica.Icons.Function;
  input String fileName "Name of the file that shall be read";
  output String stringVector[countLines(fileName)] "Content of file";

algorithm 
  for i in  1:size(stringVector, 1) loop
    stringVector[i] := readLine(fileName, i);
  end for;
  Streams.close(fileName);
end readFile;

Modelica.Utilities.Streams.readLine

Information

Syntax

(string, endOfFile) = Streams.readLine(fileName, lineNumber)

Description

Function readLine(..) opens the given file, reads enough of the content to get the requested line, and returns the line as a string. Lines are separated by LF or CR-LF; the returned string does not contain the line separator. The file might remain open after the call.

If lineNumber > countLines(fileName), an empty string is returned and endOfFile=true. Otherwise endOfFile=false.

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

Type	Name	Default	Description
String	fileName		Name of the file that shall be read
Integer	lineNumber		Number of line to read

Outputs

Type	Name	Description
String	string	Line of text
Boolean	endOfFile	If true, end-of-file was reached when trying to read line

Modelica definition

function readLine 
  "Reads a line of text from a file and returns it in a string"
  extends Modelica.Icons.Function;
  input String fileName "Name of the file that shall be read";
  input Integer lineNumber(min=1) "Number of line to read";
  output String string "Line of text";
  output Boolean endOfFile 
    "If true, end-of-file was reached when trying to read line";
 external "C" string = ModelicaInternal_readLine(fileName,lineNumber,endOfFile);
end readLine;

Modelica.Utilities.Streams.countLines

Information

Syntax

numberOfLines = Streams.countLines(fileName)

Description

Function countLines(..) opens the given file, reads the complete content, closes the file and returns the number of lines. Lines are separated by LF or CR-LF.

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

Type	Name	Default	Description
String	fileName		Name of the file that shall be read

Outputs

Type	Name	Description
Integer	numberOfLines	Number of lines in file

Modelica definition

function countLines "Returns the number of lines in a file"
  extends Modelica.Icons.Function;
  input String fileName "Name of the file that shall be read";

  output Integer numberOfLines "Number of lines in file";
external "C" numberOfLines = ModelicaInternal_countLines(fileName);
end countLines;

Modelica.Utilities.Streams.error

Information

Syntax

Streams.error(string);

Description

Print the string "string" as error message and cancel all actions. Line breaks are characterized by "\n" in the string.

Example

  Streams.error("x (= " + String(x) + ")\nhas to be in the range 0 .. 1");

See also

Streams, Streams.print, String

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

Type	Name	Default	Description
String	string		String to be printed to error message window

Modelica definition

function error "Print error message and cancel all actions"
  extends Modelica.Icons.Function;
  input String string "String to be printed to error message window";
  external "C" ModelicaError(string);
end error;

Modelica.Utilities.Streams.close

Information

Syntax

Streams.close(fileName)

Description

Close file if it is open. Ignore call if file is already closed or does not exist.

Extends from Modelica.Icons.Function (Icon for functions).

Inputs

Type	Name	Default	Description
String	fileName		Name of the file that shall be closed

Modelica definition

function close "Close file"
  extends Modelica.Icons.Function;
  input String fileName "Name of the file that shall be closed";
  external "C" ModelicaStreams_closeFile(fileName);
end close;