Fix yaz URL
[yaz-moved-to-github.git] / include / yaz / nmem.h
1 /* This file is part of the YAZ toolkit.
2  * Copyright (C) 1995-2010 Index Data.
3  * All rights reserved.
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  *
7  *     * Redistributions of source code must retain the above copyright
8  *       notice, this list of conditions and the following disclaimer.
9  *     * Redistributions in binary form must reproduce the above copyright
10  *       notice, this list of conditions and the following disclaimer in the
11  *       documentation and/or other materials provided with the distribution.
12  *     * Neither the name of Index Data nor the names of its contributors
13  *       may be used to endorse or promote products derived from this
14  *       software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  */
27
28 /**
29  * \file
30  * \brief Header for Nibble Memory functions
31  *
32  * This is a simple and fairly wasteful little module for nibble memory
33  * allocation. Eventually we'll put in something better.
34  */
35 #ifndef NMEM_H
36 #define NMEM_H
37
38 #include <stddef.h>
39 #include <yaz/yconfig.h>
40
41 YAZ_BEGIN_CDECL
42
43 /** \brief NMEM handle (an opaque pointer to memory) */
44 typedef struct nmem_control *NMEM;
45
46 /** \brief Set to 1 if YAZ BER integer is 64-bit ; 0 otherwise */
47 #ifndef NMEM_64
48 #define NMEM_64 1
49 #endif
50
51 #if NMEM_64
52
53 #ifdef _MSC_VER
54 /* Visual Studio. 6.0 and later supports this */
55 typedef __int64 nmem_int_t;
56 #define NMEM_INT_PRINTF "%I64d"
57 #else
58 /* C99 */
59 typedef long long int nmem_int_t;
60 #define NMEM_INT_PRINTF "%lld"
61 #endif
62
63 #else
64 /** \brief BER/utility integer (32-bit on most platforms) */
65 typedef int nmem_int_t;
66 /** \brief printf format for nmem_int_t type */
67 #define NMEM_INT_PRINTF "%d"
68 #endif
69
70 /** \brief BER/utility boolean */
71 typedef int nmem_bool_t;
72
73 /** \brief releases memory associaged with an NMEM handle 
74     \param n NMEM handle
75 */
76 YAZ_EXPORT void nmem_reset(NMEM n);
77
78 /** \brief returns size in bytes of memory for NMEM handle
79     \returns number of bytes
80  */
81 YAZ_EXPORT size_t nmem_total(NMEM n);
82
83 /** \brief allocates string on NMEM handle (similar strdup) 
84     \param mem HNEM handle
85     \param src string
86     \returns duplicated string
87  */
88 YAZ_EXPORT char *nmem_strdup(NMEM mem, const char *src);
89 /** \brief allocates string on NMEM handle - allows NULL ptr buffer
90     \param mem HNEM handle
91     \param src string
92     \returns duplicated string or NULL if src was NULL
93  */
94 YAZ_EXPORT char *nmem_strdup_null(NMEM mem, const char *src);
95
96 /** \brief allocates string of certain size on NMEM handle
97     \param mem NMEM handle
98     \param src string
99     \param n size of string
100     \returns duplicated string (0 terminated)
101  */
102 YAZ_EXPORT char *nmem_strdupn(NMEM mem, const char *src, size_t n);
103
104 /** \brief allocates sub strings out of string using certain delimitors
105     \param nmem NMEM handle
106     \param delim delimitor chars (splits on each char in there) 
107     \param dstr string to be split
108     \param darray result string array for each sub string
109     \param num number of result strings
110 */
111 YAZ_EXPORT void nmem_strsplit(NMEM nmem, const char *delim,
112                               const char *dstr,
113                               char ***darray, int *num);
114
115 /** \brief splits string into sub strings delimited by blanks
116     \param nmem NMEM handle
117     \param dstr string to be split
118     \param darray result string array for each sub string
119     \param num number of result strings
120 */
121 YAZ_EXPORT void nmem_strsplit_blank(NMEM nmem, const char *dstr,
122                                     char ***darray, int *num);
123
124 /** \brief allocates and sets integer for NMEM
125     \param nmem NMEM handle
126     \param v integer value
127     \returns pointer to created integer
128 */
129 YAZ_EXPORT nmem_int_t *nmem_intdup(NMEM nmem, nmem_int_t v);
130
131 /** \brief allocates and sets boolean for NMEM
132     \param nmem NMEM handle
133     \param v value (0=false, != 0 true)
134     \returns pointer to created boolean
135 */
136 YAZ_EXPORT nmem_bool_t *nmem_booldup(NMEM nmem, nmem_bool_t v);
137
138 /** \brief transfers memory from one NMEM handle to another
139     \param src source NMEM handle
140     \param dst destination NMEM handle
141  */
142 YAZ_EXPORT void nmem_transfer(NMEM dst, NMEM src);
143
144 /** \brief returns new NMEM handle 
145     \returns NMEM handle
146  */
147 YAZ_EXPORT NMEM nmem_create(void);
148
149 /** \brief destroys NMEM handle and memory associated with it
150     \param n NMEM handle
151  */
152 YAZ_EXPORT void nmem_destroy(NMEM n);
153
154 /** \brief allocates memory block on NMEM handle
155     \param n NMEM handle
156     \param size number of bytes to be allocated
157     \returns pointer to allocated memory
158  */
159 YAZ_EXPORT void *nmem_malloc(NMEM n, size_t size);
160
161 YAZ_END_CDECL
162
163 #endif
164 /*
165  * Local variables:
166  * c-basic-offset: 4
167  * c-file-style: "Stroustrup"
168  * indent-tabs-mode: nil
169  * End:
170  * vim: shiftwidth=4 tabstop=8 expandtab
171  */
172