The Built-in tolog Predicates

Reference Documentation

Published by: Ontopia Date: 2013-08-01 Version: 5.3.0

Table of contents

• 1. Introduction
• 2. The general predicates
• 3. The Topic Maps predicates
• 4. External fulltext predicates
• 5. The string module

1. Introduction

The tolog query language has a number of predefined predicates which are part of the language itself. Some of these exist in order to allow access to various parts of the Topic Maps model, while others exist because they provide generally useful query functionality. This document provides a reference to all predicates that are part of the language.

This document is quite difficult to read without a thorough understanding of the Topic Maps model. It is recommended to study the Topic Maps Data Model.

2. The general predicates

These are predicates that are built directly into the language without being part of any specific module.

Index

• /=
• <
• <=
• =
• >
• >=
• coalesce

/=

Compares two values to ensure they are different.

Parameters

Description

The predicate is true when the two values are different. For strings this means the values must be different when compared character by character case-sensitively, including all whitespace and special characters. For topic map objects this means they must be different objects. Null is different from everything except itself.

Note that this predicate cannot produce new rows in the query or new values in any columns; it can only remove rows.

Find all association types with more than two roles

select $TYPE from
  association-role($ASSOC, $ROLE1),
  association-role($ASSOC, $ROLE2), $ROLE1 /= $ROLE2,
  association-role($ASSOC, $ROLE3), $ROLE3 /= $ROLE1, $ROLE3 /= $ROLE2
  type($ASSOC, $TYPE)?

This query will first find all association roles and their associations, then repeat each row once for each role in the same association, and finaly remove the rowws where the two roles are the same. The rest of the query is similar, except that the final predicate finds the type of the association.

<

Compares two values to ensure the first is less than the second.

Parameters

Description

The predicate is true when the first value is less than the second. Note that this predicate will never bind any values, nor produce any new result rows. Like /= it can only filter out matches.

Find all operas premiered before 1900

premiere-date($OPERA, $DATE),
$DATE < "1900"?

<=

Compares two values to ensure the first is less than or equal to the second.

Parameters

Description

The predicate is true when the first value is less than or equal to the second. Note that this predicate will never bind any values, nor produce any new result rows. Like /= it can only filter out matches.

Find all operas premiered before 1900

premiere-date($OPERA, $DATE),
$DATE <= "1900"?

=

Compares two values to ensure they are equal.

Parameters

Description

The predicate is true when the two values are equal using the same comparison rule as /=. Note that at least one of the values must be present. (That is, it cannot compare two unbound variables.)

Note that unlike /= this predicate can produce new values in columns.

Find all operas premiered on a given date

premiere-date($OPERA, $DATE),
$DATE = "1870 (22 Feb)"?

This query will first set $DATE to the given date, then find all operas premiered on that date. (Thanks to the query optimizer; if that is turned off the query will be rather less efficient, if not really slow.)

>

Compares two values to ensure the first is greater than the second.

Parameters

Description

The predicate is true when the first value is greater than the second. Note that this predicate will never bind any values, nor produce any new result rows. Like /= it can only filter out matches.

Find all operas premiered after 1900

premiere-date($OPERA, $DATE),
$DATE > "1900"?

>=

Compares two values to ensure the first is greater than or equal to the second.

Parameters

Description

The predicate is true when the first value is greater than or equal to the second. Note that this predicate will never bind any values, nor produce any new result rows. Like /= it can only filter out matches.

Find all operas premiered after 1900

premiere-date($OPERA, $DATE),
$DATE >= "1900"?

coalesce

This predicate is often used to assign fallback or default values to variables. If the first argument is unbound then it is bound to the first non-null argument following it. If the first argument is bound then it will be compared to the first non-null argument following it.

Parameters

Description

The coalesce predicate is often used to assign default values, and is quite often used with optional clauses as can be seen in the example below:

Find all operas and their illustrations. Assign a default illustration to the operas that do not have one already.

select $OPERA, $ILLUSTRATION from 
instance-of($OPERA, opera), { illustration($OPERA, $I) }, 
coalesce($ILLUSTRATION, $I, "http://example.org/nicephoto.jpg")?

3. The Topic Maps predicates

Index

