Package org.basex.query.func

Class StandardFunc

java.lang.Object

org.basex.query.expr.ExprInfo

org.basex.query.expr.Expr

org.basex.query.expr.ParseExpr

org.basex.query.expr.Arr

org.basex.query.func.StandardFunc

Direct Known Subclasses:

AdminDeleteLogs, AdminLogs, AdminSessions, AdminWriteLog, ArchiveCreate, ArchiveDelete, ArchiveEntries, ArchiveExtractBinary, ArchiveExtractTo, ArchiveOptions, ArrayAppend, ArrayFilter, ArrayFlatten, ArrayFoldLeft, ArrayFoldRight, ArrayForEach, ArrayForEachPair, ArrayGet, ArrayHead, ArrayInsertBefore, ArrayJoin, ArrayPut, ArrayRemove, ArrayReverse, ArraySize, ArraySort, ArraySubarray, ArrayTail, BinAnd, BinBin, BinDecodeString, BinEncodeString, BinFind, BinFromOctets, BinHex, BinInsertBefore, BinJoin, BinLength, BinNot, BinOctal, BinOr, BinPackDouble, BinPackFloat, BinPackInteger, BinPadLeft, BinPadRight, BinPart, BinShift, BinToOctets, BinUnpackDouble, BinUnpackFloat, BinUnpackInteger, BinUnpackUnsignedInteger, BinXor, ClientClose, ClientConnect, ClientExecute, ClientInfo, ClientQuery, ContextFn, ConvertBinaryToBytes, ConvertBinaryToIntegers, ConvertDateTimeToInteger, ConvertDayTimeToInteger, ConvertFn, ConvertIntegerFromBase, ConvertIntegerToBase, ConvertIntegerToDateTime, ConvertIntegerToDayTime, CryptoDecrypt, CryptoEncrypt, CryptoGenerateSignature, CryptoHmac, CryptoValidateSignature, CsvParse, CsvSerialize, DbAdd, DbAlterBackup, DbBackups, DbContentType, DbCopy, DbCreate, DbCreateBackup, DbDelete, DbDrop, DbDropBackup, DbExists, DbExport, DbFlush, DbInfo, DbIsRaw, DbIsXml, DbList, DbName, DbNodeId, DbOpen, DbOpenId, DbOptimize, DbOption, DbPath, DbProperty, DbRename, DbReplace, DbRestore, DbRetrieve, DbStore, DbSystem, DbText, DbTextRange, Docs, FetchBinary, FetchContentType, FetchText, FetchXml, FileBaseDir, FileCopy, FileCreateDir, FileCreateTempFile, FileCurrentDir, FileDelete, FileDirSeparator, FileExists, FileIsAbsolute, FileIsDir, FileIsFile, FileLastModified, FileLineSeparator, FileList, FileName, FileParent, FilePathSeparator, FilePathToNative, FilePathToUri, FileReadBinary, FileReadText, FileReadTextLines, FileResolvePath, FileSize, FileTempDir, FileWrite, FileWriteBinary, FileWriteText, FileWriteTextLines, FnAbs, FnAdjustDateToTimezone, FnAdjustTimeToTimezone, FnAdustDateTimeToTimezone, FnAnalyzeString, FnApply, FnAvailableEnvironmentVariables, FnBoolean, FnCeiling, FnCodepointEqual, FnCodepointsToString, FnCompare, FnConcat, FnContains, FnContainsToken, FnCount, FnCurrentDate, FnCurrentDateTime, FnCurrentTime, FnDateTime, FnDayFromDate, FnDayFromDateTime, FnDayFromDuration, FnDeepEqual, FnDefaultCollation, FnDefaultLanguage, FnDistinctValues, FnEmpty, FnEncodeForUri, FnEndsWith, FnEnvironmentVariable, FnError, FnEscapeHtmlUri, FnExactlyOne, FnFalse, FnFilter, FnFloor, FnFoldLeft, FnFoldRight, FnForEach, FnForEachPair, FnFormatDate, FnFormatDateTime, FnFormatInteger, FnFormatNumber, FnFormatTime, FnFunctionArity, FnFunctionLookup, FnFunctionName, FnHead, FnHoursFromDateTime, FnHoursFromDuration, FnHoursFromTime, FnImplicitTimezone, FnIndexOf, FnInScopePrefixes, FnInsertBefore, FnIriToUri, FnLast, FnLocalNameFromQName, FnLowerCase, FnMatches, FnMin, FnMinutesFromDateTime, FnMinutesFromDuration, FnMinutesFromTime, FnMonthFromDate, FnMonthFromDateTime, FnMonthsFromDuration, FnNamespaceUriForPrefix, FnNamespaceUriFromQName, FnNormalizeUnicode, FnNot, FnOneOrMore, FnOutermost, FnParseIetfDate, FnPosition, FnPrefixFromQName, FnPut, FnQName, FnRandomNumberGenerator, FnRemove, FnReplace, FnResolveQName, FnResolveUri, FnReverse, FnRound, FnSecondsFromDateTime, FnSecondsFromDuration, FnSecondsFromTime, FnSerialize, FnSort, FnStartsWith, FnStaticBaseUri, FnStringJoin, FnStringToCodepoints, FnSubsequence, FnSubstring, FnSubstringAfter, FnSubstringBefore, FnSum, FnTail, FnTimezoneFromDate, FnTimezoneFromDateTime, FnTimezoneFromTime, FnTokenize, FnTrace, FnTranslate, FnTrue, FnUnordered, FnUpperCase, FnYearFromDate, FnYearFromDateTime, FnYearsFromDuration, FnZeroOrOne, FtContains, FtCount, FtMark, FtScore, FtSearch, FtTokenize, FtTokens, HashHash, HashMd5, HashSha1, HashSha256, HofFoldLeft1, HofId, HofScanLeft, HofSortWith, HofTakeWhile, HofTopKBy, HofTopKWith, HofUntil, HtmlParse, HtmlParser, HttpSendRequest, IndexFn, InspectContext, InspectFunction, InspectFunctionAnnotations, InspectFunctions, InspectModule, InspectStaticContext, InspectType, InspectXqdoc, JobsCurrent, JobsEval, JobsFinished, JobsList, JobsListDetails, JobsResult, JobsServices, JobsStop, JobsWait, JsonParse, JsonSerialize, LazyCache, LazyIsCached, LazyIsLazy, MapContains, MapEntry, MapFind, MapForEach, MapGet, MapKeys, MapMerge, MapPut, MapRemove, MapSize, MathAtan2, MathFn, OutCr, OutFormat, OutNl, OutTab, Parse, ProcExecute, ProcFork, ProcProperty, ProcPropertyNames, ProcSystem, ProfCurrentMs, ProfCurrentNs, ProfGc, ProfHuman, ProfRuntime, ProfSleep, ProfTime, ProfTrack, ProfType, ProfVariables, ProfVoid, RandomDouble, RandomGaussian, RandomInteger, RandomSeededDouble, RandomSeededInteger, RandomSeededPermutation, RandomUuid, RepoDelete, RepoInstall, RepoList, SqlClose, SqlCommit, SqlConnect, SqlExecute, SqlInit, SqlPrepare, SqlRollback, StringsColognePhonetic, StringsLevenshtein, StringsSoundex, UnitAssert, UnitAssertEquals, UnitFail, UpdateCache, UpdateOutput, UserAlter, UserCheck, UserCreate, UserCurrent, UserDrop, UserExists, UserGrant, UserInfo, UserList, UserPassword, UserUpdateInfo, UtilArrayMembers, UtilArrayValues, UtilChars, UtilDdo, UtilDeepEqual, UtilDuplicates, UtilIf, UtilInit, UtilIntersperse, UtilItem, UtilLast, UtilMapEntries, UtilMapValues, UtilOr, UtilReplicate, UtilRoot, UtilWithin, ValidateDtd, ValidateRng, ValidateXsd, ValidateXsdProcessor, ValidateXsdVersion, WebContentType, WebCreateUrl, WebDecodeUrl, WebEncodeUrl, WebError, WebForward, WebRedirect, WebResponseHeader, XQueryEval, XQueryForkJoin, XQueryParse, XsltInit, XsltProcessor, XsltTransform, XsltVersion, ZipBinaryEntry, ZipEntries, ZipZipFile

