.Dd January 24, 2024
.Dt SQLITE3CHANGESET_NEW 3
.Os
.Sh NAME
.Nm sqlite3changeset_new
.Nd obtain new.* values from a changeset iterator
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3changeset_new
.Fa "sqlite3_changeset_iter *pIter"
.Fa "int iVal"
.Fa "sqlite3_value **ppValue"
.Fc
.Sh DESCRIPTION
The pIter argument passed to this function may either be an iterator
passed to a conflict-handler by
.Fn sqlite3changeset_apply ,
or an iterator created by
.Fn sqlite3changeset_start .
In the latter case, the most recent call to
.Fn sqlite3changeset_next
must have returned SQLITE_ROW.
Furthermore, it may only be called if the type of change that the iterator
currently points to is either SQLITE_UPDATE or SQLITE_INSERT.
Otherwise, this function returns SQLITE_MISUSE and sets
*ppValue to NULL.
.Pp
Argument iVal must be greater than or equal to 0, and less than the
number of columns in the table affected by the current change.
Otherwise, SQLITE_RANGE is returned and *ppValue is set
to NULL.
.Pp
If successful, this function sets *ppValue to point to a protected
sqlite3_value object containing the iVal'th value from the vector of
new row values stored as part of the UPDATE or INSERT change and returns
SQLITE_OK.
If the change is an UPDATE and does not include a new value for the
requested column, *ppValue is set to NULL and SQLITE_OK returned.
The name of the function comes from the fact that this is similar to
the "new.*" columns available to update or delete triggers.
.Pp
If some other error occurs (e.g. an OOM condition), an SQLite error
code is returned and *ppValue is set to NULL.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 11630.
.Bd -literal
SQLITE_API int sqlite3changeset_new(
  sqlite3_changeset_iter *pIter,  /* Changeset iterator */
  int iVal,                       /* Column number */
  sqlite3_value **ppValue         /* OUT: New value (or NULL pointer) */
);
.Ed
.Sh SEE ALSO
.Xr sqlite3changeset_apply 3 ,
.Xr sqlite3changeset_next 3 ,
.Xr sqlite3changeset_start 3 ,
.Xr SQLITE_CREATE_INDEX 3 ,
.Xr SQLITE_OK 3