.Dd January 24, 2024
.Dt SQLITE3_STR_NEW 3
.Os
.Sh NAME
.Nm sqlite3_str_new
.Nd create a new dynamic string object
.Sh SYNOPSIS
.In sqlite3.h
.Ft sqlite3_str *
.Fo sqlite3_str_new
.Fa "sqlite3*"
.Fc
.Sh DESCRIPTION
The sqlite3_str_new(D) interface allocates and initializes
a new sqlite3_str object.
To avoid memory leaks, the object returned by
.Fn sqlite3_str_new
must be freed by a subsequent call to sqlite3_str_finish(X).
.Pp
The sqlite3_str_new(D) interface always returns a
pointer to a valid sqlite3_str object, though in the event
of an out-of-memory error the returned object might be a special singleton
that will silently reject new text, always return SQLITE_NOMEM from
.Fn sqlite3_str_errcode ,
always return 0 for
.Fn sqlite3_str_length ,
and always return NULL from sqlite3_str_finish(X).
It is always safe to use the value returned by sqlite3_str_new(D)
as the sqlite3_str parameter to any of the other sqlite3_str
methods.
.Pp
The D parameter to sqlite3_str_new(D) may be NULL.
If the D parameter in sqlite3_str_new(D) is not NULL,
then the maximum length of the string contained in the sqlite3_str
object will be the value set for sqlite3_limit(D,SQLITE_LIMIT_LENGTH)
instead of SQLITE_MAX_LENGTH.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 8400.
.Bd -literal
SQLITE_API sqlite3_str *sqlite3_str_new(sqlite3*);
.Ed
.Sh SEE ALSO
.Xr sqlite3_limit 3 ,
.Xr sqlite3_str 3 ,
.Xr sqlite3_str_errcode 3 ,
.Xr SQLITE_LIMIT_LENGTH 3