+** There is the new notion of 'discouraged' features.
+
+This is a milder form of deprecation.
+
+Things that are discouraged should not be used in new code, but it is
+OK to leave them in old code for now. When a discouraged feature is
+used, no warning message is printed like there is for 'deprecated'
+features. Also, things that are merely discouraged are nevertheless
+implemented efficiently, while deprecated features can be very slow.
+
+You can omit discouraged features from libguile by configuring it with
+the '--disable-discouraged' option.
+
+** A new family of functions for converting between C values and
+ Scheme values has been added.
+
+These functions follow a common naming scheme and are designed to be
+easier to use, thread-safe and more future-proof than the older
+alternatives.
+
+ - int scm_is_* (...)
+
+ These are predicates that return a C boolean: 1 or 0. Instead of
+ SCM_NFALSEP, you can now use scm_is_true, for example.
+
+ - <type> scm_to_<type> (SCM val, ...)
+
+ These are functions that convert a Scheme value into an appropriate
+ C value. For example, you can use scm_to_int to safely convert from
+ a SCM to an int.
+
+ - SCM scm_from_<type>) (<type> val, ...)
+
+ These functions convert from a C type to a SCM value; for example,
+ scm_from_int for ints.
+
+There is a huge number of these functions, for numbers, strings,
+symbols, vectors, etc. They are documented in the reference manual in
+the API section together with the types that they apply to.
+
+** New functions for dealing with complex numbers in C have been added.
+
+The new functions are scm_c_make_rectangular, scm_c_make_polar,
+scm_c_real_part, scm_c_imag_part, scm_c_magnitude and scm_c_angle.
+They work like scm_make_rectangular etc but take or return doubles
+directly.
+
+** The function scm_make_complex has been discouraged.
+
+Use scm_c_make_rectangular instead.
+
+** The INUM macros have been deprecated.
+
+A lot of code uses these macros to do general integer conversions,
+although the macros only work correctly with fixnums. Use the
+following alternatives.
+
+ SCM_INUMP -> scm_is_integer or similar
+ SCM_NINUMP -> !scm_is_integer or similar
+ SCM_MAKINUM -> scm_from_int or similar
+ SCM_INUM -> scm_to_int or similar
+
+ SCM_VALIDATE_INUM_* -> Do not use these; scm_to_int, etc. will
+ do the validating for you.
+
+** The scm_num2<type> and scm_<type>2num functions and scm_make_real
+ have been discouraged.
+
+Use the newer scm_to_<type> and scm_from_<type> functions instead for
+new code. The functions have been discouraged since they don't fit
+the naming scheme.
+
+** The 'boolean' macros SCM_FALSEP etc have been discouraged.
+
+They have strange names, especially SCM_NFALSEP, and SCM_BOOLP
+evaluates its argument twice. Use scm_is_true, etc. instead for new
+code.
+
+** The macro SCM_EQ_P has been discouraged.
+
+Use scm_is_eq for new code, which fits better into the naming
+conventions.
+
+** The macros SCM_CONSP, SCM_NCONSP, SCM_NULLP, and SCM_NNULLP have
+ been discouraged.
+
+Use the function scm_is_pair or scm_is_null instead.
+
+** The functions scm_round and scm_truncate have been deprecated and
+ are now available as scm_c_round and scm_c_truncate, respectively.
+
+These functions occupy the names that scm_round_number and
+scm_truncate_number should have.
+
+** The functions scm_c_string2str, scm_c_substring2str, and
+ scm_c_symbol2str have been deprecated.
+
+Use scm_to_locale_stringbuf or similar instead, maybe together with
+scm_substring.
+
+** New functions scm_c_make_string, scm_c_string_length,
+ scm_c_string_ref, scm_c_string_set_x, scm_c_substring,
+ scm_c_substring_shared, scm_c_substring_copy.
+
+These are like scm_make_string, scm_length, etc. but are slightly
+easier to use from C.
+
+** The macros SCM_STRINGP, SCM_STRING_CHARS, SCM_STRING_LENGTH,
+ SCM_SYMBOL_CHARS, and SCM_SYMBOL_LENGTH have been deprecated.
+
+They export too many assumptions about the implementation of strings
+and symbols that are no longer true in the presence of
+mutation-sharing substrings and when Guile switches to some form of
+Unicode.
+
+When working with strings, it is often best to use the normal string
+functions provided by Guile, such as scm_c_string_ref,
+scm_c_string_set_x, scm_string_append, etc. Be sure to look in the
+manual since many more such functions are now provided than
+previously.
+
+When you want to convert a SCM string to a C string, use the
+scm_to_locale_string function or similar instead. For symbols, use
+scm_symbol_to_string and then work with that string. Because of the
+new string representation, scm_symbol_to_string does not need to copy
+and is thus quite efficient.
+
+** Some string, symbol and keyword functions have been discouraged.
+
+They don't fit into the uniform naming scheme and are not explicit
+about the character encoding.
+
+Replace according to the following table:
+
+ scm_allocate_string -> scm_c_make_string
+ scm_take_str -> scm_take_locale_stringn
+ scm_take0str -> scm_take_locale_string
+ scm_mem2string -> scm_from_locale_stringn
+ scm_str2string -> scm_from_locale_string
+ scm_makfrom0str -> scm_from_locale_string
+ scm_mem2symbol -> scm_from_locale_symboln
+ scm_mem2uninterned_symbol -> scm_from_locale_stringn + scm_make_symbol
+ scm_str2symbol -> scm_from_locale_symbol
+
+ SCM_SYMBOL_HASH -> scm_hashq
+ SCM_SYMBOL_INTERNED_P -> scm_symbol_interned_p
+
+ scm_c_make_keyword -> scm_from_locale_keyword
+
+** The functions scm_keyword_to_symbol and sym_symbol_to_keyword are
+ now also available to C code.
+
+** SCM_KEYWORDP and SCM_KEYWORDSYM have been deprecated.
+
+Use scm_is_keyword and scm_keyword_to_symbol instead, but note that
+the latter returns the true name of the keyword, not the 'dash name',
+as SCM_KEYWORDSYM used to do.
+
+** SCM_CELL_WORD_LOC has been deprecated.
+
+Use the new macro SCM_CELL_OBJECT_LOC instead, which returns a pointer
+to a SCM, as opposed to a pointer to a scm_t_bits.
+
+This was done to allow the correct use of pointers into the Scheme
+heap. Previously, the heap words were of type scm_t_bits and local
+variables and function arguments were of type SCM, making it
+non-standards-conformant to have a pointer that can point to both.
+
+** New macros SCM_SMOB_DATA_2, SCM_SMOB_DATA_3, etc.
+
+These macros should be used instead of SCM_CELL_WORD_2/3 to access the
+second and third words of double smobs. Likewise for
+SCM_SET_SMOB_DATA_2 and SCM_SET_SMOB_DATA_3.
+
+Also, there is SCM_SMOB_FLAGS and SCM_SET_SMOB_FLAGS that should be
+used to get and set the 16 exra bits in the zeroth word of a smob.
+
+And finally, there is SCM_SMOB_OBJECT and SCM_SMOB_SET_OBJECT for
+accesing the first immediate word of a smob as a SCM value, and there
+is SCM_SMOB_OBJECT_LOC for getting a pointer to the first immediate
+smob word. Like wise for SCM_SMOB_OBJECT_2, etc.
+
+** New way to deal with non-local exits and re-entries.
+
+There is a new set of functions that essentially do what
+scm_internal_dynamic_wind does, but in a way that is more convenient
+for C code in some situations. Here is a quick example of how to
+prevent a potential memory leak:
+
+ void
+ foo ()
+ {
+ char *mem;
+
+ scm_frame_begin (0);
+
+ mem = scm_malloc (100);
+ scm_frame_unwind_handler (free, mem, SCM_F_WIND_EXPLICITELY);
+
+ /* MEM would leak if BAR throws an error.
+ SCM_FRAME_UNWIND_HANDLER frees it nevertheless.
+ */
+
+ bar ();
+
+ scm_frame_end ();
+
+ /* Because of SCM_F_WIND_EXPLICITELY, MEM will be freed by
+ SCM_FRAME_END as well.
+ */
+ }
+
+For full documentation, see the node "Frames" in the manual.
+
+** New function scm_frame_free
+
+This function calls 'free' on a given pointer when a frame is left.
+Thus the call to scm_frame_unwind_handler above could be replaced with
+simply scm_frame_free (mem).
+
+** New way to block and unblock asyncs
+
+In addition to scm_c_call_with_blocked_asyncs you can now also use
+scm_frame_block_asyncs in a 'frame' (see above). Likewise for
+scm_c_call_with_unblocked_asyncs and scm_frame_unblock_asyncs.
+
+** New way to temporarily set the current input, output or error ports
+
+C code can now use scm_frame_current_<foo>_port in a 'frame' (see
+above). <foo> is one of "input", "output" or "error".
+
+** New way to temporarily set fluids
+
+C code can now use scm_frame_fluid in a 'frame' (see
+above) to temporarily set the value of a fluid.
+
+** New types scm_t_intmax and scm_t_uintmax.
+
+On platforms that have them, these types are identical to intmax_t and
+uintmax_t, respectively. On other platforms, they are identical to
+the largest integer types that Guile knows about.
+
+** The functions scm_unmemocopy and scm_unmemoize have been removed.
+
+You should not have used them.
+
+** Many public #defines with generic names have been made private.
+
+#defines with generic names like HAVE_FOO or SIZEOF_FOO have been made
+private or renamed with a more suitable public name.
+
+** The macro SCM_TYP16S has been deprecated.
+
+This macro is not intended for public use.
+
+** The macro SCM_SLOPPY_INEXACTP has been deprecated.
+
+Use scm_is_true (scm_inexact_p (...)) instead.
+
+** The macro SCM_SLOPPY_REALP has been deprecated.
+
+Use scm_is_real instead.
+
+** The macro SCM_SLOPPY_COMPLEXP has been deprecated.
+
+Use scm_is_complex instead.
+
+** Some preprocessor defines have been deprecated.
+
+These defines indicated whether a certain feature was present in Guile
+or not. Going forward, assume that the features are always present.
+
+The macros are: USE_THREADS, GUILE_ISELECT, READER_EXTENSIONS,
+DEBUG_EXTENSIONS, DYNAMIC_LINKING.
+
+The following macros have been removed completely: MEMOIZE_LOCALS,
+SCM_RECKLESS, SCM_CAUTIOUS.
+
+** The preprocessor define STACK_DIRECTION has been deprecated.
+
+There should be no need to know about the stack direction for ordinary
+programs.
+
HCoop / bpt / guile.git / blobdiff