.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Class::MethodMaker::hash 3" .TH Class::MethodMaker::hash 3 2024-11-16 "perl v5.40.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Class::Method::hash \- Create methods for handling a hash value. .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 2 \& use Class::MethodMaker \& [ hash => [qw/ x /] ]; \& \& $instance\->x; # empty \& $instance\->x(a => 1, b => 2, c => 3); \& $instance\->x_count == 3; # true \& $instance\->x = (b => 5, d => 8); # Note this *replaces* the hash, \& # not adds to it \& $instance\->x_index(\*(Aqb\*(Aq) == 5; # true \& $instance\->x_exists(\*(Aqc\*(Aq); # false \& $instance\->x_exists(\*(Aqd\*(Aq); # true .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" Creates methods to handle hash values in an object. For a component named \&\f(CW\*(C`x\*(C'\fR, by default creates methods \f(CW\*(C`x\*(C'\fR, \f(CW\*(C`x_reset\*(C'\fR, \f(CW\*(C`x_clear\*(C'\fR, \f(CW\*(C`x_isset\*(C'\fR, \&\f(CW\*(C`x_count\*(C'\fR, \f(CW\*(C`x_index\*(C'\fR, \f(CW\*(C`x_keys\*(C'\fR, \f(CW\*(C`x_values\*(C'\fR, \f(CW\*(C`x_each\*(C'\fR, \f(CW\*(C`x_exists\*(C'\fR, \&\f(CW\*(C`x_delete\*(C'\fR, \f(CW\*(C`x_set\*(C'\fR, \f(CW\*(C`x_get\*(C'\fR. .PP Methods available are: .PP \fR\f(CI\*(C`*\*(C'\fR\fI\fR .IX Subsection "*" .PP \&\fICreated by default\fR. This method returns the list of keys and values stored in the slot (they are returned pairwise, i.e., key, value, key, value; as with perl hashes, no order of keys is guaranteed). If any arguments are provided to this method, they \fBreplace\fR the current hash contents. In an array context it returns the keys, values as an array and in a scalar context as a hash-reference. Note that this reference is no longer a direct reference to the storage, in contrast to Class::MethodMaker v1. This is to protect encapsulation. See x_ref if you need that functionality (and are prepared to take the associated risk.) .PP If a single argument is provided that is an arrayref or hashref, it is expanded and its contents used in place of the existing contents. This is a more efficient passing mechanism for large numbers of values. .PP \fR\f(CI*_reset\fR\fI\fR .IX Subsection "*_reset" .PP \&\fICreated by default\fR. Called without an argument, this resets the component as a whole; deleting any associated storage, and returning the component to its default state. Normally, this means that \fI*_isset\fR will return false, and \fI*\fR will return undef. If \f(CW\*(C`\-default\*(C'\fR is in effect, then the component will be set to the default value, and \fI*_isset\fR will return true. If \&\f(CW\*(C`\-default_ctor\*(C'\fR is in effect, then the default subr will be invoked, and its return value used to set the value of the component, and \fI*_isset\fR will return true. .PP If called with arguments, these arguments are treated as indexes into the component, and the individual elements thus referenced are reset (their storage deleted, so that \fI*_isset(n)\fR will return false for appropriate \fIn\fR, except where \f(CW\*(C`\-default\*(C'\fR or \f(CW\*(C`\-default_ctor\*(C'\fR are in force, as above). As with perl arrays, resetting the highest set value implicitly decreases the count (but x_reset(n) never unsets the aggregate itself, even if all the elements are not set). .PP \fR\f(CI*_clear\fR\fI\fR .IX Subsection "*_clear" .PP \&\fICreated by default\fR. Empty the component of all elements, but without deleting the storage itself. .PP If given a list of keys, then the elements \fIthat exist\fR indexed by those keys are set to undef (but not deleted). .PP Note the very different semantics: \f(CW\*(C`$x\->a_clear(\*(Aqb\*(Aq)\*(C'\fR sets the value of \&\f(CW\*(C`b\*(C'\fR in component 'a' to undef (if \f(CW\*(C`b\*(C'\fR) already exists (so \f(CW\*(C`$x\->a_isset(\*(Aqb\*(Aq))\*(C'\fR returns true), but \f(CW\*(C`$x\->a_clear()\*(C'\fR deletes the element \f(CW\*(C`b\*(C'\fR from component 'a' (so \f(CW\*(C`$x\->a_isset(\*(Aqb\*(Aq))\*(C'\fR returns false). .PP \fR\f(CI*_isset\fR\fI\fR .IX Subsection "*_isset" .PP \&\fICreated by default\fR. Whether the component is currently set. This is different from being defined; initially, the component is not set (and if read, will return undef); it can be set to undef (which is a set value, which also returns undef). Having been set, the only way to unset the component is with \f(CW*_reset\fR. .PP If a default value is in effect, then \f(CW*_isset\fR will always return true. .PP \&\fI*\fR\f(BI_isset()\fR tests the component as a whole. \fI*_isset(a)\fR tests the element indexed by \fIa\fR. \fI*_isset(a,b)\fR tests the elements indexed by \fIa\fR, \fIb\fR, and returns the logical conjunction (\fIand\fR) of the tests. .PP \fR\f(CI*_count\fR\fI\fR .IX Subsection "*_count" .PP \&\fICreated by default\fR. Returns the number of elements in this component. This is not affected by presence (or lack) of a \f(CW\*(C`default\*(C'\fR (or \&\f(CW\*(C`default_ctor\*(C'\fR). Returns \f(CW\*(C`undef\*(C'\fR if whole component not set (as per \&\fI*_isset\fR). .PP \fR\f(CI*_index\fR\fI\fR .IX Subsection "*_index" .PP \&\fICreated by default\fR. Takes a list of indices, returns a list of the corresponding values. .PP If a default (or a default ctor) is in force, then a lookup by index will vivify & set to the default the respective elements (and therefore the aggregate data-structure also, if it's not already). .PP \fR\f(CI*_keys\fR\fI\fR .IX Subsection "*_keys" .PP \&\fICreated by default\fR. The known keys, as a list in list context, as an arrayref in scalar context. .PP If you're expecting a count of the keys in scalar context, see \fI*_count\fR. .PP \fR\f(CI*_values\fR\fI\fR .IX Subsection "*_values" .PP \&\fICreated by default\fR. The known values, as a list in list context, as an arrayref in scalar context. .PP \fR\f(CI*_each\fR\fI\fR .IX Subsection "*_each" .PP \&\fICreated by default\fR. The next pair of key, value (as a list) from the hash. .PP \fR\f(CI*_exists\fR\fI\fR .IX Subsection "*_exists" .PP \&\fICreated by default\fR. Takes any number of arguments, considers each as a key, and determines whether the key exists in the has. Returns the logical conjunction (\fIand\fR). .PP \fR\f(CI*_delete\fR\fI\fR .IX Subsection "*_delete" .PP \&\fICreated by default\fR. This operates exactly like \fI*_reset\fR, except that calling this with no args does nothing. This is provided for orthogonality with the Perl \f(CW\*(C`delete\*(C'\fR operator, while \fI*_reset\fR is provided for orthogonality with other component types. .PP \fR\f(CI*_set\fR\fI\fR .IX Subsection "*_set" .PP .Vb 3 \& %n = $x\->h; # (a=>1,b=>2,c=>3) (in some order) \& $h\->h_set(b=>4,d=>7); \& %n = $h\->a; # (a=>1,b=>4,c=>3,d=>7) (in some order) .Ve .PP \&\fICreated by default\fR. Takes a list, treated as pairs of index => value; each given index is set to the corresponding value. No return. .PP If two arguments are given, of which the first is an arrayref, then it is treated as a list of indices of which the second argument (which must also be an arrayref) are the corresponding values. Thus the following two commands are equivalent: .PP .Vb 2 \& $x\->a_set(b=>4,d=>7); \& $x\->a_set([\*(Aqb\*(Aq,\*(Aqd\*(Aq],[4,7]); .Ve .PP \fR\f(CI*_get\fR\fI\fR .IX Subsection "*_get" .PP \&\fICreated by default\fR. Retrieves the value of the component without setting (ignores any arguments passed).