Tcl - Tcl_StringObj (3)

Tcl Library Procedures

NAME

Tcl_NewStringObj, Tcl_SetStringObj, Tcl_GetStringFromObj, Tcl_StringObjAppend, Tcl_StringObjAppendObj - manipulate Tcl string objects

SYNOPSIS

#include <tcl.h>

Tcl_Obj *
Tcl_NewStringObj(bytes, length)

Tcl_SetStringObj(objPtr, bytes, length)

char *
Tcl_GetStringFromObj(interp, objPtr, lengthPtr)

Tcl_StringObjAppend(interp, objPtr, bytes, length)

Tcl_StringObjAppendObj(interp, objPtr, srcPtr)

ARGUMENTS

char *bytes (in): Points to the first byte of an array of bytes used to initialize, set, or append to a string object. This byte array may contain embedded null bytes unless length is negative.
int length (in): The number of bytes to copy from bytes when initializing, setting, or appending to a string object. If negative, all bytes up to the first null are used.
Tcl_Obj *objPtr (in/out): For Tcl_SetStringObj, this points to the object to be modified to hold the specified string. In Tcl_GetStringFromObj, this points to the object from which to get a string given by the returned byte pointer and length (stored in lengthPtr). For Tcl_StringObjAppend and Tcl_StringObjAppendObj, this refers to the object to which is appended either a specified string or another object's string representation; if objPtr does not already point to a string object, it will be converted to one.
Tcl_Interp *interp (in/out): Interpreter used to obtain any information needed for type conversion such as the current double-to-string formatting precision.
int *lengthPtr (out): The location where Tcl_GetStringFromObj will store the the length of an object's string representation.
Tcl_Obj *srcPtr (in/out): This refers to an object whose string representation is appended to objPtr by Tcl_StringObjAppendObj.
int objc (in): The number of objects that Tcl_ConcatObj will concatenate.
Tcl_Obj **objv (in): Points to an array of pointers to Tcl objects whose string representations are concatenated by Tcl_ConcatObj.

DESCRIPTION

Tcl string objects have an internal representation that supports the efficient construction of arbitrarily long string values by appending information. These procedures described in this man page are used by C code to create, modify, concatenate, append to, and get strings from Tcl string objects.

Tcl_NewStringObj and Tcl_SetStringObj create a new object or modify an existing object to hold a copy of the string given by bytes and length. Tcl_NewStringObj returns a pointer to a newly created object with reference count 1. Both procedures set the object to hold a copy of the specified string. Tcl_SetStringObj frees any old string representation as well as any old internal representation of the object.

Tcl_GetStringFromObj returns an object's string representation. This is given by the returned byte pointer and length, which is stored in lengthPtr. If the object's string representation is invalid (its byte pointer is NULL), the string representation is regenerated from the object's internal representation.

Tcl_StringObjAppend appends a string to the object specified by objPtr. Tcl_StringObjAppend ensures that objPtr refers to a string object. If objPtr does not already refer to a string object, Tcl_StringObjAppend will convert it to one (this conversion always succeeds). Tcl_StringObjAppend frees any old string representation and, if the object is not already a string object, frees any old internal representation.

Tcl_StringObjAppendObj resembles Tcl_StringObjAppend except that it appends a copy of another object's string representation. srcPtr is a pointer to the object whose string representation is to be appended to the object referenced by objPtr. Tcl_StringObjAppendObj frees any old string representation of objPtr and, if it is not already a string object, frees any old internal representation.

KEYWORDS

append, concatenate, internal representation, object, object type, string object, string type, string representation

Last change: 8.0