1.\" $NetBSD: prop_number.3,v 1.9 2008/04/30 13:10:46 martin Exp $ 2.\" 3.\" Copyright (c) 2006 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 January 21, 2008 31.Dt PROP_NUMBER 3 32.Os 33.Sh NAME 34.Nm prop_number , 35.Nm prop_number_create_integer , 36.Nm prop_number_create_unsigned_integer , 37.Nm prop_number_copy , 38.Nm prop_number_size , 39.Nm prop_number_unsigned , 40.Nm prop_number_integer_value , 41.Nm prop_number_unsigned_integer_value , 42.Nm prop_number_equals , 43.Nm prop_number_equals_integer , 44.Nm prop_number_equals_unsigned_integer 45.Nd numeric value property object 46.Sh LIBRARY 47.Lb libprop 48.Sh SYNOPSIS 49.In libprop/proplib.h 50.\" 51.Ft prop_number_t 52.Fn prop_number_create_integer "int64_t val" 53.Ft prop_number_t 54.Fn prop_number_create_unsigned_integer "uint64_t val" 55.Ft prop_number_t 56.Fn prop_number_copy "prop_number_t number" 57.\" 58.Ft int 59.Fn prop_number_size "prop_number_t number" 60.Ft bool 61.Fn prop_number_unsigned "prop_number_t number" 62.Ft int64_t 63.Fn prop_number_integer_value "prop_number_t number" 64.Ft uint64_t 65.Fn prop_number_unsigned_integer_value "prop_number_t number" 66.\" 67.Ft bool 68.Fn prop_number_equals "prop_number_t num1" "prop_number_t num2" 69.Ft bool 70.Fn prop_number_equals_integer "prop_number_t number" "int64_t val" 71.Ft bool 72.Fn prop_number_equals_unsigned_integer "prop_number_t number" "uint64_t val" 73.Sh DESCRIPTION 74The 75.Nm prop_number 76family of functions operate on a numeric value property object type. 77Values are either signed or unsigned, and promoted to a 64-bit type 78.Pq int64_t or uint64_t , respectively . 79.Pp 80It is possible to compare number objects that differ in sign. 81Such comparisons first test to see if each object is within the valid 82number range of the other: 83.Bl -bullet 84.It 85Signed numbers that are greater than or equal to 0 can be compared to 86unsigned numbers. 87.It 88Unsigned numbers that are less than or equal to the largest signed 64-bit 89value 90.Pq Dv INT64_MAX 91can be compared to signed numbers. 92.El 93.Pp 94Number objects have a different externalized representation depending 95on their sign: 96.Bl -bullet 97.It 98Signed numbers are externalized in base-10 99.Pq decimal . 100.It 101Unsigned numbers are externalized in base-16 102.Pq hexadecimal . 103.El 104.Pp 105When numbers are internalized, the sign of the resulting number object 106.Pq and thus its valid range 107is determined by a set of rules evaluated in the following order: 108.Bl -bullet 109.It 110If the first character of the number is a 111.Sq - 112then the number is signed. 113.It 114If the first two characters of the number are 115.Sq 0x 116then the number is unsigned. 117.It 118If the number value fits into the range of a signed number then the 119number is signed. 120.It 121In all other cases, the number is unsigned. 122.El 123.Bl -tag -width "xxxxx" 124.It Fn prop_number_create_integer "int64_t val" 125Create a numeric value object with the signed value 126.Fa val . 127Returns 128.Dv NULL 129on failure. 130.It Fn prop_number_create_unsigned_integer "uint64_t val" 131Create a numeric value object with the unsigned value 132.Fa val . 133Returns 134.Dv NULL 135on failure. 136.It Fn prop_number_copy "prop_number_t number" 137Copy a numeric value object. 138If the supplied object isn't a numeric value, 139.Dv NULL 140is returned. 141.It Fn prop_number_size "prop_number_t number" 142Returns 8, 16, 32, or 64, representing the number of bits required to 143hold the value of the object. 144If the supplied object isn't a numeric value, 145.Dv NULL 146is returned. 147.It Fn prop_number_unsigned "prop_number_t number" 148Returns 149.Dv true 150if the numeric value object has an unsigned value. 151.It Fn prop_number_integer_value "prop_number_t number" 152Returns the signed integer value of the numeric value object. 153If the supplied object isn't a numeric value, zero is returned. 154Thus, 155it is not possible to distinguish between 156.Dq not a prop_number_t 157and 158.Dq prop_number_t has a value of 0 . 159.It Fn prop_number_unsigned_integer_value "prop_number_t number" 160Returns the unsigned integer value of the numeric value object. 161If the supplied object isn't a numeric value, zero is returned. 162Thus, 163it is not possible to distinguish between 164.Dq not a prop_number_t 165and 166.Dq prop_number_t has a value of 0 . 167.It Fn prop_number_equals "prop_number_t num1" "prop_number_t num2" 168Returns 169.Dv true 170if the two numeric value objects are equivalent. 171If at least one of the supplied objects isn't a numeric value, 172.Dv false 173is returned. 174.It Fn prop_number_equals_integer "prop_number_t number" "int64_t val" 175Returns 176.Dv true 177if the object's value is equivalent to the signed value 178.Fa val . 179If the supplied object isn't a numerical value or if 180.Fa val 181exceeds 182.Dv INT64_MAX , 183.Dv false 184is returned. 185.It Fn prop_number_equals_unsigned_integer "prop_number_t number" \ 186 "uint64_t val" 187Returns 188.Dv true 189if the object's value is equivalent to the unsigned value 190.Fa val . 191If the supplied object isn't a numerical value or if 192.Fa val 193exceeds 194.Dv INT64_MAX , 195.Dv false 196is returned. 197.El 198.Sh SEE ALSO 199.Xr prop_array 3 , 200.Xr prop_bool 3 , 201.Xr prop_data 3 , 202.Xr prop_dictionary 3 , 203.Xr prop_object 3 , 204.Xr prop_string 3 , 205.Xr proplib 3 206.Sh HISTORY 207The 208.Nm proplib 209property container object library first appeared in 210.Nx 4.0 . 211