1% -*- latex -*-
2%
3This software may only be used by you under license from the
4University of Notre Dame.  A copy of the University of Notre Dame's
5Source Code Agreement is available at the inilib Internet website
6having the URL: <http://inilib.sourceforge.net/license/> If you
7received this software without first entering into a license with the
8University of Notre Dame, you have an infringing copy of this software
9and cannot use it without violating the University of Notre Dame's
10intellectual property rights.
11%
12% $Id: attribute.tex,v 1.14 2005/03/09 21:41:33 bwbarrett Exp $
13%
14
15\subsection[attribute]{{\tt attribute} Class}
16\label{sec:attribute}
17
18The {\tt attribute} class is a base class from which four classes are
19derived (see Section~\ref{sec:implementation:attribute}).  The
20constructors and destructors will rarely be used directly by the
21programmer -- the {\tt registry} and {\tt section} classes are
22intended to act as the primary interface to attributes.
23
24Table~\ref{tbl:attribute-members} summarizes the members functions on
25the {\tt attribute} class.
26
27\begin{table}[htbp]
28  \begin{center}
29    \leavevmode
30    \begin{tabular}{|l|p{3in}|}
31      \hline
32      \multicolumn{1}{|c|}{Name} & \multicolumn{1}{c|}{Purpose} \\
33      \hline
34      Default constructor & Create an empty attribute. \\
35      Copy constructor & Perform a deep copy. \\
36      {\sc Datatype} constructor & Intializer constructor. \\
37      Destructor & Destroy the section and all associated data. \\
38      \hline
39      {\tt operator=} & Assignment operator; clear the section and
40      perform deep copy.\\
41      Casting operators & Convert the attribute to an {\tt bool}, {\tt
42        int}, {\tt double}, or {\tt string}. \\
43      Unary operators & As appropriate (see
44      Section~\ref{sec:op_overload}). \\
45      {\tt get\_type} & Return an enum indicating the underlying
46      attribute's real type. \\
47      {\tt get\_precision} & Get the precision that will be used to
48      convert doubles to strings. \\
49      {\tt set\_precision} & Set the precision that will be used to
50      convert doubles to strings. \\
51      \hline
52    \end{tabular}
53    \caption{Member functions in the {\tt attribute} class.}
54    \label{tbl:attribute-members}
55  \end{center}
56\end{table}
57
58
59\subsubsection{Type Enumeration}
60
61Each attribute has a type associated with it.  The {\tt get\_type()}
62function (see Section~\ref{sec:att:gettype}) can be used to determine
63the type of an attribute.  The following enumeration is used to
64determine type:
65
66\vspace{11pt}
67\bind{enum attr\_type \{BOOL, DOUBLE, INT, STRING, NONE\};}
68
69\subsubsection{Constructors}
70
71\bind{attribute()}
72\bind{attribute(attribute*)}
73\bind{attribute(const attribute\&)}
74\bind{attribute({\sc Datatype} value)}
75
76Creates an attribute.  For each of the four attribute types, {\tt
77value} can only be the same type as the attribute.  For example, {\tt
78bool\_attribute} only has a constructor with {\tt value} of type bool.
79
80\subsubsection{Destructors}
81
82\bind{\~{}attribute()}
83
84Destroys the attribute, freeing any memory associated with it.  {\tt
85wrap\_attributes} also destroy the underlying {\tt attribute}, if any
86(See Section~\ref{sec:implementation:attribute}).
87
88\subsubsection{Assignment Operator}
89
90\bind{attribute\& operator=({\sc Datatype} value)}
91
92Assigns {\tt value} to the attribute.  For more information on how
93conversions are handled by {\tt inilib}, see
94Section~\ref{sec:conversions}.  {\tt value} will be cast to the type
95of the underlying attribute, which may cause a loss of data (such as
96assigning a {\tt double} to any of the other three data types).  The
97precision of a {\tt double} assigned to a {\tt std::string} can be
98modified using the {\tt set\_precision()} and {\tt get\_precision()}
99methods (Section~\ref{sec:att:precision}).
100
101\subsubsection{Casting Operator}
102
103\bind{operator {\sc Datatype}()}
104
105Casts the value of the attribute to the specified type.  However, with
106{\tt operator=()}, certain casts can cause a loss of data (such as
107casting a {\tt double} to an {\tt int}).  Form more information on how
108conversions are handled during casting, see
109Section~\ref{sec:conversions}.
110
111As the casting operator is defined for {\tt int}, {\tt double}, {\tt
112  bool}, and {\tt std::string}, compiler ambiguities can arise when
113using attributes for many common operations ({\tt operator==()}, for
114instance).  To avoid the problem of compiler ambiguities that arise
115because of the {\tt operator=()} being overloaded, many of the
116operators have been overloaded for the attribute classes.  More
117information is available in Section~\ref{sec:op_overload}.
118
119\subsubsection{Other Overloaded Operators}
120
121In order to eliminate compiler ambiguities, many of the overloadable
122C++ operators are overloaded for the {\tt attribute} classes. See
123Section~\ref{sec:op_overload} for more information.
124
125\subsubsection{{\tt get\_type}}
126\label{sec:att:gettype}
127
128\bind{attr\_type get\_type()}
129
130Returns the underlying type of the attribute.  If the attribute is a
131{\tt wrap\_attribute}, the result will be the type of the underlying
132attribute.  If an attribute has not yet been assigned a type, {\tt
133NONE} is returned.
134
135\subsubsection{Double Precision Setting}
136\label{sec:att:precision}
137
138\bind{int attribute::get\_precision()}
139\bind{void attribute::set\_precision(int precision)}
140
141Certain functions require that a {\tt double} be assigned or cast to a
142{\tt std::string}.  The {\tt set\_precision()} function is used to set
143the number of significant figures  that will be stored after the
144conversion.  The {\tt get\_precision()} function allows access to the
145current precision for the conversion.  Both functions are {\tt static}
146to the {\tt attribute} class, meaning that the precision level is for
147the entire class, not specific instances.
148
149{\tt precision} should be no higher than 100.  If {\tt precision}
150is higher than 100, it will automatically be reduced to 100
151without warning.  The result of {\tt get\_precision()} in this case
152will be 100.
153