public abstract class StandardFunc
extends Arr

Built-in functions.

Author:

BaseX Team 2005-21, BSD License, Christian Gruen

Field Summary

Fields

Modifier and Type	Field	Description
FuncDefinition	definition	Function definition.
StaticContext	sc	Static context.

Fields inherited from class org.basex.query.expr.Arr

exprs

Fields inherited from class org.basex.query.expr.ParseExpr

exprType, info

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	StandardFunc()	Constructor.

Method Summary

Modifier and Type	Method	Description
protected final void	checkAdmin(QueryContext qc)	Checks if the current user has create permissions.
protected final FItem	checkArity(Expr expr, int nargs, boolean updating, QueryContext qc)	Casts and checks the function item for its arity.
protected final FItem	checkArity(Expr expr, int nargs, QueryContext qc)	Casts and checks the function item for its arity.
protected final void	checkCreate(QueryContext qc)	Checks if the current user has create permissions.
protected final Data	checkData(QueryContext qc)	Returns a database instance for the first string argument of the function.
protected final IO	checkPath(byte[] uri)	Returns a valid reference if a file is found at the specified path or the static base uri.
protected final IO	checkPath(int i, QueryContext qc)	Returns a valid reference if a file is found at the specified path or the static base uri.
final Expr	coerceFunc(Expr expr, CompileContext cc, SeqType declType, SeqType... argTypes)	Refines the type of a function item argument.
protected final Expr	compileData(CompileContext cc)	Opens a database at compile time.
final StandardFunc	copy(CompileContext cc, IntObjMap<Var> vm)	Copies an expression.
final Data	data()	Returns the data reference bound to this expression.
final void	data(Data dt)	Assigns a data reference, if supported.
protected final boolean	dataLock(ASTVisitor visitor, int i)	Tries to mark the specified argument for locking.
protected final long	dateTimeToMs(Expr expr, QueryContext qc)	Converts the specified dateTime to milliseconds.
final String	description()	Returns a string description of the expression.
final boolean	equals(Object obj)	This function is e.g.
boolean	has(Flag... flags)	Indicates if an expression has one of the specified compiler properties.
protected Expr	opt(CompileContext cc)	Performs function specific optimizations.
protected final Expr	optFirst()	Optimizes a function that returns an empty sequence when the first atomized argument is empty, and adjusts the occurrence indicator if the argument will always yield one item.
protected final Expr	optFirst(boolean occ, boolean atom, Value value)	Optimizes a function that returns an empty sequence when the first argument or the context value is empty.
final Expr	optimize(CompileContext cc)	Optimizes an already compiled expression without recompiling its sub-expressions.
final void	plan(QueryPlan plan)	Creates a query plan.
final void	plan(QueryString qs)	Creates a query string.
protected final byte[]	serialize(Iter iter, SerializerOptions opts, QueryError err, QueryContext qc)	Serializes the data from the specified iterator.
protected void	simplifyArgs(CompileContext cc)	Simplifies the types of all arguments.
protected final String	toBaseUri(String path, Options options)	Evaluates the specified URI.
protected final HashMap<String,Value>	toBindings(int i, QueryContext qc)	Returns all keys and values of the specified binding argument.
protected final Collation	toCollation(int i, QueryContext qc)	Checks if the specified collation is supported.
protected final ADate	toDate(Item item, AtomType type, QueryContext qc)	Checks if the specified item has the specified Date type.
protected final DBNode	toDBNode(Item item)	Checks if the specified expression is a database node.
protected final String	toEncodingOrNull(int i, QueryError err, QueryContext qc)	Returns a normalized encoding representation.
protected final Item	toNodeOrAtomItem(int i, QueryContext qc)	Returns the expression at the specified index as node or atomized item.
protected final <E extends Options> E	toOptions(int i, E opts, QueryContext qc)	Parses the options at the specified index.
protected final Path	toPath(byte[] path)	Converts the specified string to a file path.
protected final Path	toPath(int i, QueryContext qc)	Converts the specified argument to a file path.
protected final IOContent	toQuery(byte[] uri, QueryContext qc)	Evaluates the specified URI.
protected final IOContent	toQuery(int i, QueryContext qc)	Evaluates the specified URI.
boolean	vacuous()	Tests if this is a vacuous expression (empty sequence or error function).

