+@c PSPP - a program for statistical analysis.
+@c Copyright (C) 2019 Free Software Foundation, Inc.
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+@c A copy of the license is included in the section entitled "GNU
+@c Free Documentation License".
+@c
+
@node Basic Concepts
@chapter Basic Concepts
@func{value_destroy} are actually required for the given @var{width}.
@end deftypefun
-@deftypefun double value_num (const union value *@var{value})
-Returns the numeric value in @var{value}, which must have been
-initialized as a numeric value. Equivalent to @code{@var{value}->f}.
-@end deftypefun
-
-@deftypefun {const char *} value_str (const union value *@var{value}, int @var{width})
-@deftypefunx {char *} value_str_rw (union value *@var{value}, int @var{width})
-Returns the string value in @var{value}, which must have been
-initialized with positive width @var{width}. The string returned is
-not null-terminated. Only @var{width} bytes of returned data may be
-accessed.
-
-The two different functions exist only for @code{const}-correctness.
-Otherwise they are identical.
-
-It is important that @var{width} be the correct value that was passed
-to @func{value_init}. Passing a smaller or larger value (e.g.@:
-because that number of bytes will be accessed) will not always work
-and should be avoided.
-@end deftypefun
-
@deftypefun void value_copy (union value *@var{dst}, @
const union value *@var{src}, @
int @var{width})
@end deftypefun
@deftypefun {struct fmt_number_style} *fmt_create (void)
-A function which creates an array of all the styles used by pspp, and
+A function which creates an array of all the styles used by pspp, and
calls fmt_number_style_init on each of them.
@end deftypefun
@deftypefunx char * data_out_legacy (const union value *@var{input}, const char *@var{encoding}, const struct fmt_spec *@var{format})
Converts the data pointed to by @var{input} into a string value, which
will be encoded in UTF-8, according to output format specifier @var{format}.
-Format
+Format
must be a valid output format. The width of @var{input} is
inferred from @var{format} using an algorithm equivalent to
@func{fmt_var_width}.
@node Variable Name
@subsection Variable Name
-A variable name is a string between 1 and @code{VAR_NAME_LEN} bytes
+A variable name is a string between 1 and @code{ID_MAX_LEN} bytes
long that satisfies the rules for PSPP identifiers
(@pxref{Tokens,,,pspp, PSPP Users Guide}). Variable names are
mixed-case and treated case-insensitively.
-@deftypefn Macro int VAR_NAME_LEN
+@deftypefn Macro int ID_MAX_LEN
Maximum length of a variable name, in bytes, currently 64.
@end deftypefn
Renaming Variables}).
@end deftypefun
-@anchor{var_is_plausible_name}
-@deftypefun {bool} var_is_valid_name (const char *@var{name}, bool @var{issue_error})
-@deftypefunx {bool} var_is_plausible_name (const char *@var{name}, bool @var{issue_error})
-Tests @var{name} for validity or ``plausibility.'' Returns true if
-the name is acceptable, false otherwise. If the name is not
-acceptable and @var{issue_error} is true, also issues an error message
-explaining the violation.
-
-A valid name is one that fully satisfies all of the requirements for
-variable names (@pxref{Tokens,,,pspp, PSPP Users Guide}). A
-``plausible'' name is simply a string whose length is in the valid
-range and that is not a reserved word. PSPP accepts plausible but
-invalid names as variable names in some contexts where the character
-encoding scheme is ambiguous, as when reading variable names from
-system files.
-@end deftypefun
-
@deftypefun {enum dict_class} var_get_dict_class (const struct variable *@var{var})
Returns the dictionary class of @var{var}'s name (@pxref{Dictionary
Class}).
@var{value} must have the same width as @var{var}.
If a label exists, it will be appended to the string pointed to by @var{str}.
Otherwise, it formats @var{value}
-using @var{var}'s print format (@pxref{Input and Output Formats})
+using @var{var}'s print format (@pxref{Input and Output Formats})
and appends the formatted string.
@end deftypefun
@node Variable Short Names
@subsection Variable Short Names
-PSPP variable names may be up to 64 (@code{VAR_NAME_LEN}) bytes long.
+PSPP variable names may be up to 64 (@code{ID_MAX_LEN}) bytes long.
The system and portable file formats, however, were designed when
variable names were limited to 8 bytes in length. Since then, the
system file format has been augmented with an extension record that
Sets @var{var}'s short name to @var{short_name}, or removes
@var{var}'s short name if @var{short_name} is a null pointer. If it
is non-null, then @var{short_name} must be a plausible name for a
-variable (@pxref{var_is_plausible_name}). The name will be truncated
+variable. The name will be truncated
to 8 bytes in length and converted to all-uppercase.
@end deftypefun
To prevent multiple clients from attempting to use a variable's single
auxiliary data field at the same time, we adopt the convention that
-use of auxiliary data in the active file dictionary is restricted to
+use of auxiliary data in the active dataset dictionary is restricted to
the currently executing command. In particular, transformations must
-not attach auxiliary data to a variable in the active file in the
-expectation that it can be used later when the active file is read and
+not attach auxiliary data to a variable in the active dataset in the
+expectation that it can be used later when the active dataset is read and
the transformation is executed. To help enforce this restriction,
-auxiliary data is deleted from all variables in the active file
+auxiliary data is deleted from all variables in the active dataset
dictionary after the execution of each PSPP command.
This convention for safe use of auxiliary data applies only to the
-active file dictionary. Rules for other dictionaries may be
+active dataset dictionary. Rules for other dictionaries may be
established separately.
Auxiliary data should be replaced by a more flexible mechanism at some
(see below).
@end deftypefun
-@deftypefun size_t dict_get_var_cnt (const struct dictionary *@var{dict})
+@deftypefun size_t dict_get_n_vars (const struct dictionary *@var{dict})
Returns the number of variables in @var{dict}.
@end deftypefun
associated storage.
Deleting a variable to which there might be external pointers is a bad
-idea. In particular, deleting variables from the active file
+idea. In particular, deleting variables from the active dataset
dictionary is a risky proposition, because transformations can retain
references to arbitrary variables. Therefore, no variable should be
-deleted from the active file dictionary when any transformations are
+deleted from the active dataset dictionary when any transformations are
active, because those transformations might reference the variable to
be deleted. The safest time to delete a variable is just after a
procedure has been executed, as done by @cmd{DELETE VARIABLES}.
@node Dictionary Filter Variable
@subsection Filter Variable
-When the active file is read by a procedure, cases can be excluded
+When the active dataset is read by a procedure, cases can be excluded
from analysis based on the values of a @dfn{filter variable}.
@xref{FILTER,,,pspp, PSPP Users Guide}, for a user view of filtering.
The user may use the @cmd{SPLIT FILE} command (@pxref{SPLIT
FILE,,,pspp, PSPP Users Guide}) to select a set of variables on which
-to split the active file into groups of cases to be analyzed
+to split the active dataset into groups of cases to be analyzed
independently in each statistical procedure. The set of split
variables is stored as part of the dictionary, although the effect on
data analysis is implemented by each individual statistical procedure.
caller must not modify or free the returned array.
@end deftypefun
-@deftypefun size_t dict_get_split_cnt (const struct dictionary *@var{dict})
+@deftypefun size_t dict_get_n_splits (const struct dictionary *@var{dict})
Returns the number of split variables.
@end deftypefun
pair.
@end deftypefun
-@deftypefun size_t dict_get_document_line_cnt (const struct dictionary *@var{dict})
+@deftypefun size_t dict_get_document_n_lines (const struct dictionary *@var{dict})
Returns the number of line of documents in @var{dict}. If the
dictionary contains no documents, returns 0.
@end deftypefun
projects / pspp / blobdiff