• association
• association-role
• base-locator
• datatype
• direct-instance-of
• instance-of
• item-identifier
• object-id
• occurrence
• reifies
• resource
• role-player
• scope
• subject-identifier
• subject-locator
• topic
• topicmap
• topic-name
• type
• value
• value-like
• variant

association

Used to verify that a value is actually an association.

Parameters

Description

This predicate is true if the parameter is an association, and false if it is not. If used with an unbound variable it will produce all associations in the topic map.

Counting the associations in the topic map

select count($ASSOC) from
  association($ASSOC)?

The above query counts the associations in the topic map by first producing all of them, then counting them.

Finding all association types

select $TYPE from
  association($ASSOC), type($ASSOC, $TYPE)?

The above query first finds all associations in the topic map, then finds the type of each, and finally reduces the result to only the types.

association-role

Used to query the relationship between associations and the roles they contain.

Parameters

Description

This predicate is true for a given association and association role if the association role is contained in the role. Can be used to find the association a role belongs to, all roles in an association, or all roles in all associations.

Finding all unary association types

select $TYPE from
  association-role($ASSOC, $ROLE1),
  not(association-role($ASSOC, $ROLE2), $ROLE2 /= $ROLE1),
  type($ASSOC, $TYPE)?

The above query first finds all roles in all associations, then removes the associations where there exists another role in the same association, finds the type of the association, and projects us down to the list of types. (So for any given type in the result there could be associations that are instances of it which are not unary. This can be solved, but is more involved.)

Finding all associations between two topics

select $ASSOC from
  role-player($ROLE1, topic1),
  association-role($ASSOC, $ROLE1),
  association-role($ASSOC, $ROLE2),
  role-player($ROLE2, topic2)?

The above query first finds all roles played by topic1, then finds the association of the role, then finds all other roles in the same association, then removes all rows where the second role isn't played by topic2, and finally projects us down to just the associations.

base-locator

Used to find the base locator of the topic map.

Parameters

Description

This predicate is true for a single value: the base locator of the topic map, if it has one.

Finding the base locator of the topic map

base-locator($LOC)?

This will return the base locator of the topic map, if it has one. For a topic map loaded from a file this will be the URI of the file, while for an RDBMS topic map this will a JDBC URI pointing to the database.

datatype

Finds the datatype of an occurrence or variant name.

Parameters

Description

The predicate is true when the object has the datatype as its datatype URI. The predicate can be used to find the datatype of an object, all objects with a specific datatype, or all object/datatype combinations.

Find all occurrences with integer values

select $OCC from
  occurrence($TOPIC, $OCC),
  datatype($OCC, "http://www.w3.org/2001/XMLSchema#integer")?

This query will find all occurrences in the topic map, then remove the ones whose datatype is not the XML Schema integer datatype.

direct-instance-of

Used to query the types topic are instances of; usually to find the most specific types of the topics.

Parameters

Description

This predicate is true when the instance topic is explicitly defined by the topic map as being an instance of the type topic. (Contrast with instance-of, where this need not be said explicitly.)

Finding all topic types in the topic map

select $TYPE from
  direct-instance-of($INSTANCE, $TYPE)?

This will find all instance-type pairs in the topic map, then cut away the instances, leaving only the types.

Finding persons and their types

  instance-of($PERSON, person),
  direct-instance-of($PERSON, $TYPE)?

In the opera.ltm topic map this query would first find all instances of the type person (that is, the instances of all subtypes of person, such as composers, librettists, writers, characters, and so on), and then find the types actually given to the topics in the topic map. The result would be something like the table shown below.

Table 3.1. Example query result

instance-of

Used to query the types topic are instances of; takes the superclass-subclass association into account.

Parameters

Description

This predicate is true when the instance topic is an instance of the type topic. This can be either directly, or instance can be an instance of a type that is a subtype of type. Note that for this to work the superclass-subclass association type must use the XTM 1.0 PSIs. (Contrast with direct-instance-of, where this needs to be said explicitly in the topic map, and the superclass-subclass associations are ignored.)

Finding all abstract topic types in the topic map

select $TYPE from
  instance-of($INST, $TYPE),
  not(direct-instance-of($INST, $TYPE))?