Methods inherited from class org.basex.query.expr.Arr

accept, allAreValues, args, checkUp, compile, copyAll, count, exprSize, flatten, inline, inline, inlineable, mayBePositional, simplifyAll

Methods inherited from class org.basex.query.expr.ParseExpr

adoptType, atomValue, checkAllUp, checkNoEmpty, checkNoEmpty, checkNoneUp, checkNoUp, checkType, checkType, checkUp, copyType, ctxValue, ebv, item, iter, refineType, seqType, size, test, toArray, toArray, toAtomItem, toB64, toB64, toBin, toBin, toBoolean, toBoolean, toBytes, toBytes, toDouble, toDouble, toElem, toFloat, toFunc, toItem, toItem, toLong, toLong, toMap, toMap, toNode, toNode, toNodeOrNull, toNumber, toNumberOrNull, toQNm, toQNm, toToken, toToken, toTokenOrNull, toZeroToken, value

Methods inherited from class org.basex.query.expr.Expr

arg, atomItem, atomIter, ddo, funcType, hasFreeVars, indexAccessible, isSimple, markTailCalls, mergeEbv, simplifyFor, typeCheck, uses, visitAll

Methods inherited from class org.basex.query.expr.ExprInfo

toErrorString, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

definition

public FuncDefinition definition

