conversions.c: Add conversions for largest max sized integer
[asterisk/asterisk.git] / include / asterisk / conversions.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2017, Digium, Inc.
5  *
6  * Kevin Harwell <kharwell@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Conversion utility functions
21  */
22
23 #ifndef _ASTERISK_CONVERSIONS_H
24 #define _ASTERISK_CONVERSIONS_H
25
26 #include <stdint.h>
27
28 /*!
29  * \brief Convert the given string to an unsigned integer
30  *
31  * This function will return failure for the following reasons:
32  *
33  *   The given string to convert is NULL
34  *   The given string to convert is empty.
35  *   The given string to convert is negative (starts with a '-')
36  *   The given string to convert contains non numeric values
37  *   Once converted the number is out of range (greater than UINT_MAX)
38  *
39  * \param str The string to convert
40  * \param res [out] The converted value
41  *
42  * \returns -1 if it fails to convert, 0 on success
43  */
44 int ast_str_to_uint(const char *str, unsigned int *res);
45
46 /*!
47  * \brief Convert the given string to an unsigned long
48  *
49  * This function will return failure for the following reasons:
50  *
51  *   The given string to convert is NULL
52  *   The given string to convert is empty.
53  *   The given string to convert is negative (starts with a '-')
54  *   The given string to convert contains non numeric values
55  *   Once converted the number is out of range (greater than ULONG_MAX)
56  *
57  * \param str The string to convert
58  * \param res [out] The converted value
59  *
60  * \returns -1 if it fails to convert, 0 on success
61  */
62 int ast_str_to_ulong(const char *str, unsigned long *res);
63
64 /*!
65  * \brief Convert the given string to an unsigned max size integer
66  *
67  * This function will return failure for the following reasons:
68  *
69  *   The given string to convert is NULL
70  *   The given string to convert is empty.
71  *   The given string to convert is negative (starts with a '-')
72  *   The given string to convert contains non numeric values
73  *   Once converted the number is out of range (greater than UINTMAX_MAX)
74  *
75  * \param str The string to convert
76  * \param res [out] The converted value
77  *
78  * \returns -1 if it fails to convert, 0 on success
79  */
80 int ast_str_to_umax(const char *str, uintmax_t *res);
81
82 #endif /* _ASTERISK_CONVERSIONS_H */