libguile/discouraged.h

   1 /* This file contains definitions for discouraged features.  When you
   2    discourage something, move it here when that is feasible.
   3
   4    A discouraged feature is one that shouldn't be used in new code
   5    since we have a better alternative now.  However, there is nothing
   6    wrong with using the old feature, so it is OK to continue to use
   7    it.
   8
   9    Eventually, discouraged features can be deprecated since removing
  10    them will make Guile simpler.
  11 */
  12
  13 #ifndef SCM_DISCOURAGED_H
  14 #define SCM_DISCOURAGED_H
  15
  16 /* Copyright (C) 2004, 2006 Free Software Foundation, Inc.
  17  *
  18  * This library is free software; you can redistribute it and/or
  19  * modify it under the terms of the GNU Lesser General Public License
  20  * as published by the Free Software Foundation; either version 3 of
  21  * the License, or (at your option) any later version.
  22  *
  23  * This library is distributed in the hope that it will be useful, but
  24  * WITHOUT ANY WARRANTY; without even the implied warranty of
  25  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  26  * Lesser General Public License for more details.
  27  *
  28  * You should have received a copy of the GNU Lesser General Public
  29  * License along with this library; if not, write to the Free Software
  30  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  31  * 02110-1301 USA
  32  */
  33
  34 #include "libguile/__scm.h"
  35
  36 #if SCM_ENABLE_DISCOURAGED == 1
  37
  38 /* Discouraged because they do not follow the naming convention.  That
  39    is, they end in "P" but return a C boolean.  Also, SCM_BOOLP
  40    evaluates its argument twice.
  41 */
  42
  43 #define SCM_FALSEP              scm_is_false
  44 #define SCM_NFALSEP             scm_is_true
  45 #define SCM_BOOLP               scm_is_bool
  46 #define SCM_EQ_P                scm_is_eq
  47
  48
  49 /* Convert from a C boolean to a SCM boolean value */
  50 #define SCM_BOOL                scm_from_bool
  51
  52 /* Convert from a C boolean to a SCM boolean value and negate it */
  53 #define SCM_NEGATE_BOOL(f)      scm_from_bool(!(f))
  54
  55 /* SCM_BOOL_NOT returns the other boolean.
  56  * The order of ^s here is important for Borland C++ (!?!?!)
  57  */
  58 #define SCM_BOOL_NOT(x)         (SCM_PACK (SCM_UNPACK (x) \
  59                                            ^ (SCM_UNPACK (SCM_BOOL_T) \
  60                                               ^ SCM_UNPACK (SCM_BOOL_F))))
  61
  62 /* scm_to_int, scm_from_int are the official functions to do the job,
  63    but there is nothing wrong with using scm_num2int, etc.
  64
  65    These could be trivially defined via macros, but we leave them as
  66    functions since existing code may take their addresses.
  67 */
  68
  69 SCM_API SCM scm_short2num (short n);
  70 SCM_API SCM scm_ushort2num (unsigned short n);
  71 SCM_API SCM scm_int2num (int n);
  72 SCM_API SCM scm_uint2num (unsigned int n);
  73 SCM_API SCM scm_long2num (long n);
  74 SCM_API SCM scm_ulong2num (unsigned long n);
  75 SCM_API SCM scm_size2num (size_t n);
  76 SCM_API SCM scm_ptrdiff2num (scm_t_ptrdiff n);
  77 SCM_API short scm_num2short (SCM num, unsigned long int pos,
  78                              const char *s_caller);
  79 SCM_API unsigned short scm_num2ushort (SCM num, unsigned long int pos,
  80                                        const char *s_caller);
  81 SCM_API int scm_num2int (SCM num, unsigned long int pos,
  82                          const char *s_caller);
  83 SCM_API unsigned int scm_num2uint (SCM num, unsigned long int pos,
  84                                    const char *s_caller);
  85 SCM_API long scm_num2long (SCM num, unsigned long int pos,
  86                            const char *s_caller);
  87 SCM_API unsigned long scm_num2ulong (SCM num, unsigned long int pos,
  88                                      const char *s_caller);
  89 SCM_API scm_t_ptrdiff scm_num2ptrdiff (SCM num, unsigned long int pos,
  90                                        const char *s_caller);
  91 SCM_API size_t scm_num2size (SCM num, unsigned long int pos,
  92                              const char *s_caller);
  93 #if SCM_SIZEOF_LONG_LONG != 0
  94 SCM_API SCM scm_long_long2num (long long sl);
  95 SCM_API SCM scm_ulong_long2num (unsigned long long sl);
  96 SCM_API long long scm_num2long_long (SCM num, unsigned long int pos,
  97                                      const char *s_caller);
  98 SCM_API unsigned long long scm_num2ulong_long (SCM num, unsigned long int pos,
  99                                                const char *s_caller);
 100 #endif
 101
 102 SCM_API SCM scm_make_real (double x);
 103 SCM_API double scm_num2dbl (SCM a, const char * why);
 104 SCM_API SCM scm_float2num (float n);
 105 SCM_API SCM scm_double2num (double n);
 106
 107 /* The next two are implemented in numbers.c since they use features
 108    only available there.
 109 */
 110 SCM_API float scm_num2float (SCM num, unsigned long int pos,
 111                              const char *s_caller);
 112 SCM_API double scm_num2double (SCM num, unsigned long int pos,
 113                                const char *s_caller);
 114
 115 SCM_API SCM scm_make_complex (double x, double y);
 116
 117 /* Discouraged because they don't make the encoding explicit.
 118  */
 119
 120 SCM_API SCM scm_mem2symbol (const char *mem, size_t len);
 121 SCM_API SCM scm_mem2uninterned_symbol (const char *mem, size_t len);
 122 SCM_API SCM scm_str2symbol (const char *str);
 123
 124 SCM_API SCM scm_take_str (char *s, size_t len);
 125 SCM_API SCM scm_take0str (char *s);
 126 SCM_API SCM scm_mem2string (const char *src, size_t len);
 127 SCM_API SCM scm_str2string (const char *src);
 128 SCM_API SCM scm_makfrom0str (const char *src);
 129 SCM_API SCM scm_makfrom0str_opt (const char *src);
 130
 131 /* Discouraged because scm_c_make_string has a better name and is more
 132    consistent with make-string.
 133  */
 134 SCM_API SCM scm_allocate_string (size_t len);
 135
 136 /* Discouraged because scm_is_symbol has a better name,
 137  */
 138 #define SCM_SYMBOLP scm_is_symbol
 139
 140 /* Discouraged because the alternatives have the better names.
 141  */
 142 #define SCM_SYMBOL_FUNC             scm_symbol_fref
 143 #define SCM_SET_SYMBOL_FUNC         scm_symbol_fset_x
 144 #define SCM_SYMBOL_PROPS            scm_symbol_pref
 145 #define SCM_SET_SYMBOL_PROPS        scm_symbol_pset_x
 146
 147 /* Discouraged because there are better ways.
 148  */
 149 #define SCM_SYMBOL_HASH             scm_i_symbol_hash
 150 #define SCM_SYMBOL_INTERNED_P(X)    scm_i_symbol_is_interned
 151
 152 /* Discouraged because they evaluated their arguments twice and/or
 153    don't fit the naming scheme.
 154 */
 155
 156 #define SCM_CONSP(x)            (scm_is_pair (x))
 157 #define SCM_NCONSP(x)           (!SCM_CONSP (x))
 158 #define SCM_NULLP(x)            (scm_is_null (x))
 159 #define SCM_NNULLP(x)           (!scm_is_null (x))
 160
 161 /* Discouraged because they are just strange.
 162  */
 163
 164 SCM_API SCM scm_make_keyword_from_dash_symbol (SCM symbol);
 165 SCM_API SCM scm_keyword_dash_symbol (SCM keyword);
 166
 167 /* Discouraged because it does not state what encoding S is in.
 168  */
 169
 170 SCM_API SCM scm_c_make_keyword (const char *s);
 171
 172 /* Discouraged because the 'internal' and 'thread' moniker is
 173    confusing.
 174  */
 175
 176 #define scm_internal_select scm_std_select
 177 #define scm_thread_sleep    scm_std_sleep
 178 #define scm_thread_usleep   scm_std_usleep
 179
 180 void scm_i_init_discouraged (void);
 181
 182 #endif /* SCM_ENABLE_DISCOURAGED == 1 */
 183
 184 #endif /* SCM_DISCOURAGED_H */