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