Geek Gadgets 1

home *** CD-ROM | disk | FTP | other *** search

/ Geek Gadgets 1 / ADE-1.bin / ade-dist / octave-1.1.1p1-bin.lha / info / octave.info-6 (.txt) < prev next >

Wrap

GNU Info File | 1996-10-12 | 50KB | 941 lines

This is Info file octave.info, produced by Makeinfo-1.64 from the input file octave.texi. Copyright (C) 1993, 1994, 1995 John W. Eaton. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. File: octave.info, Node: Basic Input and Output, Next: C-Style I/O Functions, Prev: Input and Output, Up: Input and Output Basic Input and Output ====================== Since Octave normally prints the value of an expression as soon as it has been evaluated, the simplest of all I/O functions is a simple expression. For example, the following expression will display the value of pi octave:13> pi pi = 3.1416 This works well as long as it is acceptable to have the name of the variable (or `ans') printed along with the value. To print the value of a variable without printing its name, use the function `disp'. For example, the following expression disp ("The value of pi is:"), disp (pi) will print The value of pi is: 3.1416 Note that the output from `disp' always ends with a newline. A simple way to control the output format is with the `format' statement. For example, to print more digits for pi you can use the command format long Then the expression above will print The value of pi is: 3.14159265358979 Here is a summary of the options for `format': `short' This is the default format. Octave will try to print numbers with at least 5 significant figures within a field that is a maximum of 10 characters wide. If Octave is unable to format a matrix so that columns line up on the decimal point and all the numbers fit within the maximum field width, it switches to an `e' format. `long' Octave will try to print numbers with at least 15 significant figures within a field that is a maximum of 24 characters wide. As will the `short' format, Octave will switch to an `e' format if it is unable to format a matrix so that columns line up on the decimal point and all the numbers fit within the maximum field width. `long e' `short e' The same as `format long' or `format short' but always display output with an `e' format. For example, with the `short e' format, pi is displayed as 3.14e+00 `long E' `short E' The same as `format long e' or `format short e' but always display output with an uppercase `E' format. For example, with the `long E' format, pi is displayed as 3.14159265358979E+00 `free' `none' Print output in free format, without trying to line up columns of matrices on the decimal point. This also causes complex numbers to be formatted like this `(0.604194, 0.607088)' instead of like this `0.60419 + 0.60709i'. `bank' Print in a fixed format with two places to the right of the decimal point. Print a `+' symbol for nonzero matrix elements and a space for zero matrix elements. This format can be very useful for examining the structure of a large matrix. The `input' function may be used for prompting the user for a value and storing the result in a variable. For example, input ("Pick a number, any number! ") prints the prompt Pick a number, any number! and waits for the user to enter a value. The string entered by the user is evaluated as an expression, so it may be a literal constant, a variable name, or any other valid expression. Currently, `input' only returns one value, regardless of the number of values produced by the evaluation of the expression. If you are only interested in getting a literal string value, you can call `input' with the character string `s' as the second argument. This tells Octave to return the string entered by the user directly, without evaluating it first. Because there may be output waiting to be displayed by the pager, it is a good idea to always call `fflush (stdout)' before calling `input'. This will ensure that all pending output is written to the screen before your prompt. *Note C-Style I/O Functions::. The second input function, `keyboard', is normally used for simple debugging. Using `keyboard', it is possible to examine the values of variables within a function, and to assign newassign new variables Like `input', it prompts the user for input, but no value is returned, and it continues to prompt for input until the user types `quit', or `exit'. If `keyboard' is invoked without any arguments, a default prompt of `debug> ' is used. For both of these functions, the normal command line history and editing functions are available at the prompt. To save variables in a file, use the `save' command. For example, the command save data a b c saves the variables `a', `b', and `c' in the file `data'. The SAVE command can read files in Octave's text and binary formats as well as MATLAB's binary format. You can specify the default format with the built-in variable DEFAULT_SAVE_FORMAT using one of the following values: `"binary"' or `"mat-binary"'. The initial default save format is Octave's text format. You can use the built-in variable `save_precision' to specify the number of digits to keep when saving data in text format. The list of variables to save may include wildcard patterns containing the following special characters: Match any single character. Match zero or more characters. `[ LIST ]' Match the list of characters specified by LIST. If the first character is `!' or `^', match all characters except those specified by LIST. For example, the pattern `[a-zA-Z]' will match all lower and upper case alphabetic characters. The following options may be specified for `save'. `-ascii' Save the data in Octave's text data format. Using this flag overrides the value of the built-in variable `default_save_format'. `-binary' Save the data in Octave's binary data format. Using this flag overrides the value of the built-in variable `default_save_format'. `-float-binary' Save the data in Octave's binary data format but only using single precision. Using this flag overrides the value of the built-in variable `default_save_precision'. You should use this format only if you know that all the values to be saved can be represented in single precision. `-mat-binary' Save the data in MATLAB's binary data format. Using this flag overrides the value of the built-in variable `default_save_format'. `-save-builtins' Force Octave to save the values of built-in variables too. By default, Octave does not save built-in variables. Saving global variables also saves the global status of the variable, so that if it is restored at a later time using `load', it will be restored as a global variable. To restore the values from a file, use the `load' command. For example, to restore the variables saved in the file `data', use the command load data Octave will refuse to overwrite existing variables unless you use the option `-force'. If a variable that is not marked as global is loaded from a file when a global symbol with the same name already exists, it is loaded in the global symbol table. Also, if a variable is marked as global in a file and a local symbol exists, the local symbol is moved to the global symbol table and given the value from the file. Since it seems that both of these cases are likely to be the result of some sort of error, they will generate warnings. As with `save', you may specify a list of variables and `load' will only extract those variables with names that match. The `load' command can read data stored in Octave's text and binary formats, and MATLAB's binary format. It will automatically detect the type of file and do conversion from different floating point formats (currently only IEEE big and little endian, though other formats may added in the future). The following options may be specified for `save'. `-force' Force variables currently in memory to be overwritten by variables with the same name found in the file. `-ascii' Force Octave to assume the file is in Octave's text format. `-binary' Force Octave to assume the file is in Octave's binary format. `-mat-binary' Force Octave to assume the file is in MATLAB's binary format. File: octave.info, Node: C-Style I/O Functions, Prev: Basic Input and Output, Up: Input and Output C-Style I/O Functions ===================== The C-style input and output functions provide most of the functionality of the C programming language's standard I/O library. The argument lists for some of the input functions are slightly different, however, because Octave has no way of passing arguments by reference. In the following, FILE refers either to an integer file number (as returned by `fopen') or a file name. There are three files that are always available: `stdin' The standard input stream (file number 0). When Octave is used interactively, this is filtered through the command line editing functions. `stdout' The standard output stream (file number 1). Data written to the standard output is normally filtered through the pager. `stderr' The standard error stream (file number 2). Even if paging is turned on, the standard error is not sent to the pager. It is useful for error messages and prompts. You should always use the symbolic names given in the table above, rather than referring to these files by number, since it will make your programs clearer. * Menu: * Opening and Closing Files:: * Formatted Output:: * Output Conversion Syntax:: * Table of Output Conversions:: * Integer Conversions:: * Floating-Point Conversions:: * Other Output Conversions:: * Formatted Input:: * Input Conversion Syntax:: * Table of Input Conversions:: * Numeric Input Conversions:: * String Input Conversions:: * Binary I/O:: * Other I/O Functions:: File: octave.info, Node: Opening and Closing Files, Next: Formatted Output, Prev: C-Style I/O Functions, Up: C-Style I/O Functions Opening and Closing Files ------------------------- To open a file, use the function `fopen (name, mode)'. It returns an integer value that may be used to refer to the file later. The second argument is a one or two character string that specifies whether the file is to be opened for reading, writing, or both. For example, myfile = fopen ("splat.dat", "r"); opens the file `splat.dat' for reading. Opening a file that is already open has no effect. The possible values `mode' may have are Open a file for reading. Open a file for writing. The previous contents are discared. Open or create a file for writing at the end of the file. Open an existing file for reading and writing. Open a file for reading or writing. The previous contents are discared. Open or create a file for reading or writing at the end of the file. To close a file once you are finished with it, use the function `fclose (FILE)'. If an error is encountered while trying to close the file, an error message is printed and `fclose' returns 0. Otherwise, it returns 1. File: octave.info, Node: Formatted Output, Next: Output Conversion Syntax, Prev: Opening and Closing Files, Up: C-Style I/O Functions Formatted Output ---------------- This section describes how to call `printf' and related functions. The following functions are available for formatted output. They are modelled after the C language functions of the same name. `printf (TEMPLATE, ...)' The `printf' function prints the optional arguments under the control of the template string TEMPLATE to the stream `stdout'. `fprintf (FILE, TEMPLATE, ...)' This function is just like `printf', except that the output is written to the stream FILE instead of `stdout'. `sprintf (TEMPLATE, ...)' This is like `printf', except that the output is written to a string. Unlike the C library function, which requires you to provide a suitably sized string as an argument, Octave's `sprintf' function returns the string, automatically sized to hold all of the items converted. The `printf' function can be used to print any number of arguments. The template string argument you supply in a call provides information not only about the number of additional arguments, but also about their types and what style should be used for printing them. Ordinary characters in the template string are simply written to the output stream as-is, while "conversion specifications" introduced by a `%' character in the template cause subsequent arguments to be formatted and written to the output stream. For example, pct = 37; filename = "foo.txt"; printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n", filename, pct); produces output like Processing of `foo.txt' is 37% finished. Please be patient. This example shows the use of the `%d' conversion to specify that a scalar argument should be printed in decimal notation, the `%s' conversion to specify printing of a string argument, and the `%%' conversion to print a literal `%' character. There are also conversions for printing an integer argument as an unsigned value in octal, decimal, or hexadecimal radix (`%o', `%u', or `%x', respectively); or as a character value (`%c'). Floating-point numbers can be printed in normal, fixed-point notation using the `%f' conversion or in exponential notation using the `%e' conversion. The `%g' conversion uses either `%e' or `%f' format, depending on what is more appropriate for the magnitude of the particular number. You can control formatting more precisely by writing "modifiers" between the `%' and the character that indicates which conversion to apply. These slightly alter the ordinary behavior of the conversion. For example, most conversion specifications permit you to specify a minimum field width and a flag indicating whether you want the result left- or right-justified within the field. The specific flags and modifiers that are permitted and their interpretation vary depending on the particular conversion. They're all described in more detail in the following sections. File: octave.info, Node: Output Conversion Syntax, Next: Table of Output Conversions, Prev: Formatted Output, Up: C-Style I/O Functions Output Conversion Syntax ------------------------ This section provides details about the precise syntax of conversion specifications that can appear in a `printf' template string. Characters in the template string that are not part of a conversion specification are printed as-is to the output stream. The conversion specifications in a `printf' template string have the general form: % FLAGS WIDTH [ . PRECISION ] TYPE CONVERSION For example, in the conversion specifier `%-10.8ld', the `-' is a flag, `10' specifies the field width, the precision is `8', the letter `l' is a type modifier, and `d' specifies the conversion style. (This particular type specifier says to print a numeric argument in decimal notation, with a minimum of 8 digits left-justified in a field at least 10 characters wide.) In more detail, output conversion specifications consist of an initial `%' character followed in sequence by: * Zero or more "flag characters" that modify the normal behavior of the conversion specification. * An optional decimal integer specifying the "minimum field width". If the normal conversion produces fewer characters than this, the field is padded with spaces to the specified width. This is a *minimum* value; if the normal conversion produces more characters than this, the field is *not* truncated. Normally, the output is right-justified within the field. You can also specify a field width of `*'. This means that the next argument in the argument list (before the actual value to be printed) is used as the field width. The value is rounded to the nearest integer. If the value is negative, this means to set the `-' flag (see below) and to use the absolute value as the field width. * An optional "precision" to specify the number of digits to be written for the numeric conversions. If the precision is specified, it consists of a period (`.') followed optionally by a decimal integer (which defaults to zero if omitted). You can also specify a precision of `*'. This means that the next argument in the argument list (before the actual value to be printed) is used as the precision. The value must be an integer, and is ignored if it is negative. * An optional "type modifier character". This character is ignored by Octave's `printf' function, but is recognized to provide compatibility with the C language `printf'. * A character that specifies the conversion to be applied. The exact options that are permitted and how they are interpreted vary between the different conversion specifiers. See the descriptions of the individual conversions for information about the particular options that they use. File: octave.info, Node: Table of Output Conversions, Next: Integer Conversions, Prev: Output Conversion Syntax, Up: C-Style I/O Functions Table of Output Conversions --------------------------- Here is a table summarizing what all the different conversions do: `%d', `%i' Print an integer as a signed decimal number. *Note Integer Conversions::, for details. `%d' and `%i' are synonymous for output, but are different when used with `scanf' for input (*note Table of Input Conversions::.). Print an integer as an unsigned octal number. *Note Integer Conversions::, for details. Print an integer as an unsigned decimal number. *Note Integer Conversions::, for details. `%x', `%X' Print an integer as an unsigned hexadecimal number. `%x' uses lower-case letters and `%X' uses upper-case. *Note Integer Conversions::, for details. Print a floating-point number in normal (fixed-point) notation. *Note Floating-Point Conversions::, for details. `%e', `%E' Print a floating-point number in exponential notation. `%e' uses lower-case letters and `%E' uses upper-case. *Note Floating-Point Conversions::, for details. `%g', `%G' Print a floating-point number in either normal or exponential notation, whichever is more appropriate for its magnitude. `%g' uses lower-case letters and `%G' uses upper-case. *Note Floating-Point Conversions::, for details. Print a single character. *Note Other Output Conversions::. Print a string. *Note Other Output Conversions::. Print a literal `%' character. *Note Other Output Conversions::. If the syntax of a conversion specification is invalid, unpredictable things will happen, so don't do this. If there aren't enough function arguments provided to supply values for all the conversion specifications in the template string, or if the arguments are not of the correct types, the results are unpredictable. If you supply more arguments than conversion specifications, the extra argument values are simply ignored; this is sometimes useful. File: octave.info, Node: Integer Conversions, Next: Floating-Point Conversions, Prev: Table of Output Conversions, Up: C-Style I/O Functions Integer Conversions ------------------- This section describes the options for the `%d', `%i', `%o', `%u', `%x', and `%X' conversion specifications. These conversions print integers in various formats. The `%d' and `%i' conversion specifications both print an numeric argument as a signed decimal number; while `%o', `%u', and `%x' print the argument as an unsigned octal, decimal, or hexadecimal number (respectively). The `%X' conversion specification is just like `%x' except that it uses the characters `ABCDEF' as digits instead of `abcdef'. The following flags are meaningful: Left-justify the result in the field (instead of the normal right-justification). For the signed `%d' and `%i' conversions, print a plus sign if the value is positive. For the signed `%d' and `%i' conversions, if the result doesn't start with a plus or minus sign, prefix it with a space character instead. Since the `+' flag ensures that the result includes a sign, this flag is ignored if you supply both of them. For the `%o' conversion, this forces the leading digit to be `0', as if by increasing the precision. For `%x' or `%X', this prefixes a leading `0x' or `0X' (respectively) to the result. This doesn't do anything useful for the `%d', `%i', or `%u' conversions. Pad the field with zeros instead of spaces. The zeros are placed after any indication of sign or base. This flag is ignored if the `-' flag is also specified, or if a precision is specified. If a precision is supplied, it specifies the minimum number of digits to appear; leading zeros are produced if necessary. If you don't specify a precision, the number is printed with as many digits as it needs. If you convert a value of zero with an explicit precision of zero, then no characters at all are produced. File: octave.info, Node: Floating-Point Conversions, Next: Other Output Conversions, Prev: Integer Conversions, Up: C-Style I/O Functions Floating-Point Conversions -------------------------- This section discusses the conversion specifications for floating-point numbers: the `%f', `%e', `%E', `%g', and `%G' conversions. The `%f' conversion prints its argument in fixed-point notation, producing output of the form [`-']DDD`.'DDD, where the number of digits following the decimal point is controlled by the precision you specify. The `%e' conversion prints its argument in exponential notation, producing output of the form [`-']D`.'DDD`e'[`+'|`-']DD. Again, the number of digits following the decimal point is controlled by the precision. The exponent always contains at least two digits. The `%E' conversion is similar but the exponent is marked with the letter `E' instead of `e'. The `%g' and `%G' conversions print the argument in the style of `%e' or `%E' (respectively) if the exponent would be less than -4 or greater than or equal to the precision; otherwise they use the `%f' style. Trailing zeros are removed from the fractional portion of the result and a decimal-point character appears only if it is followed by a digit. The following flags can be used to modify the behavior: Left-justify the result in the field. Normally the result is right-justified. Always include a plus or minus sign in the result. If the result doesn't start with a plus or minus sign, prefix it with a space instead. Since the `+' flag ensures that the result includes a sign, this flag is ignored if you supply both of them. Specifies that the result should always include a decimal point, even if no digits follow it. For the `%g' and `%G' conversions, this also forces trailing zeros after the decimal point to be left in place where they would otherwise be removed. Pad the field with zeros instead of spaces; the zeros are placed after any sign. This flag is ignored if the `-' flag is also specified. The precision specifies how many digits follow the decimal-point character for the `%f', `%e', and `%E' conversions. For these conversions, the default precision is `6'. If the precision is explicitly `0', this suppresses the decimal point character entirely. For the `%g' and `%G' conversions, the precision specifies how many significant digits to print. Significant digits are the first digit before the decimal point, and all the digits after it. If the precision is `0' or not specified for `%g' or `%G', it is treated like a value of `1'. If the value being printed cannot be expressed precisely in the specified number of digits, the value is rounded to the nearest number that fits. File: octave.info, Node: Other Output Conversions, Next: Formatted Input, Prev: Floating-Point Conversions, Up: C-Style I/O Functions Other Output Conversions ------------------------ This section describes miscellaneous conversions for `printf'. The `%c' conversion prints a single character. The `-' flag can be used to specify left-justification in the field, but no other flags are defined, and no precision or type modifier can be given. For example: printf ("%c%c%c%c%c", "h", "e", "l", "l", "o"); prints `hello'. The `%s' conversion prints a string. The corresponding argument must be a string. A precision can be specified to indicate the maximum number of characters to write; otherwise characters in the string up to but not including the terminating null character are written to the output stream. The `-' flag can be used to specify left-justification in the field, but no other flags or type modifiers are defined for this conversion. For example: printf ("%3s%-6s", "no", "where"); prints ` nowhere '. File: octave.info, Node: Formatted Input, Next: Input Conversion Syntax, Prev: Other Output Conversions, Up: C-Style I/O Functions Formatted Input --------------- Here are the descriptions of the functions for performing formatted input. `scanf (TEMPLATE)' The `scanf' function reads formatted input from the stream `stdin' under the control of the template string TEMPLATE. The resulting values are returned. `fscanf (FILE, TEMPLATE)' This function is just like `scanf', except that the input is read from the stream FILE instead of `stdin'. `sscanf (STRING, TEMPLATE)' This is like `scanf', except that the characters are taken from the string STRING instead of from a stream. Reaching the end of the string is treated as an end-of-file condition. Calls to `scanf' are superficially similar to calls to `printf' in that arbitrary arguments are read under the control of a template string. While the syntax of the conversion specifications in the template is very similar to that for `printf', the interpretation of the template is oriented more towards free-format input and simple pattern matching, rather than fixed-field formatting. For example, most `scanf' conversions skip over any amount of "white space" (including spaces, tabs, and newlines) in the input file, and there is no concept of precision for the numeric input conversions as there is for the corresponding output conversions. Ordinarily, non-whitespace characters in the template are expected to match characters in the input stream exactly. When a "matching failure" occurs, `scanf' returns immediately, leaving the first non-matching character as the next character to be read from the stream, and `scanf' returns all the items that were successfully converted. The formatted input functions are not used as frequently as the formatted output functions. Partly, this is because it takes some care to use them properly. Another reason is that it is difficult to recover from a matching error. File: octave.info, Node: Input Conversion Syntax, Next: Table of Input Conversions, Prev: Formatted Input, Up: C-Style I/O Functions Input Conversion Syntax ----------------------- A `scanf' template string is a string that contains ordinary multibyte characters interspersed with conversion specifications that start with `%'. Any whitespace character in the template causes any number of whitespace characters in the input stream to be read and discarded. The whitespace characters that are matched need not be exactly the same whitespace characters that appear in the template string. For example, write ` , ' in the template to recognize a comma with optional whitespace before and after. Other characters in the template string that are not part of conversion specifications must match characters in the input stream exactly; if this is not the case, a matching failure occurs. The conversion specifications in a `scanf' template string have the general form: % FLAGS WIDTH TYPE CONVERSION In more detail, an input conversion specification consists of an initial `%' character followed in sequence by: * An optional "flag character" `*', which says to ignore the text read for this specification. When `scanf' finds a conversion specification that uses this flag, it reads input as directed by the rest of the conversion specification, but it discards this input, does not use a pointer argument, and does not increment the count of successful assignments. * An optional decimal integer that specifies the "maximum field width". Reading of characters from the input stream stops either when this maximum is reached or when a non-matching character is found, whichever happens first. Most conversions discard initial whitespace characters (those that don't are explicitly documented), and these discarded characters don't count towards the maximum field width. * An optional type modifier character. This character is ignored by Octave's `scanf' function, but is recognized to provide compatibility with the C language `scanf'. * A character that specifies the conversion to be applied. The exact options that are permitted and how they are interpreted vary between the different conversion specifiers. See the descriptions of the individual conversions for information about the particular options that they allow. File: octave.info, Node: Table of Input Conversions, Next: Numeric Input Conversions, Prev: Input Conversion Syntax, Up: C-Style I/O Functions Table of Input Conversions -------------------------- Here is a table that summarizes the various conversion specifications: Matches an optionally signed integer written in decimal. *Note Numeric Input Conversions::. Matches an optionally signed integer in any of the formats that the C language defines for specifying an integer constant. *Note Numeric Input Conversions::. Matches an unsigned integer written in octal radix. *Note Numeric Input Conversions::. Matches an unsigned integer written in decimal radix. *Note Numeric Input Conversions::. `%x', `%X' Matches an unsigned integer written in hexadecimal radix. *Note Numeric Input Conversions::. `%e', `%f', `%g', `%E', `%G' Matches an optionally signed floating-point number. *Note Numeric Input Conversions::. Matches a string containing only non-whitespace characters. *Note String Input Conversions::. Matches a string of one or more characters; the number of characters read is controlled by the maximum field width given for the conversion. *Note String Input Conversions::. This matches a literal `%' character in the input stream. No corresponding argument is used. If the syntax of a conversion specification is invalid, the behavior is undefined. If there aren't enough function arguments provided to supply addresses for all the conversion specifications in the template strings that perform assignments, or if the arguments are not of the correct types, the behavior is also undefined. On the other hand, extra arguments are simply ignored. File: octave.info, Node: Numeric Input Conversions, Next: String Input Conversions, Prev: Table of Input Conversions, Up: C-Style I/O Functions Numeric Input Conversions ------------------------- This section describes the `scanf' conversions for reading numeric values. The `%d' conversion matches an optionally signed integer in decimal radix. The `%i' conversion matches an optionally signed integer in any of the formats that the C language defines for specifying an integer constant. For example, any of the strings `10', `0xa', or `012' could be read in as integers under the `%i' conversion. Each of these specifies a number with decimal value `10'. The `%o', `%u', and `%x' conversions match unsigned integers in octal, decimal, and hexadecimal radices, respectively. The `%X' conversion is identical to the `%x' conversion. They both permit either uppercase or lowercase letters to be used as digits. Unlike the C language `scanf', Octave ignores the `h', `l', and `L' modifiers. File: octave.info, Node: String Input Conversions, Next: Binary I/O, Prev: Numeric Input Conversions, Up: C-Style I/O Functions String Input Conversions ------------------------ This section describes the `scanf' input conversions for reading string and character values: `%s' and `%c'. The `%c' conversion is the simplest: it matches a fixed number of characters, always. The maximum field with says how many characters to read; if you don't specify the maximum, the default is 1. This conversion does not skip over initial whitespace characters. It reads precisely the next N characters, and fails if it cannot get that many. The `%s' conversion matches a string of non-whitespace characters. It skips and discards initial whitespace, but stops when it encounters more whitespace after having read something. For example, reading the input: hello, world with the conversion `%10c' produces `" hello, wo"', but reading the same input with the conversion `%10s' produces `"hello,"'. File: octave.info, Node: Binary I/O, Next: Other I/O Functions, Prev: String Input Conversions, Up: C-Style I/O Functions Binary I/O ---------- Octave has to C-style functions for reading and writing binary data. They are `fread' and `fwrite' and are patterned after the standard C functions with the same names. `fread (FILE, SIZE, PRECISION)' This function reads data in binary form of type PRECISION from the specified FILE, which may be either a file name, or a file number as returned from `fopen'. The argument SIZE specifies the size of the matrix to return. It may be a scalar or a two-element vector. If it is a scalar, `fread' returns a column vector of the specified length. If it is a two-element vector, it specifies the number of rows and columns of the result matrix, and `fread' fills the elements of the matrix in column-major order. The argument PRECISION is a string specifying the type of data to read and may be one of `"char"', `"schar"', `"short"', `"int"', `"long"', `"float"', `"double"', `"uchar"', `"ushort"', `"uint"', or `"ulong"'. The default precision is `"uchar"'. The `fread' function returns two values, `data', which is the data read from the file, and `count', which is the number of elements read. `fwrite (FILE, DATA, PRECISION)' This function writes data in binary form of type PRECISION to the specified FILE, which may be either a file name, or a file number as returned from `fopen'. The argument DATA is a matrix of values that are to be written to the file. The values are extracted in column-major order. The argument PRECISION is a string specifying the type of data to read and may be one of `"char"', `"schar"', `"short"', `"int"', `"long"', `"float"', `"double"', `"uchar"', `"ushort"', `"uint"', or `"ulong"'. The default precision is `"uchar"'. The `fwrite' function returns the number of elements written. The behavior of `fwrite' is undefined if the values in DATA are too large to fit in the specified precision. File: octave.info, Node: Other I/O Functions, Prev: Binary I/O, Up: C-Style I/O Functions Other I/O Functions ------------------- fgets (FILE, len) Read `len' characters from a file. To flush output to a stream, use the function `fflush (FILE)'. This is useful for ensuring that all pending output makes it to the screen before some other event occurs. For example, it is always a good idea to flush the standard output stream before calling `input'. Three functions are available for setting and determining the position of the file pointer for a given file. The position of the file pointer (as the number of characters from the beginning of the file) can be obtained using the the function `ftell (FILE)'. To set the file pointer to any location within the file, use the function `fseek (FILE, offset, origin)'. The pointer is placed `offset' characters from the `origin', which may be one of the predefined variables `SEEK_CUR' (current position), `SEEK_SET' (beginning), or `SEEK_END' (end of file). If `origin' is omitted, `SEEK_SET' is assumed. The offset must be zero, or a value returned by `ftell' (in which case `origin' must be `SEEK_SET'. *Note Predefined Constants::. The function `frewind (FILE)' moves the file pointer to the beginning of a file, returning 1 for success, and 0 if an error was encountered. It is equivalent to `fseek (FILE, 0, SEEK_SET)'. The following example stores the current file position in the variable `marker', moves the pointer to the beginning of the file, reads four characters, and then returns to the original position. marker = ftell (myfile); frewind (myfile); fourch = fgets (myfile, 4); fseek (myfile, marker, SEEK_SET); The function `feof (FILE)' allows you to find out if an end-of-file condition has been encountered for a given file. Note that it will only return 1 if the end of the file has already been encountered, not if the next read operation will result in an end-of-file condition. Similarly, the function `ferror (FILE)' allows you to find out if an error condition has been encountered for a given file. Note that it will only return 1 if an error has already been encountered, not if the next operation will result in an error condition. The function `kbhit' may be usd to read a single keystroke from the keyboard. For example, x = kbhit (); will set X to the next character typed at the keyboard, without requiring a carriage return to be typed. Finally, it is often useful to know exactly which files have been opened, and whether they are open for reading, writing, or both. The command `freport' prints this information for all open files. For example, octave:13> freport number mode name 0 r stdin 1 w stdout 2 w stderr 3 r myfile File: octave.info, Node: Special Matrices, Next: Matrix Manipulation, Prev: Input and Output, Up: Top Special Matrices **************** Octave provides a number of functions for creating special matrix forms. In nearly all cases, it is best to use the built-in functions for this purpose than to try to use other tricks to achieve the same effect. * Menu: * Special Utility Matrices:: * Famous Matrices:: File: octave.info, Node: Special Utility Matrices, Next: Famous Matrices, Prev: Special Matrices, Up: Special Matrices Special Utility Matrices ======================== The function `eye' returns an identity matrix. If invoked with a single scalar argument, `eye' returns a square matrix with the dimension specified. If you supply two scalar arguments, `eye' takes them to be the number of rows and columns. If given a matrix or vector argument, `eye' returns an identity matrix with the same dimensions as the given argument. For example, eye (3) creates an identity matrix with three rows and three columns, eye (5, 8) creates an identity matrix with five rows and eight columns, and eye ([13, 21; 34, 55]) creates an identity matrix with two rows and two columns. Normally, `eye' expects any scalar arguments you provide to be real and non-negative. The variables `ok_to_lose_imaginary_part' and `treat_neg_dim_as_zero' control the behavior of `eye' for complex and negative arguments. *Note User Preferences::. Any non-integer arguments are rounded to the nearest integer value. There is an ambiguity when these functions are called with a single argument. You may have intended to create a matrix with the same dimensions as another variable, but ended up with something quite different, because the variable that you used as an argument was a scalar instead of a matrix. For example, if you need to create an identity matrix with the same dimensions as another variable in your program, it is best to use code like this eye (rows (a), columns (a)) instead of just eye (a) unless you know that the variable A will *always* be a matrix. The functions `ones', `zeros', and `rand' all work like `eye', except that they fill the resulting matrix with all ones, all zeros, or a set of random values. If you need to create a matrix whose values are all the same, you should use an expression like val_matrix = val * ones (n, m) The `rand' function also takes some additional arguments that allow you to control its behavior. For example, the function call rand ("normal") causes the sequence of numbers to be normally distributed. You may also use an argument of `"uniform"' to select a uniform distribution. To find out what the current distribution is, use an argument of `"dist"'. Normally, `rand' obtains the seed from the system clock, so that the sequence of random numbers is not the same each time you run Octave. If you really do need for to reproduce a sequence of numbers exactly, you can set the seed to a specific value. For example, the function rand ("seed", 13) sets the seed to the number 13. To see what the current seed is, use the argument `"seed"'. If it is invoked without arguments, `rand' returns a single element of a random sequence. The `rand' function uses Fortran code from RANLIB, a library of fortran routines for random number generation, compiled by Barry W. Brown and James Lovato of the Department of Biomathematics at The University of Texas, M.D. Anderson Cancer Center, Houston, TX 77030. To create a diagonal matrix with vector V on diagonal K, use the function diag (V, K). The second argument is optional. If it is positive, the vector is placed on the K-th super-diagonal. If it is negative, it is placed on the -K-th sub-diagonal. The default value of K is 0, and the vector is placed on the main diagonal. For example, octave:13> diag ([1, 2, 3], 1) ans = 0 1 0 0 0 0 2 0 0 0 0 3 0 0 0 0 The functions `linspace' and `logspace' make it very easy to create vectors with evenly or logarithmically spaced elements. For example, linspace (BASE, LIMIT, N) creates a vector with N (N greater than 2) linearly spaced elements between BASE and LIMIT. The BASE and LIMIT are always included in the range. If BASE is greater than LIMIT, the elements are stored in decreasing order. If the number of points is not specified, a value of 100 is used. The function `logspace' is similar to `linspace' except that the values are logarithmically spaced. If LIMIT is equal to pi, the points are between 10^base and pi, *not* 10^base and 10^pi, in order to be compatible with the corresponding MATLAB function. File: octave.info, Node: Famous Matrices, Prev: Special Utility Matrices, Up: Special Matrices Famous Matrices =============== The following functions return famous matrix forms. `hadamard (K)' Return the Hadamard matrix of order n = 2^k. `hankel (C, R)' Return the Hankel matrix constructed given the first column C, and (optionally) the last row R. If the last element of C is not the same as the first element of R, the last element of C is used. If the second argument is omitted, the last row is taken to be the same as the first column. A Hankel matrix formed from an m-vector C, and an n-vector R, has the elements H (i, j) = c (i+j-1), i+j-1 <= m; H (i, j) = r (i+j-m), otherwise `hilb (N)' Return the Hilbert matrix of order N. The i, j element of a Hilbert matrix is defined as H (i, j) = 1 / (i + j - 1) `invhilb (N)' Return the inverse of a Hilbert matrix of order N. This is exact. Compare with the numerical calculation of `inverse (hilb (n))', which suffers from the ill-conditioning of the Hilbert matrix, and the finite precision of your computer's floating point arithmetic. `toeplitz (C, R)' Return the Toeplitz matrix constructed given the first column C, and (optionally) the first row R. If the first element of C is not the same as the first element of R, the first element of C is used. If the second argument is omitted, the first row is taken to be the same as the first column. A square Toeplitz matrix has the form c(0) r(1) r(2) ... r(n) c(1) c(0) r(1) r(n-1) c(2) c(1) c(0) r(n-2) . . . . . . c(n) c(n-1) c(n-2) ... c(0) `vander (C)' Return the Vandermonde matrix whose next to last column is C. A Vandermonde matrix has the form c(0)^n ... c(0)^2 c(0) 1 c(1)^n ... c(1)^2 c(1) 1 . . . . . . . . . . . . c(n)^n ... c(n)^2 c(n) 1 File: octave.info, Node: Matrix Manipulation, Next: String Functions, Prev: Special Matrices, Up: Top Matrix Manipulation ******************* There are a number of functions available for checking to see if the elements of a matrix meet some condition, and for rearranging the elements of a matrix. For example, Octave can easily tell you if all the elements of a matrix are finite, or are less than some specified value. Octave can also rotate the elements, extract the upper- or lower-triangular parts, or sort the columns of a matrix. * Menu: * Finding Elements and Checking Conditions:: * Rearranging Matrices:: File: octave.info, Node: Finding Elements and Checking Conditions, Next: Rearranging Matrices, Prev: Matrix Manipulation, Up: Matrix Manipulation Finding Elements and Checking Conditions ======================================== The functions `any' and `all' are useful for determining whether any or all of the elements of a matrix satisfy some condition. The `find' function is also useful in determining which elements of a matrix meet a specified condition. Given a vector, the function `any' returns 1 if any element of the vector is nonzero. For a matrix argument, `any' returns a row vector of ones and zeros with each element indicating whether any of the elements of the corresponding column of the matrix are nonzero. For example, octave:13> any (eye (2, 4)) ans = 1 1 0 0 To see if any of the elements of a matrix are nonzero, you can use a statement like any (any (a)) For a matrix argument, `any' returns a row vector of ones and zeros with each element indicating whether any of the elements of the corresponding column of the matrix are nonzero. The function `all' behaves like the function `any', except that it returns true only if all the elements of a vector, or all the elements in a column of a matrix, are nonzero. Since the comparison operators (*note Comparison Ops::.) return matrices of ones and zeros, it is easy to test a matrix for many things, not just whether the elements are nonzero. For example, octave:13> all (all (rand (5) < 0.9)) ans = 0 tests a random 5 by 5 matrix to see if all of it's elements are less than 0.9. Note that in conditional contexts (like the test clause of `if' and `while' statements) Octave treats the test as if you had typed `all (all (condition))'. The functions `isinf', `finite', and `isnan' return 1 if their arguments are infinite, finite, or not a number, respectively, and return 0 otherwise. For matrix values, they all work on an element by element basis. For example, evaluating the expression isinf ([1, 2; Inf, 4]) produces the matrix ans = 0 0 1 0 The function `find' returns a vector of indices of nonzero elements of a matrix. To obtain a single index for each matrix element, Octave pretends that the columns of a matrix form one long vector (like Fortran arrays are stored). For example, octave:13> find (eye (2)) ans = 1 4 If two outputs are requested, `find' returns the row and column indices of nonzero elements of a matrix. For example, octave:13> [i, j] = find (eye (2)) i = 1 2 j = 1 2 If three outputs are requested, `find' also returns the nonzero values in a vector.