From 8a9d0e13bbfd821d12d0a0ecaec7b2f4fd50e473 Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Sat, 29 Aug 2009 11:15:23 -0500
Subject: [PATCH] deprecate <c-array>, and make malloc-array box its returned
 buffer in a direct array

---
 basis/alien/c-types/c-types-docs.factor         | 10 ++++++----
 basis/alien/c-types/c-types.factor              |  4 ++--
 basis/specialized-arrays/functor/functor.factor |  3 +++
 3 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/basis/alien/c-types/c-types-docs.factor b/basis/alien/c-types/c-types-docs.factor
index f5f9e004c4..e7083a2a3a 100644
--- a/basis/alien/c-types/c-types-docs.factor
+++ b/basis/alien/c-types/c-types-docs.factor
@@ -49,12 +49,11 @@ HELP: c-setter
 { $errors "Throws an error if the type does not exist." } ;
 
 HELP: <c-array>
+{ $deprecated "New code should use " { $link <c-type-array> } " or the " { $vocab-link "specialized-arrays" } " vocabularies." }
 { $values { "n" "a non-negative integer" } { "type" "a C type" } { "array" byte-array } }
 { $description "Creates a byte array large enough to hold " { $snippet "n" } " values of a C type." }
 { $errors "Throws an error if the type does not exist or the requested size is negative." } ;
 
-{ <c-array> malloc-array } related-words
-
 HELP: <c-object>
 { $values { "type" "a C type" } { "array" byte-array } }
 { $description "Creates a byte array suitable for holding a value with the given C type." }
@@ -73,9 +72,10 @@ HELP: byte-array>memory
 
 HELP: malloc-array
 { $values { "n" "a non-negative integer" } { "type" "a C type" } { "alien" alien } }
-{ $description "Allocates an unmanaged memory block large enough to hold " { $snippet "n" } " values of a C type." }
+{ $description "Allocates an unmanaged memory block large enough to hold " { $snippet "n" } " values of a C type, then wraps the memory in a sequence object using " { $link <c-type-direct-array> } "." }
+{ $notes "The appropriate direct specialized array vocabulary must be loaded; otherwise, a " { $link specialized-array-vocab-not-loaded } " error will be thrown. The vocabulary can be loaded with a " { $link POSTPONE: USING: } " form as usual, or with the " { $link require-c-type-arrays } " word. See the " { $vocab-link "specialized-arrays.direct" } " vocabulary set for details on the underlying sequence type constructed." } ;
 { $warning "Don't forget to deallocate the memory with a call to " { $link free } "." }
-{ $errors "Throws an error if the type does not exist, if the requested size is negative, or if memory allocation fails." } ;
+{ $errors "Throws an error if the type does not exist, if the requested size is negative, if a direct specialized array class appropriate to the type is not loaded, or if memory allocation fails." } ;
 
 HELP: malloc-object
 { $values { "type" "a C type" } { "alien" alien } }
@@ -89,6 +89,8 @@ HELP: malloc-byte-array
 { $warning "Don't forget to deallocate the memory with a call to " { $link free } "." }
 { $errors "Throws an error if memory allocation fails." } ;
 
+{ <c-type-array> <c-type-direct-array> malloc-array } related-words
+
 HELP: box-parameter
 { $values { "n" integer } { "ctype" string } }
 { $description "Generates code for converting a C value stored at  offset " { $snippet "n" } " from the top of the stack into a Factor object to be pushed on the data stack." }
diff --git a/basis/alien/c-types/c-types.factor b/basis/alien/c-types/c-types.factor
index 4c3c8d1668..6b56f52232 100755
--- a/basis/alien/c-types/c-types.factor
+++ b/basis/alien/c-types/c-types.factor
@@ -254,13 +254,13 @@ M: f byte-length drop 0 ; inline
     ] unless* ;
 
 : <c-array> ( n type -- array )
-    heap-size * <byte-array> ; inline
+    heap-size * <byte-array> ; inline deprecated
 
 : <c-object> ( type -- array )
     1 swap <c-array> ; inline
 
 : malloc-array ( n type -- alien )
-    heap-size calloc ; inline
+    [ heap-size calloc ] [ <c-type-direct-array> ] 2bi ; inline
 
 : malloc-object ( type -- alien )
     1 swap malloc-array ; inline
diff --git a/basis/specialized-arrays/functor/functor.factor b/basis/specialized-arrays/functor/functor.factor
index 3341a909d2..f5aca7fb95 100644
--- a/basis/specialized-arrays/functor/functor.factor
+++ b/basis/specialized-arrays/functor/functor.factor
@@ -13,6 +13,9 @@ M: bad-byte-array-length summary
 : (c-array) ( n c-type -- array )
     heap-size * (byte-array) ; inline
 
+: <c-array> ( n type -- array )
+    heap-size * <byte-array> ; inline
+
 FUNCTOR: define-array ( T -- )
 
 A            DEFINES-CLASS ${T}-array