This will find all type-instance pairs, but then remove pairs where it is explicitly said in the topic map that $INST is an instance of $TYPE. This will leave us with only the types which have no direct instances, that is, where all instances are instances of one of the subtypes. Such types are often called abstract types. One example of this in the Italian Opera topic map is "place". There are lots of places, such as cities, regions, and countries, but they are always defined as instances of one of the more specific types, never as just "place".

item-identifier

Used to query the item identifiers of a topic map construct.

Parameters

Description

The predicate is true when the locator is a item identifier for the object. This is useful for finding the item identifiers of a particular object, for looking up the object that has a particular item identifier, or for listing all item identifiers in the topic map.

Find all non-topics which have item identifiers

select $OBJECT from
  item-identifier($OBJECT, $LOC),
  not(topic($OBJECT))?

This query will, if run against a topic map that was loaded from an XTM file, find all objects in the topic map other than topics which had id attributes. It works by first finding all objects which have item identifiers (and the item identifiers), then remove the rows where the object is a topic.

object-id

Used to query object IDs of topic map objects.

Parameters

Description

This predicate is true when the id is the object ID of the object. It can be used to find the object ID of a specific object, to find the object that has a specific ID, or to find all object IDs in the topic map.

Note that the object ID is not the same as the symbolic ID used in XTM or LTM files; for this, see the item-identifier predicate.

Finding the object ID of Puccini

object-id(puccini, $ID)?

This query will produce the object ID after having looked up the Puccini topic. Note that the ID will not be "puccini", but rather something like "2532".

Finding the object with ID 241

object-id($OBJECT, "241")?

What this will return for any given topic map can't be predicted (try it in the Omnigator!), but in any non-trivial topic map it will find something.

occurrence

Used to query the topic-occurrence relationship.

Parameters

Description

This predicate is true when the occurrence is an occurrence of the topic. This is useful for finding the topic an occurrence belongs to, or all occurrences of a topic, or just all occurrences in the topic map.

Finding all occurrences of a topic

select $TYPE, $VALUE from
  occurrence(topic, $OCC),
  type($OCC, $TYPE),
  { resource($OCC, $VALUE) | value($OCC, $VALUE) }?

This query will first find all occurrences of the topic, then the type of the occurrence, then either the URI of the occurrence or its string value, and finally make a (type, value) table of the results.

Finding all persons born on a specific date

select $PERSON from
  occurrence($PERSON, $OCC),
  type($OCC, date-of-birth),
  value($OCC, "1973-12-25")?

This query will first find all occurrences of all topics, then remove the occurrences that are not date-of-birth occurrences, and then remove all occurrences that don't have "1973-12-25" as their value, and finally we project down to only the topics that have these occurrences.

Note that the easiest way to do this is to use a dynamic occurrence predicate:

Finding all persons born on a specific date

date-of-birth($PERSON, "1973-12-25")?

reifies

Used to query the relationship between a reifying topic and the thing it reifies.

Parameters

Description

This predicate is true when the reifier is an topic that reifies the reified. This is useful when you use reification and want to navigate from the name, occurrence, or association to the reifying topic (or vice versa).

Finding the topic reifying the topic map

select $TOPIC from
  topicmap($TM), reifies($TOPIC, $TM)?

This query finds the topic map first, then the topic reifying it (if there is one).

resource

Used to find the URI of an occurrence or variant name, or to find the occurrences and variant names that have a particular URI.

Parameters

Description

The predicate is true when the occurrence or variant has the locator as its URI value. This is useful for looking up all occurrences/variants with a specific URI, or finding the URI of a variant/occurrence, or all occurrences/variants which have URI values.

Find Ontopia's home page

select $URI from
  occurrence(ontopia, $OCC),
  type($OCC, homepage),
  resource($OCC, $URI)?

This query will find all occurrences of the topic ontopia, then remove the ones that are not homepage occurrences, and finally find the URIs of the ones remaining.

role-player

Used to find the topic playing a specific role, or all the roles played by a topic.

Parameters

Description

The predicate is true when the topic plays the given role. This is useful for finding all roles played by a topic, or the topic playing a particular role.

Finding all associations between two topics

select $ASSOC from
  role-player($ROLE1, topic1),
  association-role($ASSOC, $ROLE1),
  association-role($ASSOC, $ROLE2),
  role-player($ROLE2, topic2)?

