*** DRAFT ***

SQLite Requirement Matrix Details
create_function.html

Index Summary Markup Original


R-57479-00042-18825-57289-32505-64353-45358-46844 tcl slt th3 src

These functions (collectively known as "function creation routines") are used to add SQL functions or aggregates or to redefine the behavior of existing SQL functions or aggregates.

th3/req1/createfunc01.test:232

/* IMP: R-57479-00042 */
# EVIDENCE-OF: R-57479-00042 These functions (collectively known as
# "function creation routines") are used to add SQL functions or
# aggregates or to redefine the behavior of existing SQL functions or
# aggregates.

R-44114-07168-48628-58571-39460-30302-43731-62236 tcl slt th3 src

The first parameter is the database connection to which the SQL function is to be added.

th3/req1/createfunc01.test:98

/* IMP: R-44114-07168 */
# EVIDENCE-OF: R-44114-07168 The first parameter is the database
# connection to which the SQL function is to be added.

R-63464-64949-61376-49766-27105-42623-27880-27478 tcl slt th3 src

If an application uses more than one database connection then application-defined SQL functions must be added to each database connection separately.

th3/req1/createfunc01.test:101

/* IMP: R-63464-64949 */
# EVIDENCE-OF: R-63464-64949 If an application uses more than one
# database connection then application-defined SQL functions must be
# added to each database connection separately.

R-32023-34269-07081-56751-59037-09134-01490-38261 tcl slt th3 src

The second parameter is the name of the SQL function to be created or redefined.

th3/req1/createfunc01.test:134

/* IMP: R-32023-34269 */
# EVIDENCE-OF: R-32023-34269 The second parameter is the name of the SQL
# function to be created or redefined.

R-24176-11856-49416-35044-22347-11072-23258-18948 tcl slt th3 src

The length of the name is limited to 255 bytes in a UTF-8 representation, exclusive of the zero-terminator.

th3/req1/createfunc01.test:137

/* IMP: R-24176-11856 */
# EVIDENCE-OF: R-24176-11856 The length of the name is limited to 255
# bytes in a UTF-8 representation, exclusive of the zero-terminator.

R-36651-49821-06866-46556-29729-37304-36967-33618 tcl slt th3 src

Note that the name length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.

th3/req1/createfunc01.test:140

/* IMP: R-36651-49821 */
# EVIDENCE-OF: R-36651-49821 Note that the name length limit is in UTF-8
# bytes, not characters nor UTF-16 bytes.

R-14222-20715-36794-58646-49579-04398-47433-20385 tcl slt th3 src

Any attempt to create a function with a longer name will result in SQLITE_MISUSE being returned.

th3/req1/createfunc01.test:143

/* IMP: R-14222-20715 */
# EVIDENCE-OF: R-14222-20715 Any attempt to create a function with a
# longer name will result in SQLITE_MISUSE being returned.

R-17847-41579-08261-19893-13376-57099-17968-14055 tcl slt th3 src

The third parameter (nArg) is the number of arguments that the SQL function or aggregate takes.

th3/req1/createfunc02.test:89

/* IMP: R-17847-41579 */
# EVIDENCE-OF: R-17847-41579 The third parameter (nArg) is the number of
# arguments that the SQL function or aggregate takes.

R-41161-50390-16822-36301-43678-58977-40657-30512 tcl slt th3 src

If this parameter is -1, then the SQL function or aggregate may take any number of arguments between 0 and the limit set by sqlite3_limit(SQLITE_LIMIT_FUNCTION_ARG).

th3/req1/createfunc02.test:160

/* IMP: R-41161-50390 */
# EVIDENCE-OF: R-41161-50390 If this parameter is -1, then the SQL
# function or aggregate may take any number of arguments between 0 and
# the limit set by sqlite3_limit(SQLITE_LIMIT_FUNCTION_ARG).

R-53205-22341-54375-46881-03757-15307-06901-24042 tcl slt th3 src

The fourth parameter, eTextRep, specifies what text encoding this SQL function prefers for its parameters.

th3/req1/createfunc04.test:144

/* IMP: R-53205-22341 */
# EVIDENCE-OF: R-53205-22341 The fourth parameter, eTextRep, specifies
# what text encoding this SQL function prefers for its parameters.

R-64203-64297-25977-44727-61905-56050-52768-56293 tcl slt th3 src

The same SQL function may be registered multiple times using different preferred text encodings, with different implementations for each encoding.

th3/req1/createfunc04.test:147

