ajquery.c

Datatypes: AjPQuery AjPQueryField AjPList AjPStr


Datatype: AjPQuery

Query object

Sections: Query Constructors Query Destructors Query Casts Modifiers Debug exit


Section: Query Constructors

All constructors return a new query object by pointer. It is the responsibility of the user to first destroy any previous query object. The target pointer does not need to be initialised to NULL, but it is good programming practice to do so anyway.

Functions: ajQueryNew


Function ajQueryNew

Creates a new query object for a specific datatype from the AJDATATYPE enumerated types

Synopsis

Prototype
AjPQuery ajQueryNew (
      const AjEDataType datatype
);

TypeNameRead/WriteDescription
const AjEDataTypedatatypeInputEnumerated datatype
AjPQuery RETURNNew query object.

Input
datatype:(Input)Enumerated datatype
Returns
AjPQuery:New query object.

Description

Creates a new query object for a specific datatype from the AJDATATYPE enumerated types

See Also

See other functions in this section

Availability

In release 6.4.0

Section: Query Destructors

Destruction destroys all internal data structures and frees the memory allocated for the query object.

Functions: ajQueryDel


Function ajQueryDel

Deletes a query object

Synopsis

Prototype
void ajQueryDel (
      AjPQuery* pthis
);

TypeNameRead/WriteDescription
AjPQuery*pthisDeleteAddress of query object
void RETURN

Output
pthis:(Delete)Address of query object
Returns
void:No return value

Description

Deletes a query object

See Also

See other functions in this section

Availability

In release 6.4.0

Section: Query Casts

These functions examine the contents of a query object and return some derived information. Some of them provide access to the internal components of a query object. They are provided for programming convenience but should be used with caution.

Functions: ajQueryGetDatatype ajQueryGetFormat ajQueryGetId ajQueryGetQuery ajQueryGetallFields


Function ajQueryGetDatatype

Returns the query datatype from a query

Synopsis

Prototype
const char* ajQueryGetDatatype (
      const AjPQuery query
);

TypeNameRead/WriteDescription
const AjPQueryqueryInputQuery
const char* RETURNStandard name for query datatype

Input
query:(Input)Query
Returns
const char*:Standard name for query datatype

Description

Returns the query datatype from a query

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryGetFormat

Returns the format name from a query

Synopsis

Prototype
const AjPStr ajQueryGetFormat (
      const AjPQuery query
);

TypeNameRead/WriteDescription
const AjPQueryqueryInputQuery
const AjPStr RETURNFormat name

Input
query:(Input)Query
Returns
const AjPStr:Format name

Description

Returns the format name from a query

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryGetId

Returns the ID query string from a query

Synopsis

Prototype
const AjPStr ajQueryGetId (
      const AjPQuery query
);

TypeNameRead/WriteDescription
const AjPQueryqueryInputQuery
const AjPStr RETURNWildcard ID query string

Input
query:(Input)Query
Returns
const AjPStr:Wildcard ID query string

Description

Returns the ID query string from a query

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryGetQuery

Returns a report of the query string from a query

Synopsis

Prototype
AjBool ajQueryGetQuery (
      const AjPQuery query,
      AjPStr* Pdest
);

TypeNameRead/WriteDescription
const AjPQueryqueryInputQuery
AjPStr*PdestOutputQuery string
AjBool RETURNTrue on success

Input
query:(Input)Query
Output
Pdest:(Output)Query string
Returns
AjBool:True on success

Description

Returns a report of the query string from a query

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryGetallFields

Returns the standard sequence query string from a query

Synopsis

Prototype
const AjPList ajQueryGetallFields (
      const AjPQuery query
);

TypeNameRead/WriteDescription
const AjPQueryqueryInputQuery
const AjPList RETURNList of field objects

Input
query:(Input)Query
Returns
const AjPList:List of field objects

Description

Returns the standard sequence query string from a query

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryIsSet

Tests whether any element of a query has been set.

Synopsis

Prototype
AjBool ajQueryIsSet (
      const AjPQuery thys
);

TypeNameRead/WriteDescription
const AjPQuerythysInputQuery object.
AjBool RETURNajTrue if query should be made. ajFalse if the query includes all entries.

Input
thys:(Input)Query object.
Returns
AjBool:ajTrue if query should be made. ajFalse if the query includes all entries.

Description

Tests whether any element of a query has been set.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryKnownFieldC

