AT&T Home | AT&T Labs | Research
AT&T Labs, Inc. - Research

The Yoix® Scripting Language

Home | What's New | Grammar | Documentation | Download | License | YChart | YDAT | YWAIT | Byzgraf | FAQs
StringStream typedict
 
A StringStream is a type of Stream used by Yoix for directly reading from and writing to String objects. Using this Yoix type, one can treat string I/O the same as file I/O. Although the user visible portions of a StringStream only involve characters, the internals of the stream do involve bytes, thus references to character encoding and bytes occurs in the StringStream type as they do in the File type. The complete set of fields in a StringStream are:
autoready When set to a non-zero int value, read attempts on the stream will return an end-of-input indication rather than block when the stream has no input available. Since a read will not block as long as any bytes are left in the buffer, autoready is included only to provide a core of consistency to Stream types.
bufsize For efficiency, reading and writing is buffered up to the number of characters indicated by this int. Changing bufsize after a stream is used to read or write is not allowed and will result in an invalidaccess error.
callback(int mode [, Function func[, int trigger]]) A built-in for associating a user function with reading or writing activity. The mode can be READ, WRITE or EOF. When the mode is READ or WRITE, a trigger should also be supplied in addition to the user-defined function, func. Once a callback for a particular mode is defined, then the supplied values for func and trigger can be retrieved by omitting those arguments in the call to this built-in. When the mode is READ or WRITE, the supplied user function is called whenever the byte count exceeds the trigger value. When the mode is EOF, the user function is called when read operations reach the end of the stream. The byte count of activity since the callbacks were set-up is automatically supplied as the sole argument to the user function when it is called. Note that the byte count increments depend on the Stream buffer size. Thus, a trigger value of 5000 with a buffer size of 4096 means that the first function call occurs when the byte count is 8192, namely after the stream buffer is filled for the second time. This built-in is useful for providing interactive feedback using, for example, a JProgressBar.
checksum When a checksum filter is activated, the current checksum value can be obtained from this double. Note that for BSD and SYSV checksums, the built-in chkstr can be used to convert the value here to the more familiar string format. Writing any value to this field causes the checksum calculation to be reset.
cipher allows the assigning of a cipher to the stream when either reading or writing. The cipher should be suitable for the encrypting or decrypting of a large number of bytes as opposed to a small number as might occur in a signature. When assigning to this field, the value can be one of the following: a Cipher, an Array or a Dictionary. When the value is a Dictionary, it should contain at least two String fields, one called transformation and the other called keystring. Optionally, there can be a String field called provider. These field names correspond to those found in the Cipher object and have the same meaning. The same information can be supplied in shorthand via an Array. In that case, two array elements can provide transformation and keystring information, respectively, while three array elements can provide transformation, provider and keystring information, respectively. When either an Array or Dictionary is used, the mode of the cipher is automatically set to ENCRYPT_MODE for a stream that is writing and to DECRYPT_MODE for a stream that is reading. Changing cipher after a stream is used to read or write is not allowed and will result in an invalidaccess error.
encoding A String that indicates the type of byte-to-char encoding used when reading or the char-to-byte encoding used for writing. Changing encoding after a stream is used to read or write is not allowed and will result in an invalidaccess error.
filters One or more int flags can be combined to indicate how the stream should be filtered either for input or output. The flags are:
BSD Indicates that a BSD-style checksum should be calculated on the stream.
CRC32 Indicates that a CRC32-style checksum should be calculated on the stream.
GZIP Indicates that the stream should use gzip compression when writing or gzip decompression when reading.
HEXCODER Indicates that the stream should use hex encoding when writing or hex decoding when reading. Hex coding converts each character into bytes using ISO-8859-1 encoding and then converts each byte into a two character hexadecimal string with the high nybble first.
IETFCODER Indicates that the stream should use IETF RFC 2396 encoding when writing or IETF RFC 2396 decoding when reading. IETF RFC 2396 encoding is used, for example by perl's uri_escape.
LINEDHEXCODER Indicates that the stream should use fixed line length hex encoding when writing or hex decoding that ignores line breaks when reading. Output in this case is limited to 60 hex characters before a line break is inserted.
MIMECODER Indicates that the stream should use x-www-mime-urlencoded encoding when writing or x-www-mime-urlencoded decoding when reading. x-www-mime-urlencoded encoding is used, for example by Java's URLEncoder class.
SYSV Indicates that a SYSV-style checksum should be calculated on the stream.
ZIPPED Indicates that the stream should create when writing or decode when reading a stream of bytes consistent with the ZIP format (such as Java jar files or PKZIP files).
If checksum flags are used in combination with other checksum flags, the result is to default to a SYSV checksum. Changing filters after a stream is used to read or write is not allowed and will result in an invalidaccess error.
flushmode An int value that indicates the flushing strategy to use when writing. The value can be one of:
FLUSHDISABLED Do not flush output automatically except when the output buffer is full.
FLUSHLINES Flush output after each line-at-a-time write request. Note that writing an end-of-line character will not automatically cause a flush.
FLUSHWRITES Flush output after each write request.
An alternative is to explicitly call the fflush built-in.
fullname A read-only String that is always set to --string--.
interrupted An int that counts the number of times read operations on this stream are interrupted. An interrupted read operation automatically increments interrupted before returning a value that indicates the end-of-input. Writing is allowed and is the only way to reset interrupted to zero.
marksupported An int value indicating if the mark and reset built-ins are supported by this stream. A non-zero value means that they are supported, which is always the case for a StringStream.
mode An int value describing the mode of access, which is either READ or WRITE. If APPEND or UPDATE are also provided, they are ignored. Changing mode while a stream is open is not allowed and will result in an invalidaccess error.
name For an input stream, this String value provides the source for the StringStream. For an output stream, retrieving the value provides the current state of the output string. Changing name while a stream is open is not allowed and will result in an invalidaccess error.
nextbuf If the stream is open for writing, then assigning a String to this field will write it to the stream. If the stream is open for reading, then by requesting the value of this field, up to bufsize characters will be read from the stream and returned. When there is nothing to read, NULL is returned.
nextchar If the stream is open for writing, then assigning a int within the range 0 to 0xFFFF to this field will write it to the stream as a character. If the stream is open for reading, then by requesting the value of this field, the next character will be read from the stream and returned. When there is nothing to read, NULL is returned.
nextentry When a ZIPPED filter is active and the stream is open for writing, then assigning a ZipEntry to this field will write it to the stream, appropriately closing any existing entry being written. When a ZIPPED filter is active and the stream is open for reading, then requesting the value of this field causes the current entry being read, if any, to be closed and a ZipEntry describing the next entry int the stream to be returned. When there is nothing to read, NULL is returned. Accessing this field when a ZIPPED filter is not active causes an invalidaccess error.
nextline If the stream is open for writing, then assigning a String to this field will write it to the stream with a new-line appended. If the stream is open for reading, then by requesting the value of this field, all characters up to the next new-line will be returned from the input stream. The new-line itself is not returned. When there is nothing to read, NULL is returned.
open An int value indicating the open/close status of the stream. A non-zero value indicates the stream is open for access. Setting this value causes the stream to be opened or closed.
ready An int value indicating, when it is non-zero, that the stream can be read without blocking. In this case, it is non-zero as long as there is anything left to read.
size The size of the underlying string.
Several permanent fields have not been documented and should not be used in Yoix applications. Certain StringStream fields, namely: can have side-effects when accessed. Therefore, they must be explicitly referenced for their value to be retrieved. Simply dumping the entire StringStream will only display a default value for these fields.
 
 Example:   The program, 