/* IMP: R-64203-64297 */
# EVIDENCE-OF: R-64203-64297 The same SQL function may be registered
# multiple times using different preferred text encodings, with
# different implementations for each encoding.

R-12993-07777-64601-19102-35955-36137-03402-56962 tcl slt th3 src

When multiple implementations of the same function are available, SQLite will pick the one that involves the least amount of data conversion.

th3/req1/createfunc04.test:151

/* IMP: R-12993-07777 */
# EVIDENCE-OF: R-12993-07777 When multiple implementations of the same
# function are available, SQLite will pick the one that involves the
# least amount of data conversion.

R-10382-19306-57880-35714-22073-14679-32627-12019 tcl slt th3 src

The fourth parameter may optionally be ORed with SQLITE_DETERMINISTIC to signal that the function will always return the same result given the same inputs within a single SQL statement.

th3/cov1/func11.test:13

/* IMP: R-10382-19306 */
# EVIDENCE-OF: R-10382-19306 The fourth parameter may optionally be ORed
# with SQLITE_DETERMINISTIC to signal that the function will always
# return the same result given the same inputs within a single SQL
# statement.

R-58057-33391-03509-33043-33345-56148-13534-20501 tcl slt th3 src

The fourth parameter may also optionally include the SQLITE_DIRECTONLY flag, which if present prevents the function from being invoked from within VIEWs, TRIGGERs, CHECK constraints, generated column expressions, index expressions, or the WHERE clause of partial indexes.

/* IMP: R-58057-33391 */
# EVIDENCE-OF: R-58057-33391 The fourth parameter may also optionally
# include the SQLITE_DIRECTONLY flag, which if present prevents the
# function from being invoked from within VIEWs, TRIGGERs, CHECK
# constraints, generated column expressions, index expressions, or the
# WHERE clause of partial indexes.

R-17939-38828-17695-42161-08728-29310-38414-12197 tcl slt th3 src

The fifth parameter is an arbitrary pointer. The implementation of the function can gain access to this pointer using sqlite3_user_data().

th3/req1/userdata01.test:42

/* IMP: R-17939-38828 */
# EVIDENCE-OF: R-17939-38828 The fifth parameter is an arbitrary
# pointer. The implementation of the function can gain access to this
# pointer using sqlite3_user_data().

R-35036-33960-30076-49697-10834-60924-14728-15122 tcl slt th3 src

The sixth, seventh and eighth parameters passed to the three "sqlite3_create_function*" functions, xFunc, xStep and xFinal, are pointers to C-language functions that implement the SQL function or aggregate.

th3/req1/createfunc03.test:66

/* IMP: R-35036-33960 */
# EVIDENCE-OF: R-35036-33960 The sixth, seventh and eighth parameters
# passed to the three "sqlite3_create_function*" functions, xFunc, xStep
# and xFinal, are pointers to C-language functions that implement the
# SQL function or aggregate.

R-27228-35217-15852-02871-02611-58321-58852-42304 tcl slt th3 src

A scalar SQL function requires an implementation of the xFunc callback only; NULL pointers must be passed as the xStep and xFinal parameters.

th3/req1/createfunc03.test:71

/* IMP: R-27228-35217 */
# EVIDENCE-OF: R-27228-35217 A scalar SQL function requires an
# implementation of the xFunc callback only; NULL pointers must be
# passed as the xStep and xFinal parameters.

R-17719-44813-04835-03337-09891-18871-23593-16128 tcl slt th3 src

An aggregate SQL function requires an implementation of xStep and xFinal and NULL pointer must be passed for xFunc.

th3/req1/createfunc03.test:109

/* IMP: R-17719-44813 */
# EVIDENCE-OF: R-17719-44813 An aggregate SQL function requires an
# implementation of xStep and xFinal and NULL pointer must be passed for
# xFunc.

R-46513-12418-39442-33008-36450-21417-18357-12067 tcl slt th3 src

To delete an existing SQL function or aggregate, pass NULL pointers for all three function callbacks.

th3/req1/createfunc03.test:143

/* IMP: R-46513-12418 */
# EVIDENCE-OF: R-46513-12418 To delete an existing SQL function or
# aggregate, pass NULL pointers for all three function callbacks.

R-54138-14726-01342-01077-27366-45054-60392-40592 tcl slt th3 src

The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue and xInverse) passed to sqlite3_create_window_function are pointers to C-language callbacks that implement the new function.

/* IMP: R-54138-14726 */
# EVIDENCE-OF: R-54138-14726 The sixth, seventh, eighth and ninth
# parameters (xStep, xFinal, xValue and xInverse) passed to
# sqlite3_create_window_function are pointers to C-language callbacks
# that implement the new function.