Function definition.

sc

public StaticContext sc

Static context.

Constructor Details

StandardFunc

protected StandardFunc()

Constructor.

Method Details

optimize

public final Expr optimize(CompileContext cc)
                    throws QueryException

Description copied from class: Expr

Optimizes an already compiled expression without recompiling its sub-expressions.

Overrides:

optimize in class Expr

Parameters:

cc - compilation context

Returns:

optimized expression

Throws:

QueryException - query exception

simplifyArgs

protected void simplifyArgs(CompileContext cc)
                     throws QueryException

Simplifies the types of all arguments. This function is overwritten by functions that rely on the original argument type.

Parameters:

cc - compilation context

Throws:

QueryException - query exception

opt

protected Expr opt(CompileContext cc)
            throws QueryException

Performs function specific optimizations.

Parameters:

cc - compilation context

Returns:

optimized or original expression

Throws:

QueryException - query exception

copy

public final StandardFunc copy(CompileContext cc,
 IntObjMap<Var> vm)

Description copied from class: Expr

Copies an expression. Used for inlining functions, or for copying static queries. It is utilized by VarRef.inline(org.basex.query.InlineContext), FuncItem.inline(org.basex.query.expr.Expr[], org.basex.query.CompileContext), Closure.inline(org.basex.query.InlineContext) and StaticFunc.inline(org.basex.query.expr.Expr[], org.basex.query.CompileContext).

Specified by:

copy in class Expr

Parameters:

cc - compilation context

vm - mapping from old variable IDs to new variable copies. Required by Closure.copy(org.basex.query.CompileContext, org.basex.util.hash.IntObjMap<org.basex.query.var.Var>) and VarRef.copy(org.basex.query.CompileContext, org.basex.util.hash.IntObjMap<org.basex.query.var.Var>)

Returns:

copied expression

optFirst

protected final Expr optFirst()

Optimizes a function that returns an empty sequence when the first atomized argument is empty, and adjusts the occurrence indicator if the argument will always yield one item.

Returns:

original expression or function argument

optFirst

protected final Expr optFirst(boolean occ,
 boolean atom,
 Value value)

Optimizes a function that returns an empty sequence when the first argument or the context value is empty.

• Returns the first argument (or the context) if it yields an empty sequence.
• Sets the occurrence indicator to 1 if the argument returns at least one item.

Parameters:

occ - assign occurrence indicator (true if function will always yield a result if first argument is non-empty)

atom - argument will be atomized

value - context value (ignored if null)

Returns:

original expression or function argument

serialize

protected final byte[] serialize(Iter iter,
 SerializerOptions opts,
 QueryError err,
 QueryContext qc)
                          throws QueryException

Serializes the data from the specified iterator.

Parameters:

iter - data to serialize

opts - serialization parameters

err - error code

qc - query context

Returns:

result

Throws:

QueryException - query exception

has

public boolean has(Flag... flags)

