GNQuery implements also the following extension functions (in the namespace ‘http://www.teradp.com/schemas/GN4/1/Xslt’ with standard prefix ‘fn’):

fn:objectIdFromString(expr)

Converts an object id string into the corresponding numeric id – e.g. converts the string ‘obj1234’ in the number ‘1234’. Returns ‘NaN’ if the string cannot be converted.

fn:dataIdFromString(expr)

Converts a data id string into the corresponding numeric id – e.g. converts the string ‘data678’ in the number ‘678’. Returns ‘NaN’ if the string cannot be converted.

fn:in(expr,expr1,expr2, . . . )

Returns true if expr is equal to any of the values expr1, expr2 etc. The type of expr controls the type of comparison used: if expr evaluates to a number the values are converted to numbers, if expr evaluates to a string the values are converted to strings.

If expr is a node-set the function returns true if any of the nodes is equal to any of the expression, so that the query

 gn4:story[fn:in(gn4:keywords/gn4:item,'bridges','tunnels')]

returns all the stories that have at least a keyword equal to either ‘bridges’ or ‘tunnels’.

fn:ends-with(expr1, expr2)

Returns true if expr1 (as a string) ends with expr2.

GNQuery uses the same non-standard evaluation logic as for the ‘contains()’ function above.

fn:dateFromDateTime(expr)

Converts a date-time value to the corresponding date – stripping the time part.

fn:dateTimeFromString(expr)

Converts a string into the corresponding date-time. The string is expected to be in the standard format ‘YYYY-MM-DDThh:mm:ssZ’. If the string is not a valid date-time returns the minimum possible date-time.

fn:dateFromString(expr)

Converts a string into the corresponding date. The string is expected to be in the standard format ‘YYYY-MM-DDZ’. If the string is not a valid date returns the minimum possible date.

fn:dateTimeFromTimeString(expr)

Converts a time string into the corresponding date-time. The string is expected to be in the standard format ‘hh:mm:ssZ’. If the string is not a valid time returns the minimum possible date-time.

fn:inRelativeYears(expr,fromexpr,toexpr)

Checks that the date-time or date represented by the expr string is within fromexpr and toexpr years relative to the current one. fromexpr and toexpr must be numeric constants or variable references (‘$name’), a value of 0 represent the current year, positive values the years after the current one (+1 = next year etc.), negative values the years before the current one (-1 = previous year and so on). For example

 gn4:story[fn:inRelativeYears(@modifiedDate,0,1)]

returns all the stories that have been modified from the beginning of the current year (‘0’) to the beginning of next year (‘1’).

The test includes the lower bound and excludes the upper one. Each day is considered as starting at the time specified by the ‘StartDayTime’ value in the GlobalConfig configuration – by default midnight. The years start date-times are in the local time of the client executing the query. This means that if today is August 20th, 2012, ‘StartDayTime’ in GlobalConfig is ‘6:00:00’ (6 AM) and the client time-zone is US Easter Standard (UTC-5), the example above is equivalent to

 @modifiedDate >= ‘2012-01-01T11:00:00Z’ and @modifiedDate < ‘2013-01-01T11:00:00Z’

where the ‘11:00:00Z’ comes from converting 6 AM from US Eastern Time to UTC.

Use ‘infinite’ values to generate open-ended tests – i.e. all date-time before or after a certain relative date. For example

 gn4:story[fn:inRelativeYears(@modifiedDate,-1 div 0,0)]

returns all the stories modified before the current year because ‘-1 div 0’ returns negative infinite, so the ‘from’ part of the condition is always true, and the actual test is just

 @modifiedDate < ‘2012-01-01T11:00:00Z’

Similarly, to find all tasks with a due date after the end of this year use

 gn4:task[fn:inRelativeYears(@dueDate,1,1 div 0)]

that is equivalent to a test

 @dueDate >= ‘2013-01-01T11:00:00Z’

because ‘1 div 0’ returns positive infinite, so the ‘to’ part of the condition is always true.

If expr is a node-set the function returns true if any of the nodes matches the condition, so that the query

gn4:story[fn:inRelativeYears(gn4:objs/gn4:ref/nav:refObject/gn4:*/@modifiedDate,0,1)]

returns all the stories that have at least a related objects that has been modified this year.

fn:inRelativeYearsZ(expr,fromexpr,toexpr)

A variant of the ‘inRelativeYears()’ function that uses UTC times – i.e. that does not convert from the client time-zone to UTC. For example

 gn4:story[fn:inRelativeYearsZ(@modifiedDate,0,1)]

if today is August 20th, 2012 and ‘StartDayTime’ in GlobalConfig is ‘6:00:00’ (6 AM), generates this test:

 @modifiedDate >= ‘2012-01-01T06:00:00Z’ and @modifiedDate < ‘2013-01-01T06:00:00Z’

regardless of the client time-zone

fn:inRelativeYears0(expr,fromexpr,toexpr)

A variant of the ‘inRelativeYears()’ function that does not uses the start day time – i.e. that consider always the days as beginning at midnight. For example

 gn4:story[fn:inRelativeYears0(@modifiedDate,0,1)]

if today is August 20th, 2012 and the client time-zone is US Easter Standard (UTC-5), generates this test:

 @modifiedDate >= ‘2012-01-01T05:00:00Z’ and @modifiedDate < ‘2013-01-01T05:00:00Z’

regardless of the value of ‘StartDayTime’ in GlobalConfig

fn:inRelativeYearsZ0(expr,fromexpr,toexpr)

A variant of the ‘inRelativeYears()’ function that uses UTC times and does not uses the start day time. For example

 gn4:story[fn:inRelativeYearsZ0(@modifiedDate,0,1)]

if today is August 20th, 2012, generates this test:

 @modifiedDate >= ‘2012-01-01T00:00:00Z’ and @modifiedDate < ‘2013-01-01T00:00:00Z’

regardless of the client time-zone and of the value of ‘StartDayTime’ in GlobalConfig

fn:inRelativeMonths (expr,fromexpr,toexpr)

Checks that the date-time or date represented by the expr string is within fromexpr and toexpr months relative to the current one. For example executing

 gn4:story[fn:inRelativeMonths(@modifiedDate,-1,0)]

returns all stories modified from ‘-1’ = beginning of the previous month to ‘0’ = beginning of the current month  – i.e. if today is August 20th, 2012 returns all stories modified in July 2012.

See the explanation of fn:inRelativeYears() above for details about the handling of time-zones, the start of the day hour and the use of infinite values to generate open-ended tests.

As for fn:inRelativeYears() if expr is a node-set the function returns true if any of the nodes matches the condition.

fn:inRelativeMonthsZ(expr,fromexpr,toexpr)

A variant of the ‘inRelativeMonths()’ function that uses UTC times. See explanation of the similar function ‘inRelativeYearsZ()’ above.

fn:inRelativeMonths0(expr,fromexpr,toexpr)

A variant of the ‘inRelativeMonths()’ function that does not uses the start day time. See explanation of the similar function ‘inRelativeYears0()’ above.

fn:inRelativeMonthsZ0(expr,fromexpr,toexpr)

A variant of the ‘inRelativeMonths()’ function that uses UTC times and does not uses the start day time. See explanation of the similar function ‘inRelativeYearsZ0()’ above.

fn:inRelativeWeeks (expr,fromexpr,toexpr)

Checks that the date-time or date represented by the expr string is within fromexpr and toexpr weeks relative to the current one. For example executing

 gn4:story[fn:inRelativeWeeks(@modifiedDate,0,2)]

returns all stories modified from ‘0’ = beginning of this week to ‘2’ = beginning of the week after the next  – i.e. if the first day of the week is Sunday and today is Monday August 20th, 2012 the query returns all stories modified on or after Sunday, August 19th 2012 and before Sunday, September 2nd 2012.

The first day of the week is the one specified in the locale settings of the client.

See the explanation of fn:inRelativeYears() above for details about the handling of time-zones, the start of the day hour and the use of infinite values to generate open-ended tests.

As for fn:inRelativeYears() if expr is a node-set the function returns true if any of the nodes matches the condition.

fn:inRelativeWeeksZ(expr,fromexpr,toexpr)

A variant of the ‘inRelativeWeeks()’ function that uses UTC times. See explanation of the similar function ‘inRelativeYearsZ()’ above.

fn:inRelativeWeeks0(expr,fromexpr,toexpr)

A variant of the ‘inRelativeWeeks()’ function that does not uses the start day time. See explanation of the similar function ‘inRelativeYears0()’ above.

fn:inRelativeWeeksZ0(expr,fromexpr,toexpr)

A variant of the ‘inRelativeWeeks()’ function that uses UTC times and does not uses the start day time. See explanation of the similar function ‘inRelativeYearsZ0()’ above.

fn:inRelativeDays (expr,fromexpr,toexpr)

Checks that the date-time or date represented by the expr string is within fromexpr and toexpr days relative to the current one. For example executing

 gn4:story[fn:inRelativeDays(@modifiedDate,-2,-1)]

returns all stories modified from ‘-2’ = beginning of two days ago to ‘-1’ = beginning of yesterday  – i.e. if today is August 20th, 2012 the query returns all stories modified on August 18th 2012.

See the explanation of fn:inRelativeYears() above for details about the handling of time-zones, the start of the day hour and the use of infinite values to generate open-ended tests.

As for fn:inRelativeYears() if expr is a node-set the function returns true if any of the nodes matches the condition.

fn:inRelativeDaysZ(expr,fromexpr,toexpr)

A variant of the ‘inRelativeDays()’ function that uses UTC times. See explanation of the similar function ‘inRelativeYearsZ()’ above.

fn:inRelativeDays0(expr,fromexpr,toexpr)

A variant of the ‘inRelativeDays()’ function that does not uses the start day time. See explanation of the similar function ‘inRelativeYears0()’ above.

fn:inRelativeDaysZ0(expr,fromexpr,toexpr)

A variant of the ‘inRelativeDays()’ function that uses UTC times and does not uses the start day time. See explanation of the similar function ‘inRelativeYearsZ0()’ above.

fn:inRelativeHours (expr,fromexpr,toexpr)

Checks that the date-time represented by the expr string is within fromexpr and toexpr hours relative to the current one. For example executing

 gn4:story[fn:inRelativeHours(@modifiedDate,0,6)]

returns all stories modified from ‘0’ = beginning of the current hour to ‘6’ = beginning of the sixth hour from now  – i.e. if today is August 20th, 2012 at 5:40 PM  local time the query returns all stories modified on August 20th 2012 between 5:00 PM (included) and 11 PM (excluded) local time.

See the explanation of fn:inRelativeYears() above for details about the use of infinite values to generate open-ended tests.

As for fn:inRelativeYears() if expr is a node-set the function returns true if any of the nodes matches the condition.

fn:inRelativeHoursZ (expr,fromexpr,toexpr)

A variant of the ‘fn:inRelativeHours()’ function that uses UTC times. For example executing

 gn4:story[fn:inRelativeHoursZ(@modifiedDate,0,6)]

if today is August 20th, 2012 at 3:40 PM  UTC the query returns all stories modified on August 20th 2012 between 3:00 PM (included) and 9 PM (excluded) UTC.

fn:inRelativeMinutes(expr,fromexpr,toexpr)

Checks that the date-time represented by the expr string is within fromexpr and toexpr minutes relative to the current one. For example executing

 gn4:story[fn:inRelativeMinutes(@modifiedDate,0,15)]

returns all stories modified from ‘0’ = beginning of the current minute to ‘15’ = fifteen minutes from now  – i.e. if today is August 20th, 2012 at 5:40 PM  local time the query returns all stories modified on August 20th 2012 between 5:40 PM (included) and 5:55 PM (excluded) local time.

See the explanation of fn:inRelativeYears() above for details about the use of infinite values to generate open-ended tests.

As for fn:inRelativeYears() if expr is a node-set the function returns true if any of the nodes matches the condition.

fn:inRelativeMinutesZ(expr,fromexpr,toexpr)

A variant of the ‘fn:inRelativeMinutes()’ function that uses UTC times.  For example executing

 gn4:story[fn:inRelativeMinutes(@modifiedDate,0,15)]

if today is August 20th, 2012 at 3:40 PM  UTC time the query returns all stories modified on August 20th 2012 between 3:40 PM (included) and 3:55 PM (excluded) UTC.

fn:inDays (expr,fromexpr,toexpr)

Checks that the date-time or date represented by the expr string is within the fromexpr (included) and toexpr (excluded) days. fromexpr  and toexpr must be strings or string parameters in the format YYYY-MM-DD  - to use the client time zone – or YYYY-MM-DDZ – to use UTC.  For example

 gn4:story[fn:inDays(@creationDate,'2012-08-28','2012-08-29')]

returns all the stories that have been created on August 28th, 2012 – client local time, whereas

 gn4:story[fn:inDays(@creationDate,'2012-08-28Z','2012-08-29Z')]

returns all the stories that have been created on August 28th, 2012 UTC time.

Each day is considered as starting at the time specified by the ‘StartDayTime’ value in the GlobalConfig configuration – by default midnight. If for example ‘StartDayTime’ is set to 6 AM the last example generates this test:

 @modifiedDate >= ‘2012-08-28T06:00:00Z’ and @modifiedDate < ‘2012-08-29T06:00:00Z’

Use empty strings for fromexpr or toexpr to generate open-ended tests, for example

 gn4:story[fn:inDays(@creationDate,'2012-08-28','')]

returns all the stories that have been created on or after August 28th, 2012, and

 gn4:story[fn:inDays(@creationDate,'','2012-08-29')]

returns all the stories that have been created before August 29th, 2012.

fn:inDays0 (expr,fromexpr,toexpr)

A variant of the ‘inDays ()’ function that does not uses the start day time – i.e. that consider always the days as beginning at midnight. For example

 gn4:story[fn:inDays0(@creationDate,'2012-08-28Z','2012-08-29Z')]

generates this test:

 @modifiedDate >= ‘2012-08-28T00:00:00Z’ and @modifiedDate < ‘2012-08-29T00:00:00Z’

regardless of the value of ‘StartDayTime’ in GlobalConfig