R-31820-22006-44575-45426-57001-50586-37778-41806 tcl slt th3 src

If the final parameter to sqlite3_create_function_v2() or sqlite3_create_window_function() is not NULL, then it is destructor for the application data pointer. The destructor is invoked when the function is deleted, either by being overloaded or when the database connection closes.

th3/req1/createfunc07.test:12

/* IMP: R-31820-22006 */
# EVIDENCE-OF: R-31820-22006 If the final parameter to
# sqlite3_create_function_v2() or sqlite3_create_window_function() is
# not NULL, then it is destructor for the application data pointer. The
# destructor is invoked when the function is deleted, either by being
# overloaded or when the database connection closes.

R-23774-64117-15302-61921-22939-28381-40174-39816 tcl slt th3 src

The destructor is also invoked if the call to sqlite3_create_function_v2() fails.

th3/req1/createfunc07.test:77

/* IMP: R-23774-64117 */
# EVIDENCE-OF: R-23774-64117 The destructor is also invoked if the call
# to sqlite3_create_function_v2() fails.

R-34467-36570-51008-00703-20331-24944-30267-61623 tcl slt th3 src

When the destructor callback is invoked, it is passed a single argument which is a copy of the application data pointer which was the fifth parameter to sqlite3_create_function_v2().

th3/req1/createfunc07.test:18

/* IMP: R-34467-36570 */
# EVIDENCE-OF: R-34467-36570 When the destructor callback is invoked, it
# is passed a single argument which is a copy of the application data
# pointer which was the fifth parameter to sqlite3_create_function_v2().

R-24843-55391-00331-31917-58094-58865-54184-39062 tcl slt th3 src

It is permitted to register multiple implementations of the same functions with the same name but with either differing numbers of arguments or differing preferred text encodings.

th3/req1/createfunc04.test:12

/* IMP: R-24843-55391 */
# EVIDENCE-OF: R-24843-55391 It is permitted to register multiple
# implementations of the same functions with the same name but with
# either differing numbers of arguments or differing preferred text
# encodings.

R-44809-60674-55337-11812-63258-27949-26446-49308 tcl slt th3 src

SQLite will use the implementation that most closely matches the way in which the SQL function is used.

th3/req1/createfunc04.test:17

/* IMP: R-44809-60674 */
# EVIDENCE-OF: R-44809-60674 SQLite will use the implementation that
# most closely matches the way in which the SQL function is used.

R-07963-00293-13635-32107-53901-52250-25105-19603 tcl slt th3 src

A function implementation with a non-negative nArg parameter is a better match than a function implementation with a negative nArg.

th3/req1/createfunc04.test:114

/* IMP: R-07963-00293 */
# EVIDENCE-OF: R-07963-00293 A function implementation with a
# non-negative nArg parameter is a better match than a function
# implementation with a negative nArg.

R-29748-45567-07187-24756-39474-12329-09927-01777 tcl slt th3 src

A function where the preferred text encoding matches the database encoding is a better match than a function where the encoding is different.

th3/req1/createfunc04.test:140

/* IMP: R-29748-45567 */
# EVIDENCE-OF: R-29748-45567 A function where the preferred text
# encoding matches the database encoding is a better match than a
# function where the encoding is different.

R-13160-27901-08319-02808-35967-30729-30833-45529 tcl slt th3 src

A function where the encoding difference is between UTF16le and UTF16be is a closer match than a function where the encoding difference is between UTF8 and UTF16.

th3/req1/createfunc04.test:224

/* IMP: R-13160-27901 */
# EVIDENCE-OF: R-13160-27901 A function where the encoding difference is
# between UTF16le and UTF16be is a closer match than a function where
# the encoding difference is between UTF8 and UTF16.

R-42168-23975-08359-11434-07624-62565-20004-56753 tcl slt th3 src

Built-in functions may be overloaded by new application-defined functions.

th3/req1/createfunc01.test:237   th3/req1/createfunc05.test:50

/* IMP: R-42168-23975 */
# EVIDENCE-OF: R-42168-23975 Built-in functions may be overloaded by new
# application-defined functions.

R-39412-46882-37101-45160-49245-06434-49198-35151 tcl slt th3 src

An application-defined function is permitted to call other SQLite interfaces.

th3/req1/createfunc06.test:12

/* IMP: R-39412-46882 */
# EVIDENCE-OF: R-39412-46882 An application-defined function is
# permitted to call other SQLite interfaces.