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. Thus, 154it is not possible to distinguish between ``not a prop_number_t'' 155and ``prop_number_t has a value of 0''. 156.It Fn prop_number_unsigned_integer_value "prop_number_t number" 157Returns the unsigned integer value of the numeric value object. 158If the supplied object isn't a numeric value, zero is returned. Thus, 159it is not possible to distinguish between ``not a prop_number_t'' 160and ``prop_number_t has a value of 0''. 161.It Fn prop_number_equals "prop_number_t num1" "prop_number_t num2" 162Returns 163.Dv true 164if the two numeric value objects are equivalent. 165If at least one of the supplied objects isn't a numeric value, 166.Dv false 167is returned. 168.It Fn prop_number_equals_integer "prop_number_t number" "int64_t val" 169Returns 170.Dv true 171if the object's value is equivalent to the signed value 172.Fa val . 173If the supplied object isn't a numerical value or if 174.Fa val 175exceeds 176.Dv INT64_MAX , 177.Dv false 178is returned. 179.It Fn prop_number_equals_unsigned_integer "prop_number_t number" \ 180 "uint64_t val" 181Returns 182.Dv true 183if the object's value is equivalent to the unsigned value 184.Fa val . 185If the supplied object isn't a numerical value or if 186.Fa val 187exceeds 188.Dv INT64_MAX , 189.Dv false 190is returned. 191.El 192.Sh SEE ALSO 193.Xr prop_array 3 , 194.Xr prop_bool 3 , 195.Xr prop_data 3 , 196.Xr prop_dictionary 3 , 197.Xr prop_object 3 , 198.Xr prop_string 3 , 199.Xr proplib 3 200.Sh HISTORY 201The 202.Nm proplib 203property container object library first appeared in 204.Nx 4.0 . 205