The above query first finds all roles played by topic1, then finds the association of the role, then finds all other roles in the same association, then removes all rows where the second role isn't played by topic2, and finally projects us down to just the associations.

scope

Used to query the scopes of topic characteristics.

Parameters

Description

The predicate is true when the theme is a topic in the scope of the scoped thing. This is useful for finding topic characteristics in a particular scope, finding the scope of a topic characteristic, and so on.

Finding the English names of all operas

select $NAME from
  instance-of($OPERA, opera),
  topic-name($OPERA, $TNAME),
  scope($TNAME, english),
  value($TNAME, $NAME)?

The above query first finds all operas, then all topic names (or base names) of the operas, then removes the names that are not in the English scope, and finally finds the string value of the remaining names.

subject-identifier

Used to query the subject identifiers of a topic. (A subject identifier is the URI of a subject identifier.)

Parameters

Description

The predicate is true when the locator is a subject identifier for the topic. This is useful for finding the subject identifiers of a particular topic, for looking up the topic that has a particular subject identifier, or for listing all subject identifiers in the topic map.

Find all topics which have more than one subject identifier

select $TOPIC from
  subject-identifier($TOPIC, $LOC1),
  subject-identifier($TOPIC, $LOC2),
  $LOC1 /= $LOC2?

The query will first find all subject identifiers in the topic map and the topics that have them, then for each topic find other subject identifiers belonging to it (again), and finally remove the rows where the two subject identifiers are the same.

subject-locator

Used to query the subject locator of a topic. (A subject locator is the URI of the information resource that the topic represents.)

Parameters

Description

The predicate is true when the locator is a subject locator for the topic. This is useful for finding the subject locator of a particular topic, for looking up the topic that has a particular subject locator, or for listing all subject locators in the topic map.

Find all topics which represent an occurrence

select $TOPIC from
  occurrence($OTHERTOPIC, $OCC),
  resource($OCC, $LOC),
  subject-locator($TOPIC, $LOC)?

This query will find all topics which represent information resources that are occurrences of some topic in the topic map. It starts by finding all occurrences, then removes all occurrences which don't have a URI and at the same time notes the URI, and finally finds all topics which have this URI as their subject locator.

topic

Used to verify that an object is a topic or to find all topics in the topic map.

Parameters

Description

The predicate is true when the topic is a topic. Can be used to find all topics or to verify that some object is a topic.

Count the topics in the topic map

select count($TOPIC) from
  topic($TOPIC)?

This query will find all topics in the topic map, then count them.

Find all topics which have no name

select $TOPIC from
  topic($TOPIC),
  not(topic-name($TOPIC, $NAME))?

This query will find all topics in the topic map, then remove the ones that have at least one name.

topicmap

Finds the topic map.

Parameters

Description

The predicate is true when the topicmap is the topic map itself. This is useful for finding the topic map.

Find the name of the topic map

select $VALUE from
  topicmap($TM),
  reifies($TMTOPIC, $TM),
  topic-name($TMTOPIC, $NAME),
  value($NAME, $VALUE)?

This query will first find the topic map, then the topic that reifies it (if any), then all names of that topic, then their string values.

topic-name

Queries the topic-name relationship.

Parameters

Description

The predicate is true when the topic has the name as a topic name. Note that name is not a string, but an object. To find the string value use the value predicate on the name object. (Example below.)

The predicate can be used to find all names of a topic, the topic that has a particular name, or to find all names in the topic map.

Find all topics named "Tosca"

select $TOPIC from
  topic-name($TOPIC, $NAME), value($NAME, "Tosca")?

This query will find all topic names in the topic map, then remove the ones whose string value is not "Tosca". Note that this will only find names that match exactly. For inexact matching, use value-like.

Find all topics which have no name

select $TOPIC from
  topic($TOPIC),
  not(topic-name($TOPIC, $NAME))?

This query will find all topics in the topic map, then remove the ones that have at least one name.

type

Queries the type of topic map objects (but not topics).

Parameters

Description

The predicate is true when the object has the type as its type. This can be used to find the type of an object, all objects of a specific type, or all types. This predicate does not take the superclass-subclass associations into account. Also note that for topics the instance-of and direct-instance-of predicates must be used.