Checks whether a query field is defined for a database as a "fields:" string in the database definition.

Synopsis

Prototype
AjBool ajQueryKnownFieldC (
      const AjPQuery thys,
      const char* fieldtxt
);

TypeNameRead/WriteDescription
const AjPQuerythysInputQuery object
const char*fieldtxtInputfield name
AjBool RETURNajTrue if the field is defined

Input
thys:(Input)Query object
fieldtxt:(Input)field name
Returns
AjBool:ajTrue if the field is defined

Description

Checks whether a query field is defined for a database as a "fields:" string in the database definition.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryKnownFieldS

Checks whether a query field is defined for a database as a "fields:" string in the database definition.

Synopsis

Prototype
AjBool ajQueryKnownFieldS (
      const AjPQuery thys,
      const AjPStr field
);

TypeNameRead/WriteDescription
const AjPQuerythysInputQuery object
const AjPStrfieldInputfield name
AjBool RETURNajTrue if the field is defined

Input
thys:(Input)Query object
field:(Input)field name
Returns
AjBool:ajTrue if the field is defined

Description

Checks whether a query field is defined for a database as a "fields:" string in the database definition.

See Also

See other functions in this section

Availability

In release 6.4.0

Section: Modifiers

Modify values in a query object

Functions: ajQueryAddFieldAndC ajQueryAddFieldAndS ajQueryAddFieldElseC ajQueryAddFieldElseS ajQueryAddFieldEorC ajQueryAddFieldEorS ajQueryAddFieldNotC ajQueryAddFieldNotS ajQueryAddFieldOrC ajQueryAddFieldOrS ajQueryClear ajQuerySetWild ajQueryStarclear


Function ajQueryAddFieldAndC

Adds a query with an 'AND' operator

Synopsis

Prototype
AjBool ajQueryAddFieldAndC (
      AjPQuery thys,
      const char* fieldtxt,
      const char* wildquerytxt
);

TypeNameRead/WriteDescription
AjPQuerythysModifyQuery object
const char*fieldtxtInputfield name
const char*wildquerytxtInputwildcard query string
AjBool RETURNajTrue on success

Input
fieldtxt:(Input)field name
wildquerytxt:(Input)wildcard query string
Input & Output
thys:(Modify)Query object
Returns
AjBool:ajTrue on success

Description

Adds a query with an 'AND' operator

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryAddFieldAndS

Adds a query with an 'AND' operator

Synopsis

Prototype
AjBool ajQueryAddFieldAndS (
      AjPQuery thys,
      const AjPStr field,
      const AjPStr wildquery
);

TypeNameRead/WriteDescription
AjPQuerythysModifyQuery object
const AjPStrfieldInputfield name
const AjPStrwildqueryInputwildcard query string
AjBool RETURNajTrue on success

Input
field:(Input)field name
wildquery:(Input)wildcard query string
Input & Output
thys:(Modify)Query object
Returns
AjBool:ajTrue on success

Description

Adds a query with an 'AND' operator

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryAddFieldElseC

Adds a query with an 'ELSE' operator

Synopsis

Prototype
AjBool ajQueryAddFieldElseC (
      AjPQuery thys,
      const char* fieldtxt,
      const char* wildquerytxt
);

TypeNameRead/WriteDescription
AjPQuerythysModifyQuery object
const char*fieldtxtInputfield name
const char*wildquerytxtInputwildcard query string
AjBool RETURNajTrue on success

Input
fieldtxt:(Input)field name
wildquerytxt:(Input)wildcard query string
Input & Output
thys:(Modify)Query object
Returns
AjBool:ajTrue on success

Description

Adds a query with an 'ELSE' operator

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryAddFieldElseS

Adds a query with an 'ELSE' operator

Synopsis

Prototype
AjBool ajQueryAddFieldElseS (
      AjPQuery thys,
      const AjPStr field,
      const AjPStr wildquery
);

TypeNameRead/WriteDescription
AjPQuerythysModifyQuery object
const AjPStrfieldInputfield name
const AjPStrwildqueryInputwildcard query string
AjBool RETURNajTrue on success

Input
field:(Input)field name
wildquery:(Input)wildcard query string
Input & Output
thys:(Modify)Query object
Returns
AjBool:ajTrue on success

Description

Adds a query with an 'ELSE' operator

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryAddFieldEorC

