1Types(3)              User Contributed Perl Documentation             Types(3)
2
3
4

NAME

6       PDL::Types - define fundamental PDL Datatypes
7

SYNOPSIS

9        use PDL::Types;
10
11        $pdl = ushort( 2.0, 3.0 );
12        print "The actual c type used to store ushort's is '" .
13           $pdl->type->realctype() . "'\n";
14        The actual c type used to store ushort's is 'unsigned short'
15

DESCRIPTION

17       Internal module - holds all the PDL Type info.  The type info can be
18       accessed easily using the "PDL::Type" object returned by the type
19       method as shown in the synopsis.
20
21       Skip to the end of this document to find out how to change the set of
22       types supported by PDL.
23

FUNCTIONS

25       A number of functions are available for module writers to get/process
26       type information. These are used in various places (e.g. "PDL::PP",
27       "PDL::Core") to generate the appropriate type loops, etc.
28
29   typesrtkeys
30       Returns an array of keys of typehash sorted in order of type complexity
31
32        pdl> @typelist = PDL::Types::typesrtkeys;
33        pdl> print @typelist;
34        PDL_B PDL_S PDL_US PDL_L PDL_IND PDL_LL PDL_F PDL_D
35
36   ppdefs
37       Returns an array of pp symbols for all real types. This informs the
38       default "GenericTypes" for "pp_def" functions, making support for
39       complex types require an "opt-in".
40
41        pdl> print PDL::Types::ppdefs
42        B S U L N Q F D
43
44   ppdefs_complex
45       Returns an array of pp symbols for all complex types.
46
47        pdl> print PDL::Types::ppdefs_complex
48        G C
49
50   ppdefs_all
51       Returns an array of pp symbols for all types including complex.
52
53        pdl> print PDL::Types::ppdefs_all
54        B S U L N Q F D G C
55
56   typesynonyms
57       return type related synonym definitions to be included in pdl.h .  This
58       routine must be updated to include new types as required.  Mostly the
59       automatic updating should take care of the vital things.
60

PDL TYPES OVERVIEW

62       As of 2.065, PDL supports these types:
63
64       SByte
65           Signed 8-bit value.
66
67       Byte
68           Unsigned 8-bit value.
69
70       Short
71           Signed 16-bit value.
72
73       UShort
74           Unsigned 16-bit value.
75
76       Long
77           Signed 32-bit value.
78
79       ULong
80           Unsigned 32-bit value.
81
82       Indx
83           Signed value, same size as a pointer on the system in use.
84
85       LongLong
86           Signed 64-bit value.
87
88       ULongLong
89           Unsigned 64-bit value.
90
91       Float
92           IEEE 754 <https://en.wikipedia.org/wiki/IEEE_754> single-precision
93           real floating-point value.
94
95       Double
96           IEEE 754 double-precision real value.
97
98       LDouble
99           A C99 "long double", defined as "at least as precise as a double",
100           but often more precise.
101
102       CFloat
103           A C99 complex single-precision floating-point value.
104
105       CDouble
106           A C99 complex double-precision floating-point value.
107
108       CLDouble
109           A C99 complex "long double" - see above for description.
110

PDL::Type OBJECTS

112       This module declares one class - "PDL::Type" - objects of this class
113       are returned by the type method of an ndarray.  It has several methods,
114       listed below, which provide an easy way to access type information:
115
116       Additionally, comparison and stringification are overloaded so that you
117       can compare and print type objects, e.g.
118
119         $nofloat = 1 if $pdl->type < float;
120         die "must be double" if $type != double;
121
122       For further examples check again the type method.
123
124       enum
125           Returns the number representing this datatype (see get_datatype).
126
127       symbol
128           Returns one of 'PDL_B', 'PDL_S', 'PDL_US', 'PDL_L', 'PDL_IND',
129           'PDL_LL', 'PDL_F' or 'PDL_D'.
130
131       ctype
132           Returns the macro used to represent this type in C code (eg
133           'PDL_Long').
134
135       ppsym
136           The letter used to represent this type in PP code (eg 'U' for
137           ushort).
138
139       realctype
140           The actual C type used to store this type.
141
142       shortctype
143           The value returned by "ctype" without the 'PDL_' prefix.
144
145       badvalue
146           The special numerical value used to represent bad values for this
147           type.  See "badvalue" in PDL::Bad for more details.
148
149       isnan
150           Given a string representing a C value, will return a C expression
151           for this type that indicates whether that value is NaN (for complex
152           values, if either is NaN).
153
154       isfinite
155           Given a string representing a C value, will return a C expression
156           for this type that indicates whether that value is finite (for
157           complex values, if both are finite).
158
159       floatsuffix
160           The string appended to floating-point functions for this floating-
161           point type. Dies if called on non-floating-point type.
162
163       orig_badvalue
164           The default special numerical value used to represent bad values
165           for this type. (You can change the value that represents bad values
166           for each type during runtime.) See the orig_badvalue routine in
167           PDL::Bad for more details.
168
169       bswap
170           Returns the appropriate "bswap*" from PDL::IO::Misc for the size of
171           this type, including a no-op for types of size 1. Note this means a
172           one-line construction means you must call the return value:
173
174             $pdl->type->bswap->($pdl);
175

