1------------------------------------------------------------------------------
2-- |
3-- Module:      Blaze.ByteString.Builder.Int
4-- Copyright:   (c) 2013 Leon P Smith
5-- License:     BSD3
6-- Maintainer:  Leon P Smith <leon@melding-monads.com>
7-- Stability:   experimental
8--
9-- 'Write's and 'Builder's for serializing integers.
10--
11-- See "Blaze.ByteString.Builder.Word" for information about how to best write several
12-- integers at once.
13--
14------------------------------------------------------------------------------
15
16module Blaze.ByteString.Builder.Int
17    (
18    -- * Writing integers to a buffer
19
20      writeInt8
21
22    -- ** Big-endian writes
23    , writeInt16be           -- :: Int16 -> Write
24    , writeInt32be           -- :: Int32 -> Write
25    , writeInt64be           -- :: Int64 -> Write
26
27    -- ** Little-endian writes
28    , writeInt16le           -- :: Int16 -> Write
29    , writeInt32le           -- :: Int32 -> Write
30    , writeInt64le           -- :: Int64 -> Write
31
32    -- ** Host-endian writes
33    , writeInthost           -- :: Int -> Write
34    , writeInt16host         -- :: Int16 -> Write
35    , writeInt32host         -- :: Int32 -> Write
36    , writeInt64host         -- :: Int64 -> Write
37
38    -- * Creating builders from integers
39
40    -- | We provide serialization functions both for singleton integers as well as
41    -- for lists of integers. Using these list serialization functions is /much/ faster
42    -- than using @mconcat . map fromInt/<n/>@, as the list serialization
43    -- functions use a tighter inner loop.
44
45    , fromInt8
46    , fromInt8s
47
48    -- ** Big-endian serialization
49    , fromInt16be            -- :: Int16   -> Builder
50    , fromInt32be            -- :: Int32   -> Builder
51    , fromInt64be            -- :: Int64   -> Builder
52    , fromInt32sbe           -- :: [Int32] -> Builder
53    , fromInt16sbe           -- :: [Int16] -> Builder
54    , fromInt64sbe           -- :: [Int64] -> Builder
55
56    -- ** Little-endian serialization
57    , fromInt16le            -- :: Int16   -> Builder
58    , fromInt32le            -- :: Int32   -> Builder
59    , fromInt64le            -- :: Int64   -> Builder
60    , fromInt16sle           -- :: [Int16] -> Builder
61    , fromInt32sle           -- :: [Int32] -> Builder
62    , fromInt64sle           -- :: [Int64] -> Builder
63
64    -- ** Host-endian serialization
65    , fromInthost            -- :: Int     -> Builder
66    , fromInt16host          -- :: Int16   -> Builder
67    , fromInt32host          -- :: Int32   -> Builder
68    , fromInt64host          -- :: Int64   -> Builder
69    , fromIntshost           -- :: [Int]   -> Builder
70    , fromInt16shost         -- :: [Int16] -> Builder
71    , fromInt32shost         -- :: [Int32] -> Builder
72    , fromInt64shost         -- :: [Int64] -> Builder
73
74    ) where
75
76import Data.Int
77import Blaze.ByteString.Builder.Compat.Write ( Write, writePrimFixed )
78import Data.ByteString.Builder ( Builder )
79import qualified Data.ByteString.Builder       as B
80import qualified Data.ByteString.Builder.Extra as B
81import qualified Data.ByteString.Builder.Prim  as P
82
83-- | Write a single signed byte.
84--
85writeInt8      :: Int8 -> Write
86writeInt8 = writePrimFixed P.int8
87{-# INLINE writeInt8 #-}
88
89-- | Write an 'Int16' in big endian format.
90writeInt16be   :: Int16 -> Write
91writeInt16be = writePrimFixed P.int16BE
92{-# INLINE writeInt16be #-}
93
94-- | Write an 'Int32' in big endian format.
95writeInt32be   :: Int32 -> Write
96writeInt32be = writePrimFixed P.int32BE
97{-# INLINE writeInt32be #-}
98
99-- | Write an 'Int64' in big endian format.
100writeInt64be   :: Int64 -> Write
101writeInt64be = writePrimFixed P.int64BE
102{-# INLINE writeInt64be #-}
103
104-- | Write an 'Int16' in little endian format.
105writeInt16le   :: Int16 -> Write
106writeInt16le = writePrimFixed P.int16LE
107{-# INLINE writeInt16le #-}
108
109-- | Write an 'Int32' in little endian format.
110writeInt32le   :: Int32 -> Write
111writeInt32le = writePrimFixed P.int32LE
112{-# INLINE writeInt32le #-}
113
114-- | Write an 'Int64' in little endian format.
115writeInt64le   :: Int64 -> Write
116writeInt64le = writePrimFixed P.int64LE
117{-# INLINE writeInt64le #-}
118
119-- | Write a single native machine 'Int'. The 'Int' is written in host order,
120-- host endian form, for the machine you're on. On a 64 bit machine the 'Int'
121-- is an 8 byte value, on a 32 bit machine, 4 bytes. Values written this way
122-- are not portable to different endian or integer sized machines, without
123-- conversion.
124--
125writeInthost   :: Int -> Write
126writeInthost = writePrimFixed P.intHost
127{-# INLINE writeInthost #-}
128
129-- | Write an 'Int16' in native host order and host endianness.
130writeInt16host :: Int16 -> Write
131writeInt16host = writePrimFixed P.int16Host
132{-# INLINE writeInt16host #-}
133
134-- | Write an 'Int32' in native host order and host endianness.
135writeInt32host :: Int32 -> Write
136writeInt32host = writePrimFixed P.int32Host
137{-# INLINE writeInt32host #-}
138
139-- | Write an 'Int64' in native host order and host endianness.
140writeInt64host :: Int64 -> Write
141writeInt64host = writePrimFixed P.int64Host
142{-# INLINE writeInt64host #-}
143
144-- | Serialize a single byte.
145fromInt8       :: Int8    -> Builder
146fromInt8 = B.int8
147{-# INLINE fromInt8 #-}
148
149-- | Serialize a list of bytes.
150fromInt8s      :: [Int8]  -> Builder
151fromInt8s = P.primMapListFixed P.int8
152{-# INLINE fromInt8s #-}
153
154-- | Serialize an 'Int16' in big endian format.
155fromInt16be    :: Int16   -> Builder
156fromInt16be = B.int16BE
157{-# INLINE fromInt16be #-}
158
159-- | Serialize an 'Int32' in big endian format.
160fromInt32be    :: Int32   -> Builder
161fromInt32be = B.int32BE
162{-# INLINE fromInt32be #-}
163
164-- | Serialize an 'Int64' in big endian format.
165fromInt64be    :: Int64   -> Builder
166fromInt64be = B.int64BE
167{-# INLINE fromInt64be #-}
168
169-- | Serialize a list of 'Int32's in big endian format.
170fromInt32sbe   :: [Int32] -> Builder
171fromInt32sbe = P.primMapListFixed P.int32BE
172{-# INLINE fromInt32sbe #-}
173
174-- | Serialize a list of 'Int16's in big endian format.
175fromInt16sbe   :: [Int16] -> Builder
176fromInt16sbe = P.primMapListFixed P.int16BE
177{-# INLINE fromInt16sbe #-}
178
179-- | Serialize a list of 'Int64's in big endian format.
180fromInt64sbe   :: [Int64] -> Builder
181fromInt64sbe = P.primMapListFixed P.int64BE
182{-# INLINE fromInt64sbe #-}
183
184-- | Serialize an 'Int16' in little endian format.
185fromInt16le    :: Int16   -> Builder
186fromInt16le = B.int16LE
187{-# INLINE fromInt16le #-}
188
189-- | Serialize an 'Int32' in little endian format.
190fromInt32le    :: Int32   -> Builder
191fromInt32le = B.int32LE
192{-# INLINE fromInt32le #-}
193
194-- | Serialize an 'Int64' in little endian format.
195fromInt64le    :: Int64   -> Builder
196fromInt64le = B.int64LE
197{-# INLINE fromInt64le #-}
198
199-- | Serialize a list of 'Int16's in little endian format.
200fromInt16sle   :: [Int16] -> Builder
201fromInt16sle = P.primMapListFixed P.int16LE
202{-# INLINE fromInt16sle #-}
203
204-- | Serialize a list of 'Int32's in little endian format.
205fromInt32sle   :: [Int32] -> Builder
206fromInt32sle = P.primMapListFixed P.int32LE
207{-# INLINE fromInt32sle #-}
208
209-- | Serialize a list of 'Int64's in little endian format.
210fromInt64sle   :: [Int64] -> Builder
211fromInt64sle = P.primMapListFixed P.int64LE
212{-# INLINE fromInt64sle #-}
213
214-- | Serialize a single native machine 'Int'. The 'Int' is serialized in host
215-- order, host endian form, for the machine you're on. On a 64 bit machine the
216-- 'Int' is an 8 byte value, on a 32 bit machine, 4 bytes. Values written this
217-- way are not portable to different endian or integer sized machines, without
218-- conversion.
219--
220fromInthost    :: Int     -> Builder
221fromInthost = B.intHost
222{-# INLINE fromInthost #-}
223
224-- | Write an 'Int16' in native host order and host endianness.
225fromInt16host  :: Int16   -> Builder
226fromInt16host = B.int16Host
227{-# INLINE fromInt16host #-}
228
229-- | Write an 'Int32' in native host order and host endianness.
230fromInt32host  :: Int32   -> Builder
231fromInt32host = B.int32Host
232{-# INLINE fromInt32host #-}
233
234-- | Write an 'Int64' in native host order and host endianness.
235fromInt64host  :: Int64   -> Builder
236fromInt64host = B.int64Host
237{-# INLINE fromInt64host #-}
238
239-- | Serialize a list of 'Int's.
240-- See 'fromInthost' for usage considerations.
241fromIntshost   :: [Int]   -> Builder
242fromIntshost = P.primMapListFixed P.intHost
243{-# INLINE fromIntshost #-}
244
245-- | Write a list of 'Int16's in native host order and host endianness.
246fromInt16shost :: [Int16] -> Builder
247fromInt16shost = P.primMapListFixed P.int16Host
248{-# INLINE fromInt16shost #-}
249
250-- | Write a list of 'Int32's in native host order and host endianness.
251fromInt32shost :: [Int32] -> Builder
252fromInt32shost = P.primMapListFixed P.int32Host
253{-# INLINE fromInt32shost #-}
254
255-- | Write a list of 'Int64's in native host order and host endianness.
256fromInt64shost :: [Int64] -> Builder
257fromInt64shost = P.primMapListFixed P.int64Host
258{-# INLINE fromInt64shost #-}
259