1.\" $NetBSD: prop_number.3,v 1.12 2020/06/06 21:25:59 thorpej Exp $ 2.\" 3.\" Copyright (c) 2006, 2020 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd June 2, 2020 31.Dt PROP_NUMBER 3 32.Os 33.Sh NAME 34.Nm prop_number , 35.Nm prop_number_create_signed , 36.Nm prop_number_create_unsigned , 37.Nm prop_number_copy , 38.Nm prop_number_size , 39.Nm prop_number_unsigned , 40.Nm prop_number_signed_value , 41.Nm prop_number_unsigned_value , 42.Nm prop_number_schar_value , 43.Nm prop_number_short_value , 44.Nm prop_number_int_value , 45.Nm prop_number_long_value , 46.Nm prop_number_longlong_value , 47.Nm prop_number_intptr_value , 48.Nm prop_number_int8_value , 49.Nm prop_number_int16_value , 50.Nm prop_number_int32_value , 51.Nm prop_number_int64_value , 52.Nm prop_number_uchar_value , 53.Nm prop_number_ushort_value , 54.Nm prop_number_uint_value , 55.Nm prop_number_ulong_value , 56.Nm prop_number_ulonglong_value , 57.Nm prop_number_uintptr_value , 58.Nm prop_number_uint8_value , 59.Nm prop_number_uint16_value , 60.Nm prop_number_uint32_value , 61.Nm prop_number_uint64_value , 62.Nm prop_number_equals , 63.Nm prop_number_equals_signed , 64.Nm prop_number_equals_unsigned 65.Nd numeric value property object 66.Sh LIBRARY 67.Lb libprop 68.Sh SYNOPSIS 69.In prop/proplib.h 70.\" 71.Ft prop_number_t 72.Fn prop_number_create_signed "intmax_t val" 73.Ft prop_number_t 74.Fn prop_number_create_unsigned "uintmax_t val" 75.Ft prop_number_t 76.Fn prop_number_copy "prop_number_t number" 77.\" 78.Ft int 79.Fn prop_number_size "prop_number_t number" 80.Ft bool 81.Fn prop_number_unsigned "prop_number_t number" 82.Ft intmax_t 83.Fn prop_number_signed_value "prop_number_t number" 84.Ft uintmax_t 85.Fn prop_number_usigned_value "prop_number_t number" 86.\" 87.Ft bool 88.Fn prop_number_schar_value "prop_number_t number" "signed char *valp" 89.Ft bool 90.Fn prop_number_short_value "prop_number_t number" "short *valp" 91.Ft bool 92.Fn prop_number_int_value "prop_number_t number" "int *valp" 93.Ft bool 94.Fn prop_number_long_value "prop_number_t number" "long *valp" 95.Ft bool 96.Fn prop_number_longlong_value "prop_number_t number" "long long *valp" 97.Ft bool 98.Fn prop_number_intptr_value "prop_number_t number" "intptr_t *valp" 99.Ft bool 100.Fn prop_number_int8_value "prop_number_t number" "int8_t *valp" 101.Ft bool 102.Fn prop_number_int16_value "prop_number_t number" "int16_t *valp" 103.Ft bool 104.Fn prop_number_int32_value "prop_number_t number" "int32_t *valp" 105.Ft bool 106.Fn prop_number_int64_value "prop_number_t number" "int64_t *valp" 107.\" 108.Ft bool 109.Fn prop_number_uchar_value "prop_number_t number" "unsigned char *valp" 110.Ft bool 111.Fn prop_number_ushort_value "prop_number_t number" "unsigned short *valp" 112.Ft bool 113.Fn prop_number_uint_value "prop_number_t number" "unsigned int *valp" 114.Ft bool 115.Fn prop_number_ulong_value "prop_number_t number" "unsigned long *valp" 116.Ft bool 117.Fn prop_number_ulonglong_value "prop_number_t number" "unsigned long long *valp" 118.Ft bool 119.Fn prop_number_uintptr_value "prop_number_t number" "uintptr_t *valp" 120.Ft bool 121.Fn prop_number_uint8_value "prop_number_t number" "uint8_t *valp" 122.Ft bool 123.Fn prop_number_uint16_value "prop_number_t number" "uint16_t *valp" 124.Ft bool 125.Fn prop_number_uint32_value "prop_number_t number" "uint32_t *valp" 126.Ft bool 127.Fn prop_number_uint64_value "prop_number_t number" "uint64_t *valp" 128.\" 129.Ft bool 130.Fn prop_number_equals "prop_number_t num1" "prop_number_t num2" 131.Ft bool 132.Fn prop_number_equals_signed "prop_number_t number" "intmax_t val" 133.Ft bool 134.Fn prop_number_equals_unsigned "prop_number_t number" "uintmax_t val" 135.Sh DESCRIPTION 136The 137.Nm 138family of functions operate on a numeric value property object type. 139Values are either signed or unsigned, and promoted to the maximum size 140integer type 141.Pq intmax_t or uintmax_t , respectively . 142.Pp 143It is possible to compare number objects that differ in sign. 144Such comparisons first test to see if each object is within the valid 145number range of the other: 146.Bl -bullet 147.It 148Signed numbers that are greater than or equal to 0 can be compared to 149unsigned numbers. 150.It 151Unsigned numbers that are less than or equal to the largest signed 152integer value 153.Pq Dv INTMAX_MAX 154can be compared to signed numbers. 155.El 156.Pp 157Number objects have a different externalized representation depending 158on their sign: 159.Bl -bullet 160.It 161Signed numbers are externalized in base-10 162.Pq decimal . 163.It 164Unsigned numbers are externalized in base-16 165.Pq hexadecimal . 166.El 167.Pp 168When numbers are internalized, the sign of the resulting number object 169.Pq and thus its valid range 170is determined by a set of rules evaluated in the following order: 171.Bl -bullet 172.It 173If the first character of the number is a 174.Sq - 175then the number is signed. 176.It 177If the first two characters of the number are 178.Sq 0x 179then the number is unsigned. 180.It 181If the number value fits into the range of a signed number then the 182number is signed. 183.It 184In all other cases, the number is unsigned. 185.El 186.Bl -tag -width "xxxxx" 187.It Fn prop_number_create_signed "intmax_t val" 188Create a numeric value object with the signed value 189.Fa val . 190Returns 191.Dv NULL 192on failure. 193.It Fn prop_number_create_unsigned "uintmax_t val" 194Create a numeric value object with the unsigned value 195.Fa val . 196Returns 197.Dv NULL 198on failure. 199.It Fn prop_number_copy "prop_number_t number" 200Copy a numeric value object. 201If the supplied object isn't a numeric value, 202.Dv NULL 203is returned. 204.It Fn prop_number_size "prop_number_t number" 205Returns 8, 16, 32, or 64, representing the number of bits required to 206hold the value of the object. 207If the supplied object isn't a numeric value, 0 is returned. 208.It Fn prop_number_unsigned "prop_number_t number" 209Returns 210.Dv true 211if the numeric value object has an unsigned value. 212.It Fn prop_number_signed_value "prop_number_t number" 213Returns the signed value of the numeric value object. 214If the supplied object isn't a numeric value, zero is returned. 215Thus, 216it is not possible to distinguish between 217.Dq not a prop_number_t 218and 219.Dq prop_number_t has a value of 0 . 220.It Fn prop_number_unsigned_value "prop_number_t number" 221Returns the unsigned value of the numeric value object. 222If the supplied object isn't a numeric value, zero is returned. 223Thus, 224it is not possible to distinguish between 225.Dq not a prop_number_t 226and 227.Dq prop_number_t has a value of 0 . 228.\" 229.It Fn prop_number_schar_value "prop_number_t number" "signed char *valp" 230.It Fn prop_number_short_value "prop_number_t number" "short *valp" 231.It Fn prop_number_int_value "prop_number_t number" "int *valp" 232.It Fn prop_number_long_value "prop_number_t number" "long *valp" 233.It Fn prop_number_longlong_value "prop_number_t number" "long long *valp" 234.It Fn prop_number_intptr_value "prop_number_t number" "intptr_t *valp" 235.It Fn prop_number_int8_value "prop_number_t number" "int8_t *valp" 236.It Fn prop_number_int16_value "prop_number_t number" "int16_t *valp" 237.It Fn prop_number_int32_value "prop_number_t number" "int32_t *valp" 238.It Fn prop_number_int64_value "prop_number_t number" "int64_t *valp" 239.It Fn prop_number_uchar_value "prop_number_t number" "unsigned char *valp" 240.It Fn prop_number_ushort_value "prop_number_t number" "unsigned short *valp" 241.It Fn prop_number_uint_value "prop_number_t number" "unsigned int *valp" 242.It Fn prop_number_ulong_value "prop_number_t number" "unsigned long *valp" 243.It Fn prop_number_ulonglong_value "prop_number_t number" "unsigned long long *valp" 244.It Fn prop_number_uintptr_value "prop_number_t number" "uintptr_t *valp" 245.It Fn prop_number_uint8_value "prop_number_t number" "uint8_t *valp" 246.It Fn prop_number_uint16_value "prop_number_t number" "uint16_t *valp" 247.It Fn prop_number_uint32_value "prop_number_t number" "uint32_t *valp" 248.It Fn prop_number_uint64_value "prop_number_t number" "uint64_t *valp" 249These functions extract the numeric value as the specified type and 250store it in 251.Fa valp . 252The value is bounds-checked against the minimum and maximum values of 253the type. 254If the value can be represented in the specified type, these functions 255return 256.Dv true . 257Otherwise, they return 258.Dv false . 259.\" 260.It Fn prop_number_equals "prop_number_t num1" "prop_number_t num2" 261Returns 262.Dv true 263if the two numeric value objects are equivalent. 264If at least one of the supplied objects isn't a numeric value, 265.Dv false 266is returned. 267.It Fn prop_number_equals_signed "prop_number_t number" "intmax_t val" 268Returns 269.Dv true 270if the object's value is equivalent to the signed value 271.Fa val . 272If the supplied object isn't a numerical value, 273.Dv false 274is returned. 275.It Fn prop_number_equals_unsigned "prop_number_t number" \ 276 "uintmax_t val" 277Returns 278.Dv true 279if the object's value is equivalent to the unsigned value 280.Fa val . 281If the supplied object isn't a numerical value, 282.Dv false 283is returned. 284.El 285.Sh SEE ALSO 286.Xr prop_array 3 , 287.Xr prop_bool 3 , 288.Xr prop_data 3 , 289.Xr prop_dictionary 3 , 290.Xr prop_object 3 , 291.Xr prop_string 3 , 292.Xr proplib 3 293.Sh HISTORY 294The 295.Xr proplib 3 296property container object library first appeared in 297.Nx 4.0 . 298