---

2.6.11 Documents

A dictionary may include an arbitrary number of lines of explanatory text, called the dictionary’s documents. For compatibility, document lines have a fixed width, and lines that are not exactly this width are truncated or padded with spaces as necessary to bring them to the correct width.

PSPP users can use the DOCUMENT (see DOCUMENT in PSPP Users Guide), ADD DOCUMENT (see ADD DOCUMENT in PSPP Users Guide), and DROP DOCUMENTS (see DROP DOCUMENTS in PSPP Users Guide) commands to manipulate documents.

Macro: int DOC_LINE_LENGTH ¶

The fixed length of a document line, in bytes, defined to 80.

The following functions work with whole sets of documents. They accept or return sets of documents formatted as null-terminated strings that are an exact multiple of DOC_LINE_LENGTH bytes in length.

Function: const char * dict_get_documents (const struct dictionary *dict) ¶

Returns the documents in dict, or a null pointer if dict has no documents.

Function: void dict_set_documents (struct dictionary *dict, const char *new_documents) ¶

Sets dict’s documents to new_documents. If new_documents is a null pointer or an empty string, then dict’s documents are cleared. The caller retains ownership of new_documents.

Function: void dict_clear_documents (struct dictionary *dict) ¶

Clears the documents from dict.

The following functions work with individual lines in a dictionary’s set of documents.

Function: void dict_add_document_line (struct dictionary *dict, const char *content) ¶

Appends content to the documents in dict. The text in content will be truncated or padded with spaces as necessary to make it exactly DOC_LINE_LENGTH bytes long. The caller retains ownership of content.

If content is over DOC_LINE_LENGTH, this function also issues a warning using msg. To suppress the warning, enclose a call to one of this function in a msg_disable/msg_enable pair.

Function: size_t dict_get_document_n_lines (const struct dictionary *dict) ¶

Returns the number of line of documents in dict. If the dictionary contains no documents, returns 0.

Function: void dict_get_document_line (const struct dictionary *dict, size_t idx, struct string *content) ¶

Replaces the text in content (which must already have been initialized by the caller) by the document line in dict numbered idx, which must be less than the number of lines of documents in dict. Any trailing white space in the document line is trimmed, so that content will have a length between 0 and DOC_LINE_LENGTH.