#

# Copyright 2005 Sun Microsystems, Inc. All rights reserved.

# Use is subject to license terms.

#

# CDDL HEADER START

#

# The contents of this file are subject to the terms of the

# Common Development and Distribution License, Version 1.0 only

# (the "License"). You may not use this file except in compliance

# with the License.

#

# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

# or http://www.opensolaris.org/os/licensing.

# See the License for the specific language governing permissions

# and limitations under the License.

#

# When distributing Covered Code, include this CDDL HEADER in each

# file and include the License file at usr/src/OPENSOLARIS.LICENSE.

# If applicable, add the following below this CDDL HEADER, with the

# fields enclosed by brackets "[]" replaced with your own identifying

# information: Portions Copyright [yyyy] [name of copyright owner]

#

# CDDL HEADER END

#

#ident "%Z%%M% %I% %E% SMI"

#

# Sun::Solaris::Exacct::Object::Group documentation.

#

=head1 NAME

Sun::Solaris::Exacct::Object::Group - exacct group manipulation

=head1 SYNOPSIS

use Sun::Solaris::Exacct::Object;

my $ea_grp = Sun::Solaris::Exacct::Object::Group->new(

&EXT_GROUP | &EXC_DEFAULT | &EXD_GROUP_PROC);

This module is used for manipulating C<libexacct(3LIB)> Group objects. A

libexacct Group object is represented as an opaque reference blessed into the

C<Sun::Solaris::Exacct::Object::Group> class, which is a subclass of the

C<Sun::Solaris::Exacct::Object> class. The Items within a Group are stored

inside a Perl array. A reference to the array can be accessed with the

inherited value() method. The individual Items within a Group can be

manipulated with the normal Perl array syntax and operators. All data elements

of the array must be derived from the C<Sun::Solaris::Exacct::Object> class.

Group objects can also be nested inside each other simply by adding an

existing Group as a data Item.

=head2 Constants

None.

=head2 Functions

None.

=head2 Class methods

Class methods include those inherited from the C<Sun::Solaris::Exacct::Object>

base class, plus the following:

B<C<new($catalog, @objects)>>

This method creates and returns a new C<Sun::Solaris::Exacct::Object::Group>.

The catalog tag can be either an integer or a

C<Sun::Solaris::Exacct::Catalog>. The catalog tag should be a valid catalog

tag for a Perl exacct Group object. The C<@objects> parameter is a list of

C<Sun::Solaris::Exacct::Object> to be stored inside the Group. A copy of all

the passed Items is taken and any Group objects are recursively copied. The

contents of the returned Group object can be accessed with the array returned

by the C<value()> method.

=head2 Object methods

B<C<as_hash()>>

This method returns the contents of the group as a hash reference. It uses the

string value of each item's catalog ID as the hash entry key and the scalar

value returned by C<value()> as the hash entry value.

This form should be used if there are no duplicate catalog tags in the group.

This method and its companion C<as_hashlist()> are the fastest ways to access

the contents of a Group.

B<C<as_hashlist()>>

This method returns the contents of the group as a hash reference. It uses the

string value of each item's catalog id as the hash entry key and an array of

the scalar values returned by C<value()> as the hash entry value for all the

items that share a common key. This form should be used if there might be

duplicate catalog tags in the group.

This method and its companion C<as_hash()> are the fastest ways to access the

contents of a Group.

=head2 Exports

None.

=head1 ATTRIBUTES

See C<attributes(5)> for descriptions of the following attributes:

___________________________________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

|_____________________________|_____________________________|

| Availability | CPAN (http://www.cpan.org) |

|_____________________________|_____________________________|

| Interface Stability | Evolving |

|_____________________________|_____________________________|

=head1 SEE ALSO

C<Sun::Solaris::Exacct(3)>, C<Sun::Solaris::Exacct::Catalog(3)>,

C<Sun::Solaris::Exacct::File(3)>, C<Sun::Solaris::Exacct::Object(3)>,

C<Sun::Solaris::Exacct::Object::Item(3)>, C<libexacct(3LIB)>, C<attributes(5)>