Description copied from class: Expr

Indicates if an expression has one of the specified compiler properties. This method must only be called at compile time. It is invoked to test properties of sub-expressions. It returns true if at least flag matches an expression.

Overrides:

has in class Arr

Parameters:

flags - flags to be checked

Returns:

result of check

vacuous

public boolean vacuous()

Description copied from class: Expr

Tests if this is a vacuous expression (empty sequence or error function). This check is needed for updating queries.

Overrides:

vacuous in class Expr

Returns:

result of check

coerceFunc

public final Expr coerceFunc(Expr expr,
 CompileContext cc,
 SeqType declType,
 SeqType... argTypes)
                      throws QueryException

Refines the type of a function item argument.

Parameters:

expr - expression

cc - compilation context

declType - declared return type

argTypes - argument types

Returns:

old or new expression

Throws:

QueryException - query context

compileData

protected final Expr compileData(CompileContext cc)
                          throws QueryException

Opens a database at compile time.

Parameters:

cc - compilation context

Returns:

self reference

Throws:

QueryException - query exception

data

public final Data data()

Description copied from class: Expr

Returns the data reference bound to this expression. This method is currently overwritten by DBNode, DBNodeSeq, AxisPath and VarRef.

Overrides:

data in class Expr

Returns:

data reference (can be null)

data

public final void data(Data dt)

Description copied from class: Expr

Assigns a data reference, if supported.

Overrides:

data in class Expr

Parameters:

dt - data reference

toDate

protected final ADate toDate(Item item,
 AtomType type,
 QueryContext qc)
                      throws QueryException

Checks if the specified item has the specified Date type. If it is item, the specified Date is returned.

Parameters:

item - item to be checked

type - target type

qc - query context

Returns:

date

Throws:

QueryException - query exception

toDBNode

protected final DBNode toDBNode(Item item)
                         throws QueryException

Checks if the specified expression is a database node. Returns the node or an exception.

Parameters:

item - item to be checked

Returns:

item

Throws:

QueryException - query exception

toCollation

protected final Collation toCollation(int i,
 QueryContext qc)
                               throws QueryException

Checks if the specified collation is supported.

Parameters:

i - index of argument

qc - query context

Returns:

collator or null (default collation)

Throws:

QueryException - query exception

toPath

protected final Path toPath(int i,
 QueryContext qc)
                     throws QueryException

Converts the specified argument to a file path.

Parameters:

i - index of argument

qc - query context

Returns:

file instance

Throws:

QueryException - query exception

toPath

protected final Path toPath(byte[] path)
                     throws QueryException

Converts the specified string to a file path.

Parameters:

path - path string

Returns:

file instance

Throws:

QueryException - query exception

checkPath

protected final IO checkPath(int i,
 QueryContext qc)
                      throws QueryException

Returns a valid reference if a file is found at the specified path or the static base uri. Otherwise, returns an error.

Parameters:

i - index of URI argument

qc - query context

Returns:

input source, or exception

Throws:

QueryException - query exception

checkPath

protected final IO checkPath(byte[] uri)
                      throws QueryException

Returns a valid reference if a file is found at the specified path or the static base uri. Otherwise, returns an error.

Parameters:

uri - file URI

Returns:

input source, or exception

Throws:

QueryException - query exception

toQuery

protected final IOContent toQuery(int i,
 QueryContext qc)
                           throws QueryException

Evaluates the specified URI.

Parameters:

i - index of input argument

qc - query context

Returns:

query contents and URL

Throws:

QueryException - query exception

toQuery

protected final IOContent toQuery(byte[] uri,
 QueryContext qc)
                           throws QueryException

Evaluates the specified URI.

Parameters:

uri - uri

qc - query context

Returns:

query contents and URL

Throws:

QueryException - query exception

toBaseUri

protected final String toBaseUri(String path,
 Options options)

Evaluates the specified URI.

Parameters:

path - custom path

options - options with base-uri property

Returns:

base URI

toEncodingOrNull

protected final String toEncodingOrNull(int i,
 QueryError err,
 QueryContext qc)
                                 throws QueryException

Returns a normalized encoding representation.

Parameters:

i - index of encoding argument

err - error for invalid encoding

qc - query context