DEVELOPER NOTES ON ADDING/REMOVING TYPEs

177       You can change the types that PDL knows about by editing entries in the
178       definition of the variable @types that appears close to the top of the
179       file Types.pm.PL (i.e. the file from which this module was generated).
180
181   Format of a type entry
182       Each entry in the @types array is a hash reference. Here is an example
183       taken from the actual code that defines the "ushort" type:
184
185                    {
186                     identifier => 'US',
187                     onecharident => 'U',   # only needed if different from identifier
188                     pdlctype => 'PDL_Ushort',
189                     realctype => 'unsigned short',
190                     ppforcetype => 'ushort',
191                     usenan => 0,
192                     packtype => 'S*',
193                     defaultbadval => 'USHRT_MAX',
194                     real=>1,
195                     integer=>1,
196                     unsigned=>1,
197                    },
198
199       Before we start to explain the fields please take this important
200       message on board: entries must be listed in order of increasing
201       complexity. This is critical to ensure that PDL's type conversion works
202       correctly.  Basically, a less complex type will be converted to a more
203       complex type as required.
204
205   Fields in a type entry
206       Each type entry has a number of required and optional entry.
207
208       A list of all the entries:
209
210       •   identifier
211
212           Required. A short sequence of upercase letters that identifies this
213           type uniquely. More than three characters is probably overkill.
214
215       •   onecharident
216
217           Optional. Only required if the "identifier" has more than one
218           character.  This should be a unique uppercase character that will
219           be used to reference this type in PP macro expressions of the
220           "TBSULFD" type - see "$T" in PDL::PP.
221
222       •   pdlctype
223
224           Required. The "typedef"ed name that will be used to access this
225           type from C code.
226
227       •   realctype
228
229           Required. The C compiler type that is used to implement this type.
230           For portability reasons this one might be platform dependent.
231
232       •   ppforcetype
233
234           Required. The type name used in PP signatures to refer to this
235           type.
236
237       •   usenan
238
239           Required. Flag that signals if this type has to deal with NaN
240           issues.  Generally only required for floating point types.
241
242       •   packtype
243
244           Required. The Perl pack type used to pack Perl values into the
245           machine representation for this type. For details see "perldoc -f
246           pack".
247
248       •   integer
249
250           Required. Boolean - is this an integer type?
251
252       •   unsigned
253
254           Required. Boolean - is this an unsigned type?
255
256       •   real
257
258           Required. Boolean - is this a real (not complex) type?
259
260       •   realversion
261
262           String - the real version of this type (e.g. cdouble -> 'D').
263
264       •   complexversion
265
266           String - the complex version of this type (e.g. double -> 'C').
267
268       Also have a look at the entries at the top of Types.pm.PL.
269
270       The syntax is not written into stone yet and might change as the
271       concept matures.
272
273   Other things you need to do
274       You need to check modules that do I/O (generally in the IO part of the
275       directory tree). In the future we might add fields to type entries to
276       automate this. This requires changes to those IO modules first though.
277
278       You should also make sure that any type macros in PP files (i.e.
279       "$TBSULFD...") are updated to reflect the new type. PDL::PP::Dump has a
280       mode to check for type macros requiring updating. Do something like
281
282           find . -name \*.pd -exec perl -Mblib=. -M'PDL::PP::Dump=typecheck' {} \;
283
284       from the PDL root directory after updating Types.pm.PL to check for
285       such places.
286
287
288
289perl v5.34.0                      2022-02-28                          Types(3)
Impressum