String Manipulation and Conversion

(string) Strcat(string1, string2)
This function appends string2 to string1 and returns the new string. The `+ ' operator is overloaded to also perform this function on string operands.

(int) Strcmp(string1, string2)
This function returns an integer representing the lexical difference between string1 and string2. This is the same as the ``strcmp'' C library function, except that null strings are accepted and have the minimum lexical value. The comparison operators are overloaded to also perform this function on string operands.

(int) Strncmp(string1, string2, n)
This compares at most n characters in strings 1 and 2 and returns the lexical difference. This is equivalent to the C library ``strncmp'' function, except that null strings are accepted and have the minimum lexical value.

(int) Strcasecmp(string1, string2)
This internally converts strings 1 and 2 to lower case, and returns the lexical difference. This is equivalent to the C library ``strcasecmp'' function, except that null strings are accepted and have the minimum lexical value.

(int) Strncasecmp(string1, string2, n)
This internally converts strings 1 and 2 to lower case, and compares at most n characters, returning the lexical difference. This is equivalent to the C library ``strncasecmp'' function. except that null strings are accepted and have the minimum lexical value.

(string) Strdup(string)
This function returns a new string variable containing a copy of the argument's string. An error occurs if the argument is not string-type. Note that this differs from assignment, which propagates a pointer to the string data rather than copying.

(string) Strtok(str, sep)
The Strtok function is used to isolate sequential tokens in a string, str. These tokens are separated in the string by at least one of the characters in the string sep. The first time that Strtok is called, str should be specified; subsequent calls, wishing to obtain further tokens from the same string, should pass 0 instead. The separator string, sep, must be supplied each time, and may change between calls.

The Strtok function returns a reference to each subsequent token in the string, after replacing the separator character with a NULL character. When no more tokens remain, a null string is returned. Note that this is destructive to str.

This function is similar to the C library ``strtok'' function.

Example: print the space-separated words

teststr = "here are \ tsome words"
word = Strtok(teststr, " \ t")
Print("First word is", word);
while (word = Strtok(0, " \ t"))
Print("Next word:", word)
done

(string) Strchr(string, char)
The second argument is an integer representing a character. The return value is a pointer into string offset to point to the first instance of the character. If the character is not in the string, a null pointer is returned. This is basically the same as the C strchr function.

(string) Strrchr(string, char)
The second argument is an integer representing a character. The return value is a pointer into string offset to point to the last instance of the character. If the character is not in the string, a null pointer is returned. This is basically the same as the C strrchr function.

(string) Strstr(string, char)
The second argument is a string which is expected to be a substring of the string. The return value is a pointer into string to the start of the first occurrence of the substring. If there are no occurrences, a null pointer is returned. This is equivalent to the C strstr function.

(string) Strpath(string)
This returns a copy of the file name part of a full path given in the string.

(int) Strlen(string)
This function returns the number of characters in string.

(int) Sizeof(arg)
This function returns the allocated size of the argument, which is mostly useful for determining the size of an array. The return value is

string length	arg is a string
allocated array size	arg is an array
number of trapezoids	arg is a zoidlist
1	arg is none of above

(scalar) ToReal(string)
The returned value is a variable of type scalar containing the numeric value from the passed argument, which is a string. The text of the string should be interpretable as a numeric constant. If the argument is instead a scalar, the value is simply copied.

(string) ToString(real)
The returned value is a variable of type string containing a text representation of the passed variable, which is expected to be of type scalar. The format is the same as the C printf function with ``%g'' as a format specifier. If the argument is instead a string, the returned value points to that string.

(string) ToStringA(real, digits)
This will return a string containing the real number argument in SPICE format, which is a form consisting of a fixed point number followed by an alpha character or sequence which designates a scale factor. These are the same scale factors as used in the number parser. though ``mils'' is not used. The second argument is an integer giving the number of digits to print (in the range 2-15). If out of this range, a default of 6 is used.

If the first argument is a string, the string contents will be parsed as a number, and the result output as described above. If the parse fails, the number is silently taken as zero.

(string) ToFormat(format, arg_list)
This function returns a string, formatted in the manner of the C printf function. The first argument is a format string, as would be given to printf. Additional arguments (there can be zero or more) are the variables that correspond to the format specification. The type and position of the arguments must match the format specification, which means that the variables passed must resolve to strings or to numeric scalars. All of the formatting options described in the Unix manual page for printf are available, with the following exceptions:

1. No random argument access.
2. At most one `*' per substitution.
3. ``%p'' will always print zero.
4. ``%n'' is not supported.

The function fails if the first argument is not a string, is null, or there is a syntax error or unsupported construct, or there is a type or number mismatch between specification and arguments.

For example, the ``id'' returned from GetObjectID prints as a floating point value by default (since it is a large integer), which is usually not useful. One can print this as a hex value as follows:

id = GetObjectID(handle)
Print("Id =", ToFormat("0x%x", id))

(string) ToChar(integer)
This function takes as its input an integer value for a character, and returns a string containing a printable representation of the character. A null string is returned if the input is not a valid character index. This function can be used to preformat character data for printing with the various print functions.