p:count (3.0) 

Count the number of documents.

Summary

<p:declare-step type="p:count">
  <input port="source" primary="true" content-types="any" sequence="true"/>
  <output port="result" primary="true" content-types="application/xml" sequence="false"/>
  <option name="limit" as="xs:integer" required="false" select="0"/>
</p:declare-step>

The p:count step counts the number of documents appearing on its source port and returns an XML document on its result port containing that number.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

any

true

The sequence of documents to count.

result

output

true

application/xml

false

An XML document consisting of a single <c:result> element containing the number of documents on the source port, or the limit set by the limit option (the c prefix here is bound to the http://www.w3.org/ns/xproc-step namespace).

Example: <c:result xmlns:c="http://www.w3.org/ns/xproc-step">3</c:result>

Options:

Name

Type

Req?

Default

Description

limit

xs:integer

false

0

If the value of this option is greater than 0, the p:count will count at most that many documents. See the Limiting the count example.

Since p:count will stop processing documents on its source when this limit is reached, this provides an efficient mechanism to discover if a sequence consists of more than X documents.

Description

The p:count step simply counts the number of documents appearing on its source port. It emits a very simple document on its result port containing this number, wrapped in a <c:result> element (the c prefix here is bound to the http://www.w3.org/ns/xproc-step namespace). For example: <c:result>3</c:result>.

Using this step you can find out how many documents are flowing through your pipeline and make decision based on that number. For instance: stop processing if there are too many.

There is another way of doing this, see the Alternative to p:count example. This is probably easier, because the required count is directly in a variable and the flow of documents in the pipeline is not interrupted. Which method (p:count or a count variable) is faster is hard to say and probably dependent on the XProc processor used. If this matters to you, you’ll have to do some experiments.

Examples

Basic usage

The following pipeline produces a sequence of 3 documents and counts these:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source" sequence="true">
    <p:document href="in1.xml"/>
    <p:document href="in1.xml"/>
    <p:document href="in1.xml"/>
  </p:input>
  <p:output port="result"/>

  <p:count/>

</p:declare-step>

Result document:

<c:result xmlns:c="http://www.w3.org/ns/xproc-step">3</c:result>

Using this count to make a decision could be done as follows:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source" sequence="true">
    <p:document href="in1.xml"/>
    <p:document href="in1.xml"/>
    <p:document href="in1.xml"/>
  </p:input>
  <p:output port="result"/>

  <p:count/>

  <p:choose>
    <p:when test="number(.) eq 3">
      <p:identity>
        <p:with-input>
          <count-is-exactly-3/>
        </p:with-input>
      </p:identity>
    </p:when>
    <p:otherwise>
      <p:identity>
        <p:with-input>
          <count-is-not-3/>
        </p:with-input>
      </p:identity>
    </p:otherwise>
  </p:choose>


</p:declare-step>

Result document:

<count-is-exactly-3/>

Limiting the count

The following pipeline produces a sequence of 3 documents and counts these with a limit of 1:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source" sequence="true">
    <p:document href="in1.xml"/>
    <p:document href="in1.xml"/>
    <p:document href="in1.xml"/>
  </p:input>
  <p:output port="result"/>

  <p:count limit="1"/>

</p:declare-step>

Result document:

<c:result xmlns:c="http://www.w3.org/ns/xproc-step">1</c:result>

Alternative to p:count

You don’t need p:count to count documents. An alternative is to declare a variable that gets its value by counting the size of the collection of documents flowing through it:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source" sequence="true">
    <p:document href="in1.xml"/>
    <p:document href="in1.xml"/>
    <p:document href="in1.xml"/>
  </p:input>
  <p:output port="result"/>

  <p:variable name="count" select="count(collection())" collection="true"/>

  <p:identity>
    <p:with-input>
      <document-count>{$count}</document-count>
    </p:with-input>
  </p:identity>

</p:declare-step>

Result document:

<document-count>3</document-count>

The p:identity after the variable declaration is only there for demonstration purposes: to show the value of the count. In a real pipeline you would probably follow it up with a <p:if> or <p:choose>/<p:when>/<p:otherwise> and make some decision based on the document count.

Additional details

  • No document-properties from the documents on the source port survive. The resulting document has a content-type document-property set to application/xml and no base-uri document-property.

Reference information

This description of the p:count step is for XProc version: 3.0. This is a required step (an XProc 3.0 processor must support this).

The formal specification for the p:count step can be found here.

The p:count step is part of categories:

The p:count step is also present in version: 3.1.