Adds a query with an 'EOR' operator

Synopsis

Prototype
AjBool ajQueryAddFieldEorC (
      AjPQuery thys,
      const char* fieldtxt,
      const char* wildquerytxt
);

TypeNameRead/WriteDescription
AjPQuerythysModifyQuery object
const char*fieldtxtInputfield name
const char*wildquerytxtInputwildcard query string
AjBool RETURNajTrue on success

Input
fieldtxt:(Input)field name
wildquerytxt:(Input)wildcard query string
Input & Output
thys:(Modify)Query object
Returns
AjBool:ajTrue on success

Description

Adds a query with an 'EOR' operator

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryAddFieldEorS

Adds a query with an 'EOR' operator

Synopsis

Prototype
AjBool ajQueryAddFieldEorS (
      AjPQuery thys,
      const AjPStr field,
      const AjPStr wildquery
);

TypeNameRead/WriteDescription
AjPQuerythysModifyQuery object
const AjPStrfieldInputfield name
const AjPStrwildqueryInputwildcard query string
AjBool RETURNajTrue on success

Input
field:(Input)field name
wildquery:(Input)wildcard query string
Input & Output
thys:(Modify)Query object
Returns
AjBool:ajTrue on success

Description

Adds a query with an 'EOR' operator

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryAddFieldNotC

Adds a query with a 'NOT' operator

Synopsis

Prototype
AjBool ajQueryAddFieldNotC (
      AjPQuery thys,
      const char* fieldtxt,
      const char* wildquerytxt
);

TypeNameRead/WriteDescription
AjPQuerythysModifyQuery object
const char*fieldtxtInputfield name
const char*wildquerytxtInputwildcard query string
AjBool RETURNajTrue on success

Input
fieldtxt:(Input)field name
wildquerytxt:(Input)wildcard query string
Input & Output
thys:(Modify)Query object
Returns
AjBool:ajTrue on success

Description

Adds a query with a 'NOT' operator

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryAddFieldNotS

Adds a query with a 'NOT' operator

Synopsis

Prototype
AjBool ajQueryAddFieldNotS (
      AjPQuery thys,
      const AjPStr field,
      const AjPStr wildquery
);

TypeNameRead/WriteDescription
AjPQuerythysModifyQuery object
const AjPStrfieldInputfield name
const AjPStrwildqueryInputwildcard query string
AjBool RETURNajTrue on success

Input
field:(Input)field name
wildquery:(Input)wildcard query string
Input & Output
thys:(Modify)Query object
Returns
AjBool:ajTrue on success

Description

Adds a query with a 'NOT' operator

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryAddFieldOrC

Adds a query with an 'OR' operator

Synopsis

Prototype
AjBool ajQueryAddFieldOrC (
      AjPQuery thys,
      const char* fieldtxt,
      const char* wildquerytxt
);

TypeNameRead/WriteDescription
AjPQuerythysModifyQuery object
const char*fieldtxtInputfield name
const char*wildquerytxtInputwildcard query string
AjBool RETURNajTrue on success

Input
fieldtxt:(Input)field name
wildquerytxt:(Input)wildcard query string
Input & Output
thys:(Modify)Query object
Returns
AjBool:ajTrue on success

Description

Adds a query with an 'OR' operator

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryAddFieldOrS

Adds a query with an 'OR' operator

Synopsis

Prototype
AjBool ajQueryAddFieldOrS (
      AjPQuery thys,
      const AjPStr field,
      const AjPStr wildquery
);

TypeNameRead/WriteDescription
AjPQuerythysModifyQuery object
const AjPStrfieldInputfield name
const AjPStrwildqueryInputwildcard query string
AjBool RETURNajTrue on success

Input
field:(Input)field name
wildquery:(Input)wildcard query string
Input & Output
thys:(Modify)Query object
Returns
AjBool:ajTrue on success

Description

Adds a query with an 'OR' operator

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryClear

Resets a query object to a clean state for reuse. Keep the begin, end and reverse values.

Synopsis

Prototype
void ajQueryClear (
      AjPQuery thys
);

TypeNameRead/WriteDescription
AjPQuerythysModifyquery object
void RETURN

Input & Output
thys:(Modify)query object
Returns
void:No return value

Description

Resets a query object to a clean state for reuse. Keep the begin, end and reverse values.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQuerySetWild

Tests whether a query includes wild cards in any element, or can return more than one entry (keyword and some other search terms will find multiple entries)

Synopsis

Prototype
AjBool ajQuerySetWild (
      AjPQuery thys
);

TypeNameRead/WriteDescription
AjPQuerythysModifyQuery object.
AjBool RETURNajTrue if query had wild cards.

Input & Output
thys:(Modify)Query object.
Returns
AjBool:ajTrue if query had wild cards.

Description

Tests whether a query includes wild cards in any element, or can return more than one entry (keyword and some other search terms will find multiple entries)

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryStarclear

Clears elements of a query object if they are simply "*" because this is equivalent to a null string.

Synopsis

Prototype
void ajQueryStarclear (
      AjPQuery thys
);

TypeNameRead/WriteDescription
AjPQuerythysModifyQuery object.
void RETURN

Input & Output
thys:(Modify)Query object.
Returns
void:No return value

Description

Clears elements of a query object if they are simply "*" because this is equivalent to a null string.

See Also

See other functions in this section

Availability

In release 6.4.0

Section: Debug

Reports sequence contents for debugging purposes

Functions: ajQueryTrace


Function ajQueryTrace

Debug calls to trace the data in a query object.

Synopsis

Prototype
void ajQueryTrace (
      const AjPQuery thys
);

TypeNameRead/WriteDescription
const AjPQuerythysInputquery object.
void RETURN

Input
thys:(Input)query object.
Returns
void:No return value

Description

Debug calls to trace the data in a query object.

See Also

See other functions in this section

Availability

In release 6.4.0

Section: exit

Functions called on exit from the program by ajExit to do any necessary cleanup and to report internal statistics to the debug file

Functions: ajQueryExit


Function ajQueryExit

Cleans up query processing internal memory

Synopsis

Prototype
void ajQueryExit (
      void
);

TypeNameRead/WriteDescription
void RETURN

Returns
void:No return value

Description

Cleans up query processing internal memory

See Also

See other functions in this section

Availability

In release 6.4.0

Datatype: AjPQueryField

Query fields

Sections: constructors Query Field Destructors


Section: constructors

Constructors

Functions: ajQueryfieldNewC ajQueryfieldNewS


Function ajQueryfieldNewC

Constructor for a query field

Synopsis

Prototype
AjPQueryField ajQueryfieldNewC (
      const char* fieldtxt,
      const char* wildtxt,
      AjEQryLink oper
);

TypeNameRead/WriteDescription
const char*fieldtxtInputField name
const char*wildtxtInputWildcard query string
AjEQryLinkoperInputOperator
AjPQueryField RETURNQuery field

Input
fieldtxt:(Input)Field name
wildtxt:(Input)Wildcard query string
oper:(Input)Operator
Returns
AjPQueryField:Query field

Description

Constructor for a query field

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQueryfieldNewS

Constructor for a query field

Synopsis

Prototype
AjPQueryField ajQueryfieldNewS (
      const AjPStr field,
      const AjPStr wild,
      AjEQryLink oper
);

TypeNameRead/WriteDescription
const AjPStrfieldInputField name
const AjPStrwildInputWildcard query string
AjEQryLinkoperInputOperator
AjPQueryField RETURNQuery field

Input
field:(Input)Field name
wild:(Input)Wildcard query string
oper:(Input)Operator
Returns
AjPQueryField:Query field

Description

Constructor for a query field

See Also

See other functions in this section

Availability

In release 6.4.0

Section: Query Field Destructors

Destruction destroys all internal data structures and frees the memory allocated for the query field object.

Functions: ajQueryfieldDel


Function ajQueryfieldDel

Destructor for a query field

Synopsis

Prototype
void ajQueryfieldDel (
      AjPQueryField* Pthis
);

TypeNameRead/WriteDescription
AjPQueryField*PthisDeleteQuery field object to be deleted
void RETURN

Output
Pthis:(Delete)Query field object to be deleted
Returns
void:No return value

Description

Destructor for a query field

See Also

See other functions in this section

Availability

In release 6.4.0

Datatype: AjPList

Query field list

Sections: Debug


Section: Debug

Reports sequence contents for debugging purposes

Functions: ajQuerylistTrace


Function ajQuerylistTrace

Traces the nodes in a query list

Synopsis

Prototype
void ajQuerylistTrace (
      const AjPList list
);

TypeNameRead/WriteDescription
const AjPListlistInputThe query list
void RETURN

