[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
gauche.uvector
 Uniform vectorsProvides vectors whose elements are of the same numeric type, as defined in SRFI4 (SRFI4).
Gauche’s implementation is a superset of SRFI4 in a few ways:
TAGvector>list
takes optional start and end indices, and TAGvectorref
takes optional fallback value.
TAGvectorcopy
and
TAGvectorcopy!
), conversion procedures
(TAGvector>vector
and vector>TAGvector
),
and some arithmetic functions (TAGvectoradd
, etc.)
gauche.collection
 Collection framework)
and the sequence framework (See section gauche.sequence
 Sequence framework). So the
methods like map
, foreach
, ref
or subseq
can be used on the SRFI4 vector types.
f16vector
, a vector of 16bit floating point number
as used in highdynamic range image format (1 sign bit, 5 exponent bits,
and 10 mantissa bits).
There are some advantages of using SRFI4 vectors over normal (heterogeneous) vectors. It may be more compact than the normal vectors. Some operations (especially Gauche’s extension of vector arithmetic operations) can bypass type check and conversion of individual elements, thus be more efficient. And it is much easier and efficient to communicate with external libraries that require homogeneous array of numbers; for example, OpenGL binding of Gauche uses SRFI4 vectors extensively.
The following ten types of vectors are defined.
Elements are exact integers in the range between 2^7 and 2^71
Elements are exact integers in the range between 0 and 2^81
Elements are exact integers in the range between 2^15 and 2^151
Elements are exact integers in the range between 0 and 2^161
Elements are exact integers in the range between 2^31 and 2^311
Elements are exact integers in the range between 0 and 2^321
Elements are exact integers in the range between 2^63 and 2^631
Elements are exact integers in the range between 0 and 2^641
Elements are inexact real numbers representable in 16bits float (a.k.a half float)
Elements are inexact real numbers representable in the float
of
C compiler that compiles Gauche. Usually it is a single precision
IEEE floating point number.
Elements are inexact real numbers representable in the double
of
C compiler that compiles Gauche. Usually it is a double precision
IEEE floating point number.
When you try to store a number out of the range of the vector type, an error is signalled by default. However, some procedures take an optional argument clamp that specifies alternative behavior in such a case. Clamp argument may take one of the following values.
#f
Default behavior (signals an error).
high
Clamps high bound; i.e. if the value to be stored is beyond the higher bound of the range, the maximum value is stored instead.
low
Clamps low bound; i.e. if the value to be stored is below the lower bound of the range, the minimum value is stored instead.
both
Clamps both sides; does both high
and low
.
(list>u8vector '(1)) ⇒ error (list>u8vector '(1) 'low) ⇒ #u8(0) (list>u8vector '(1) 'high) ⇒ error (list>u8vector '(3000) 'high) ⇒ #u8(255) (list>u8vector '(100 20 300) 'both) ⇒ #u8(0 20 255) 
In the following description, TAG
can be replaced
for any of s8
, u8
, s16
, u16
,
s32
, u32
, s64
, u64
,
f16
, f32
, f64
.
9.31.1 Uvector basic operations  
9.31.2 Uvector conversion operations  
9.31.3 Uvector numeric operations  
9.31.4 Uvector block I/O 
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
A class for TAGvector. It inherits <sequence>
.
#TAG(n …)
Denotes a literal homogeneous vector.
#s8(3 2 4) #u32(4154 88357 2 323) #f32(3.14 0.554525 3.342) 
[SRFI4]
Returns #t
if obj is a TAGvector, #f
otherwise.
[SRFI4] Constructs TAGvector whose elements are numbers x …. The numbers must be exact integer for exact integer vectors, and in the valid range of the vector.
(s8vector 1 2 3) ⇒ #s8(1 2 3) 
[SRFI4] Constructs a TAGvector of length len. The elements are initialized by a number fill. For exact integer vectors, fill must be an exact integer and in the valid range. If fill is omitted, the content of the vector is undefined.
(makeu8vector 4 0) ⇒ #u8(0 0 0 0) 
[SRFI4] Returns the length of the TAGvector vec.
Note that the generic function sizeof
can be used
to obtain the length of vec as well,
if you import gauche.collection
(See section gauche.collection
 Collection framework).
(s16vectorlength '#s16(111 222 333)) ⇒ 3 (use gauche.collection) (sizeof '#s16(111 222 333)) ⇒ 3 
This function can be applied to any type of uniform vectors, and returns the raw size of the uvector in number of octets.
When start and/or end is/are given, the size of data
between those indices are calculated. The special value 1
for end indicates the end of the vector.
The returned value matches the number of octets to be written out
by (writeblock uvector port start end)
.
(uvectorsize '#u8(1 2 3)) ⇒ 3 (uvectorsize '#u64(1 2 3)) ⇒ 24 (uvectorsize '#u32(0 1 2 3) 2) ⇒ 8 (uvectorsize '#u32(0 1 2 3) 0 1) ⇒ 4 
[SRFI4+] Returns the kth element of TAGvector vec.
If the index k is out of the valid range, an error is signalled unless an optional argument fallback is given; in that case, fallback is returned.
Note that the generic function ref
can be used as well,
if you import gauche.collection
.
(u16vectorref '#u16(111 222 333) 1) ⇒ 222 (use gauche.collection) (ref '#u16(111 222 333) 1) ⇒ 222 
[SRFI4+] Sets a number n to the kth element of TAGvector vec. Optional clamp argument specifies the behavior when n is out of valid range. Default is to signal an error.
Note that the setter of the generic function ref
can be used as well,
if you import gauche.collection
.
(let ((v (s32vector 439 852 8933))) (s32vectorset! v 1 4) v) ⇒ #s32vector(439 4 8933) (use gauche.collection) (let ((v (s32vector 439 852 8933))) (set! (ref v 1) 4) v) ⇒ #s32vector(439 4 8933) 
Stores fill in every element of vec, ranging from start to end of vec, if they are given.
Copies the srfi4 vector vec. If start and/or end are given, they limit the range of vec to be copied.
(u8vectorcopy '#u8(1 2 3 4)) ⇒ #u8(1 2 3 4) (u8vectorcopy '#u8(1 2 3 4) 2) ⇒ #u8(3 4) (u8vectorcopy '#u8(1 2 3 4) 1 3) ⇒ #u8(2 3) 
Both target and source must be TAGvectors, and target must be mutable. This procedure copies the elements of source, beginning from index sstart (inclusive) and up to send, into target, beginning from index tstart. sstart and send may be omitted, and in that case 0 and the length of source are assumed, respectively.
(let ((target (u8vector 0 1 2 3 4 5 6))) (u8vectorcopy! target 2 '#u8(10 11 12 13 14) 1 4) target) ⇒ #u8(0 1 11 12 13 6) 
If the number of elements in the source vector between sstart and send is larger than the target vector beginning from tstart, the excess elements are silently discarded.
Note: This procedure used to take just two uniform vectors, target
and source, and just copies contents of source to target.
Both vectors had to be the same type and same length. The API is revised
to the current form to make it parallel with stringcopy!
(SRFI13)
and vectorcopy!
(SRFI43). The old interface is still supported
for the backward compatibility, but it is deprecated and will be gone
in the future releases.
Using collection and sequence framework, you can perform various operations on the homogeneous vectors.
(use gauche.collection) (use gauche.sequence) (fold + 0 '#s32(1 2 3 4)) ⇒ 10 (mapto <f32vector> * '#f32(3.2 1.1 4.3) '#f32(4.3 2.2 9.4)) ⇒ #f32(13.760001 2.420000 40.420002) (subseq #u32(1 4 3 4 5) 2 4) ⇒ #u32(3 4) 
This is a generic version of TAGvectorcopy!
.
The destination target and the source source can be
any type of uniform vectors, and they don’t need to match.
The copy is done bitbybit. So if you copy to a different type
of uvector, the result depends on how the numbers are represented
internally. This is mainly to manipulate binary data.
Tstart is interpreted according to the type of target, and sstart and send are interpreted according to the type of source.
(rlet1 v (makeu8vector 6 0) (uvectorcopy! v 1 '#u32(0 #x01020304 0) 1 2)) ⇒ #u8(0 1 2 3 4 0) or #u8(0 4 3 2 1 0) 
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
[SRFI4+] Converts TAGvector vec to a list. If start and/or end are given, they limit the range of vec to be extracted.
Note that the generic function coerceto
can be used as well,
if you import gauche.collection
.
(u32vector>list '#u32(9 2 5)) ⇒ (9 2 5) (use gauche.collection) (coerceto <list> '#u32(9 2 5)) ⇒ (9 2 5) 
Converts TAGvector vec to a vector. If start and/or end are given, they limit the range of vec to be copied.
Note that the generic function coerceto
can be used as well,
if you import gauche.collection
.
(f32vector>vector '#f32(9.3 2.2 5.5)) ⇒ #(9.3 2.2 5.5) (f32vector>vector '#f32(9.3 2.2 5.5) 2) ⇒ #(5.5) (use gauche.collection) (coerceto <vector> '#f32(9.3 2.2 5.5)) ⇒ #(9.3 2.2 5.5) 
[SRFI4+] Converts a list list to a TAGvector. Optional argument clamp specifies the behavior when the element of list is out of the valid range.
Note that the generic function coerceto
can be used as well,
if you import gauche.collection
.
(list>s64vector '(9 2 5)) ⇒ #s64(9 2 5) (use gauche.collection) (coerceto <s64vector> '(9 2 5)) ⇒ #s64(9 2 5) 
Converts a vector vec to a TAGvector. If start and/or end are given, they limit the range of vec to be copied. Optional argument clamp specifies the behavior when the element of vec is out of the valid range.
Note that the generic function coerceto
can be used as well,
if you import gauche.collection
.
(vector>f64vector '#(3.1 5.4 3.2)) ⇒ #f64(3.1 5.4 3.2) (use gauche.collection) (coerceto <f64vector> '#(3.1 5.4 3.2)) ⇒ #f64(3.1 5.4 3.2) 
Returns an s8vector or u8vector whose byte sequence is the same as the internal representation of the given string. Optional range arguments start and end specifies the character position inside string to be converted.
These procedures are useful when you want to access byte sequence of the string randomly.
(string>u8vector "abc") ⇒ #u8(97 98 99) 
Target must be an s8vector or a u8vector, respectively. Target must be mutable. Like copies the raw byte representation of string into target beginning from index tstart.
Returns target.
(let ((target (makeu8vector 10 0))) (string>u8vector! target 3 "abcde")) ⇒ #u8(0 0 0 97 98 99 100 101 0 0) 
Converts a byte sequence in s8vector or u8vector to a string that has the same byte sequence. Optional range arguments start and end specifies the byte position in vec to be converted.
Note that these procedure may result an incomplete string if vec contains a byte sequence invalid as the internal encoding of the string.
Returns an s32vector or u32vector whose elements are the internal codes of the characters in the string. Optional range arguments start and end specifies the character position inside string to be converted.
These procedures are useful when you want to access the characters in the string randomly.
Without start and end, these procedures work like this:
(lambda (vec) (mapto <string> integer>char vec))) 
Optional range arguments start and end limits the range of conversion between them.
This procedure creates an uvector of class uvectorclass that shares the storage of the given uniform vector vec. If optional start and end arguments are given, only the specified range of vec is used for the new vector. Since the storage is shared, modification of the original vector can be seen from the new vector, or vice versa.
The class uvectorclass must be either one of the uniform vector class, but is not necessary match the class of the source vector vec. In such case, the new vector looks at the same region of vec’s memory, but interprets it differently. For example, the following code determines whether Gauche is running on bigendian or littleendian machine:
(let ((u8v (uvectoralias <u8vector> #u32(1)))) (if (zero? (u8vectorref u8v 0)) 'bigendian 'littleendian)) 
If the uvectorclass is other than s8vector or u8vector, the region the new vector points has to meet the alignment requirement. You can assume the beginning of the source vector is aligned suitable for any uniform vectors. So, for example, if you’re creating u32vector from u8vector, the start and end must be multiple of 4 (or, if they’re omitted, the length of the original u8vector must be multiple of 4). An error is signalled when the given parameters doesn’t satisfy alignment constraint.
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
Elementwise arithmetic. Vec must be a TAGvector, and val must be either a TAGvector, a vector, or a list of the same length as vec, or a number (an exact integer for integer vectors, and a real number for f32 and f64vectors).
If val is a TAGvector, its elements are added to, subtracted from, or multiplied by the corresponding elements of vec, respectively, and the results are gathered to a TAGvector and returned. The destructive version (those have bang ‘!’ in the name) reuses vec to store the result. If the result of calculation goes out of the range of TAGvector’s element, the behavior is specified by clamp optional argument. (For f32vector and f64vector, clamp argument is ignored and the result may contain infinity).
If val is a number, it is added to, subtracted from, or multiplied by each element of vec, respectively.
(s8vectoradd '#s8(1 2 3 4) '#s8(5 6 7 8)) ⇒ #s8(6 8 10 12)
(u8vectorsub '#u8(1 2 3 4) '#u8(2 2 2 2)) ⇒ error
(u8vectorsub '#u8(1 2 3 4) '#u8(2 2 2 2) 'both) ⇒ #u8(0 0 1 2)
(f32vectormul '#f32(3.0 2.0 1.0) 1.5) ⇒ #f32(4.5 3.0 1.5)

Elementwise division of flonum vectors. These are only defined for f16, f32 and f64vector. val must be a TAGvector, a vector or a list of the same length as vec, or a real number.
(f32vectordiv '#f32(1.0 2.0 3.0) 2.0) ⇒ #f32(0.5 1.0 1.5) 
Elementwise logical (bitwise) operation. These procedures are only defined for integral vectors. val must be a TAGvector, a vector or a list of the same length as vec, or an exact integer. Bitwise and, inclusive or or exclusive or is calculated between each element in vec and the corresponding element of val (when val is a nonscalar value), or val itself (when val is an integer). The result is returned in a TAGvector. The destructive version reuses vec to store the result.
Calculates the dot product of two TAGvectors. The length of vec0 and vec1 must be the same.
Vec must be a TAGvector, and each of min and max
must be either a TAGvector, a vector or a list of the same length
as vec, or a number, or #f
.
For each element in vec, this procedure checks if the value
is between minval and maxval inclusive, where
minval and maxval are the corresponding values of
min and max (when min and/or max is/are
nonscalar value) or min and max themselves (when
min and/or max is/are a number).
When min is #f
, negative infinity is assumed.
When max is #f
, positive infinity is assumed.
If all the elements in vec are within the range, #f
is
returned. Otherwise, the index of the leftmost element of vec
that is out of range is returned.
(u8vectorrangecheck '#u8(3 1 0 2) 0 3) ⇒ #f (u8vectorrangecheck '#u8(3 1 0 2) 1 3) ⇒ 2 (u8vectorrangecheck '#u8(4 32 64 98) 0 '#u8(10 40 70 90)) ⇒ 3 ;; Range check in a program (cond ((u8vectorrangecheck u8v 1 31) => (lambda (i) (errorf "~sth vector element is out of range: ~s" i (u8vectorref u8v i)))) (else (dosomething u8v))) 
Vec must be a TAGvector, and each of min and max
must be either a TAGvector, a vector or a list of the same length
as vec, or a number, or #f
.
Like TAGvectorrangecheck, these procedures check if each element of vec are within the range between minval and maxval inclusive, which are derived from min and max. If the value is less than minval, it is replaced by minval. If the value is grater than maxval, it is replaced by maxval.
TAGvectorclamp creates a copy of vec and do clamp operation on it, while TAGvectorclamp! modifies vec. Both return the clamped vector.
(s8vectorclamp '#s8(8 14 3 22 0) 10 10) ⇒ #s8(8 10 3 10 0) 
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ]  [Top]  [Contents]  [Index]  [ ? ] 
A uniform vector can be seen as an abstraction of a chunk of memory. So you might want to use it for binary I/O. Yes, you can do it.
Reads a chunk of data from the given input port iport, and stores it to the uniform vector vec. You can give any uniform vector. If optional start and end arguments are given, they specify the index range in vec that is to be filled, and the rest of the vector remains untouched. Otherwise, entire vector is used. A special value 1 for end indicates the end of vec. If iport is omitted, the current input port is used.
If the input reached EOF before the required region of vec is filled, the rest of the vector is untouched.
If iport is already reached EOF when readblock!
is
called, an EOF object is returned. Otherwise,
the procedure returns the number of elements read (not bytes).
If the iport is a buffered port with ‘modest’ or ‘none’
buffering mode (See section File ports), readblock!
may return
before all the elements in vec is filled, even if iport
hasn’t reached EOF. The ports connected to a pipe or a network socket
behave so by default. If you know there will be enough data arriving and
want to make sure vec is filled, change the buffering mode of
iport to ‘full’.
The data is read as a byte stream, so if you give uniform vectors
other than s8vector or u8vector, your result may affected by
the endianness. If the optional argument endian is
given, the input is interpreted in that endianness.
When omitted, the value of the parameter defaultendian
is used. See section Endianness, for more about endian handling.
Writes out the content of the uniform vector vec ’as is’ to the output port oport. If oport is omitted, the current output port is used. If optional start and end arguments are given, they specify the index range in vec to be written out. A special value 1 for end indicates the end of vec. This procedure returns an unspecified value.
If you write out a uniform vector except s8vector and u8vector, the
care should be taken about the endianness, as in readblock!
.
The optional argument endian specifies the output endian.
When it is omitted, the value of the parameter defaultendian
is used (See section Endianness).
[ < ]  [ > ]  [ << ]  [ Up ]  [ >> ] 
This document was generated by Shiro Kawai on May 28, 2012 using texi2html 1.82.