dt_stringvalue

Daylight v4.9
Release Date: 1 February 2008

Name

dt_stringvalue - return the string value of an object

Generic Prototype

dt_stringvalue(dt_Handle) => dt_Handle

C Prototype

#include "dt_smiles.h"

dt_String dt_stringvalue(dt_Integer *len, dt_Handle object)

FORTRAN Prototype

include 'dt_f_smiles.inc'

integer*4 dt_f_stringvalue(object, string)

integer*4 object
character*() string

Description

Returns the object's string value. The object owns the returned string, so the string must not be modified in any way by the user. The proper way to modify the string value is to use dt_setstringvalue(3) to change the object or dt_appendstringvalue(3) to append data.

Note also that calling dt_setstringvalue(3) or dt_appendstringvalue(3) causes the results of dt_stringvalue(3) to be invalidated. The user must not reference the string from a previous dt_stringvalue(3) call after the object has been modified. It is necessary to call dt_stringvalue(3) again and use that returned string.

If the user wishes to manipulate the returned string data, a copy of the string must be made by the user.

Not all objects that return a string allow you to set that value; in some cases the string value is derived from other properties of the object.

In the Daylight Toolkit, the term "string" refers to an array of 8-bit integers. The Toolkit assigns no special meaning to NULL, space, newline, etc. All string functions operate with explicit lengths.

For a fingerprint object, returns the bitmap. The string's length will be dt_fp_nbits(fp)/8.

For a server, returns the server's hostname and service. This is not necessarily the same as the name used to connect to the server, as it is a value reported by thee server itself. The server always returns its true name, regardless of the name used to establish the connection.

For a database, returns the full database name, including the full file-system path to the database on the server machine.

For a THOR datatype, returns the internal tag that names the object. For a datafield, returns the text value of the datafield.

For a program object, returns the path used to start the program. If the program was allocated with a stream or sequence, returns the string that was associated with the first object in the stream or sequence. If the program was allocated with any other object type, returns that object's string value.

Return Value