X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fdev%2Fconcepts.texi;h=ed7f44d061d9deec6dc8bd45dcd8377bf697e37f;hb=ca55d1892bd94f4eca0435fc7d92909be7a0c201;hp=053d2521c1298045b0ca774509f0d0379aada084;hpb=9ade26c8349b4434008c46cf09bc7473ec743972;p=pspp diff --git a/doc/dev/concepts.texi b/doc/dev/concepts.texi index 053d2521c1..ed7f44d061 100644 --- a/doc/dev/concepts.texi +++ b/doc/dev/concepts.texi @@ -1,3 +1,13 @@ +@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 @@ -156,27 +166,6 @@ This function returns false if @func{value_init} and @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}) @@ -609,7 +598,7 @@ Destroys @var{style}, freeing its storage. @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 @@ -698,7 +687,7 @@ This function is declared in @file{data/data-in.h}. @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}. @@ -1356,7 +1345,7 @@ Looks for a label for @var{value} in @var{var}'s set of value labels. @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 @@ -1866,16 +1855,16 @@ associate data with a variable. 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 @@ -2026,7 +2015,7 @@ Returns the variable at the given @var{position} in @var{dict}. (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 @@ -2109,10 +2098,10 @@ variables. They also destroy the removed variables and free their 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}. @@ -2195,7 +2184,7 @@ current name. Renames each of the @var{count} variables in @var{vars} to the name in the corresponding position of @var{new_names}. If the renaming would result in a duplicate variable name, returns false and stores one of -the names that would be be duplicated into @code{*@var{err_name}}, if +the names that would be duplicated into @code{*@var{err_name}}, if @var{err_name} is non-null. Otherwise, the renaming is successful, and true is returned. @end deftypefun @@ -2244,7 +2233,7 @@ is null, then @var{dict}'s weighting variable, if any, is cleared. @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. @@ -2290,7 +2279,7 @@ Sets @var{dict}'s case limit to @var{limit}. 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. @@ -2309,7 +2298,7 @@ only if there are no split variables, returns a null pointer. The 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 @@ -2404,7 +2393,7 @@ call to one of this function in a @func{msg_disable}/@func{msg_enable} 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