Find all association types

select $TYPE from
  association($ASSOC),
  type($ASSOC, $TYPE)?

This query will first find all associations, then the type of each association, and finally produce just a list of the types.

value

Finds the string value of an object.

Parameters

Description

The predicate is true when the object has the value as its string value. Variant names and occurrences which have URIs have no string value, and so will not be matched by this predicate. The predicate can be used to find the string value of an object, all objects with a specific value, or all string values.

Find all topics named "Tosca"

select $TOPIC from
  topic-name($TOPIC, $NAME), value($NAME, "Tosca")?

This query will find all topic names in the topic map, then remove the ones whose string value is not "Tosca". Note that this will only find names that match exactly. For inexact matching, use value-like.

value-like

Performs a full-text search.

Parameters

Description

The predicate is true when the object has a string value which matches the query. This can be used to find topic names, variants, and occurrences matching a particular string. Note that the object found is not a topic, but a topic name, variant, or occurrence. The other predicates must be used to connect this to a topic.

Find all topics matching "tosca"

select $TOPIC from
  { topic-name($TOPIC, $NAME), value-like($NAME, "tosca") |
    occurrence($TOPIC, $OCC),  value-like($OCC,  "tosca") |
    topic-name($TOPIC, $TN), variant($TN, $V), value-like($V, "tosca")
    }?

This query will find all topics in the topic map matching the full-text query, whether the full-text query matches a topic name, variant, or occurrence.

Find default names matching "tosca"

select $NAME, $SCORE from
  topic-name($TOPIC, $NAME), not(scope($NAME, $SCOPE)),
  value-like($NAME, "tosca", $SCORE), $SCORE >= 0.50 ?

This query makes use of the optional third argument to the value-like predicate. The query finds all unconstrained topic names containing the pattern "tosca", and where the score value is greater than or equal to 0.50. The score value is also included in the projection.

variant

Queries the topic name-variant relationship.

Parameters

Description

The predicate is true when the variant is a variant of the topicname. Can be used to find all variants of a topic name, the topic name of a variant, or all variants.

Note that although XTM allows variants to nest within each other TMDM collapses this structure, and so that structure is not available to be queried in tolog.

Find all topics which have a sort name

select $TOPIC from
  topic-name($TOPIC, $NAME),
  variant($NAME, $VARIANT),
  scope($VARIANT, i"http://www.topicmaps.org/xtm/1.0/core.xtm#sort")?

This query will find all topic names in the topic map together with their topics, then all variants of the topic names, and finally removes the rows where the variant is not in the scope of the sort PSI defined by XTM 1.0.

4. External fulltext predicates

It is possible to extend tolog with external fulltext predicates by implementing the SearcherIF and SearchResultIF interfaces from the net.ontopia.topicmaps.query.spi package (see the API documentation for more information). If the class com.foo.MySearcher implements the SearcherIF interface, that class can be used in tolog as follows:

import "urn:x-java:com.foo.MySearcher" as fulltext
select $A, $RELEVANCE from
  fulltext:search($A, "CMS", $RELEVANCE)
order by $RELEVANCE?

The class name in the import URI is enough for Ontopia to instantiate the class and use it. The actual predicate name (fulltext:search in the example above) does not need to be significant. The name is passed into the SearcherIF class, but it is up to the SearcherIF class to attach significance to the predicate name. (One alternative is to always use a specific name, such as "search". Another is to use the name to select which full-text index to search.)

The parameters to external fulltext predicates are:

The SearcherIF implementation can produce values of different types, as indicated by the getValueType method. The table below explains the different possible values.

5. The string module

The URI of this module is http://psi.ontopia.net/tolog/string/. For usage, see the examples.

Index

• concat
• contains
• ends-with
• index-of
• last-index-of
• length
• starts-with
• substring
• substring-after
• substring-before
• translate

concat

Concatenates two strings.

Parameters

Description

The predicate is true when OUT is equal to IN1 immediately followed by IN2.

Concatenate two strings

import "http://psi.ontopia.net/tolog/string/" as str
  str:concat($NAME, "Ontopia", " AS")? 

This results in a single row with a single column containing the string "Ontopia AS".

contains