Input
list:(Input)The query list
Returns
void:No return value

Description

Traces the nodes in a query list

See Also

See other functions in this section

Availability

In release 6.4.0

Datatype: AjPStr

Query string

Sections: Query string parsing


Section: Query string parsing

Parses a query string and removes the processed string trokens

Functions: ajQuerystrParseFormat ajQuerystrParseListfile ajQuerystrParseRange ajQuerystrParseRead


Function ajQuerystrParseFormat

Parses a query (USA, UFO or general query).

Then tests for "format::" and returns this if it is found, removing the format part of the original query.

Synopsis

Prototype
const AjPStr ajQuerystrParseFormat (
      AjPStr* Pqry,
      AjPTextin textin,
      AjBool function findformat
);

TypeNameRead/WriteDescription
AjPStr*PqryModifyQuery string
AjPTextintextinModifyText input object
AjBool functionfindformatFunctionFunction to validate format name
const AjPStr RETURNFormat name if found

Input
findformat:(Function)Function to validate format name
Input & Output
Pqry:(Modify)Query string
textin:(Modify)Text input object
Returns
const AjPStr:Format name if found

Description

Parses a query (USA, UFO or general query).

Then tests for "format::" and returns this if it is found, removing the format part of the original query.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQuerystrParseListfile

Parses a query (USA, UFO or general query).

Then tests for "list::" or "

Synopsis

Prototype
AjBool ajQuerystrParseListfile (
      AjPStr* Pqry
);

TypeNameRead/WriteDescription
AjPStr*PqryModifyQuery string
AjBool RETURNTrue if found

Input & Output
Pqry:(Modify)Query string
Returns
AjBool:True if found

Description

Parses a query (USA, UFO or general query).

Then tests for "list::" or "

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQuerystrParseRange

Parses a query (USA, UFO or general query).

Tests for "[n:n:r]" range and sets this if it is found, removing the range part of the original query.

Synopsis

Prototype
AjBool ajQuerystrParseRange (
      AjPStr* Pqry,
      ajint* Pbegin,
      ajint* Pend,
      AjBool* Prev
);

TypeNameRead/WriteDescription
AjPStr*PqryModifyQuery string
ajint*PbeginModifyBegin position
ajint*PendModifyEnd position
AjBool*PrevModifyReverse orientation
AjBool RETURNTrue if range was found.

Input & Output
Pqry:(Modify)Query string
Pbegin:(Modify)Begin position
Pend:(Modify)End position
Prev:(Modify)Reverse orientation
Returns
AjBool:True if range was found.

Description

Parses a query (USA, UFO or general query).

Tests for "[n:n:r]" range and sets this if it is found, removing the range part of the original query.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajQuerystrParseRead

Parses a query (USA, UFO or general query).

First tests for "asis" input and sets the rest of the query as input data.

Then tests for server:dbname:query or dbname:query and tests whether the access method is a text method.

For text access, calls the access method to opens the file (and set the file position).

If there is no database, looks for file:query and opens the file. If an offset is provided as %offset sets the file position

If the file does now exist, tests again for a database of that name from any known server.

If no text data was found, returns the filled in datatype-specific details

Synopsis

Prototype
AjBool ajQuerystrParseRead (
      AjPStr* Pqry,
      AjPTextin textin,
      AjBool function findformat,
      AjBool* Pnontext
);

TypeNameRead/WriteDescription
AjPStr*PqryModifyQuery string
AjPTextintextinModifyText input structure.
AjBool functionfindformatFunctionFunction to validate format name
AjBool*PnontextOutputTrue if access is a non-text method
AjBool RETURNajTrue on success.

Input
findformat:(Function)Function to validate format name
Output
Pnontext:(Output)True if access is a non-text method
Input & Output
Pqry:(Modify)Query string
textin:(Modify)Text input structure.
Returns
AjBool:ajTrue on success.

Description

Parses a query (USA, UFO or general query).

First tests for "asis" input and sets the rest of the query as input data.

Then tests for server:dbname:query or dbname:query and tests whether the access method is a text method.

For text access, calls the access method to opens the file (and set the file position).

If there is no database, looks for file:query and opens the file. If an offset is provided as %offset sets the file position

If the file does now exist, tests again for a database of that name from any known server.

If no text data was found, returns the filled in datatype-specific details

See Also

See other functions in this section

Availability

In release 6.4.0