X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fdev%2Fconcepts.texi;h=053d2521c1298045b0ca774509f0d0379aada084;hb=9ade26c8349b4434008c46cf09bc7473ec743972;hp=cc6e75226f3ce952f6e0db1dcaa95ae67f07db47;hpb=04d2c99833753252b724dd9d4f15cc3a80b6bec8;p=pspp-builds.git diff --git a/doc/dev/concepts.texi b/doc/dev/concepts.texi index cc6e7522..053d2521 100644 --- a/doc/dev/concepts.texi +++ b/doc/dev/concepts.texi @@ -637,11 +637,6 @@ work with these global styles: 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 @@ -654,19 +649,17 @@ Returns the name of the given format @var{type}. 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 @@ -701,21 +694,15 @@ not propagated to the caller as errors. 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}), @@ -1233,12 +1220,12 @@ The following sections describe variable-related functions and macros. @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 @@ -1261,23 +1248,6 @@ dictionary. Use @func{dict_rename_var} instead (@pxref{Dictionary 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}). @@ -1777,7 +1747,7 @@ To delete a variable from a dictionary and destroy it, use @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 @@ -1842,7 +1812,7 @@ been assigned a short name. 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 @@ -2114,17 +2084,23 @@ if through a call to @code{var_create} with those arguments 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