Tests whether a substring appears in another string.

Parameters

Description

The predicate is true when SUBSTRING appears at some position inside STR.

Find all PSIs defined by Ontopia

import "http://psi.ontopia.net/tolog/string/" as str
select $SI from
  subject-identifier($TOPIC, $SI),
  str:contains($SI, ".ontopia.net/")?

In the following topic map:

[subtype-of : hierarchical-relation-type = "Subtype of"
  @"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass"]
[supertype = "Supertype"
  @"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass"]
[subtype = "Subtype"
  @"http://www.topicmaps.org/xtm/1.0/core.xtm#subclass"]
[descr = "Description"
    @"http://psi.ontopia.net/occurrence/description"]

The result of this query would be one row, containing "http://psi.ontopia.net/occurrence/description".

ends-with

Tests whether a substring appears at the end of another string.

Parameters

Description

The predicate is true when SUFFIX appears as the last part of STR. In other words, if STR is the concatenation of some other string and SUFFIX the predicate is true.

Find all class PSIs

import "http://psi.ontopia.net/tolog/string/" as str
select $SI from
  subject-identifier($TOPIC, $SI),
  str:ends-with($SI, "class")?

In the following topic map:

[subtype-of : hierarchical-relation-type = "Subtype of"
  @"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass"]
[supertype = "Supertype"
  @"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass"]
[subtype = "Subtype"
  @"http://www.topicmaps.org/xtm/1.0/core.xtm#subclass"]
[descr = "Description"
    @"http://psi.ontopia.net/occurrence/description"]

The result of this query would be three rows, containing "http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass", "http://www.topicmaps.org/xtm/1.0/core.xtm#subclass", and "http://www.topicmaps.org/xtm/1.0/core.xtm#superclass".

index-of

Finds the first occurrence of a substring within another string.

Parameters

Description

The predicate is true when SEARCHFOR can be found inside IN starting at position OUT, and there are no occurrences of SEARCHFOR at a lower position inside IN. Position counts start at zero. This means that if the substring cannot be found at all the predicate does not match. Multiple occurrences of the substring later in the string are ignored.

Find the first occurrence of a word in a string.

import "http://psi.ontopia.net/tolog/string/" as str
  str:index-of($POS, "The first occurrence of 'the' in the sentence.", "the")? 

This results is a single row with a single column containing the position of the left-most occurrence of 'the' (all lowercase) in the sentence, i.e. 25.

last-index-of

Finds the last occurrence of a substring within another string.

Parameters

Description

The predicate is true when SEARCHFOR can be found inside IN starting at position OUT, and there are no occurrences of SEARCHFOR at a higher position inside IN. Position counts start at zero. This means that if the substring cannot be found at all the predicate does not match. Multiple occurrences of the substring earlier in the string are ignored.

Find all PSI namespaces in a topic map

import "http://psi.ontopia.net/tolog/string/" as str
select $PREFIX from
  subject-identifier($TOPIC, $SI),
  str:last-index-of($IX, $SI, "/"),
  str:substring($PREFIX, $SI, 0, $IX)
order by $PREFIX?

In the following topic map:

[subtype-of : hierarchical-relation-type = "Subtype of"
  @"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass"]
[supertype = "Supertype"
  @"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass"]
[subtype = "Subtype"
  @"http://www.topicmaps.org/xtm/1.0/core.xtm#subclass"]
[descr = "Description"
    @"http://psi.ontopia.net/occurrence/description"]

The result of this query would be two rows, containing "http://www.topicmaps.org/xtm/1.0/" and "http://psi.ontopia.net/occurrence/".

length

Finds the length of a string.

Parameters

Description

The predicate is true when STRING contains exactly LEN characters.

Find the topics with the longest names

import "http://psi.ontopia.net/tolog/string/" as str
select $TOPIC from
  topic-name($TOPIC, $TN),
  value($TN, $NAME),
  str:length($NAME, $LEN),
  not(topic-name($TOPIC2, $TN2),
      value($TN2, $NAME2),
      str:length($NAME2, $LEN2),
      $LEN < $LEN2)?

This query will find the topic with the longest name, or almost. What it in fact will do is to find all topics for which there is no topic with a longer name. This means that if, say, three topics all have names 26 characters long, and no topics have longer names, then all those three topics will be found.

