String data type

The string data type is used to represent a string of characters.

You can declare a variable of type string:

  local string title

The default value for an uninitialized string shelf item is an empty string (that is, a string zero characters long). You can assign a value to a string in several ways:

You can assign the value of a literal string to a string variable:

  local string title initial {"Moby Dick"}
  set title to "Moby Dick"

You can assign the value of a closed stream to a string:

  process
     local stream temp
     local string message
     open temp as buffer
     using output as temp
        output "Hello, World!%n"
     close temp
     set message to temp
     output message

You can assign the value of a stream, string, or string source function to a string:

  define string source function weekday
   value integer day 
   as
     do select day
       case 1 output "Sunday"
       case 2 output "Monday"
       case 3 output "Tuesday"
       case 4 output "Wednesday"
       case 5 output "Thursday"
       case 6 output "Friday"
       case 7 output "Saturday"
     done
  
  process
     local string today
     set today to weekday 1
     output today || "%n"

You can define a function of type string and pass a string argument to a function:

  define string function greet
   value string recipient
   as 
     return "Hello " || recipient || "!"
  
  process
     output greet "Mars" || "%n"

The value of a string can be output, scanned, or used as the input to the markup parser. For instance,

  process
     local string s initial {"<a><b><c/></b></a>"}
     do xml-parse scan s
        output "%c"
     done

Strings and streams

The string data type replaces one of the functions of the stream data type. (Streams will continue to operate as strings when used as such, but this usage is deprecated.) However, string and stream are distinct types. A string and a stream can be used interchangeably in contexts in which they return the same type of value (a string), such as when they are output or passed to a value argument of a function, but you cannot perform stream-specific operation on a string:

A string cannot be closed
A string cannot be discarded
A string cannot be opened
A string cannot be the subject of stream-type tests.
A string shelf cannot be copyed or copy-cleared to a stream shelf.
A string cannot be passed to a function expecting a modifiable stream or write-only-stream shelf argument.
A string shelf can be passed to a function expecting a read-only stream argument. However, this may lead to run-time errors if the function performs stream-specific operations on the string. For example, the program:

  define function foo 
   read-only stream bar
   as
     output name of bar
  
  process
     local string baz
     foo baz

will compile correctly, but will lead to a run-time error because a string variable cannot be used with the name of operation.

Superseded functionality

The type stream has several roles in OmniMark, including the role of acting as a string variable. The role of string variable is now provided by the string type and the use of stream for this purpose is deprecated.

The type stream remains an important part of OmniMark and is still used for all cases where you need to attach a stream to a destination in order to stream data to that destination:

  process
     local stream out-file
     open out-file as file "out.txt"
     using output as out-file
        submit file #args[1]

The use of stream in the following contexts is deprecated in favor of string:

Declaring a function argument as value stream

Function arguments of type value stream:

  define function foo value stream my-stream

is deprecated in favor of value string:

  define function foo value string my-string

Stream as a return type

The use of stream as a return type for a function:

  define stream function foo

is deprecated in favor of string:

  define string function foo

Stream as a remainder type

The syntax remainder stream:

  define function foo (remainder stream s, ...)

is deprecated in favor of remainder string:

  define function foo (remainder string s, ...)

Prerequisite Concepts

Data types