← Back to branch summary

~ubuntu-branches/ubuntu/trusty/ocamlnet/trusty

« back to all changes in this revision

Viewing changes to src/netstring/netnumber.mli

  • Committer: Bazaar Package Importer
  • Author(s): Stéphane Glondu
  • Date: 2011-09-02 14:12:33 UTC
  • mfrom: (18.2.3 sid)
  • Revision ID: james.westby@ubuntu.com-20110902141233-zbj0ygxb92u6gy4z
Tags: 3.4-1
http://bugs.debian.org/637147
* New upstream release
  - add a new NetcgiRequire directive to ease dependency management
    (Closes: #637147)
  - remove patches that were applied upstream:
    + Added-missing-shebang-lines-in-example-shell-scripts
    + Try-also-ocamlc-for-POSIX-threads

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/netstring/netnumber.mli
 
1
(* $Id: netnumber.mli 1558 2011-03-04 17:15:46Z gerd $ *)
 
2
 
 
3
(** Binary encodings of numbers *)
 
4
 
 
5
(** This is the successor of the {!Rtypes} module *)
 
6
 
 
7
(** {2 Numeric types} *)
 
8
 
 
9
 
 
10
(* 4- and 8-bytes representation of signed integers *)
 
11
 
 
12
type int4
 
13
  (** 32 bit signed integer *)
 
14
 
 
15
type int8
 
16
  (** 64 bit signed integer *)
 
17
 
 
18
(* 4- and 8-bytes representation of non-negative integers *)
 
19
 
 
20
type uint4
 
21
  (** 32 bit unsigned integer *)
 
22
 
 
23
type uint8
 
24
  (** 64 bit unsigned integer *)
 
25
 
 
26
(* Floating-point numbers of single and double precision according to IEEE *)
 
27
 
 
28
type fp4
 
29
  (** single precision float (IEEE "float") *)
 
30
 
 
31
type fp8
 
32
  (** double precision float (IEEE "double") *)
 
33
 
 
34
exception Cannot_represent of string
 
35
  (** raised if a conversion can't be done *)
 
36
 
 
37
exception Out_of_range
 
38
  (** raised if string position out of range *)
 
39
 
 
40
 
 
41
 
 
42
(** {2 Basic encoding/decoding functions} *)
 
43
 
 
44
val mk_int4 : char * char * char * char -> int4
 
45
val mk_int8 : char * char * char * char * char * char * char * char -> int8
 
46
val mk_uint4 : char * char * char * char -> uint4
 
47
val mk_uint8 : char * char * char * char * char * char * char * char -> uint8
 
48
  (** [mk_]<t> create integer values from character tuples. In these tuples
 
49
    * the MSB is the first component and the LSB the last.
 
50
   *)
 
51
 
 
52
 
 
53
(* destroy integers and get tuples *)
 
54
 
 
55
val dest_int4 : int4 -> char * char * char * char
 
56
val dest_int8 : int8 -> char * char * char * char * char * char * char * char
 
57
val dest_uint4 : uint4 -> char * char * char * char
 
58
val dest_uint8 : uint8 -> char * char * char * char * char * char * char * char
 
59
  (** [dest_]<t> destroy integer values and returns the corresponding char
 
60
    * tuples.
 
61
   *)
 
62
 
 
63
val mk_fp4 : char * char * char * char -> fp4
 
64
val mk_fp8 : char * char * char * char * char * char * char * char -> fp8
 
65
val dest_fp4 : fp4 -> char * char * char * char
 
66
val dest_fp8 : fp8 -> char * char * char * char * char * char * char * char
 
67
 
 
68
 
 
69
(** {2 Conversions} *)
 
70
 
 
71
(** Conversions from int to (u)int and vice versa.
 
72
 * On 32-bit computers, the type [int] can hold 31-bit signed integers
 
73
 * (including the sign, i.e. one bit cannot be used).
 
74
 * On 64-bit computers, the type [int] can hold 63-bit signed integers
 
75
 * (including the sign, i.e. one bit cannot be used).
 
76
 * The [int_of_xxx] functions raise [Cannot_represent] if the number to
 
77
 * convert is too big (or too small) to be represented as [int]. Note
 
78
 * that this depends on the word size of your architecture.
 
79
 *)
 
80
 
 
81
val int_of_int4  : int4  -> int
 
82
val int_of_uint4 : uint4 -> int
 
83
val int_of_int8  : int8  -> int
 
84
val int_of_uint8 : uint8 -> int
 
85
 
 
86
val int4_of_int  : int -> int4
 
87
val uint4_of_int : int -> uint4
 
88
val int8_of_int  : int -> int8
 
89
val uint8_of_int : int -> uint8
 
90
 
 
91
val int32_of_int4  : int4  -> int32
 
92
val int32_of_uint4 : uint4 -> int32
 
93
val int32_of_int8  : int8  -> int32
 
94
val int32_of_uint8 : uint8 -> int32
 
95
 
 
96
val int4_of_int32  : int32 -> int4
 
97
val uint4_of_int32 : int32 -> uint4
 
98
val int8_of_int32  : int32 -> int8
 
99
val uint8_of_int32 : int32 -> uint8
 
100
 
 
101
val int64_of_int4  : int4  -> int64
 
102
val int64_of_uint4 : uint4 -> int64
 
103
val int64_of_int8  : int8  -> int64
 
104
val int64_of_uint8 : uint8 -> int64
 
105
 
 
106
val int4_of_int64  : int64 -> int4
 
107
val uint4_of_int64 : int64 -> uint4
 
108
val int8_of_int64  : int64 -> int8
 
109
val uint8_of_int64 : int64 -> uint8
 
110
 
 
111
(** Casts from [uint4]/[uint8] to [int32]/[int64]. Here, the sign is ignored and
 
112
 * simply considered as a bit.
 
113
 *)
 
114
 
 
115
val logical_uint4_of_int32 : int32 -> uint4
 
116
val logical_int32_of_uint4 : uint4 -> int32
 
117
val logical_uint8_of_int64 : int64 -> uint8
 
118
val logical_int64_of_uint8 : uint8 -> int64
 
119
 
 
120
val fp8_of_fp4 : fp4 -> fp8
 
121
val fp4_of_fp8 : fp8 -> fp4
 
122
  (** Note [fp4_of_fp8]: This conversion is not exact. It is quite
 
123
   * normal that precision is lost. Numbers too small or too large
 
124
   * for fp4 are converted to the "infinity" value.
 
125
   *)
 
126
 
 
127
val float_of_fp4 : fp4 -> float
 
128
val float_of_fp8 : fp8 -> float
 
129
val fp4_of_float : float -> fp4
 
130
val fp8_of_float : float -> fp8
 
131
  (** Note fp4_of_float: The same problems as in fp4_of_fp8 may arise *)
 
132
 
 
133
(** {2 Comparisons} *)
 
134
 
 
135
(** The comparisons "=" and "<>" work for all numbers.
 
136
 
 
137
    For signed integers, the operators "<", "<=", ">", and ">=" work, too.
 
138
    The unsigned integer type use representation that are not compatible
 
139
    with these operators, and the following functions need to be called.
 
140
    
 
141
    For [fp4] and [fp8] there are no comparison functions - convert to
 
142
    [float] first and compare then.
 
143
 *)
 
144
 
 
145
val lt_uint4 : uint4 -> uint4 -> bool
 
146
  (** [lt_uint4] is true iff the first value is less than the second value 
 
147
      as unsigned int
 
148
   *)
 
149
val le_uint4 : uint4 -> uint4 -> bool
 
150
val gt_uint4 : uint4 -> uint4 -> bool
 
151
val ge_uint4 : uint4 -> uint4 -> bool
 
152
  (** Other comparisons *)
 
153
 
 
154
val lt_uint8 : uint8 -> uint8 -> bool
 
155
  (** [lt_uint8] is true iff the first value is less than the second value 
 
156
      as unsigned int
 
157
   *)
 
158
val le_uint8 : uint8 -> uint8 -> bool
 
159
val gt_uint8 : uint8 -> uint8 -> bool
 
160
val ge_uint8 : uint8 -> uint8 -> bool
 
161
  (** Other comparisons *)
 
162
 
 
163
 
 
164
module type ENCDEC = sig
 
165
  (** Encode/decode numbers as strings. These functions exist in two
 
166
      flavors:
 
167
      - {!Netnumber.BE} implements network byte order (big endian)
 
168
      - {!Netnumber.LE} implements little endian
 
169
   *)
 
170
 
 
171
  val read_int4 : string -> int -> int4
 
172
  val read_int8 : string -> int -> int8
 
173
  val read_uint4 : string -> int -> uint4
 
174
  val read_uint8 : string -> int -> uint8
 
175
    (** [read_]<t> create integer values from the characters found at a
 
176
        certain position in the string. Raises [Out_of_range] if the position
 
177
        is bad
 
178
     *)
 
179
 
 
180
  val read_int4_unsafe : string -> int -> int4
 
181
  val read_int8_unsafe : string -> int -> int8
 
182
  val read_uint4_unsafe : string -> int -> uint4
 
183
  val read_uint8_unsafe : string -> int -> uint8
 
184
    (** Same, but no index check *)
 
185
 
 
186
  val write_int4 : string -> int -> int4 -> unit
 
187
  val write_int8 : string -> int -> int8 -> unit
 
188
  val write_uint4 : string -> int -> uint4 -> unit
 
189
  val write_uint8 : string -> int -> uint8 -> unit
 
190
    (** [write_]<t> copies the characters corresponding to the integer values 
 
191
        into the string at the given positions. Raises [Out_of_range] if the
 
192
        position is bad. 
 
193
     *)
 
194
 
 
195
  val write_int4_unsafe : string -> int -> int4 -> unit
 
196
  val write_int8_unsafe : string -> int -> int8 -> unit
 
197
  val write_uint4_unsafe : string -> int -> uint4 -> unit
 
198
  val write_uint8_unsafe : string -> int -> uint8 -> unit
 
199
    (** [write_]<t>[_unsafe]: Same, but no index check. *)
 
200
 
 
201
 
 
202
  val int4_as_string : int4 -> string
 
203
  val int8_as_string : int8 -> string
 
204
  val uint4_as_string : uint4 -> string
 
205
  val uint8_as_string : uint8 -> string
 
206
    (** <t>[_as_string]: Returns the corresponding string for an integer value
 
207
     *)
 
208
 
 
209
  val fp4_as_string : fp4 -> string
 
210
  val fp8_as_string : fp8 -> string
 
211
    
 
212
  val read_fp4 : string -> int -> fp4
 
213
  val read_fp8 : string -> int -> fp8
 
214
    
 
215
end
 
216
 
 
217
 
 
218
module BE : ENCDEC
 
219
  (** Encoders/decoders for big endian - network byte order *)
 
220
 
 
221
module LE : ENCDEC
 
222
  (** Encoders/decoders for little endian *)
 
223
 
 
224
module HO : ENCDEC
 
225
  (** Encoders/decoders for host byte order - which is either little
 
226
      endian or big endian, depending on the CPU (or CPU mode)
 
227
   *)