.Dd December 19, 2018
.Dt SQLITE3_STR_NEW 3
.Os
.Sh NAME
.Nm sqlite3_str_new
.Nd Create A New Dynamic String Object
.Sh SYNOPSIS
.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 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
sqlite3_str_errcode(), always return 0 for 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 SEE ALSO
.Xr sqlite3_limit 3 ,
.Xr sqlite3_str 3 ,
.Xr sqlite3_str_errcode 3 ,
.Xr sqlite3_str_new 3 ,
.Xr SQLITE_LIMIT_LENGTH 3