7.2 String
Conversion API
sc2for—C
null-terminated string to an output FORTRAN string
sc2for(c_string, max_length, for_string, argptr, nargs, argno, strno);
This
routine converts a standard C null-terminated string to an output FORTRAN
string. It is used to send strings back to a FORTRAN caller.
Arguments:
- C_STRING:
string, input
String
to convert in standard null-terminated C format.
- MAX_LENGTH:
integer, input.
Alternate
maximum length of the FORTRAN string. Normally the maximum length is obtained
from the output FORTRAN string itself (the “n” in the CHARACTER*n
declaration. If MAX_LENGTH is passed in as 0, then this natural length is used.
MAX_LENGTH is an alternate maximum string length in case one is provided as a
parameter to the routine. The actual maximum FORTRAN length used is the minimum
of the passed in MAX_LENGTH (if not 0) and the natural FORTRAN string length.
The output string will be truncated if the FORTRAN string is not long enough.
Any extra space at the end of the FORTRAN string will be padded with blanks in
the standard FORTRAN style.
- FOR_STRING,
ARGPTR, NARGS, ARGNO, STRNO
See
7.1.1
Common Features: Rules and arguments common to all string routines
above.
7.2.2 sc2for_array—C
null-terminated array of strings to FORTRAN string array
sc2for_array(c_string,len,nelements,for_string,max_length,argptr,nargs, argno,strno);
This
routine converts a standard C null-terminated array of strings into an output
FORTRAN string array. The C string array must be a two-dimensional array of
characters, not} an array of pointers to strings. The FORTRAN string should be
declared as a single-dimensional array of CHARACTER*n in the calling routine.
Arguments:
- C_STRING:
string array, input
String
array to convert in standard null-terminated C format. It must be a
two-dimensional array of char, not an array of pointers to strings. Each string
should have its own null terminator.
- LEN:
integer, input
LEN
is the size of the inner dimension of the C string array. If the array is
declared as “char x[10][81];+” (10 strings of 80 characters each
plus terminator), then LEN would be 81.
- NELEMENTS:
integer, input
NELEMENTS
is the number of strings in the array to convert.
- MAX_LENGTH:
integer, input/output
On
input, MAX_LENGTH is the alternate maximum length of each FORTRAN string.
Normally the maximum length is obtained from the output FORTRAN string array
itself (the “n” in a CHARACTER*n declaration). If MAX_LENGTH is
passed in as 0, then this natural length is used. MAX_LENGTH is an alternate
maximum string length in case one is provided as a parameter to the routine.
The actual maximum FORTRAN length used is the minimum of the passed in
MAX_LENGTH (if not 0) and the natural FORTRAN string length. The output string
will be truncated if the FORTRAN string is not long enough. Any extra space at
the end of the FORTRAN string will be padded with blanks in the standard
FORTRAN style. MAX_LENGTH should normally be passed in as 0, as it makes little
sense to override the natural FORTRAN string length. However, it is possible,
and might be useful in some unusual cases.
On
output, MAX_LENGTH returns the actual FORTRAN string length used by the routine.
- FOR_STRING,
ARGPTR, NARGS, ARGNO, STRNO
See
7.1.1
Common Features: Rules and arguments common to all string routines
above.
7.2.3 sfor2c—FORTRAN
input string to a standard C null-terminated string
sfor2c(c_string, len, for_string, argptr, nargs, argno, strno);
This
routine converts FORTRAN input string to a standard C null-terminated string.
It is used to receive string parameters from a FORTRAN caller.
Arguments:
-
C_STRING:
string, output
Buffer
to hold the output C string. The string will be truncated if the buffer is not
big enough. It will always be null terminated, even if it was truncated. Any
trailing blanks in the FORTRAN string will be removed.
- LEN:
integer, input
Maximum
length of the output C string. This parameter defines the size of the C string
buffer. It is expressed in terms of the maximum length} of the string, which
means it does not include the terminator byte. The buffer should actually be
declared to be one byte larger than LEN to allow room for the null terminator.
So, if the declaration is “char buffer[80];”, then LEN should be 79.
- FOR_STRING,
ARGPTR, NARGS, ARGNO, STRNO
See
7.1.1
Common Features: Rules and arguments common to all string routines
above.
7.2.4 sfor2c_array—FORTRAN
string array to C null-terminated array of strings
sfor2c_array(c_string, max_length, nelements, for_string, argptr, nargs, argno, strno);
This
routine converts a FORTRAN string array to a standard C null-terminated array
of strings. The returned C string array is a two-dimensional array of
characters, not} an array of pointers to strings. The FORTRAN string should be
declared as a single-dimensional array of CHARACTER*n in the calling routine.
This
routine is somewhat unusual in that it actually allocates the memory for the C
string for you. You pass in the address of a character pointer, not the address
of a buffer for the characters.
sfor2c_array
calls malloc()}to allocate the required memory, and returns the address of that
memory in the pointer. It is your responsibility to call free()to free up that
memory when you are done with it.
Arguments:
- C_STRING:
pointer to string array, output
C_STRING
is the address of a pointer that will be filled in to point at the string
array. The returned array will be a two-dimensional array of characters, not an
array of pointers to strings. Each string will have its own null terminator.
This
routine actually allocates the memory for the C string for you. C_STRING is the
address of a character pointer, not the address of a buffer for the characters.
sfor2c_array}
calls sub malloc() to allocate the required memory, and returns the address of
that memory in C_STRING. It is your responsibility to call free() to free up
that memory when you are done with it.
The
inner dimension of the array is returned via the MAX_LENGTH parameter. Since
you don't know this size at compile time, you can't access the strings like a
normal two-dimensional array. It is easy enough to do your own addressing,
however. For example:
char *array;
int maxlen=0;
...
sfor2c_array(&array, &maxlen, ...);
...
process_string(array+(i*maxlen)); /* to get at the i'th string */
-
MAX_LENGTH: integer, input/output
On
input, MAX_LENGTH is the alternate maximum length of each FORTRAN string.
Normally the maximum length is obtained from the input FORTRAN string array
itself (the “n” in a CHARACTER*n declaration). If MAX_LENGTH is
passed in as 0, then this natural length is used. MAX_LENGTH is an alternate
maximum string length in case one is provided as a parameter to the routine.
The actual maximum FORTRAN length used is the minimum of the passed in
MAX_LENGTH (if not 0) and the natural FORTRAN string length. MAX_LENGTH should
almost always be passed in as 0, as it makes little sense to override the
natural FORTRAN string length, especially on an array. However, it is possible,
and might be useful in some unusual cases.
On
output, MAX_LENGTH returns the size of the inner dimension of the C string
array that was allocated by
sfor2c_array}.
To access the i'th string in the array, simply add i*maxlen to the returned
array pointer.
7.2.5 sfor2len—Length
of a FORTRAN string
length = sfor2len(for_string, argptr, nargs, argno, strno);
This
routine returns the length of a FORTRAN string. It does not get a pointer to
the characters, nor does it convert them to a C string. It is most useful to
get the length of a string in order to allocate a buffer for it before calling
sfor2c.
Note that the length returned is the “n” in the CHARACTER*n
declaration, not the number of characters currently in the string.
Arguments:
7.2.6 sfor2ptr—Pointer
to actual characters in FORTRAN string
ptr = sfor2ptr(for_string);
This
routine returns a pointer to the actual characters in an input FORTRAN string.
It does not get the FORTRAN string length, nor does it copy the string to an
output C string. It merely returns a pointer to the characters. No guarantee is
made that any of the characters are valid, since that depends on the FORTRAN
string length. You can be sure that there will not be a null terminator. Some
machines may have one, but you may not depend on a null terminator being there.
This
routine should be used sparingly; use
sfor2c
for most FORTRAN string conversion.
sfor2ptr
is mainly intended for use in scanning a variable-length argument list to find
the end-of-list marker. It is used extensively inside the RTL for this purpose.
It should only rarely if ever be used in application code.
Note
that only the FOR_STRING standard argument is required. This is because the
FORTRAN string length is ignored. All the other parameters are used to find the
length.
Arguments: