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

NAME

6       Data::Types - Validate and convert data types.
7

SYNOPSIS

9         use Data::Types qw(:all);
10
11         my $whole = 4.5;
12         $whole = to_whole($whole) unless is_whole($whole);
13
14         my $int = 1.2;
15         $int = to_int($int) unless is_int($int);
16
17         my $decimal = '1.2foo';
18         $decimal = to_decimal($decimal) unless is_decimal($decimal);
19
20         my $real = '1.2foo';
21         $real = to_real($real) unless is_real($real);
22
23         my $float = '1.2foo';
24         $float = to_float($float) unless is_float($float);
25
26         my $string = [];
27         $string = to_string($string) unless is_string($string);
28

DESCRIPTION

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

EXPORT

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
40       :whole
41           Exports is_whole() and to_whole().
42
43       :count
44           Exports is_count() and to_count().
45
46       :int
47           Exports is_int() and to_int().
48
49       :decimal
50           Exports is_decimal() and to_decimal().
51
52       :real
53           Exports is_real() and to_real().
54
55       :float
56           Exports is_float() and to_float().
57
58       :string
59           Exports is_string() and to_string().
60
61       :is Exports all validation functions: is_whole(), is_int(), is_real(),
62           is_decimal(), is_float(), and is_string().
63
64       :to Exports all conversion functions: to_whole(), to_int(), to_real(),
65           to_decimal(), to_float(), and to_string().
66
67       :all
68           Exports all functions.
69

FUNCTIONS

71   is_whole
72         my $bool = is_whole($val);
73
74       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
78         my $bool = is_whole(1); # Returns true.
79         $bool = is_whole(-1);   # Returns false.
80         $bool = is_whole(0);    # Returns true.
81
82   to_whole
83         my $whole = to_whole($val);
84
85       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
90         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
97   is_count
98         my $bool = is_count($val);
99
100       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
104         my $bool = is_count(1); # Returns true.
105         $bool = is_count(-1);   # Returns false.
106         $bool = is_count(0);    # Returns false.
107
108   to_count
109         my $count = to_count($val);
110
111       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
118         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
125   is_int
126         my $bool = is_int($val);
127
128       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
132         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
137   to_int
138         my $int = to_int($val);
139
140       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
145         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
151   is_decimal
152         my $bool = is_decimal($val);
153
154       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
158         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
163   to_decimal
164         my $dec = to_decimal($val);
165         $dec = to_decimal($val, $precision);
166
167       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
172         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
180   is_real
181         my $bool = is_real($val);
182
183       Returns true if $val is a real number, and false if it is not.
184
185       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
189   to_real
190         my $real = to_real($val);
191         $real = to_real($val, $precision);
192
193       Converts $val to a real number.
194
195       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
199   is_float
200         my $bool = is_float($val);
201
202       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
206         my $bool = is_float(30);   # Returns true.
207         $bool = is_float(1.23e99); # Returns true.
208         $bool = is_float('foo');   # Returns false.
209
210   to_float
211         my $dec = to_float($val);
212         $dec = to_float($val, $precision);
213
214       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
219         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
225   is_string
226         my $bool = is_string($val);
227
228       Returns true if $val is a string, and false if it is not. All defined
229       non-references are considered strings.
230
231         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
236   to_string
237         my $string = to_string($val);
238         $string = to_string($val, $length);
239
240       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
248         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

SUPPORT

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
258       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
262       Patches against Class::Meta are welcome. Please send bug reports to
263       <bug-data-types@rt.cpan.org>.
264

AUTHOR

266       David E. Wheeler <david@justatheory.com>
267
268       Currently maintained by Mohammad S Anwar "<mohammad.anwar @ yahoo.com>"
269

SEE ALSO

271       perlfaq4 lists the most of the regular expressions used to identify the
272       different numeric types used in this module.
273
274       String::Checker also does some data type validation.
275
276       String::Scanf reimplements the C sscanf() function in perl, and also
277       does data type validation and conversion.
278
279       Regexp::Common contains many useful common regular expressions
280       (surprise!), including some that can be used to identify data types.
281
282       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
289       This module is free software; you can redistribute it and/or modify it
290       under the same terms as Perl itself.
291
292
293
294perl v5.36.0                      2023-01-20                    Data::Types(3)
Impressum