starts-with

Tests whether a substring appears at the beginning of another string.

Parameters

Description

The predicate is true when PREFIX appears inside STR starting at position 0.

Find all PSIs defined by Ontopia

import "http://psi.ontopia.net/tolog/string/" as str
select $SI from
  subject-identifier($TOPIC, $SI),
  str:starts-with($SI, "http://psi.ontopia.net/")?

In the following topic map:

[subtype-of : hierarchical-relation-type = "Subtype of"
  @"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass"]
[supertype = "Supertype"
  @"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass"]
[subtype = "Subtype"
  @"http://www.topicmaps.org/xtm/1.0/core.xtm#subclass"]
[descr = "Description"
    @"http://psi.ontopia.net/occurrence/description"]

The result of this query would be one row, containing "http://psi.ontopia.net/occurrence/description".

substring

Extract part of a string.

Parameters

Description

The predicate is true when OUT is equal to the substring of STR starting at position FROM and ending at position TO (non-inclusive). If TO is not given, the substring extends to the end of the string. All position counts are zero-based.

Find all PSI namespaces in a topic map

import "http://psi.ontopia.net/tolog/string/" as str
select $PREFIX from
  subject-identifier($TOPIC, $SI),
  str:last-index-of($IX, $SI, "/"),
  str:substring($PREFIX, $SI, 0, $IX)
order by $PREFIX?

This query would produce all PSI namespaces used in a given topic map.

substring-after

Extract part of a string after the first occurrence of a substring.

Parameters

Description

The predicate is true when OUT is equal to the substring of STR after the first occurrence of SUB within STR. If there are no occurrences of SUB the predicate is false.

Get month and day

import "http://psi.ontopia.net/tolog/string/" as str
select $DATE from
  str:substring-after($DATE, "2007-03-12", "-")?

This query would produce 03-12.

substring-before

Extract part of a string before the first occurrence of a substring.

Parameters

Description

The predicate is true when OUT is equal to the substring of STR before the first occurrence of SUB within STR. If there are no occurrences of SUB the predicate is false.

Get month and day

import "http://psi.ontopia.net/tolog/string/" as str
select $DATE from
  str:substring-before($DATE, "2007-03-12", "-")?

This query would produce 2007.

translate

Replace and/or delete characters in one string. Often used to remove whitespace or do case normalization.

Parameters

Description

The predicate builds a translation table where the first character in FROM maps to the first character in TO (and so on). This is the basic function performed by the predicate.

The predicate is really a mix of the XPath translate function and the Python translate function, turned into a predicate. If the DELETE parameter is provided it behaves like the Python function, and if not it behaves like the XPath function.

That is, if the DELETE is not present, then the predicate translates characters as specified by the translation table, but any characters for which no mapping has been defined will be deleted. Characters in the FROM string for which there are no corresponding characters in the TO string will map to themselves (that is, if FROM is longer than TO). Conversely, if TO is longer than FROM any excess characters in TO will be ignored.

Lowercasing

import "http://psi.ontopia.net/tolog/string/" as str
select $OUT from
  str:translate($OUT,
    "Addis Abeba (12)",
    "ABCDEFGHIJKLMNOPQRSTUVXYZabcdefghijklmnopqrstuvxyz ",
    "abcdefghijklmnopqrstuvxyzabcdefghijklmnopqrstuvxyz ")?

The example above produces "addis abeba " as the output. If we remove the space at the end of the FROM string the result is "addisabeba".

If the DELETE is present, then the predicate translates characters as specified by the translation table and any characters for which no mapping has been defined will be mapped to themselves. Any characters in the DELETE string will be deleted, of course. If FROM and TO are of different lengths the effect is the same as specified above when DELETE is not present.

Lowercasing

import "http://psi.ontopia.net/tolog/string/" as str
select $OUT from
  str:translate($OUT,
    "Addis Abeba (12)",
    "ABCDEFGHIJKLMNOPQRSTUVXYZabcdefghijklmnopqrstuvxyz",
    "abcdefghijklmnopqrstuvxyzabcdefghijklmnopqrstuvxyz",
    "()")?

The example above produces "addis abeba 12" as the output.