Returns the numeric style for the given format @var{type}.
@end deftypefun
-@deftypefun void fmt_check_style (const struct fmt_number_style *@var{style})
-Asserts that style is self consistent.
-@end deftypefun
-
-
@deftypefun {const char *} fmt_name (enum fmt_type @var{type})
Returns the name of the given format @var{type}.
@end deftypefun
These functions provide the ability to convert data fields into
@union{value}s and vice versa.
-@deftypefun bool data_in (struct substring @var{input}, enum legacy_encoding @var{legacy_encoding}, enum fmt_type @var{type}, int @var{implied_decimals}, int @var{first_column}, union value *@var{output}, int @var{width})
+@deftypefun bool data_in (struct substring @var{input}, const char *@var{encoding}, enum fmt_type @var{type}, int @var{implied_decimals}, int @var{first_column}, const struct dictionary *@var{dict}, union value *@var{output}, int @var{width})
Parses @var{input} as a field containing data in the given format
@var{type}. The resulting value is stored in @var{output}, which the
caller must have initialized with the given @var{width}. For
consistency, @var{width} must be 0 if
@var{type} is a numeric format type and greater than 0 if @var{type}
is a string format type.
-
-Ordinarily @var{legacy_encoding} should be @code{LEGACY_NATIVE},
-indicating that @var{input} is encoded in the character set
-conventionally used on the host machine. It may be set to
-@code{LEGACY_EBCDIC} to cause @var{input} to be re-encoded from EBCDIC
-during data parsing.
+@var{encoding} should be set to indicate the character
+encoding of @var{input}.
+@var{dict} must be a pointer to the dictionary with which @var{output}
+is associated.
If @var{input} is the empty string (with length 0), @var{output} is
set to the value set on SET BLANKS (@pxref{SET BLANKS,,,pspp, PSPP
This function is declared in @file{data/data-in.h}.
@end deftypefun
-@deftypefun void data_out (const union value *@var{input}, const struct fmt_spec *@var{format}, char *@var{output})
-@deftypefunx void data_out_legacy (const union value *@var{input}, enum legacy_encoding @var{legacy_encoding}, const struct fmt_spec *@var{format}, char *@var{output})
-Converts the data pointed to by @var{input} into a data field in
-@var{output} according to output format specifier @var{format}, which
-must be a valid output format. Exactly @code{@var{format}->w} bytes
-are written to @var{output}. The width of @var{input} is also
+@deftypefun char * data_out (const union value *@var{input}, const struct fmt_spec *@var{format})
+@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
+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}.
-If @func{data_out} is called, or @func{data_out_legacy} is called with
-@var{legacy_encoding} set to @code{LEGACY_NATIVE}, @var{output} will
-be encoded in the character set conventionally used on the host
-machine. If @var{legacy_encoding} is set to @code{LEGACY_EBCDIC},
-@var{output} will be re-encoded from EBCDIC during data output.
-
When @var{input} contains data that cannot be represented in the given
@var{format}, @func{data_out} may output a message using @func{msg},
@c (@pxref{msg}),
@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}).
@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
of variables, and returns the new variable.
@end deftypefun
-@deftypefun {struct variable *} dict_clone_var (struct dictionary *@var{dict}, const struct variable *@var{old_var}, const char *@var{name})
-@deftypefunx {struct variable *} dict_clone_var_assert (struct dictionary *@var{dict}, const struct variable *@var{old_var}, const char *@var{name})
+@deftypefun {struct variable *} dict_clone_var (struct dictionary *@var{dict}, const struct variable *@var{old_var})
+@deftypefunx {struct variable *} dict_clone_var_assert (struct dictionary *@var{dict}, const struct variable *@var{old_var})
Creates a new variable as a clone of @var{var}, inserts the new
-variable into @var{dict}, and returns the new variable. The new
-variable is named @var{name}. Other properties of the new variable
-are copied from @var{old_var}, except for those not copied by
-@code{var_clone} (@pxref{var_clone}).
+variable into @var{dict}, and returns the new variable. Other
+properties of the new variable are copied from @var{old_var}, except
+for those not copied by @code{var_clone} (@pxref{var_clone}).
@var{var} does not need to be a member of any dictionary.
@end deftypefun
+@deftypefun {struct variable *} dict_clone_var_as (struct dictionary *@var{dict}, const struct variable *@var{old_var}, const char *@var{name})
+@deftypefunx {struct variable *} dict_clone_var_as_assert (struct dictionary *@var{dict}, const struct variable *@var{old_var}, const char *@var{name})
+These functions are similar to @code{dict_clone_var} and
+@code{dict_clone_var_assert}, respectively, except that the new
+variable is named @var{name} instead of keeping @var{old_var}'s name.
+@end deftypefun
+
@node Dictionary Deleting Variables
@subsection Deleting Variables
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.
projects / pspp-builds.git / blobdiff