Returns:

string or null

Throws:

QueryException - query exception

toNodeOrAtomItem

protected final Item toNodeOrAtomItem(int i,
 QueryContext qc)
                               throws QueryException

Returns the expression at the specified index as node or atomized item. Returns the item or throws an exception.

Parameters:

i - index of argument

qc - query context

Returns:

node or atomized item

Throws:

QueryException - query exception

toOptions

protected final <E extends Options> E toOptions(int i,
 E opts,
 QueryContext qc)
                                         throws QueryException

Parses the options at the specified index.

Type Parameters:

E - options type

Parameters:

i - index of argument (can exceed length of argument, or may yield an empty sequence)

opts - options

qc - query context

Returns:

passed on options

Throws:

QueryException - query exception

toBindings

protected final HashMap<String,Value> toBindings(int i,
 QueryContext qc)
                                          throws QueryException

Returns all keys and values of the specified binding argument.

Parameters:

i - index of argument

qc - query context

Returns:

resulting map

Throws:

QueryException - query exception

checkData

protected final Data checkData(QueryContext qc)
                        throws QueryException

Returns a database instance for the first string argument of the function. This method assumes that the function has at least one argument.

Parameters:

qc - query context

Returns:

data instance

Throws:

QueryException - query exception

checkAdmin

protected final void checkAdmin(QueryContext qc)
                         throws QueryException

Checks if the current user has create permissions. If negative, an exception is thrown.

Parameters:

qc - query context

Throws:

QueryException - query exception

checkCreate

protected final void checkCreate(QueryContext qc)
                          throws QueryException

Checks if the current user has create permissions. If negative, an exception is thrown.

Parameters:

qc - query context

Throws:

QueryException - query exception

checkArity

protected final FItem checkArity(Expr expr,
 int nargs,
 QueryContext qc)
                          throws QueryException

Casts and checks the function item for its arity.

Parameters:

expr - expression

nargs - number of arguments (arity)

qc - query context

Returns:

function item

Throws:

QueryException - query exception

checkArity

protected final FItem checkArity(Expr expr,
 int nargs,
 boolean updating,
 QueryContext qc)
                          throws QueryException

Casts and checks the function item for its arity.

Parameters:

expr - expression

nargs - number of arguments (arity)

qc - query context

updating - updating flag

Returns:

function item

Throws:

QueryException - query exception

dateTimeToMs

protected final long dateTimeToMs(Expr expr,
 QueryContext qc)
                           throws QueryException

Converts the specified dateTime to milliseconds.

Parameters:

expr - expression

qc - query context

Returns:

resulting value

Throws:

QueryException - query exception

dataLock

protected final boolean dataLock(ASTVisitor visitor,
 int i)

Tries to mark the specified argument for locking.

Parameters:

visitor - visitor

i - index of database argument

Returns:

result of check

equals

public final boolean equals(Object obj)

Description copied from class: Arr

This function is e.g. called by:

• If.optimize(CompileContext), Switch.optimize(CompileContext), Typeswitch.optimize(CompileContext), in order to discard identical expressions.
• CmpR.mergeEbv(Expr, boolean, CompileContext) or CmpSR.mergeEbv(Expr, boolean, CompileContext), in order to merge expressions with identical input.
• CmpG.optimize(CompileContext) or CmpV.optimize(CompileContext), in order to pre-evaluate equality tests.
• CmpG.optimize(CompileContext) or Pos.get(Expr, CmpV.OpV, InputInfo, CompileContext), in order to compare the start and end value.
• PathCache, in order to find identical root values at runtime.

Must be overwritten by implementing class.

Overrides:

equals in class Arr

description

public final String description()

Description copied from class: ExprInfo

Returns a string description of the expression. This method is only called by error messages. Contrary to the ExprInfo.toString() method, arguments are not included in the output.

Overrides:

description in class ExprInfo

Returns:

result of check

plan

public final void plan(QueryPlan plan)

Description copied from class: ExprInfo

Creates a query plan.

Overrides:

plan in class Arr

Parameters:

plan - expression plan

plan

public final void plan(QueryString qs)

Description copied from class: ExprInfo

Creates a query string.

Specified by:

plan in class ExprInfo

Parameters:

qs - query string builder