1Data::Types(3) User Contributed Perl Documentation Data::Types(3)
2
6 Data::Types - Validate and convert data types.
7
9 use Data::Types qw(:all);
10 my $whole = 4.5;
12 $whole = to_whole($whole) unless is_whole($whole);
13 my $int = 1.2;
15 $int = to_int($int) unless is_int($int);
16 my $decimal = '1.2foo';
18 $decimal = to_decimal($decimal) unless is_decimal($decimal);
19 my $real = '1.2foo';
21 $real = to_real($real) unless is_real($real);
22 my $float = '1.2foo';
24 $float = to_float($float) unless is_float($float);
25 my $string = [];
27 $string = to_string($string) unless is_string($string);
28
30 This module exports a number of functions that are useful for
31 validating and converting data types. It is intended for use in
32 applications where data types are more important than they typically
33 are in Perl -- e.g., database applications.
34
36 No functions are exported by default, though each function may be
37 exported explicitly (see "FUNCTIONS" below, for a list of functions
38 available for export). The following export tags are supported:
39 :whole
41 Exports is_whole() and to_whole().
42 :count
44 Exports is_count() and to_count().
45 :int
47 Exports is_int() and to_int().
48 :decimal
50 Exports is_decimal() and to_decimal().
51 :real
53 Exports is_real() and to_real().
54 :float
56 Exports is_float() and to_float().
57 :string
59 Exports is_string() and to_string().
60 :is Exports all validation functions: is_whole(), is_int(), is_real(),
62 is_decimal(), is_float(), and is_string().
63 :to Exports all conversion functions: to_whole(), to_int(), to_real(),
65 to_decimal(), to_float(), and to_string().
66 :all
68 Exports all functions.
69
71 is_whole
72 my $bool = is_whole($val);
73 Returns true if $val is a whole number (including 0), and false if it
75 is not. The regular expression used to test the wholeness of $val is
76 "/^\d+$/".
77 my $bool = is_whole(1); # Returns true.
79 $bool = is_whole(-1); # Returns false.
80 $bool = is_whole(0); # Returns true.
81 to_whole
83 my $whole = to_whole($val);
84 Converts $val to a whole number and returns it. Numbers will be rounded
86 to the nearest whole. If $val is a mixture of numbers and letters,
87 to_whole() will extract the first decimal number it finds and convert
88 that number to a whole number.
89 my $whole = to_whole(10); # Returns 10.
91 $whole = to_whole(0); # Returns 0.
92 $whole = to_whole(.22); # Returns 0.
93 $whole = to_whole(-2); # Returns undef.
94 $whole = to_whole('foo3.56'); # Returns 4.
95 $whole = to_whole('foo'); # Returns undef.
96 is_count
98 my $bool = is_count($val);
99 Returns true if $val is a counting number (1, 2, 3, ...), and false if
101 it is not. The regular expression used to test whether $val is a
102 counting number is "/^\d+$/".
103 my $bool = is_count(1); # Returns true.
105 $bool = is_count(-1); # Returns false.
106 $bool = is_count(0); # Returns false.
107 to_count
109 my $count = to_count($val);
110 Converts $val to a counting number and returns it. Numbers will be
112 rounded to the nearest counting number. Note that since 0 (zero) is not
113 considered a counting number by this module, it will not be returned.
114 If $val is a mixture of numbers and letters, to_count() will extract
115 the first decimal number it finds and convert that number to a counting
116 number.
117 my $count = to_count(10); # Returns 10.
119 $count = to_count(0); # Returns undef.
120 $count = to_count(.22); # Returns undef (rounded down to 0).
121 $count = to_count(-2); # Returns undef.
122 $count = to_count('foo3.56'); # Returns 4.
123 $count = to_count('foo'); # Returns undef.
124 is_int
126 my $bool = is_int($val);
127 Returns true if $val is an integer, and false if it is not. Numbers may
129 be preceded by a plus or minus sign. The regular expression used to
130 test for an integer in $val is "/^[+-]?\d+$/".
131 my $bool = is_int(0); # Returns true.
133 $bool = is_int(22); # Returns true.
134 $bool = is_int(-22); # Returns true.
135 $bool = is_int(3.2); # Returns false.
136 to_int
138 my $int = to_int($val);
139 Converts $val to an integer. If $val is a decimal number, it will be
141 rounded to the nearest integer. If $val is a mixture of numbers and
142 letters, to_int() will extract the first decimal number it finds and
143 convert that number to an integer.
144 my $int = to_int(10.5); # Returns 10.
146 $int = to_int(10.51); # Returns 11.
147 $int = to_int(-0.22); # Returns 0.
148 $int = to_int(-6.51); # Returns 7.
149 $int = to_int('foo'); # Returns undef.
150 is_decimal
152 my $bool = is_decimal($val);
153 Returns true if $val is a decimal number, and false if it is not.
155 Numbers may be preceded by a plus or minus sign. The regular expression
156 used to test $val is "/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/".
157 my $bool = is_decimal(10) # Returns true.
159 $bool = is_decimal(10.8) # Returns true.
160 $bool = is_decimal(-33.48) # Returns true.
161 $bool = is_decimal(1.23e99) # Returns false.
162 to_decimal
164 my $dec = to_decimal($val);
165 $dec = to_decimal($val, $precision);
166 Converts $val to a decimal number. The optional second argument sets
168 the precision of the number. The default precision is 5. If $val is a
169 mixture of numbers and letters, to_decimal() will extract the first
170 decimal number it finds.
171 my $dec = to_decimal(0); # Returns 0.00000.
173 $dec = to_decimal(10.5); # Returns 10.5.
174 $dec = to_decimal(10.500009); # Returns 10.50001.
175 $dec = to_decimal(10.500009, 7); # Returns 10.5000090.
176 $dec = to_decimal('foo10.3') # Returns 10.30000.
177 $dec = to_decimal('foo-4.9') # Returns -4.90000.
178 $dec = to_decimal('foo') # Returns undef.
179 is_real
181 my $bool = is_real($val);
182 Returns true if $val is a real number, and false if it is not.
184 Note: This function is currently equivalent to is_decimal(), since this
186 module cannot identify non-decimal real numbers (e.g., irrational
187 numbers). This implementation may change in the future.
188 to_real
190 my $real = to_real($val);
191 $real = to_real($val, $precision);
192 Converts $val to a real number.
194 Note: Currently, this function is the equivalent of to_decimal(), since
196 this module cannot identify non-decimal real numbers (e.g., irrational
197 numbers). This implementation may change in the future.
198 is_float
200 my $bool = is_float($val);
201 Returns true if $val is a float, and false if it is not. The regular
203 expression used to test $val is
204 "/^([+-]?)(?=[0-9]|\.[0-9])[0-9]*(\.[0-9]*)?([Ee]([+-]?[0-9]+))?$/".
205 my $bool = is_float(30); # Returns true.
207 $bool = is_float(1.23e99); # Returns true.
208 $bool = is_float('foo'); # Returns false.
209 to_float
211 my $dec = to_float($val);
212 $dec = to_float($val, $precision);
213 Converts $val to a float. The optional second argument sets the
215 precision of the number. The default precision is 5. If $val is a
216 mixture of numbers and letters, to_float() will extract the first float
217 it finds.
218 my $float = to_float(1.23); # Returns 1.23000.
220 $float = to_float(1.23e99); # Returns 1.23000e+99.
221 $float = to_float(1.23e99, 1); # Returns 1.2e+99.
222 $float = to_float('foo-1.23'); # Returns -1.23000.
223 $float = to_float('ick_1.23e99foo'); # Returns 1.23000e+99.
224 is_string
226 my $bool = is_string($val);
227 Returns true if $val is a string, and false if it is not. All defined
229 non-references are considered strings.
230 my $bool = is_string('foo'); # Returns true.
232 $bool = is_string(20001); # Returns true.
233 $bool = is_string([]); # Returns false.
234 $bool = is_string(undef); # Returns false.
235 to_string
237 my $string = to_string($val);
238 $string = to_string($val, $length);
239 Converts $val into a string. If $val is a reference, the string value
241 of the reference will be returned. Such a value may be a memory
242 address, or some other value, if the stringification operator has been
243 overridden for the object stored in $val. If the optional second
244 argument $length is passed, to_string() will truncate the string to
245 that length. If $length is 0 (zero), it will not limit the length of
246 the return string. If $val is undefined, to_string() will return undef.
247 my $string = to_string('foo'); # Returns 'foo'.
249 $string = to_string([]); # Returns 'ARRAY(0x101bec14)'.
250 $string = to_string(undef); # Returns undef.
251 $string = to_string('hello', 4); # Returns 'hell'.
252
254 This module is stored in an open GitHub repository
255 <http://github.com/manwar/data-types/>. Feel free to fork and
256 contribute!
257 Please file bug reports via GitHub Issues
259 <http://github.com/manwar/data-types/issues/> or by sending mail to
260 bug-Data-Types@rt.cpan.org <mailto:bug-Data-Types@rt.cpan.org>.
261 Patches against Class::Meta are welcome. Please send bug reports to
263 <bug-data-types@rt.cpan.org>.
264
266 David E. Wheeler <david@justatheory.com>
267 Currently maintained by Mohammad S Anwar "<mohammad.anwar @ yahoo.com>"
269
271 perlfaq4 lists the most of the regular expressions used to identify the
272 different numeric types used in this module.
273 String::Checker also does some data type validation.
275 String::Scanf reimplements the C sscanf() function in perl, and also
277 does data type validation and conversion.
278 Regexp::Common contains many useful common regular expressions
280 (surprise!), including some that can be used to identify data types.
281 Arthur Bergman's types pragma, offers compile-time data types for Perl
283 5.8.0. The data types include int, float, and string. I highly
284 recommend using this pragma for fast, static data types.
285
287 Copyright (c) 2002-2011, David E. Wheeler. Some Rights Reserved.
288 This module is free software; you can redistribute it and/or modify it
290 under the same terms as Perl itself.
291perl v5.38.0 2023-07-20 Data::Types(3)