import yoix.*.*;

StringStream outstr = new StringStream {
    int mode = WRITE;
    int filters = ZIPPED | CRC32;
    int open = TRUE;
};

ZipEntry ze;
String line;

ze.name = "odyssey.txt";
ze.extra = "The Odyssey (translation: Robert Fagles)";

outstr.nextentry = ze;

outstr.nextline =
    "Sing to me of the man, Muse, the man of twists and turns";
outstr.nextline =
    "driven time and again off course, once he had plundered";
outstr.nextline = "the hallowed heights of Troy.";

ze.name = "aeneid.txt";
ze.extra = "The Aeneid (translation: Allen Mandelbaum)";

outstr.nextentry = ze;

outstr.nextline = "I sing of arms and of a man: his fate";
outstr.nextline = "had made him fugitive; he was the first";
outstr.nextline = "to journey from the coasts of Troy as far";
outstr.nextline = "as Italy and the Lavinian shores.";

fprintf(stdout, "checksum for output: %d\n\n", outstr.checksum);

close(outstr);

StringStream instr = {
    String name = outstr.name;
    int mode = READ;
    int filters = ZIPPED | CRC32;
    int open = TRUE;
};

while(ze = instr.nextentry) {
    stdout.nextline = ze.extra;
    stdout.nextline = "";
    while(line = instr.nextline)
        stdout.nextline = line;
    stdout.nextline = "";
}

fprintf(stdout, "checksum for input: %d\n", instr.checksum);

close(instr);
writes a zipped package of information to a string and also computes a CRC32 checksum in the process. It then reads the result back, computes a CRC32 checksum on the input and writes the input and the checksum to standard output. The result on standard output would be as follows: 
checksum for output: 3299451163

The Odyssey (translation: Robert Fagles)

Sing to me of the man, Muse, the man of twists and turns
driven time and again off course, once he had plundered
the hallowed heights of Troy.

The Aeneid (translation: Allen Mandelbaum)

I sing of arms and of a man: his fate
had made him fugitive; he was the first
to journey from the coasts of Troy as far
as Italy and the Lavinian shores.

checksum for input: 3299451163
Note that the checksum values agree.
 
 See Also:   close, File, fopen, open, read, readChar, readLine, readStream, Stream, URL, write, writeChar, writeLine, ZipEntry

 

Yoix is a registered trademark of AT&T Inc.