1This is guile.info, produced by makeinfo version 6.7 from guile.texi. 2 3This manual documents Guile version 3.0.7. 4 5 Copyright (C) 1996-1997, 2000-2005, 2009-2021 Free Software 6Foundation, Inc. 7 8 Permission is granted to copy, distribute and/or modify this document 9under the terms of the GNU Free Documentation License, Version 1.3 or 10any later version published by the Free Software Foundation; with no 11Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A 12copy of the license is included in the section entitled “GNU Free 13Documentation License.” 14INFO-DIR-SECTION The Algorithmic Language Scheme 15START-INFO-DIR-ENTRY 16* Guile Reference: (guile). The Guile reference manual. 17END-INFO-DIR-ENTRY 18 19 20File: guile.info, Node: Reals and Rationals, Next: Complex Numbers, Prev: Integers, Up: Numbers 21 226.6.2.3 Real and Rational Numbers 23................................. 24 25Mathematically, the real numbers are the set of numbers that describe 26all possible points along a continuous, infinite, one-dimensional line. 27The rational numbers are the set of all numbers that can be written as 28fractions P/Q, where P and Q are integers. All rational numbers are 29also real, but there are real numbers that are not rational, for example 30the square root of 2, and pi. 31 32 Guile can represent both exact and inexact rational numbers, but it 33cannot represent precise finite irrational numbers. Exact rationals are 34represented by storing the numerator and denominator as two exact 35integers. Inexact rationals are stored as floating point numbers using 36the C type ‘double’. 37 38 Exact rationals are written as a fraction of integers. There must be 39no whitespace around the slash: 40 41 1/2 42 -22/7 43 44 Even though the actual encoding of inexact rationals is in binary, it 45may be helpful to think of it as a decimal number with a limited number 46of significant figures and a decimal point somewhere, since this 47corresponds to the standard notation for non-whole numbers. For 48example: 49 50 0.34 51 -0.00000142857931198 52 -5648394822220000000000.0 53 4.0 54 55 The limited precision of Guile’s encoding means that any finite 56“real” number in Guile can be written in a rational form, by multiplying 57and then dividing by sufficient powers of 10 (or in fact, 2). For 58example, ‘-0.00000142857931198’ is the same as −142857931198 divided by 59100000000000000000. In Guile’s current incarnation, therefore, the 60‘rational?’ and ‘real?’ predicates are equivalent for finite numbers. 61 62 Dividing by an exact zero leads to a error message, as one might 63expect. However, dividing by an inexact zero does not produce an error. 64Instead, the result of the division is either plus or minus infinity, 65depending on the sign of the divided number and the sign of the zero 66divisor (some platforms support signed zeroes ‘-0.0’ and ‘+0.0’; ‘0.0’ 67is the same as ‘+0.0’). 68 69 Dividing zero by an inexact zero yields a NaN (‘not a number’) value, 70although they are actually considered numbers by Scheme. Attempts to 71compare a NaN value with any number (including itself) using ‘=’, ‘<’, 72‘>’, ‘<=’ or ‘>=’ always returns ‘#f’. Although a NaN value is not ‘=’ 73to itself, it is both ‘eqv?’ and ‘equal?’ to itself and other NaN 74values. However, the preferred way to test for them is by using ‘nan?’. 75 76 The real NaN values and infinities are written ‘+nan.0’, ‘+inf.0’ and 77‘-inf.0’. This syntax is also recognized by ‘read’ as an extension to 78the usual Scheme syntax. These special values are considered by Scheme 79to be inexact real numbers but not rational. Note that non-real complex 80numbers may also contain infinities or NaN values in their real or 81imaginary parts. To test a real number to see if it is infinite, a NaN 82value, or neither, use ‘inf?’, ‘nan?’, or ‘finite?’, respectively. 83Every real number in Scheme belongs to precisely one of those three 84classes. 85 86 On platforms that follow IEEE 754 for their floating point 87arithmetic, the ‘+inf.0’, ‘-inf.0’, and ‘+nan.0’ values are implemented 88using the corresponding IEEE 754 values. They behave in arithmetic 89operations like IEEE 754 describes it, i.e., ‘(= +nan.0 +nan.0)’ ⇒ ‘#f’. 90 91 -- Scheme Procedure: real? obj 92 -- C Function: scm_real_p (obj) 93 Return ‘#t’ if OBJ is a real number, else ‘#f’. Note that the sets 94 of integer and rational values form subsets of the set of real 95 numbers, so the predicate will also be fulfilled if OBJ is an 96 integer number or a rational number. 97 98 -- Scheme Procedure: rational? x 99 -- C Function: scm_rational_p (x) 100 Return ‘#t’ if X is a rational number, ‘#f’ otherwise. Note that 101 the set of integer values forms a subset of the set of rational 102 numbers, i.e. the predicate will also be fulfilled if X is an 103 integer number. 104 105 -- Scheme Procedure: rationalize x eps 106 -- C Function: scm_rationalize (x, eps) 107 Returns the _simplest_ rational number differing from X by no more 108 than EPS. 109 110 As required by R5RS, ‘rationalize’ only returns an exact result 111 when both its arguments are exact. Thus, you might need to use 112 ‘inexact->exact’ on the arguments. 113 114 (rationalize (inexact->exact 1.2) 1/100) 115 ⇒ 6/5 116 117 -- Scheme Procedure: inf? x 118 -- C Function: scm_inf_p (x) 119 Return ‘#t’ if the real number X is ‘+inf.0’ or ‘-inf.0’. 120 Otherwise return ‘#f’. 121 122 -- Scheme Procedure: nan? x 123 -- C Function: scm_nan_p (x) 124 Return ‘#t’ if the real number X is ‘+nan.0’, or ‘#f’ otherwise. 125 126 -- Scheme Procedure: finite? x 127 -- C Function: scm_finite_p (x) 128 Return ‘#t’ if the real number X is neither infinite nor a NaN, 129 ‘#f’ otherwise. 130 131 -- Scheme Procedure: nan 132 -- C Function: scm_nan () 133 Return ‘+nan.0’, a NaN value. 134 135 -- Scheme Procedure: inf 136 -- C Function: scm_inf () 137 Return ‘+inf.0’, positive infinity. 138 139 -- Scheme Procedure: numerator x 140 -- C Function: scm_numerator (x) 141 Return the numerator of the rational number X. 142 143 -- Scheme Procedure: denominator x 144 -- C Function: scm_denominator (x) 145 Return the denominator of the rational number X. 146 147 -- C Function: int scm_is_real (SCM val) 148 -- C Function: int scm_is_rational (SCM val) 149 Equivalent to ‘scm_is_true (scm_real_p (val))’ and ‘scm_is_true 150 (scm_rational_p (val))’, respectively. 151 152 -- C Function: double scm_to_double (SCM val) 153 Returns the number closest to VAL that is representable as a 154 ‘double’. Returns infinity for a VAL that is too large in 155 magnitude. The argument VAL must be a real number. 156 157 -- C Function: SCM scm_from_double (double val) 158 Return the ‘SCM’ value that represents VAL. The returned value is 159 inexact according to the predicate ‘inexact?’, but it will be 160 exactly equal to VAL. 161 162 163File: guile.info, Node: Complex Numbers, Next: Exactness, Prev: Reals and Rationals, Up: Numbers 164 1656.6.2.4 Complex Numbers 166....................... 167 168Complex numbers are the set of numbers that describe all possible points 169in a two-dimensional space. The two coordinates of a particular point 170in this space are known as the “real” and “imaginary” parts of the 171complex number that describes that point. 172 173 In Guile, complex numbers are written in rectangular form as the sum 174of their real and imaginary parts, using the symbol ‘i’ to indicate the 175imaginary part. 176 177 3+4i 178 ⇒ 179 3.0+4.0i 180 181 (* 3-8i 2.3+0.3i) 182 ⇒ 183 9.3-17.5i 184 185Polar form can also be used, with an ‘@’ between magnitude and angle, 186 187 1@3.141592 ⇒ -1.0 (approx) 188 -1@1.57079 ⇒ 0.0-1.0i (approx) 189 190 Guile represents a complex number as a pair of inexact reals, so the 191real and imaginary parts of a complex number have the same properties of 192inexactness and limited precision as single inexact real numbers. 193 194 Note that each part of a complex number may contain any inexact real 195value, including the special values ‘+nan.0’, ‘+inf.0’ and ‘-inf.0’, as 196well as either of the signed zeroes ‘0.0’ or ‘-0.0’. 197 198 -- Scheme Procedure: complex? z 199 -- C Function: scm_complex_p (z) 200 Return ‘#t’ if Z is a complex number, ‘#f’ otherwise. Note that 201 the sets of real, rational and integer values form subsets of the 202 set of complex numbers, i.e. the predicate will also be fulfilled 203 if Z is a real, rational or integer number. 204 205 -- C Function: int scm_is_complex (SCM val) 206 Equivalent to ‘scm_is_true (scm_complex_p (val))’. 207 208 209File: guile.info, Node: Exactness, Next: Number Syntax, Prev: Complex Numbers, Up: Numbers 210 2116.6.2.5 Exact and Inexact Numbers 212................................. 213 214R5RS requires that, with few exceptions, a calculation involving inexact 215numbers always produces an inexact result. To meet this requirement, 216Guile distinguishes between an exact integer value such as ‘5’ and the 217corresponding inexact integer value which, to the limited precision 218available, has no fractional part, and is printed as ‘5.0’. Guile will 219only convert the latter value to the former when forced to do so by an 220invocation of the ‘inexact->exact’ procedure. 221 222 The only exception to the above requirement is when the values of the 223inexact numbers do not affect the result. For example ‘(expt n 0)’ is 224‘1’ for any value of ‘n’, therefore ‘(expt 5.0 0)’ is permitted to 225return an exact ‘1’. 226 227 -- Scheme Procedure: exact? z 228 -- C Function: scm_exact_p (z) 229 Return ‘#t’ if the number Z is exact, ‘#f’ otherwise. 230 231 (exact? 2) 232 ⇒ #t 233 234 (exact? 0.5) 235 ⇒ #f 236 237 (exact? (/ 2)) 238 ⇒ #t 239 240 -- C Function: int scm_is_exact (SCM z) 241 Return a ‘1’ if the number Z is exact, and ‘0’ otherwise. This is 242 equivalent to ‘scm_is_true (scm_exact_p (z))’. 243 244 An alternate approch to testing the exactness of a number is to use 245 ‘scm_is_signed_integer’ or ‘scm_is_unsigned_integer’. 246 247 -- Scheme Procedure: inexact? z 248 -- C Function: scm_inexact_p (z) 249 Return ‘#t’ if the number Z is inexact, ‘#f’ else. 250 251 -- C Function: int scm_is_inexact (SCM z) 252 Return a ‘1’ if the number Z is inexact, and ‘0’ otherwise. This 253 is equivalent to ‘scm_is_true (scm_inexact_p (z))’. 254 255 -- Scheme Procedure: inexact->exact z 256 -- C Function: scm_inexact_to_exact (z) 257 Return an exact number that is numerically closest to Z, when there 258 is one. For inexact rationals, Guile returns the exact rational 259 that is numerically equal to the inexact rational. Inexact complex 260 numbers with a non-zero imaginary part can not be made exact. 261 262 (inexact->exact 0.5) 263 ⇒ 1/2 264 265 The following happens because 12/10 is not exactly representable as 266 a ‘double’ (on most platforms). However, when reading a decimal 267 number that has been marked exact with the “#e” prefix, Guile is 268 able to represent it correctly. 269 270 (inexact->exact 1.2) 271 ⇒ 5404319552844595/4503599627370496 272 273 #e1.2 274 ⇒ 6/5 275 276 -- Scheme Procedure: exact->inexact z 277 -- C Function: scm_exact_to_inexact (z) 278 Convert the number Z to its inexact representation. 279 280 281File: guile.info, Node: Number Syntax, Next: Integer Operations, Prev: Exactness, Up: Numbers 282 2836.6.2.6 Read Syntax for Numerical Data 284...................................... 285 286The read syntax for integers is a string of digits, optionally preceded 287by a minus or plus character, a code indicating the base in which the 288integer is encoded, and a code indicating whether the number is exact or 289inexact. The supported base codes are: 290 291‘#b’ 292‘#B’ 293 the integer is written in binary (base 2) 294 295‘#o’ 296‘#O’ 297 the integer is written in octal (base 8) 298 299‘#d’ 300‘#D’ 301 the integer is written in decimal (base 10) 302 303‘#x’ 304‘#X’ 305 the integer is written in hexadecimal (base 16) 306 307 If the base code is omitted, the integer is assumed to be decimal. 308The following examples show how these base codes are used. 309 310 -13 311 ⇒ -13 312 313 #d-13 314 ⇒ -13 315 316 #x-13 317 ⇒ -19 318 319 #b+1101 320 ⇒ 13 321 322 #o377 323 ⇒ 255 324 325 The codes for indicating exactness (which can, incidentally, be 326applied to all numerical values) are: 327 328‘#e’ 329‘#E’ 330 the number is exact 331 332‘#i’ 333‘#I’ 334 the number is inexact. 335 336 If the exactness indicator is omitted, the number is exact unless it 337contains a radix point. Since Guile can not represent exact complex 338numbers, an error is signalled when asking for them. 339 340 (exact? 1.2) 341 ⇒ #f 342 343 (exact? #e1.2) 344 ⇒ #t 345 346 (exact? #e+1i) 347 ERROR: Wrong type argument 348 349 Guile also understands the syntax ‘+inf.0’ and ‘-inf.0’ for plus and 350minus infinity, respectively. The value must be written exactly as 351shown, that is, they always must have a sign and exactly one zero digit 352after the decimal point. It also understands ‘+nan.0’ and ‘-nan.0’ for 353the special ‘not-a-number’ value. The sign is ignored for 354‘not-a-number’ and the value is always printed as ‘+nan.0’. 355 356 357File: guile.info, Node: Integer Operations, Next: Comparison, Prev: Number Syntax, Up: Numbers 358 3596.6.2.7 Operations on Integer Values 360.................................... 361 362 -- Scheme Procedure: odd? n 363 -- C Function: scm_odd_p (n) 364 Return ‘#t’ if N is an odd number, ‘#f’ otherwise. 365 366 -- Scheme Procedure: even? n 367 -- C Function: scm_even_p (n) 368 Return ‘#t’ if N is an even number, ‘#f’ otherwise. 369 370 -- Scheme Procedure: quotient n d 371 -- Scheme Procedure: remainder n d 372 -- C Function: scm_quotient (n, d) 373 -- C Function: scm_remainder (n, d) 374 Return the quotient or remainder from N divided by D. The quotient 375 is rounded towards zero, and the remainder will have the same sign 376 as N. In all cases quotient and remainder satisfy N = Q*D + R. 377 378 (remainder 13 4) ⇒ 1 379 (remainder -13 4) ⇒ -1 380 381 See also ‘truncate-quotient’, ‘truncate-remainder’ and related 382 operations in *note Arithmetic::. 383 384 -- Scheme Procedure: modulo n d 385 -- C Function: scm_modulo (n, d) 386 Return the remainder from N divided by D, with the same sign as D. 387 388 (modulo 13 4) ⇒ 1 389 (modulo -13 4) ⇒ 3 390 (modulo 13 -4) ⇒ -3 391 (modulo -13 -4) ⇒ -1 392 393 See also ‘floor-quotient’, ‘floor-remainder’ and related operations 394 in *note Arithmetic::. 395 396 -- Scheme Procedure: gcd x... 397 -- C Function: scm_gcd (x, y) 398 Return the greatest common divisor of all arguments. If called 399 without arguments, 0 is returned. 400 401 The C function ‘scm_gcd’ always takes two arguments, while the 402 Scheme function can take an arbitrary number. 403 404 -- Scheme Procedure: lcm x... 405 -- C Function: scm_lcm (x, y) 406 Return the least common multiple of the arguments. If called 407 without arguments, 1 is returned. 408 409 The C function ‘scm_lcm’ always takes two arguments, while the 410 Scheme function can take an arbitrary number. 411 412 -- Scheme Procedure: modulo-expt n k m 413 -- C Function: scm_modulo_expt (n, k, m) 414 Return N raised to the integer exponent K, modulo M. 415 416 (modulo-expt 2 3 5) 417 ⇒ 3 418 419 -- Scheme Procedure: exact-integer-sqrt K 420 -- C Function: void scm_exact_integer_sqrt (SCM K, SCM *S, SCM *R) 421 Return two exact non-negative integers S and R such that K = S^2 + 422 R and S^2 <= K < (S + 1)^2. An error is raised if K is not an 423 exact non-negative integer. 424 425 (exact-integer-sqrt 10) ⇒ 3 and 1 426 427 428File: guile.info, Node: Comparison, Next: Conversion, Prev: Integer Operations, Up: Numbers 429 4306.6.2.8 Comparison Predicates 431............................. 432 433The C comparison functions below always takes two arguments, while the 434Scheme functions can take an arbitrary number. Also keep in mind that 435the C functions return one of the Scheme boolean values ‘SCM_BOOL_T’ or 436‘SCM_BOOL_F’ which are both true as far as C is concerned. Thus, always 437write ‘scm_is_true (scm_num_eq_p (x, y))’ when testing the two Scheme 438numbers ‘x’ and ‘y’ for equality, for example. 439 440 -- Scheme Procedure: = 441 -- C Function: scm_num_eq_p (x, y) 442 Return ‘#t’ if all parameters are numerically equal. 443 444 -- Scheme Procedure: < 445 -- C Function: scm_less_p (x, y) 446 Return ‘#t’ if the list of parameters is monotonically increasing. 447 448 -- Scheme Procedure: > 449 -- C Function: scm_gr_p (x, y) 450 Return ‘#t’ if the list of parameters is monotonically decreasing. 451 452 -- Scheme Procedure: <= 453 -- C Function: scm_leq_p (x, y) 454 Return ‘#t’ if the list of parameters is monotonically 455 non-decreasing. 456 457 -- Scheme Procedure: >= 458 -- C Function: scm_geq_p (x, y) 459 Return ‘#t’ if the list of parameters is monotonically 460 non-increasing. 461 462 -- Scheme Procedure: zero? z 463 -- C Function: scm_zero_p (z) 464 Return ‘#t’ if Z is an exact or inexact number equal to zero. 465 466 -- Scheme Procedure: positive? x 467 -- C Function: scm_positive_p (x) 468 Return ‘#t’ if X is an exact or inexact number greater than zero. 469 470 -- Scheme Procedure: negative? x 471 -- C Function: scm_negative_p (x) 472 Return ‘#t’ if X is an exact or inexact number less than zero. 473 474 475File: guile.info, Node: Conversion, Next: Complex, Prev: Comparison, Up: Numbers 476 4776.6.2.9 Converting Numbers To and From Strings 478.............................................. 479 480The following procedures read and write numbers according to their 481external representation as defined by R5RS (*note R5RS Lexical 482Structure: (r5rs)Lexical structure.). *Note the ‘(ice-9 i18n)’ module: 483Number Input and Output, for locale-dependent number parsing. 484 485 -- Scheme Procedure: number->string n [radix] 486 -- C Function: scm_number_to_string (n, radix) 487 Return a string holding the external representation of the number N 488 in the given RADIX. If N is inexact, a radix of 10 will be used. 489 490 -- Scheme Procedure: string->number string [radix] 491 -- C Function: scm_string_to_number (string, radix) 492 Return a number of the maximally precise representation expressed 493 by the given STRING. RADIX must be an exact integer, either 2, 8, 494 10, or 16. If supplied, RADIX is a default radix that may be 495 overridden by an explicit radix prefix in STRING (e.g. "#o177"). 496 If RADIX is not supplied, then the default radix is 10. If string 497 is not a syntactically valid notation for a number, then 498 ‘string->number’ returns ‘#f’. 499 500 -- C Function: SCM scm_c_locale_stringn_to_number (const char *string, 501 size_t len, unsigned radix) 502 As per ‘string->number’ above, but taking a C string, as pointer 503 and length. The string characters should be in the current locale 504 encoding (‘locale’ in the name refers only to that, there’s no 505 locale-dependent parsing). 506 507 508File: guile.info, Node: Complex, Next: Arithmetic, Prev: Conversion, Up: Numbers 509 5106.6.2.10 Complex Number Operations 511.................................. 512 513 -- Scheme Procedure: make-rectangular real_part imaginary_part 514 -- C Function: scm_make_rectangular (real_part, imaginary_part) 515 Return a complex number constructed of the given REAL-PART and 516 IMAGINARY-PART parts. 517 518 -- Scheme Procedure: make-polar mag ang 519 -- C Function: scm_make_polar (mag, ang) 520 Return the complex number MAG * e^(i * ANG). 521 522 -- Scheme Procedure: real-part z 523 -- C Function: scm_real_part (z) 524 Return the real part of the number Z. 525 526 -- Scheme Procedure: imag-part z 527 -- C Function: scm_imag_part (z) 528 Return the imaginary part of the number Z. 529 530 -- Scheme Procedure: magnitude z 531 -- C Function: scm_magnitude (z) 532 Return the magnitude of the number Z. This is the same as ‘abs’ 533 for real arguments, but also allows complex numbers. 534 535 -- Scheme Procedure: angle z 536 -- C Function: scm_angle (z) 537 Return the angle of the complex number Z. 538 539 -- C Function: SCM scm_c_make_rectangular (double re, double im) 540 -- C Function: SCM scm_c_make_polar (double x, double y) 541 Like ‘scm_make_rectangular’ or ‘scm_make_polar’, respectively, but 542 these functions take ‘double’s as their arguments. 543 544 -- C Function: double scm_c_real_part (z) 545 -- C Function: double scm_c_imag_part (z) 546 Returns the real or imaginary part of Z as a ‘double’. 547 548 -- C Function: double scm_c_magnitude (z) 549 -- C Function: double scm_c_angle (z) 550 Returns the magnitude or angle of Z as a ‘double’. 551 552 553File: guile.info, Node: Arithmetic, Next: Scientific, Prev: Complex, Up: Numbers 554 5556.6.2.11 Arithmetic Functions 556............................. 557 558The C arithmetic functions below always takes two arguments, while the 559Scheme functions can take an arbitrary number. When you need to invoke 560them with just one argument, for example to compute the equivalent of 561‘(- x)’, pass ‘SCM_UNDEFINED’ as the second one: ‘scm_difference (x, 562SCM_UNDEFINED)’. 563 564 -- Scheme Procedure: + z1 ... 565 -- C Function: scm_sum (z1, z2) 566 Return the sum of all parameter values. Return 0 if called without 567 any parameters. 568 569 -- Scheme Procedure: - z1 z2 ... 570 -- C Function: scm_difference (z1, z2) 571 If called with one argument Z1, -Z1 is returned. Otherwise the sum 572 of all but the first argument are subtracted from the first 573 argument. 574 575 -- Scheme Procedure: * z1 ... 576 -- C Function: scm_product (z1, z2) 577 Return the product of all arguments. If called without arguments, 578 1 is returned. 579 580 -- Scheme Procedure: / z1 z2 ... 581 -- C Function: scm_divide (z1, z2) 582 Divide the first argument by the product of the remaining 583 arguments. If called with one argument Z1, 1/Z1 is returned. 584 585 -- Scheme Procedure: 1+ z 586 -- C Function: scm_oneplus (z) 587 Return Z + 1. 588 589 -- Scheme Procedure: 1- z 590 -- C function: scm_oneminus (z) 591 Return Z - 1. 592 593 -- Scheme Procedure: abs x 594 -- C Function: scm_abs (x) 595 Return the absolute value of X. 596 597 X must be a number with zero imaginary part. To calculate the 598 magnitude of a complex number, use ‘magnitude’ instead. 599 600 -- Scheme Procedure: max x1 x2 ... 601 -- C Function: scm_max (x1, x2) 602 Return the maximum of all parameter values. 603 604 -- Scheme Procedure: min x1 x2 ... 605 -- C Function: scm_min (x1, x2) 606 Return the minimum of all parameter values. 607 608 -- Scheme Procedure: truncate x 609 -- C Function: scm_truncate_number (x) 610 Round the inexact number X towards zero. 611 612 -- Scheme Procedure: round x 613 -- C Function: scm_round_number (x) 614 Round the inexact number X to the nearest integer. When exactly 615 halfway between two integers, round to the even one. 616 617 -- Scheme Procedure: floor x 618 -- C Function: scm_floor (x) 619 Round the number X towards minus infinity. 620 621 -- Scheme Procedure: ceiling x 622 -- C Function: scm_ceiling (x) 623 Round the number X towards infinity. 624 625 -- C Function: double scm_c_truncate (double x) 626 -- C Function: double scm_c_round (double x) 627 Like ‘scm_truncate_number’ or ‘scm_round_number’, respectively, but 628 these functions take and return ‘double’ values. 629 630 -- Scheme Procedure: euclidean/ X Y 631 -- Scheme Procedure: euclidean-quotient X Y 632 -- Scheme Procedure: euclidean-remainder X Y 633 -- C Function: void scm_euclidean_divide (SCM X, SCM Y, SCM *Q, SCM *R) 634 -- C Function: SCM scm_euclidean_quotient (SCM X, SCM Y) 635 -- C Function: SCM scm_euclidean_remainder (SCM X, SCM Y) 636 These procedures accept two real numbers X and Y, where the divisor 637 Y must be non-zero. ‘euclidean-quotient’ returns the integer Q and 638 ‘euclidean-remainder’ returns the real number R such that X = Q*Y + 639 R and 0 <= R < |Y|. ‘euclidean/’ returns both Q and R, and is more 640 efficient than computing each separately. Note that when Y > 0, 641 ‘euclidean-quotient’ returns floor(X/Y), otherwise it returns 642 ceiling(X/Y). 643 644 Note that these operators are equivalent to the R6RS operators 645 ‘div’, ‘mod’, and ‘div-and-mod’. 646 647 (euclidean-quotient 123 10) ⇒ 12 648 (euclidean-remainder 123 10) ⇒ 3 649 (euclidean/ 123 10) ⇒ 12 and 3 650 (euclidean/ 123 -10) ⇒ -12 and 3 651 (euclidean/ -123 10) ⇒ -13 and 7 652 (euclidean/ -123 -10) ⇒ 13 and 7 653 (euclidean/ -123.2 -63.5) ⇒ 2.0 and 3.8 654 (euclidean/ 16/3 -10/7) ⇒ -3 and 22/21 655 656 -- Scheme Procedure: floor/ X Y 657 -- Scheme Procedure: floor-quotient X Y 658 -- Scheme Procedure: floor-remainder X Y 659 -- C Function: void scm_floor_divide (SCM X, SCM Y, SCM *Q, SCM *R) 660 -- C Function: SCM scm_floor_quotient (X, Y) 661 -- C Function: SCM scm_floor_remainder (X, Y) 662 These procedures accept two real numbers X and Y, where the divisor 663 Y must be non-zero. ‘floor-quotient’ returns the integer Q and 664 ‘floor-remainder’ returns the real number R such that Q = 665 floor(X/Y) and X = Q*Y + R. ‘floor/’ returns both Q and R, and is 666 more efficient than computing each separately. Note that R, if 667 non-zero, will have the same sign as Y. 668 669 When X and Y are integers, ‘floor-remainder’ is equivalent to the 670 R5RS integer-only operator ‘modulo’. 671 672 (floor-quotient 123 10) ⇒ 12 673 (floor-remainder 123 10) ⇒ 3 674 (floor/ 123 10) ⇒ 12 and 3 675 (floor/ 123 -10) ⇒ -13 and -7 676 (floor/ -123 10) ⇒ -13 and 7 677 (floor/ -123 -10) ⇒ 12 and -3 678 (floor/ -123.2 -63.5) ⇒ 1.0 and -59.7 679 (floor/ 16/3 -10/7) ⇒ -4 and -8/21 680 681 -- Scheme Procedure: ceiling/ X Y 682 -- Scheme Procedure: ceiling-quotient X Y 683 -- Scheme Procedure: ceiling-remainder X Y 684 -- C Function: void scm_ceiling_divide (SCM X, SCM Y, SCM *Q, SCM *R) 685 -- C Function: SCM scm_ceiling_quotient (X, Y) 686 -- C Function: SCM scm_ceiling_remainder (X, Y) 687 These procedures accept two real numbers X and Y, where the divisor 688 Y must be non-zero. ‘ceiling-quotient’ returns the integer Q and 689 ‘ceiling-remainder’ returns the real number R such that Q = 690 ceiling(X/Y) and X = Q*Y + R. ‘ceiling/’ returns both Q and R, and 691 is more efficient than computing each separately. Note that R, if 692 non-zero, will have the opposite sign of Y. 693 694 (ceiling-quotient 123 10) ⇒ 13 695 (ceiling-remainder 123 10) ⇒ -7 696 (ceiling/ 123 10) ⇒ 13 and -7 697 (ceiling/ 123 -10) ⇒ -12 and 3 698 (ceiling/ -123 10) ⇒ -12 and -3 699 (ceiling/ -123 -10) ⇒ 13 and 7 700 (ceiling/ -123.2 -63.5) ⇒ 2.0 and 3.8 701 (ceiling/ 16/3 -10/7) ⇒ -3 and 22/21 702 703 -- Scheme Procedure: truncate/ X Y 704 -- Scheme Procedure: truncate-quotient X Y 705 -- Scheme Procedure: truncate-remainder X Y 706 -- C Function: void scm_truncate_divide (SCM X, SCM Y, SCM *Q, SCM *R) 707 -- C Function: SCM scm_truncate_quotient (X, Y) 708 -- C Function: SCM scm_truncate_remainder (X, Y) 709 These procedures accept two real numbers X and Y, where the divisor 710 Y must be non-zero. ‘truncate-quotient’ returns the integer Q and 711 ‘truncate-remainder’ returns the real number R such that Q is X/Y 712 rounded toward zero, and X = Q*Y + R. ‘truncate/’ returns both Q 713 and R, and is more efficient than computing each separately. Note 714 that R, if non-zero, will have the same sign as X. 715 716 When X and Y are integers, these operators are equivalent to the 717 R5RS integer-only operators ‘quotient’ and ‘remainder’. 718 719 (truncate-quotient 123 10) ⇒ 12 720 (truncate-remainder 123 10) ⇒ 3 721 (truncate/ 123 10) ⇒ 12 and 3 722 (truncate/ 123 -10) ⇒ -12 and 3 723 (truncate/ -123 10) ⇒ -12 and -3 724 (truncate/ -123 -10) ⇒ 12 and -3 725 (truncate/ -123.2 -63.5) ⇒ 1.0 and -59.7 726 (truncate/ 16/3 -10/7) ⇒ -3 and 22/21 727 728 -- Scheme Procedure: centered/ X Y 729 -- Scheme Procedure: centered-quotient X Y 730 -- Scheme Procedure: centered-remainder X Y 731 -- C Function: void scm_centered_divide (SCM X, SCM Y, SCM *Q, SCM *R) 732 -- C Function: SCM scm_centered_quotient (SCM X, SCM Y) 733 -- C Function: SCM scm_centered_remainder (SCM X, SCM Y) 734 These procedures accept two real numbers X and Y, where the divisor 735 Y must be non-zero. ‘centered-quotient’ returns the integer Q and 736 ‘centered-remainder’ returns the real number R such that X = Q*Y + 737 R and -|Y/2| <= R < |Y/2|. ‘centered/’ returns both Q and R, and 738 is more efficient than computing each separately. 739 740 Note that ‘centered-quotient’ returns X/Y rounded to the nearest 741 integer. When X/Y lies exactly half-way between two integers, the 742 tie is broken according to the sign of Y. If Y > 0, ties are 743 rounded toward positive infinity, otherwise they are rounded toward 744 negative infinity. This is a consequence of the requirement that 745 -|Y/2| <= R < |Y/2|. 746 747 Note that these operators are equivalent to the R6RS operators 748 ‘div0’, ‘mod0’, and ‘div0-and-mod0’. 749 750 (centered-quotient 123 10) ⇒ 12 751 (centered-remainder 123 10) ⇒ 3 752 (centered/ 123 10) ⇒ 12 and 3 753 (centered/ 123 -10) ⇒ -12 and 3 754 (centered/ -123 10) ⇒ -12 and -3 755 (centered/ -123 -10) ⇒ 12 and -3 756 (centered/ 125 10) ⇒ 13 and -5 757 (centered/ 127 10) ⇒ 13 and -3 758 (centered/ 135 10) ⇒ 14 and -5 759 (centered/ -123.2 -63.5) ⇒ 2.0 and 3.8 760 (centered/ 16/3 -10/7) ⇒ -4 and -8/21 761 762 -- Scheme Procedure: round/ X Y 763 -- Scheme Procedure: round-quotient X Y 764 -- Scheme Procedure: round-remainder X Y 765 -- C Function: void scm_round_divide (SCM X, SCM Y, SCM *Q, SCM *R) 766 -- C Function: SCM scm_round_quotient (X, Y) 767 -- C Function: SCM scm_round_remainder (X, Y) 768 These procedures accept two real numbers X and Y, where the divisor 769 Y must be non-zero. ‘round-quotient’ returns the integer Q and 770 ‘round-remainder’ returns the real number R such that X = Q*Y + R 771 and Q is X/Y rounded to the nearest integer, with ties going to the 772 nearest even integer. ‘round/’ returns both Q and R, and is more 773 efficient than computing each separately. 774 775 Note that ‘round/’ and ‘centered/’ are almost equivalent, but their 776 behavior differs when X/Y lies exactly half-way between two 777 integers. In this case, ‘round/’ chooses the nearest even integer, 778 whereas ‘centered/’ chooses in such a way to satisfy the constraint 779 -|Y/2| <= R < |Y/2|, which is stronger than the corresponding 780 constraint for ‘round/’, -|Y/2| <= R <= |Y/2|. In particular, when 781 X and Y are integers, the number of possible remainders returned by 782 ‘centered/’ is |Y|, whereas the number of possible remainders 783 returned by ‘round/’ is |Y|+1 when Y is even. 784 785 (round-quotient 123 10) ⇒ 12 786 (round-remainder 123 10) ⇒ 3 787 (round/ 123 10) ⇒ 12 and 3 788 (round/ 123 -10) ⇒ -12 and 3 789 (round/ -123 10) ⇒ -12 and -3 790 (round/ -123 -10) ⇒ 12 and -3 791 (round/ 125 10) ⇒ 12 and 5 792 (round/ 127 10) ⇒ 13 and -3 793 (round/ 135 10) ⇒ 14 and -5 794 (round/ -123.2 -63.5) ⇒ 2.0 and 3.8 795 (round/ 16/3 -10/7) ⇒ -4 and -8/21 796 797 798File: guile.info, Node: Scientific, Next: Bitwise Operations, Prev: Arithmetic, Up: Numbers 799 8006.6.2.12 Scientific Functions 801............................. 802 803The following procedures accept any kind of number as arguments, 804including complex numbers. 805 806 -- Scheme Procedure: sqrt z 807 Return the square root of Z. Of the two possible roots (positive 808 and negative), the one with a positive real part is returned, or if 809 that’s zero then a positive imaginary part. Thus, 810 811 (sqrt 9.0) ⇒ 3.0 812 (sqrt -9.0) ⇒ 0.0+3.0i 813 (sqrt 1.0+1.0i) ⇒ 1.09868411346781+0.455089860562227i 814 (sqrt -1.0-1.0i) ⇒ 0.455089860562227-1.09868411346781i 815 816 -- Scheme Procedure: expt z1 z2 817 Return Z1 raised to the power of Z2. 818 819 -- Scheme Procedure: sin z 820 Return the sine of Z. 821 822 -- Scheme Procedure: cos z 823 Return the cosine of Z. 824 825 -- Scheme Procedure: tan z 826 Return the tangent of Z. 827 828 -- Scheme Procedure: asin z 829 Return the arcsine of Z. 830 831 -- Scheme Procedure: acos z 832 Return the arccosine of Z. 833 834 -- Scheme Procedure: atan z 835 -- Scheme Procedure: atan y x 836 Return the arctangent of Z, or of Y/X. 837 838 -- Scheme Procedure: exp z 839 Return e to the power of Z, where e is the base of natural 840 logarithms (2.71828...). 841 842 -- Scheme Procedure: log z 843 Return the natural logarithm of Z. 844 845 -- Scheme Procedure: log10 z 846 Return the base 10 logarithm of Z. 847 848 -- Scheme Procedure: sinh z 849 Return the hyperbolic sine of Z. 850 851 -- Scheme Procedure: cosh z 852 Return the hyperbolic cosine of Z. 853 854 -- Scheme Procedure: tanh z 855 Return the hyperbolic tangent of Z. 856 857 -- Scheme Procedure: asinh z 858 Return the hyperbolic arcsine of Z. 859 860 -- Scheme Procedure: acosh z 861 Return the hyperbolic arccosine of Z. 862 863 -- Scheme Procedure: atanh z 864 Return the hyperbolic arctangent of Z. 865 866 867File: guile.info, Node: Bitwise Operations, Next: Random, Prev: Scientific, Up: Numbers 868 8696.6.2.13 Bitwise Operations 870........................... 871 872For the following bitwise functions, negative numbers are treated as 873infinite precision twos-complements. For instance -6 is bits ...111010, 874with infinitely many ones on the left. It can be seen that adding 6 875(binary 110) to such a bit pattern gives all zeros. 876 877 -- Scheme Procedure: logand n1 n2 ... 878 -- C Function: scm_logand (n1, n2) 879 Return the bitwise AND of the integer arguments. 880 881 (logand) ⇒ -1 882 (logand 7) ⇒ 7 883 (logand #b111 #b011 #b001) ⇒ 1 884 885 -- Scheme Procedure: logior n1 n2 ... 886 -- C Function: scm_logior (n1, n2) 887 Return the bitwise OR of the integer arguments. 888 889 (logior) ⇒ 0 890 (logior 7) ⇒ 7 891 (logior #b000 #b001 #b011) ⇒ 3 892 893 -- Scheme Procedure: logxor n1 n2 ... 894 -- C Function: scm_loxor (n1, n2) 895 Return the bitwise XOR of the integer arguments. A bit is set in 896 the result if it is set in an odd number of arguments. 897 898 (logxor) ⇒ 0 899 (logxor 7) ⇒ 7 900 (logxor #b000 #b001 #b011) ⇒ 2 901 (logxor #b000 #b001 #b011 #b011) ⇒ 1 902 903 -- Scheme Procedure: lognot n 904 -- C Function: scm_lognot (n) 905 Return the integer which is the ones-complement of the integer 906 argument, ie. each 0 bit is changed to 1 and each 1 bit to 0. 907 908 (number->string (lognot #b10000000) 2) 909 ⇒ "-10000001" 910 (number->string (lognot #b0) 2) 911 ⇒ "-1" 912 913 -- Scheme Procedure: logtest j k 914 -- C Function: scm_logtest (j, k) 915 Test whether J and K have any 1 bits in common. This is equivalent 916 to ‘(not (zero? (logand j k)))’, but without actually calculating 917 the ‘logand’, just testing for non-zero. 918 919 (logtest #b0100 #b1011) ⇒ #f 920 (logtest #b0100 #b0111) ⇒ #t 921 922 -- Scheme Procedure: logbit? index j 923 -- C Function: scm_logbit_p (index, j) 924 Test whether bit number INDEX in J is set. INDEX starts from 0 for 925 the least significant bit. 926 927 (logbit? 0 #b1101) ⇒ #t 928 (logbit? 1 #b1101) ⇒ #f 929 (logbit? 2 #b1101) ⇒ #t 930 (logbit? 3 #b1101) ⇒ #t 931 (logbit? 4 #b1101) ⇒ #f 932 933 -- Scheme Procedure: ash n count 934 -- C Function: scm_ash (n, count) 935 Return floor(n * 2^{count}). N and COUNT must be exact integers. 936 937 With N viewed as an infinite-precision twos-complement integer, 938 ‘ash’ means a left shift introducing zero bits when COUNT is 939 positive, or a right shift dropping bits when COUNT is negative. 940 This is an “arithmetic” shift. 941 942 (number->string (ash #b1 3) 2) ⇒ "1000" 943 (number->string (ash #b1010 -1) 2) ⇒ "101" 944 945 ;; -23 is bits ...11101001, -6 is bits ...111010 946 (ash -23 -2) ⇒ -6 947 948 -- Scheme Procedure: round-ash n count 949 -- C Function: scm_round_ash (n, count) 950 Return round(n * 2^count). N and COUNT must be exact integers. 951 952 With N viewed as an infinite-precision twos-complement integer, 953 ‘round-ash’ means a left shift introducing zero bits when COUNT is 954 positive, or a right shift rounding to the nearest integer (with 955 ties going to the nearest even integer) when COUNT is negative. 956 This is a rounded “arithmetic” shift. 957 958 (number->string (round-ash #b1 3) 2) ⇒ \"1000\" 959 (number->string (round-ash #b1010 -1) 2) ⇒ \"101\" 960 (number->string (round-ash #b1010 -2) 2) ⇒ \"10\" 961 (number->string (round-ash #b1011 -2) 2) ⇒ \"11\" 962 (number->string (round-ash #b1101 -2) 2) ⇒ \"11\" 963 (number->string (round-ash #b1110 -2) 2) ⇒ \"100\" 964 965 -- Scheme Procedure: logcount n 966 -- C Function: scm_logcount (n) 967 Return the number of bits in integer N. If N is positive, the 968 1-bits in its binary representation are counted. If negative, the 969 0-bits in its two’s-complement binary representation are counted. 970 If zero, 0 is returned. 971 972 (logcount #b10101010) 973 ⇒ 4 974 (logcount 0) 975 ⇒ 0 976 (logcount -2) 977 ⇒ 1 978 979 -- Scheme Procedure: integer-length n 980 -- C Function: scm_integer_length (n) 981 Return the number of bits necessary to represent N. 982 983 For positive N this is how many bits to the most significant one 984 bit. For negative N it’s how many bits to the most significant 985 zero bit in twos complement form. 986 987 (integer-length #b10101010) ⇒ 8 988 (integer-length #b1111) ⇒ 4 989 (integer-length 0) ⇒ 0 990 (integer-length -1) ⇒ 0 991 (integer-length -256) ⇒ 8 992 (integer-length -257) ⇒ 9 993 994 -- Scheme Procedure: integer-expt n k 995 -- C Function: scm_integer_expt (n, k) 996 Return N raised to the power K. K must be an exact integer, N can 997 be any number. 998 999 Negative K is supported, and results in 1/n^abs(k) in the usual 1000 way. N^0 is 1, as usual, and that includes 0^0 is 1. 1001 1002 (integer-expt 2 5) ⇒ 32 1003 (integer-expt -3 3) ⇒ -27 1004 (integer-expt 5 -3) ⇒ 1/125 1005 (integer-expt 0 0) ⇒ 1 1006 1007 -- Scheme Procedure: bit-extract n start end 1008 -- C Function: scm_bit_extract (n, start, end) 1009 Return the integer composed of the START (inclusive) through END 1010 (exclusive) bits of N. The STARTth bit becomes the 0-th bit in the 1011 result. 1012 1013 (number->string (bit-extract #b1101101010 0 4) 2) 1014 ⇒ "1010" 1015 (number->string (bit-extract #b1101101010 4 9) 2) 1016 ⇒ "10110" 1017 1018 1019File: guile.info, Node: Random, Prev: Bitwise Operations, Up: Numbers 1020 10216.6.2.14 Random Number Generation 1022................................. 1023 1024Pseudo-random numbers are generated from a random state object, which 1025can be created with ‘seed->random-state’ or ‘datum->random-state’. An 1026external representation (i.e. one which can written with ‘write’ and 1027read with ‘read’) of a random state object can be obtained via 1028‘random-state->datum’. The STATE parameter to the various functions 1029below is optional, it defaults to the state object in the 1030‘*random-state*’ variable. 1031 1032 -- Scheme Procedure: copy-random-state [state] 1033 -- C Function: scm_copy_random_state (state) 1034 Return a copy of the random state STATE. 1035 1036 -- Scheme Procedure: random n [state] 1037 -- C Function: scm_random (n, state) 1038 Return a number in [0, N). 1039 1040 Accepts a positive integer or real n and returns a number of the 1041 same type between zero (inclusive) and N (exclusive). The values 1042 returned have a uniform distribution. 1043 1044 -- Scheme Procedure: random:exp [state] 1045 -- C Function: scm_random_exp (state) 1046 Return an inexact real in an exponential distribution with mean 1. 1047 For an exponential distribution with mean U use ‘(* U 1048 (random:exp))’. 1049 1050 -- Scheme Procedure: random:hollow-sphere! vect [state] 1051 -- C Function: scm_random_hollow_sphere_x (vect, state) 1052 Fills VECT with inexact real random numbers the sum of whose 1053 squares is equal to 1.0. Thinking of VECT as coordinates in space 1054 of dimension N = ‘(vector-length VECT)’, the coordinates are 1055 uniformly distributed over the surface of the unit n-sphere. 1056 1057 -- Scheme Procedure: random:normal [state] 1058 -- C Function: scm_random_normal (state) 1059 Return an inexact real in a normal distribution. The distribution 1060 used has mean 0 and standard deviation 1. For a normal 1061 distribution with mean M and standard deviation D use ‘(+ M (* D 1062 (random:normal)))’. 1063 1064 -- Scheme Procedure: random:normal-vector! vect [state] 1065 -- C Function: scm_random_normal_vector_x (vect, state) 1066 Fills VECT with inexact real random numbers that are independent 1067 and standard normally distributed (i.e., with mean 0 and variance 1068 1). 1069 1070 -- Scheme Procedure: random:solid-sphere! vect [state] 1071 -- C Function: scm_random_solid_sphere_x (vect, state) 1072 Fills VECT with inexact real random numbers the sum of whose 1073 squares is less than 1.0. Thinking of VECT as coordinates in space 1074 of dimension N = ‘(vector-length VECT)’, the coordinates are 1075 uniformly distributed within the unit N-sphere. 1076 1077 -- Scheme Procedure: random:uniform [state] 1078 -- C Function: scm_random_uniform (state) 1079 Return a uniformly distributed inexact real random number in [0,1). 1080 1081 -- Scheme Procedure: seed->random-state seed 1082 -- C Function: scm_seed_to_random_state (seed) 1083 Return a new random state using SEED. 1084 1085 -- Scheme Procedure: datum->random-state datum 1086 -- C Function: scm_datum_to_random_state (datum) 1087 Return a new random state from DATUM, which should have been 1088 obtained by ‘random-state->datum’. 1089 1090 -- Scheme Procedure: random-state->datum state 1091 -- C Function: scm_random_state_to_datum (state) 1092 Return a datum representation of STATE that may be written out and 1093 read back with the Scheme reader. 1094 1095 -- Scheme Procedure: random-state-from-platform 1096 -- C Function: scm_random_state_from_platform () 1097 Construct a new random state seeded from a platform-specific source 1098 of entropy, appropriate for use in non-security-critical 1099 applications. Currently ‘/dev/urandom’ is tried first, or else the 1100 seed is based on the time, date, process ID, an address from a 1101 freshly allocated heap cell, an address from the local stack frame, 1102 and a high-resolution timer if available. 1103 1104 -- Variable: *random-state* 1105 The global random state used by the above functions when the STATE 1106 parameter is not given. 1107 1108 Note that the initial value of ‘*random-state*’ is the same every 1109time Guile starts up. Therefore, if you don’t pass a STATE parameter to 1110the above procedures, and you don’t set ‘*random-state*’ to 1111‘(seed->random-state your-seed)’, where ‘your-seed’ is something that 1112_isn’t_ the same every time, you’ll get the same sequence of “random” 1113numbers on every run. 1114 1115 For example, unless the relevant source code has changed, ‘(map 1116random (cdr (iota 30)))’, if the first use of random numbers since Guile 1117started up, will always give: 1118 1119 (map random (cdr (iota 19))) 1120 ⇒ 1121 (0 1 1 2 2 2 1 2 6 7 10 0 5 3 12 5 5 12) 1122 1123 To seed the random state in a sensible way for non-security-critical 1124applications, do this during initialization of your program: 1125 1126 (set! *random-state* (random-state-from-platform)) 1127 1128 1129File: guile.info, Node: Characters, Next: Character Sets, Prev: Numbers, Up: Data Types 1130 11316.6.3 Characters 1132---------------- 1133 1134In Scheme, there is a data type to describe a single character. 1135 1136 Defining what exactly a character _is_ can be more complicated than 1137it seems. Guile follows the advice of R6RS and uses The Unicode 1138Standard to help define what a character is. So, for Guile, a character 1139is anything in the Unicode Character Database. 1140 1141 The Unicode Character Database is basically a table of characters 1142indexed using integers called ’code points’. Valid code points are in 1143the ranges 0 to ‘#xD7FF’ inclusive or ‘#xE000’ to ‘#x10FFFF’ inclusive, 1144which is about 1.1 million code points. 1145 1146 Any code point that has been assigned to a character or that has 1147otherwise been given a meaning by Unicode is called a ’designated code 1148point’. Most of the designated code points, about 200,000 of them, 1149indicate characters, accents or other combining marks that modify other 1150characters, symbols, whitespace, and control characters. Some are not 1151characters but indicators that suggest how to format or display 1152neighboring characters. 1153 1154 If a code point is not a designated code point – if it has not been 1155assigned to a character by The Unicode Standard – it is a ’reserved code 1156point’, meaning that they are reserved for future use. Most of the code 1157points, about 800,000, are ’reserved code points’. 1158 1159 By convention, a Unicode code point is written as “U+XXXX” where 1160“XXXX” is a hexadecimal number. Please note that this convenient 1161notation is not valid code. Guile does not interpret “U+XXXX” as a 1162character. 1163 1164 In Scheme, a character literal is written as ‘#\NAME’ where NAME is 1165the name of the character that you want. Printable characters have 1166their usual single character name; for example, ‘#\a’ is a lower case 1167‘a’. 1168 1169 Some of the code points are ’combining characters’ that are not meant 1170to be printed by themselves but are instead meant to modify the 1171appearance of the previous character. For combining characters, an 1172alternate form of the character literal is ‘#\’ followed by U+25CC (a 1173small, dotted circle), followed by the combining character. This allows 1174the combining character to be drawn on the circle, not on the backslash 1175of ‘#\’. 1176 1177 Many of the non-printing characters, such as whitespace characters 1178and control characters, also have names. 1179 1180 The most commonly used non-printing characters have long character 1181names, described in the table below. 1182 1183Character Codepoint 1184Name 1185‘#\nul’ U+0000 1186‘#\alarm’ U+0007 1187‘#\backspace’ U+0008 1188‘#\tab’ U+0009 1189‘#\linefeed’ U+000A 1190‘#\newline’ U+000A 1191‘#\vtab’ U+000B 1192‘#\page’ U+000C 1193‘#\return’ U+000D 1194‘#\esc’ U+001B 1195‘#\space’ U+0020 1196‘#\delete’ U+007F 1197 1198 There are also short names for all of the “C0 control characters” 1199(those with code points below 32). The following table lists the short 1200name for each character. 1201 12020 = ‘#\nul’ 1 = ‘#\soh’ 2 = ‘#\stx’ 3 = ‘#\etx’ 12034 = ‘#\eot’ 5 = ‘#\enq’ 6 = ‘#\ack’ 7 = ‘#\bel’ 12048 = ‘#\bs’ 9 = ‘#\ht’ 10 = ‘#\lf’ 11 = ‘#\vt’ 120512 = ‘#\ff’ 13 = ‘#\cr’ 14 = ‘#\so’ 15 = ‘#\si’ 120616 = ‘#\dle’ 17 = ‘#\dc1’ 18 = ‘#\dc2’ 19 = ‘#\dc3’ 120720 = ‘#\dc4’ 21 = ‘#\nak’ 22 = ‘#\syn’ 23 = ‘#\etb’ 120824 = ‘#\can’ 25 = ‘#\em’ 26 = ‘#\sub’ 27 = ‘#\esc’ 120928 = ‘#\fs’ 29 = ‘#\gs’ 30 = ‘#\rs’ 31 = ‘#\us’ 121032 = ‘#\sp’ 1211 1212 The short name for the “delete” character (code point U+007F) is 1213‘#\del’. 1214 1215 The R7RS name for the “escape” character (code point U+001B) is 1216‘#\escape’. 1217 1218 There are also a few alternative names left over for compatibility 1219with previous versions of Guile. 1220 1221Alternate Standard 1222‘#\nl’ ‘#\newline’ 1223‘#\np’ ‘#\page’ 1224‘#\null’ ‘#\nul’ 1225 1226 Characters may also be written using their code point values. They 1227can be written with as an octal number, such as ‘#\10’ for ‘#\bs’ or 1228‘#\177’ for ‘#\del’. 1229 1230 If one prefers hex to octal, there is an additional syntax for 1231character escapes: ‘#\xHHHH’ – the letter ’x’ followed by a hexadecimal 1232number of one to eight digits. 1233 1234 -- Scheme Procedure: char? x 1235 -- C Function: scm_char_p (x) 1236 Return ‘#t’ if X is a character, else ‘#f’. 1237 1238 Fundamentally, the character comparison operations below are numeric 1239comparisons of the character’s code points. 1240 1241 -- Scheme Procedure: char=? x y 1242 Return ‘#t’ if code point of X is equal to the code point of Y, 1243 else ‘#f’. 1244 1245 -- Scheme Procedure: char<? x y 1246 Return ‘#t’ if the code point of X is less than the code point of 1247 Y, else ‘#f’. 1248 1249 -- Scheme Procedure: char<=? x y 1250 Return ‘#t’ if the code point of X is less than or equal to the 1251 code point of Y, else ‘#f’. 1252 1253 -- Scheme Procedure: char>? x y 1254 Return ‘#t’ if the code point of X is greater than the code point 1255 of Y, else ‘#f’. 1256 1257 -- Scheme Procedure: char>=? x y 1258 Return ‘#t’ if the code point of X is greater than or equal to the 1259 code point of Y, else ‘#f’. 1260 1261 Case-insensitive character comparisons use _Unicode case folding_. 1262In case folding comparisons, if a character is lowercase and has an 1263uppercase form that can be expressed as a single character, it is 1264converted to uppercase before comparison. All other characters undergo 1265no conversion before the comparison occurs. This includes the German 1266sharp S (Eszett) which is not uppercased before conversion because its 1267uppercase form has two characters. Unicode case folding is language 1268independent: it uses rules that are generally true, but, it cannot cover 1269all cases for all languages. 1270 1271 -- Scheme Procedure: char-ci=? x y 1272 Return ‘#t’ if the case-folded code point of X is the same as the 1273 case-folded code point of Y, else ‘#f’. 1274 1275 -- Scheme Procedure: char-ci<? x y 1276 Return ‘#t’ if the case-folded code point of X is less than the 1277 case-folded code point of Y, else ‘#f’. 1278 1279 -- Scheme Procedure: char-ci<=? x y 1280 Return ‘#t’ if the case-folded code point of X is less than or 1281 equal to the case-folded code point of Y, else ‘#f’. 1282 1283 -- Scheme Procedure: char-ci>? x y 1284 Return ‘#t’ if the case-folded code point of X is greater than the 1285 case-folded code point of Y, else ‘#f’. 1286 1287 -- Scheme Procedure: char-ci>=? x y 1288 Return ‘#t’ if the case-folded code point of X is greater than or 1289 equal to the case-folded code point of Y, else ‘#f’. 1290 1291 -- Scheme Procedure: char-alphabetic? chr 1292 -- C Function: scm_char_alphabetic_p (chr) 1293 Return ‘#t’ if CHR is alphabetic, else ‘#f’. 1294 1295 -- Scheme Procedure: char-numeric? chr 1296 -- C Function: scm_char_numeric_p (chr) 1297 Return ‘#t’ if CHR is numeric, else ‘#f’. 1298 1299 -- Scheme Procedure: char-whitespace? chr 1300 -- C Function: scm_char_whitespace_p (chr) 1301 Return ‘#t’ if CHR is whitespace, else ‘#f’. 1302 1303 -- Scheme Procedure: char-upper-case? chr 1304 -- C Function: scm_char_upper_case_p (chr) 1305 Return ‘#t’ if CHR is uppercase, else ‘#f’. 1306 1307 -- Scheme Procedure: char-lower-case? chr 1308 -- C Function: scm_char_lower_case_p (chr) 1309 Return ‘#t’ if CHR is lowercase, else ‘#f’. 1310 1311 -- Scheme Procedure: char-is-both? chr 1312 -- C Function: scm_char_is_both_p (chr) 1313 Return ‘#t’ if CHR is either uppercase or lowercase, else ‘#f’. 1314 1315 -- Scheme Procedure: char-general-category chr 1316 -- C Function: scm_char_general_category (chr) 1317 Return a symbol giving the two-letter name of the Unicode general 1318 category assigned to CHR or ‘#f’ if no named category is assigned. 1319 The following table provides a list of category names along with 1320 their meanings. 1321 1322 Lu Uppercase letter Pf Final quote punctuation 1323 Ll Lowercase letter Po Other punctuation 1324 Lt Titlecase letter Sm Math symbol 1325 Lm Modifier letter Sc Currency symbol 1326 Lo Other letter Sk Modifier symbol 1327 Mn Non-spacing mark So Other symbol 1328 Mc Combining spacing mark Zs Space separator 1329 Me Enclosing mark Zl Line separator 1330 Nd Decimal digit number Zp Paragraph separator 1331 Nl Letter number Cc Control 1332 No Other number Cf Format 1333 Pc Connector punctuation Cs Surrogate 1334 Pd Dash punctuation Co Private use 1335 Ps Open punctuation Cn Unassigned 1336 Pe Close punctuation 1337 Pi Initial quote punctuation 1338 1339 -- Scheme Procedure: char->integer chr 1340 -- C Function: scm_char_to_integer (chr) 1341 Return the code point of CHR. 1342 1343 -- Scheme Procedure: integer->char n 1344 -- C Function: scm_integer_to_char (n) 1345 Return the character that has code point N. The integer N must be 1346 a valid code point. Valid code points are in the ranges 0 to 1347 ‘#xD7FF’ inclusive or ‘#xE000’ to ‘#x10FFFF’ inclusive. 1348 1349 -- Scheme Procedure: char-upcase chr 1350 -- C Function: scm_char_upcase (chr) 1351 Return the uppercase character version of CHR. 1352 1353 -- Scheme Procedure: char-downcase chr 1354 -- C Function: scm_char_downcase (chr) 1355 Return the lowercase character version of CHR. 1356 1357 -- Scheme Procedure: char-titlecase chr 1358 -- C Function: scm_char_titlecase (chr) 1359 Return the titlecase character version of CHR if one exists; 1360 otherwise return the uppercase version. 1361 1362 For most characters these will be the same, but the Unicode 1363 Standard includes certain digraph compatibility characters, such as 1364 ‘U+01F3’ “dz”, for which the uppercase and titlecase characters are 1365 different (‘U+01F1’ “DZ” and ‘U+01F2’ “Dz” in this case, 1366 respectively). 1367 1368 -- C Function: scm_t_wchar scm_c_upcase (scm_t_wchar C) 1369 -- C Function: scm_t_wchar scm_c_downcase (scm_t_wchar C) 1370 -- C Function: scm_t_wchar scm_c_titlecase (scm_t_wchar C) 1371 1372 These C functions take an integer representation of a Unicode 1373 codepoint and return the codepoint corresponding to its uppercase, 1374 lowercase, and titlecase forms respectively. The type 1375 ‘scm_t_wchar’ is a signed, 32-bit integer. 1376 1377 Characters also have “formal names”, which are defined by Unicode. 1378These names can be accessed in Guile from the ‘(ice-9 unicode)’ module: 1379 1380 (use-modules (ice-9 unicode)) 1381 1382 -- Scheme Procedure: char->formal-name chr 1383 Return the formal all-upper-case Unicode name of CH, as a string, 1384 or ‘#f’ if the character has no name. 1385 1386 -- Scheme Procedure: formal-name->char name 1387 Return the character whose formal all-upper-case Unicode name is 1388 NAME, or ‘#f’ if no such character is known. 1389 1390 1391File: guile.info, Node: Character Sets, Next: Strings, Prev: Characters, Up: Data Types 1392 13936.6.4 Character Sets 1394-------------------- 1395 1396The features described in this section correspond directly to SRFI-14. 1397 1398 The data type “charset” implements sets of characters (*note 1399Characters::). Because the internal representation of character sets is 1400not visible to the user, a lot of procedures for handling them are 1401provided. 1402 1403 Character sets can be created, extended, tested for the membership of 1404a characters and be compared to other character sets. 1405 1406* Menu: 1407 1408* Character Set Predicates/Comparison:: 1409* Iterating Over Character Sets:: Enumerate charset elements. 1410* Creating Character Sets:: Making new charsets. 1411* Querying Character Sets:: Test charsets for membership etc. 1412* Character-Set Algebra:: Calculating new charsets. 1413* Standard Character Sets:: Variables containing predefined charsets. 1414 1415 1416File: guile.info, Node: Character Set Predicates/Comparison, Next: Iterating Over Character Sets, Up: Character Sets 1417 14186.6.4.1 Character Set Predicates/Comparison 1419........................................... 1420 1421Use these procedures for testing whether an object is a character set, 1422or whether several character sets are equal or subsets of each other. 1423‘char-set-hash’ can be used for calculating a hash value, maybe for 1424usage in fast lookup procedures. 1425 1426 -- Scheme Procedure: char-set? obj 1427 -- C Function: scm_char_set_p (obj) 1428 Return ‘#t’ if OBJ is a character set, ‘#f’ otherwise. 1429 1430 -- Scheme Procedure: char-set= char_set ... 1431 -- C Function: scm_char_set_eq (char_sets) 1432 Return ‘#t’ if all given character sets are equal. 1433 1434 -- Scheme Procedure: char-set<= char_set ... 1435 -- C Function: scm_char_set_leq (char_sets) 1436 Return ‘#t’ if every character set CHAR_SETi is a subset of 1437 character set CHAR_SETi+1. 1438 1439 -- Scheme Procedure: char-set-hash cs [bound] 1440 -- C Function: scm_char_set_hash (cs, bound) 1441 Compute a hash value for the character set CS. If BOUND is given 1442 and non-zero, it restricts the returned value to the range 0 ... 1443 BOUND - 1. 1444 1445 1446File: guile.info, Node: Iterating Over Character Sets, Next: Creating Character Sets, Prev: Character Set Predicates/Comparison, Up: Character Sets 1447 14486.6.4.2 Iterating Over Character Sets 1449..................................... 1450 1451Character set cursors are a means for iterating over the members of a 1452character sets. After creating a character set cursor with 1453‘char-set-cursor’, a cursor can be dereferenced with ‘char-set-ref’, 1454advanced to the next member with ‘char-set-cursor-next’. Whether a 1455cursor has passed past the last element of the set can be checked with 1456‘end-of-char-set?’. 1457 1458 Additionally, mapping and (un-)folding procedures for character sets 1459are provided. 1460 1461 -- Scheme Procedure: char-set-cursor cs 1462 -- C Function: scm_char_set_cursor (cs) 1463 Return a cursor into the character set CS. 1464 1465 -- Scheme Procedure: char-set-ref cs cursor 1466 -- C Function: scm_char_set_ref (cs, cursor) 1467 Return the character at the current cursor position CURSOR in the 1468 character set CS. It is an error to pass a cursor for which 1469 ‘end-of-char-set?’ returns true. 1470 1471 -- Scheme Procedure: char-set-cursor-next cs cursor 1472 -- C Function: scm_char_set_cursor_next (cs, cursor) 1473 Advance the character set cursor CURSOR to the next character in 1474 the character set CS. It is an error if the cursor given satisfies 1475 ‘end-of-char-set?’. 1476 1477 -- Scheme Procedure: end-of-char-set? cursor 1478 -- C Function: scm_end_of_char_set_p (cursor) 1479 Return ‘#t’ if CURSOR has reached the end of a character set, ‘#f’ 1480 otherwise. 1481 1482 -- Scheme Procedure: char-set-fold kons knil cs 1483 -- C Function: scm_char_set_fold (kons, knil, cs) 1484 Fold the procedure KONS over the character set CS, initializing it 1485 with KNIL. 1486 1487 -- Scheme Procedure: char-set-unfold p f g seed [base_cs] 1488 -- C Function: scm_char_set_unfold (p, f, g, seed, base_cs) 1489 This is a fundamental constructor for character sets. 1490 • G is used to generate a series of “seed” values from the 1491 initial seed: SEED, (G SEED), (G^2 SEED), (G^3 SEED), ... 1492 • P tells us when to stop – when it returns true when applied to 1493 one of the seed values. 1494 • F maps each seed value to a character. These characters are 1495 added to the base character set BASE_CS to form the result; 1496 BASE_CS defaults to the empty set. 1497 1498 -- Scheme Procedure: char-set-unfold! p f g seed base_cs 1499 -- C Function: scm_char_set_unfold_x (p, f, g, seed, base_cs) 1500 This is a fundamental constructor for character sets. 1501 • G is used to generate a series of “seed” values from the 1502 initial seed: SEED, (G SEED), (G^2 SEED), (G^3 SEED), ... 1503 • P tells us when to stop – when it returns true when applied to 1504 one of the seed values. 1505 • F maps each seed value to a character. These characters are 1506 added to the base character set BASE_CS to form the result; 1507 BASE_CS defaults to the empty set. 1508 1509 -- Scheme Procedure: char-set-for-each proc cs 1510 -- C Function: scm_char_set_for_each (proc, cs) 1511 Apply PROC to every character in the character set CS. The return 1512 value is not specified. 1513 1514 -- Scheme Procedure: char-set-map proc cs 1515 -- C Function: scm_char_set_map (proc, cs) 1516 Map the procedure PROC over every character in CS. PROC must be a 1517 character -> character procedure. 1518 1519 1520File: guile.info, Node: Creating Character Sets, Next: Querying Character Sets, Prev: Iterating Over Character Sets, Up: Character Sets 1521 15226.6.4.3 Creating Character Sets 1523............................... 1524 1525New character sets are produced with these procedures. 1526 1527 -- Scheme Procedure: char-set-copy cs 1528 -- C Function: scm_char_set_copy (cs) 1529 Return a newly allocated character set containing all characters in 1530 CS. 1531 1532 -- Scheme Procedure: char-set chr ... 1533 -- C Function: scm_char_set (chrs) 1534 Return a character set containing all given characters. 1535 1536 -- Scheme Procedure: list->char-set list [base_cs] 1537 -- C Function: scm_list_to_char_set (list, base_cs) 1538 Convert the character list LIST to a character set. If the 1539 character set BASE_CS is given, the character in this set are also 1540 included in the result. 1541 1542 -- Scheme Procedure: list->char-set! list base_cs 1543 -- C Function: scm_list_to_char_set_x (list, base_cs) 1544 Convert the character list LIST to a character set. The characters 1545 are added to BASE_CS and BASE_CS is returned. 1546 1547 -- Scheme Procedure: string->char-set str [base_cs] 1548 -- C Function: scm_string_to_char_set (str, base_cs) 1549 Convert the string STR to a character set. If the character set 1550 BASE_CS is given, the characters in this set are also included in 1551 the result. 1552 1553 -- Scheme Procedure: string->char-set! str base_cs 1554 -- C Function: scm_string_to_char_set_x (str, base_cs) 1555 Convert the string STR to a character set. The characters from the 1556 string are added to BASE_CS, and BASE_CS is returned. 1557 1558 -- Scheme Procedure: char-set-filter pred cs [base_cs] 1559 -- C Function: scm_char_set_filter (pred, cs, base_cs) 1560 Return a character set containing every character from CS so that 1561 it satisfies PRED. If provided, the characters from BASE_CS are 1562 added to the result. 1563 1564 -- Scheme Procedure: char-set-filter! pred cs base_cs 1565 -- C Function: scm_char_set_filter_x (pred, cs, base_cs) 1566 Return a character set containing every character from CS so that 1567 it satisfies PRED. The characters are added to BASE_CS and BASE_CS 1568 is returned. 1569 1570 -- Scheme Procedure: ucs-range->char-set lower upper [error [base_cs]] 1571 -- C Function: scm_ucs_range_to_char_set (lower, upper, error, base_cs) 1572 Return a character set containing all characters whose character 1573 codes lie in the half-open range [LOWER,UPPER). 1574 1575 If ERROR is a true value, an error is signalled if the specified 1576 range contains characters which are not contained in the 1577 implemented character range. If ERROR is ‘#f’, these characters 1578 are silently left out of the resulting character set. 1579 1580 The characters in BASE_CS are added to the result, if given. 1581 1582 -- Scheme Procedure: ucs-range->char-set! lower upper error base_cs 1583 -- C Function: scm_ucs_range_to_char_set_x (lower, upper, error, 1584 base_cs) 1585 Return a character set containing all characters whose character 1586 codes lie in the half-open range [LOWER,UPPER). 1587 1588 If ERROR is a true value, an error is signalled if the specified 1589 range contains characters which are not contained in the 1590 implemented character range. If ERROR is ‘#f’, these characters 1591 are silently left out of the resulting character set. 1592 1593 The characters are added to BASE_CS and BASE_CS is returned. 1594 1595 -- Scheme Procedure: ->char-set x 1596 -- C Function: scm_to_char_set (x) 1597 Coerces x into a char-set. X may be a string, character or 1598 char-set. A string is converted to the set of its constituent 1599 characters; a character is converted to a singleton set; a char-set 1600 is returned as-is. 1601 1602 1603File: guile.info, Node: Querying Character Sets, Next: Character-Set Algebra, Prev: Creating Character Sets, Up: Character Sets 1604 16056.6.4.4 Querying Character Sets 1606............................... 1607 1608Access the elements and other information of a character set with these 1609procedures. 1610 1611 -- Scheme Procedure: %char-set-dump cs 1612 Returns an association list containing debugging information for 1613 CS. The association list has the following entries. 1614 ‘char-set’ 1615 The char-set itself 1616 ‘len’ 1617 The number of groups of contiguous code points the char-set 1618 contains 1619 ‘ranges’ 1620 A list of lists where each sublist is a range of code points 1621 and their associated characters 1622 The return value of this function cannot be relied upon to be 1623 consistent between versions of Guile and should not be used in 1624 code. 1625 1626 -- Scheme Procedure: char-set-size cs 1627 -- C Function: scm_char_set_size (cs) 1628 Return the number of elements in character set CS. 1629 1630 -- Scheme Procedure: char-set-count pred cs 1631 -- C Function: scm_char_set_count (pred, cs) 1632 Return the number of the elements int the character set CS which 1633 satisfy the predicate PRED. 1634 1635 -- Scheme Procedure: char-set->list cs 1636 -- C Function: scm_char_set_to_list (cs) 1637 Return a list containing the elements of the character set CS. 1638 1639 -- Scheme Procedure: char-set->string cs 1640 -- C Function: scm_char_set_to_string (cs) 1641 Return a string containing the elements of the character set CS. 1642 The order in which the characters are placed in the string is not 1643 defined. 1644 1645 -- Scheme Procedure: char-set-contains? cs ch 1646 -- C Function: scm_char_set_contains_p (cs, ch) 1647 Return ‘#t’ if the character CH is contained in the character set 1648 CS, or ‘#f’ otherwise. 1649 1650 -- Scheme Procedure: char-set-every pred cs 1651 -- C Function: scm_char_set_every (pred, cs) 1652 Return a true value if every character in the character set CS 1653 satisfies the predicate PRED. 1654 1655 -- Scheme Procedure: char-set-any pred cs 1656 -- C Function: scm_char_set_any (pred, cs) 1657 Return a true value if any character in the character set CS 1658 satisfies the predicate PRED. 1659 1660 1661File: guile.info, Node: Character-Set Algebra, Next: Standard Character Sets, Prev: Querying Character Sets, Up: Character Sets 1662 16636.6.4.5 Character-Set Algebra 1664............................. 1665 1666Character sets can be manipulated with the common set algebra operation, 1667such as union, complement, intersection etc. All of these procedures 1668provide side-effecting variants, which modify their character set 1669argument(s). 1670 1671 -- Scheme Procedure: char-set-adjoin cs chr ... 1672 -- C Function: scm_char_set_adjoin (cs, chrs) 1673 Add all character arguments to the first argument, which must be a 1674 character set. 1675 1676 -- Scheme Procedure: char-set-delete cs chr ... 1677 -- C Function: scm_char_set_delete (cs, chrs) 1678 Delete all character arguments from the first argument, which must 1679 be a character set. 1680 1681 -- Scheme Procedure: char-set-adjoin! cs chr ... 1682 -- C Function: scm_char_set_adjoin_x (cs, chrs) 1683 Add all character arguments to the first argument, which must be a 1684 character set. 1685 1686 -- Scheme Procedure: char-set-delete! cs chr ... 1687 -- C Function: scm_char_set_delete_x (cs, chrs) 1688 Delete all character arguments from the first argument, which must 1689 be a character set. 1690 1691 -- Scheme Procedure: char-set-complement cs 1692 -- C Function: scm_char_set_complement (cs) 1693 Return the complement of the character set CS. 1694 1695 Note that the complement of a character set is likely to contain many 1696reserved code points (code points that are not associated with 1697characters). It may be helpful to modify the output of 1698‘char-set-complement’ by computing its intersection with the set of 1699designated code points, ‘char-set:designated’. 1700 1701 -- Scheme Procedure: char-set-union cs ... 1702 -- C Function: scm_char_set_union (char_sets) 1703 Return the union of all argument character sets. 1704 1705 -- Scheme Procedure: char-set-intersection cs ... 1706 -- C Function: scm_char_set_intersection (char_sets) 1707 Return the intersection of all argument character sets. 1708 1709 -- Scheme Procedure: char-set-difference cs1 cs ... 1710 -- C Function: scm_char_set_difference (cs1, char_sets) 1711 Return the difference of all argument character sets. 1712 1713 -- Scheme Procedure: char-set-xor cs ... 1714 -- C Function: scm_char_set_xor (char_sets) 1715 Return the exclusive-or of all argument character sets. 1716 1717 -- Scheme Procedure: char-set-diff+intersection cs1 cs ... 1718 -- C Function: scm_char_set_diff_plus_intersection (cs1, char_sets) 1719 Return the difference and the intersection of all argument 1720 character sets. 1721 1722 -- Scheme Procedure: char-set-complement! cs 1723 -- C Function: scm_char_set_complement_x (cs) 1724 Return the complement of the character set CS. 1725 1726 -- Scheme Procedure: char-set-union! cs1 cs ... 1727 -- C Function: scm_char_set_union_x (cs1, char_sets) 1728 Return the union of all argument character sets. 1729 1730 -- Scheme Procedure: char-set-intersection! cs1 cs ... 1731 -- C Function: scm_char_set_intersection_x (cs1, char_sets) 1732 Return the intersection of all argument character sets. 1733 1734 -- Scheme Procedure: char-set-difference! cs1 cs ... 1735 -- C Function: scm_char_set_difference_x (cs1, char_sets) 1736 Return the difference of all argument character sets. 1737 1738 -- Scheme Procedure: char-set-xor! cs1 cs ... 1739 -- C Function: scm_char_set_xor_x (cs1, char_sets) 1740 Return the exclusive-or of all argument character sets. 1741 1742 -- Scheme Procedure: char-set-diff+intersection! cs1 cs2 cs ... 1743 -- C Function: scm_char_set_diff_plus_intersection_x (cs1, cs2, 1744 char_sets) 1745 Return the difference and the intersection of all argument 1746 character sets. 1747 1748 1749File: guile.info, Node: Standard Character Sets, Prev: Character-Set Algebra, Up: Character Sets 1750 17516.6.4.6 Standard Character Sets 1752............................... 1753 1754In order to make the use of the character set data type and procedures 1755useful, several predefined character set variables exist. 1756 1757 These character sets are locale independent and are not recomputed 1758upon a ‘setlocale’ call. They contain characters from the whole range 1759of Unicode code points. For instance, ‘char-set:letter’ contains about 1760100,000 characters. 1761 1762 -- Scheme Variable: char-set:lower-case 1763 -- C Variable: scm_char_set_lower_case 1764 All lower-case characters. 1765 1766 -- Scheme Variable: char-set:upper-case 1767 -- C Variable: scm_char_set_upper_case 1768 All upper-case characters. 1769 1770 -- Scheme Variable: char-set:title-case 1771 -- C Variable: scm_char_set_title_case 1772 All single characters that function as if they were an upper-case 1773 letter followed by a lower-case letter. 1774 1775 -- Scheme Variable: char-set:letter 1776 -- C Variable: scm_char_set_letter 1777 All letters. This includes ‘char-set:lower-case’, 1778 ‘char-set:upper-case’, ‘char-set:title-case’, and many letters that 1779 have no case at all. For example, Chinese and Japanese characters 1780 typically have no concept of case. 1781 1782 -- Scheme Variable: char-set:digit 1783 -- C Variable: scm_char_set_digit 1784 All digits. 1785 1786 -- Scheme Variable: char-set:letter+digit 1787 -- C Variable: scm_char_set_letter_and_digit 1788 The union of ‘char-set:letter’ and ‘char-set:digit’. 1789 1790 -- Scheme Variable: char-set:graphic 1791 -- C Variable: scm_char_set_graphic 1792 All characters which would put ink on the paper. 1793 1794 -- Scheme Variable: char-set:printing 1795 -- C Variable: scm_char_set_printing 1796 The union of ‘char-set:graphic’ and ‘char-set:whitespace’. 1797 1798 -- Scheme Variable: char-set:whitespace 1799 -- C Variable: scm_char_set_whitespace 1800 All whitespace characters. 1801 1802 -- Scheme Variable: char-set:blank 1803 -- C Variable: scm_char_set_blank 1804 All horizontal whitespace characters, which notably includes 1805 ‘#\space’ and ‘#\tab’. 1806 1807 -- Scheme Variable: char-set:iso-control 1808 -- C Variable: scm_char_set_iso_control 1809 The ISO control characters are the C0 control characters (U+0000 to 1810 U+001F), delete (U+007F), and the C1 control characters (U+0080 to 1811 U+009F). 1812 1813 -- Scheme Variable: char-set:punctuation 1814 -- C Variable: scm_char_set_punctuation 1815 All punctuation characters, such as the characters 1816 ‘!"#%&'()*,-./:;?@[\\]_{}’ 1817 1818 -- Scheme Variable: char-set:symbol 1819 -- C Variable: scm_char_set_symbol 1820 All symbol characters, such as the characters ‘$+<=>^`|~’. 1821 1822 -- Scheme Variable: char-set:hex-digit 1823 -- C Variable: scm_char_set_hex_digit 1824 The hexadecimal digits ‘0123456789abcdefABCDEF’. 1825 1826 -- Scheme Variable: char-set:ascii 1827 -- C Variable: scm_char_set_ascii 1828 All ASCII characters. 1829 1830 -- Scheme Variable: char-set:empty 1831 -- C Variable: scm_char_set_empty 1832 The empty character set. 1833 1834 -- Scheme Variable: char-set:designated 1835 -- C Variable: scm_char_set_designated 1836 This character set contains all designated code points. This 1837 includes all the code points to which Unicode has assigned a 1838 character or other meaning. 1839 1840 -- Scheme Variable: char-set:full 1841 -- C Variable: scm_char_set_full 1842 This character set contains all possible code points. This 1843 includes both designated and reserved code points. 1844 1845 1846File: guile.info, Node: Strings, Next: Symbols, Prev: Character Sets, Up: Data Types 1847 18486.6.5 Strings 1849------------- 1850 1851Strings are fixed-length sequences of characters. They can be created 1852by calling constructor procedures, but they can also literally get 1853entered at the REPL or in Scheme source files. 1854 1855 Strings always carry the information about how many characters they 1856are composed of with them, so there is no special end-of-string 1857character, like in C. That means that Scheme strings can contain any 1858character, even the ‘#\nul’ character ‘\0’. 1859 1860 To use strings efficiently, you need to know a bit about how Guile 1861implements them. In Guile, a string consists of two parts, a head and 1862the actual memory where the characters are stored. When a string (or a 1863substring of it) is copied, only a new head gets created, the memory is 1864usually not copied. The two heads start out pointing to the same 1865memory. 1866 1867 When one of these two strings is modified, as with ‘string-set!’, 1868their common memory does get copied so that each string has its own 1869memory and modifying one does not accidentally modify the other as well. 1870Thus, Guile’s strings are ‘copy on write’; the actual copying of their 1871memory is delayed until one string is written to. 1872 1873 This implementation makes functions like ‘substring’ very efficient 1874in the common case that no modifications are done to the involved 1875strings. 1876 1877 If you do know that your strings are getting modified right away, you 1878can use ‘substring/copy’ instead of ‘substring’. This function performs 1879the copy immediately at the time of creation. This is more efficient, 1880especially in a multi-threaded program. Also, ‘substring/copy’ can 1881avoid the problem that a short substring holds on to the memory of a 1882very large original string that could otherwise be recycled. 1883 1884 If you want to avoid the copy altogether, so that modifications of 1885one string show up in the other, you can use ‘substring/shared’. The 1886strings created by this procedure are called “mutation sharing 1887substrings” since the substring and the original string share 1888modifications to each other. 1889 1890 If you want to prevent modifications, use ‘substring/read-only’. 1891 1892 Guile provides all procedures of SRFI-13 and a few more. 1893 1894* Menu: 1895 1896* String Syntax:: Read syntax for strings. 1897* String Predicates:: Testing strings for certain properties. 1898* String Constructors:: Creating new string objects. 1899* List/String Conversion:: Converting from/to lists of characters. 1900* String Selection:: Select portions from strings. 1901* String Modification:: Modify parts or whole strings. 1902* String Comparison:: Lexicographic ordering predicates. 1903* String Searching:: Searching in strings. 1904* Alphabetic Case Mapping:: Convert the alphabetic case of strings. 1905* Reversing and Appending Strings:: Appending strings to form a new string. 1906* Mapping Folding and Unfolding:: Iterating over strings. 1907* Miscellaneous String Operations:: Replicating, insertion, parsing, ... 1908* Representing Strings as Bytes:: Encoding and decoding strings. 1909* Conversion to/from C:: 1910* String Internals:: The storage strategy for strings. 1911 1912 1913File: guile.info, Node: String Syntax, Next: String Predicates, Up: Strings 1914 19156.6.5.1 String Read Syntax 1916.......................... 1917 1918The read syntax for strings is an arbitrarily long sequence of 1919characters enclosed in double quotes ("). 1920 1921 Backslash is an escape character and can be used to insert the 1922following special characters. \" and \\ are R5RS standard, \| is R7RS 1923standard, the next seven are R6RS standard — notice they follow C syntax 1924— and the remaining four are Guile extensions. 1925 1926\\ 1927 Backslash character. 1928 1929\" 1930 Double quote character (an unescaped " is otherwise the end of the 1931 string). 1932 1933\| 1934 Vertical bar character. 1935 1936\a 1937 Bell character (ASCII 7). 1938 1939\f 1940 Formfeed character (ASCII 12). 1941 1942\n 1943 Newline character (ASCII 10). 1944 1945\r 1946 Carriage return character (ASCII 13). 1947 1948\t 1949 Tab character (ASCII 9). 1950 1951\v 1952 Vertical tab character (ASCII 11). 1953 1954\b 1955 Backspace character (ASCII 8). 1956 1957\0 1958 NUL character (ASCII 0). 1959 1960\( 1961 Open parenthesis. This is intended for use at the beginning of 1962 lines in multiline strings to avoid confusing Emacs lisp modes. 1963 1964\ followed by newline (ASCII 10) 1965 Nothing. This way if \ is the last character in a line, the string 1966 will continue with the first character from the next line, without 1967 a line break. 1968 1969 If the ‘hungry-eol-escapes’ reader option is enabled, which is not 1970 the case by default, leading whitespace on the next line is 1971 discarded. 1972 1973 "foo\ 1974 bar" 1975 ⇒ "foo bar" 1976 (read-enable 'hungry-eol-escapes) 1977 "foo\ 1978 bar" 1979 ⇒ "foobar" 1980\xHH 1981 Character code given by two hexadecimal digits. For example \x7f 1982 for an ASCII DEL (127). 1983 1984\uHHHH 1985 Character code given by four hexadecimal digits. For example 1986 \u0100 for a capital A with macron (U+0100). 1987 1988\UHHHHHH 1989 Character code given by six hexadecimal digits. For example 1990 \U010402. 1991 1992The following are examples of string literals: 1993 1994 "foo" 1995 "bar plonk" 1996 "Hello World" 1997 "\"Hi\", he said." 1998 1999 The three escape sequences ‘\xHH’, ‘\uHHHH’ and ‘\UHHHHHH’ were 2000chosen to not break compatibility with code written for previous 2001versions of Guile. The R6RS specification suggests a different, 2002incompatible syntax for hex escapes: ‘\xHHHH;’ – a character code 2003followed by one to eight hexadecimal digits terminated with a semicolon. 2004If this escape format is desired instead, it can be enabled with the 2005reader option ‘r6rs-hex-escapes’. 2006 2007 (read-enable 'r6rs-hex-escapes) 2008 2009 For more on reader options, *Note Scheme Read::. 2010 2011 2012File: guile.info, Node: String Predicates, Next: String Constructors, Prev: String Syntax, Up: Strings 2013 20146.6.5.2 String Predicates 2015......................... 2016 2017The following procedures can be used to check whether a given string 2018fulfills some specified property. 2019 2020 -- Scheme Procedure: string? obj 2021 -- C Function: scm_string_p (obj) 2022 Return ‘#t’ if OBJ is a string, else ‘#f’. 2023 2024 -- C Function: int scm_is_string (SCM obj) 2025 Returns ‘1’ if OBJ is a string, ‘0’ otherwise. 2026 2027 -- Scheme Procedure: string-null? str 2028 -- C Function: scm_string_null_p (str) 2029 Return ‘#t’ if STR’s length is zero, and ‘#f’ otherwise. 2030 (string-null? "") ⇒ #t 2031 y ⇒ "foo" 2032 (string-null? y) ⇒ #f 2033 2034 -- Scheme Procedure: string-any char_pred s [start [end]] 2035 -- C Function: scm_string_any (char_pred, s, start, end) 2036 Check if CHAR_PRED is true for any character in string S. 2037 2038 CHAR_PRED can be a character to check for any equal to that, or a 2039 character set (*note Character Sets::) to check for any in that 2040 set, or a predicate procedure to call. 2041 2042 For a procedure, calls ‘(CHAR_PRED c)’ are made successively on the 2043 characters from START to END. If CHAR_PRED returns true (ie. 2044 non-‘#f’), ‘string-any’ stops and that return value is the return 2045 from ‘string-any’. The call on the last character (ie. at END-1), 2046 if that point is reached, is a tail call. 2047 2048 If there are no characters in S (ie. START equals END) then the 2049 return is ‘#f’. 2050 2051 -- Scheme Procedure: string-every char_pred s [start [end]] 2052 -- C Function: scm_string_every (char_pred, s, start, end) 2053 Check if CHAR_PRED is true for every character in string S. 2054 2055 CHAR_PRED can be a character to check for every character equal to 2056 that, or a character set (*note Character Sets::) to check for 2057 every character being in that set, or a predicate procedure to 2058 call. 2059 2060 For a procedure, calls ‘(CHAR_PRED c)’ are made successively on the 2061 characters from START to END. If CHAR_PRED returns ‘#f’, 2062 ‘string-every’ stops and returns ‘#f’. The call on the last 2063 character (ie. at END-1), if that point is reached, is a tail call 2064 and the return from that call is the return from ‘string-every’. 2065 2066 If there are no characters in S (ie. START equals END) then the 2067 return is ‘#t’. 2068 2069 2070File: guile.info, Node: String Constructors, Next: List/String Conversion, Prev: String Predicates, Up: Strings 2071 20726.6.5.3 String Constructors 2073........................... 2074 2075The string constructor procedures create new string objects, possibly 2076initializing them with some specified character data. See also *Note 2077String Selection::, for ways to create strings from existing strings. 2078 2079 -- Scheme Procedure: string char... 2080 Return a newly allocated string made from the given character 2081 arguments. 2082 2083 (string #\x #\y #\z) ⇒ "xyz" 2084 (string) ⇒ "" 2085 2086 -- Scheme Procedure: list->string lst 2087 -- C Function: scm_string (lst) 2088 Return a newly allocated string made from a list of characters. 2089 2090 (list->string '(#\a #\b #\c)) ⇒ "abc" 2091 2092 -- Scheme Procedure: reverse-list->string lst 2093 -- C Function: scm_reverse_list_to_string (lst) 2094 Return a newly allocated string made from a list of characters, in 2095 reverse order. 2096 2097 (reverse-list->string '(#\a #\B #\c)) ⇒ "cBa" 2098 2099 -- Scheme Procedure: make-string k [chr] 2100 -- C Function: scm_make_string (k, chr) 2101 Return a newly allocated string of length K. If CHR is given, then 2102 all elements of the string are initialized to CHR, otherwise the 2103 contents of the string are unspecified. 2104 2105 -- C Function: SCM scm_c_make_string (size_t len, SCM chr) 2106 Like ‘scm_make_string’, but expects the length as a ‘size_t’. 2107 2108 -- Scheme Procedure: string-tabulate proc len 2109 -- C Function: scm_string_tabulate (proc, len) 2110 PROC is an integer->char procedure. Construct a string of size LEN 2111 by applying PROC to each index to produce the corresponding string 2112 element. The order in which PROC is applied to the indices is not 2113 specified. 2114 2115 -- Scheme Procedure: string-join ls [delimiter [grammar]] 2116 -- C Function: scm_string_join (ls, delimiter, grammar) 2117 Append the string in the string list LS, using the string DELIMITER 2118 as a delimiter between the elements of LS. DELIMITER defaults to 2119 ‘ ’, that is, strings in LS are appended with the space character 2120 in between them. GRAMMAR is a symbol which specifies how the 2121 delimiter is placed between the strings, and defaults to the symbol 2122 ‘infix’. 2123 2124 ‘infix’ 2125 Insert the separator between list elements. An empty string 2126 will produce an empty list. 2127 ‘strict-infix’ 2128 Like ‘infix’, but will raise an error if given the empty list. 2129 ‘suffix’ 2130 Insert the separator after every list element. 2131 ‘prefix’ 2132 Insert the separator before each list element. 2133 2134 2135File: guile.info, Node: List/String Conversion, Next: String Selection, Prev: String Constructors, Up: Strings 2136 21376.6.5.4 List/String conversion 2138.............................. 2139 2140When processing strings, it is often convenient to first convert them 2141into a list representation by using the procedure ‘string->list’, work 2142with the resulting list, and then convert it back into a string. These 2143procedures are useful for similar tasks. 2144 2145 -- Scheme Procedure: string->list str [start [end]] 2146 -- C Function: scm_substring_to_list (str, start, end) 2147 -- C Function: scm_string_to_list (str) 2148 Convert the string STR into a list of characters. 2149 2150 -- Scheme Procedure: string-split str char_pred 2151 -- C Function: scm_string_split (str, char_pred) 2152 Split the string STR into a list of substrings delimited by 2153 appearances of characters that 2154 2155 • equal CHAR_PRED, if it is a character, 2156 2157 • satisfy the predicate CHAR_PRED, if it is a procedure, 2158 2159 • are in the set CHAR_PRED, if it is a character set. 2160 2161 Note that an empty substring between separator characters will 2162 result in an empty string in the result list. 2163 2164 (string-split "root:x:0:0:root:/root:/bin/bash" #\:) 2165 ⇒ 2166 ("root" "x" "0" "0" "root" "/root" "/bin/bash") 2167 2168 (string-split "::" #\:) 2169 ⇒ 2170 ("" "" "") 2171 2172 (string-split "" #\:) 2173 ⇒ 2174 ("") 2175 2176 2177File: guile.info, Node: String Selection, Next: String Modification, Prev: List/String Conversion, Up: Strings 2178 21796.6.5.5 String Selection 2180........................ 2181 2182Portions of strings can be extracted by these procedures. ‘string-ref’ 2183delivers individual characters whereas ‘substring’ can be used to 2184extract substrings from longer strings. 2185 2186 -- Scheme Procedure: string-length string 2187 -- C Function: scm_string_length (string) 2188 Return the number of characters in STRING. 2189 2190 -- C Function: size_t scm_c_string_length (SCM str) 2191 Return the number of characters in STR as a ‘size_t’. 2192 2193 -- Scheme Procedure: string-ref str k 2194 -- C Function: scm_string_ref (str, k) 2195 Return character K of STR using zero-origin indexing. K must be a 2196 valid index of STR. 2197 2198 -- C Function: SCM scm_c_string_ref (SCM str, size_t k) 2199 Return character K of STR using zero-origin indexing. K must be a 2200 valid index of STR. 2201 2202 -- Scheme Procedure: string-copy str [start [end]] 2203 -- C Function: scm_substring_copy (str, start, end) 2204 -- C Function: scm_string_copy (str) 2205 Return a copy of the given string STR. 2206 2207 The returned string shares storage with STR initially, but it is 2208 copied as soon as one of the two strings is modified. 2209 2210 -- Scheme Procedure: substring str start [end] 2211 -- C Function: scm_substring (str, start, end) 2212 Return a new string formed from the characters of STR beginning 2213 with index START (inclusive) and ending with index END (exclusive). 2214 STR must be a string, START and END must be exact integers 2215 satisfying: 2216 2217 0 <= START <= END <= ‘(string-length STR)’. 2218 2219 The returned string shares storage with STR initially, but it is 2220 copied as soon as one of the two strings is modified. 2221 2222 -- Scheme Procedure: substring/shared str start [end] 2223 -- C Function: scm_substring_shared (str, start, end) 2224 Like ‘substring’, but the strings continue to share their storage 2225 even if they are modified. Thus, modifications to STR show up in 2226 the new string, and vice versa. 2227 2228 -- Scheme Procedure: substring/copy str start [end] 2229 -- C Function: scm_substring_copy (str, start, end) 2230 Like ‘substring’, but the storage for the new string is copied 2231 immediately. 2232 2233 -- Scheme Procedure: substring/read-only str start [end] 2234 -- C Function: scm_substring_read_only (str, start, end) 2235 Like ‘substring’, but the resulting string can not be modified. 2236 2237 -- C Function: SCM scm_c_substring (SCM str, size_t start, size_t end) 2238 -- C Function: SCM scm_c_substring_shared (SCM str, size_t start, 2239 size_t end) 2240 -- C Function: SCM scm_c_substring_copy (SCM str, size_t start, size_t 2241 end) 2242 -- C Function: SCM scm_c_substring_read_only (SCM str, size_t start, 2243 size_t end) 2244 Like ‘scm_substring’, etc. but the bounds are given as a ‘size_t’. 2245 2246 -- Scheme Procedure: string-take s n 2247 -- C Function: scm_string_take (s, n) 2248 Return the N first characters of S. 2249 2250 -- Scheme Procedure: string-drop s n 2251 -- C Function: scm_string_drop (s, n) 2252 Return all but the first N characters of S. 2253 2254 -- Scheme Procedure: string-take-right s n 2255 -- C Function: scm_string_take_right (s, n) 2256 Return the N last characters of S. 2257 2258 -- Scheme Procedure: string-drop-right s n 2259 -- C Function: scm_string_drop_right (s, n) 2260 Return all but the last N characters of S. 2261 2262 -- Scheme Procedure: string-pad s len [chr [start [end]]] 2263 -- Scheme Procedure: string-pad-right s len [chr [start [end]]] 2264 -- C Function: scm_string_pad (s, len, chr, start, end) 2265 -- C Function: scm_string_pad_right (s, len, chr, start, end) 2266 Take characters START to END from the string S and either pad with 2267 CHR or truncate them to give LEN characters. 2268 2269 ‘string-pad’ pads or truncates on the left, so for example 2270 2271 (string-pad "x" 3) ⇒ " x" 2272 (string-pad "abcde" 3) ⇒ "cde" 2273 2274 ‘string-pad-right’ pads or truncates on the right, so for example 2275 2276 (string-pad-right "x" 3) ⇒ "x " 2277 (string-pad-right "abcde" 3) ⇒ "abc" 2278 2279 -- Scheme Procedure: string-trim s [char_pred [start [end]]] 2280 -- Scheme Procedure: string-trim-right s [char_pred [start [end]]] 2281 -- Scheme Procedure: string-trim-both s [char_pred [start [end]]] 2282 -- C Function: scm_string_trim (s, char_pred, start, end) 2283 -- C Function: scm_string_trim_right (s, char_pred, start, end) 2284 -- C Function: scm_string_trim_both (s, char_pred, start, end) 2285 Trim occurrences of CHAR_PRED from the ends of S. 2286 2287 ‘string-trim’ trims CHAR_PRED characters from the left (start) of 2288 the string, ‘string-trim-right’ trims them from the right (end) of 2289 the string, ‘string-trim-both’ trims from both ends. 2290 2291 CHAR_PRED can be a character, a character set, or a predicate 2292 procedure to call on each character. If CHAR_PRED is not given the 2293 default is whitespace as per ‘char-set:whitespace’ (*note Standard 2294 Character Sets::). 2295 2296 (string-trim " x ") ⇒ "x " 2297 (string-trim-right "banana" #\a) ⇒ "banan" 2298 (string-trim-both ".,xy:;" char-set:punctuation) 2299 ⇒ "xy" 2300 (string-trim-both "xyzzy" (lambda (c) 2301 (or (eqv? c #\x) 2302 (eqv? c #\y)))) 2303 ⇒ "zz" 2304 2305 2306File: guile.info, Node: String Modification, Next: String Comparison, Prev: String Selection, Up: Strings 2307 23086.6.5.6 String Modification 2309........................... 2310 2311These procedures are for modifying strings in-place. This means that 2312the result of the operation is not a new string; instead, the original 2313string’s memory representation is modified. 2314 2315 -- Scheme Procedure: string-set! str k chr 2316 -- C Function: scm_string_set_x (str, k, chr) 2317 Store CHR in element K of STR and return an unspecified value. K 2318 must be a valid index of STR. 2319 2320 -- C Function: void scm_c_string_set_x (SCM str, size_t k, SCM chr) 2321 Like ‘scm_string_set_x’, but the index is given as a ‘size_t’. 2322 2323 -- Scheme Procedure: string-fill! str chr [start [end]] 2324 -- C Function: scm_substring_fill_x (str, chr, start, end) 2325 -- C Function: scm_string_fill_x (str, chr) 2326 Stores CHR in every element of the given STR and returns an 2327 unspecified value. 2328 2329 -- Scheme Procedure: substring-fill! str start end fill 2330 -- C Function: scm_substring_fill_x (str, start, end, fill) 2331 Change every character in STR between START and END to FILL. 2332 2333 (define y (string-copy "abcdefg")) 2334 (substring-fill! y 1 3 #\r) 2335 y 2336 ⇒ "arrdefg" 2337 2338 -- Scheme Procedure: substring-move! str1 start1 end1 str2 start2 2339 -- C Function: scm_substring_move_x (str1, start1, end1, str2, start2) 2340 Copy the substring of STR1 bounded by START1 and END1 into STR2 2341 beginning at position START2. STR1 and STR2 can be the same 2342 string. 2343 2344 -- Scheme Procedure: string-copy! target tstart s [start [end]] 2345 -- C Function: scm_string_copy_x (target, tstart, s, start, end) 2346 Copy the sequence of characters from index range [START, END) in 2347 string S to string TARGET, beginning at index TSTART. The 2348 characters are copied left-to-right or right-to-left as needed – 2349 the copy is guaranteed to work, even if TARGET and S are the same 2350 string. It is an error if the copy operation runs off the end of 2351 the target string. 2352 2353 2354File: guile.info, Node: String Comparison, Next: String Searching, Prev: String Modification, Up: Strings 2355 23566.6.5.7 String Comparison 2357......................... 2358 2359The procedures in this section are similar to the character ordering 2360predicates (*note Characters::), but are defined on character sequences. 2361 2362 The first set is specified in R5RS and has names that end in ‘?’. 2363The second set is specified in SRFI-13 and the names have not ending 2364‘?’. 2365 2366 The predicates ending in ‘-ci’ ignore the character case when 2367comparing strings. For now, case-insensitive comparison is done using 2368the R5RS rules, where every lower-case character that has a single 2369character upper-case form is converted to uppercase before comparison. 2370See *Note the ‘(ice-9 i18n)’ module: Text Collation, for 2371locale-dependent string comparison. 2372 2373 -- Scheme Procedure: string=? s1 s2 s3 ... 2374 Lexicographic equality predicate; return ‘#t’ if all strings are 2375 the same length and contain the same characters in the same 2376 positions, otherwise return ‘#f’. 2377 2378 The procedure ‘string-ci=?’ treats upper and lower case letters as 2379 though they were the same character, but ‘string=?’ treats upper 2380 and lower case as distinct characters. 2381 2382 -- Scheme Procedure: string<? s1 s2 s3 ... 2383 Lexicographic ordering predicate; return ‘#t’ if, for every pair of 2384 consecutive string arguments STR_I and STR_I+1, STR_I is 2385 lexicographically less than STR_I+1. 2386 2387 -- Scheme Procedure: string<=? s1 s2 s3 ... 2388 Lexicographic ordering predicate; return ‘#t’ if, for every pair of 2389 consecutive string arguments STR_I and STR_I+1, STR_I is 2390 lexicographically less than or equal to STR_I+1. 2391 2392 -- Scheme Procedure: string>? s1 s2 s3 ... 2393 Lexicographic ordering predicate; return ‘#t’ if, for every pair of 2394 consecutive string arguments STR_I and STR_I+1, STR_I is 2395 lexicographically greater than STR_I+1. 2396 2397 -- Scheme Procedure: string>=? s1 s2 s3 ... 2398 Lexicographic ordering predicate; return ‘#t’ if, for every pair of 2399 consecutive string arguments STR_I and STR_I+1, STR_I is 2400 lexicographically greater than or equal to STR_I+1. 2401 2402 -- Scheme Procedure: string-ci=? s1 s2 s3 ... 2403 Case-insensitive string equality predicate; return ‘#t’ if all 2404 strings are the same length and their component characters match 2405 (ignoring case) at each position; otherwise return ‘#f’. 2406 2407 -- Scheme Procedure: string-ci<? s1 s2 s3 ... 2408 Case insensitive lexicographic ordering predicate; return ‘#t’ if, 2409 for every pair of consecutive string arguments STR_I and STR_I+1, 2410 STR_I is lexicographically less than STR_I+1 regardless of case. 2411 2412 -- Scheme Procedure: string-ci<=? s1 s2 s3 ... 2413 Case insensitive lexicographic ordering predicate; return ‘#t’ if, 2414 for every pair of consecutive string arguments STR_I and STR_I+1, 2415 STR_I is lexicographically less than or equal to STR_I+1 regardless 2416 of case. 2417 2418 -- Scheme Procedure: string-ci>? s1 s2 s3 ... 2419 Case insensitive lexicographic ordering predicate; return ‘#t’ if, 2420 for every pair of consecutive string arguments STR_I and STR_I+1, 2421 STR_I is lexicographically greater than STR_I+1 regardless of case. 2422 2423 -- Scheme Procedure: string-ci>=? s1 s2 s3 ... 2424 Case insensitive lexicographic ordering predicate; return ‘#t’ if, 2425 for every pair of consecutive string arguments STR_I and STR_I+1, 2426 STR_I is lexicographically greater than or equal to STR_I+1 2427 regardless of case. 2428 2429 -- Scheme Procedure: string-compare s1 s2 proc_lt proc_eq proc_gt 2430 [start1 [end1 [start2 [end2]]]] 2431 -- C Function: scm_string_compare (s1, s2, proc_lt, proc_eq, proc_gt, 2432 start1, end1, start2, end2) 2433 Apply PROC_LT, PROC_EQ, PROC_GT to the mismatch index, depending 2434 upon whether S1 is less than, equal to, or greater than S2. The 2435 mismatch index is the largest index I such that for every 0 <= J < 2436 I, S1[J] = S2[J] – that is, I is the first position that does not 2437 match. 2438 2439 -- Scheme Procedure: string-compare-ci s1 s2 proc_lt proc_eq proc_gt 2440 [start1 [end1 [start2 [end2]]]] 2441 -- C Function: scm_string_compare_ci (s1, s2, proc_lt, proc_eq, 2442 proc_gt, start1, end1, start2, end2) 2443 Apply PROC_LT, PROC_EQ, PROC_GT to the mismatch index, depending 2444 upon whether S1 is less than, equal to, or greater than S2. The 2445 mismatch index is the largest index I such that for every 0 <= J < 2446 I, S1[J] = S2[J] – that is, I is the first position where the 2447 lowercased letters do not match. 2448 2449 -- Scheme Procedure: string= s1 s2 [start1 [end1 [start2 [end2]]]] 2450 -- C Function: scm_string_eq (s1, s2, start1, end1, start2, end2) 2451 Return ‘#f’ if S1 and S2 are not equal, a true value otherwise. 2452 2453 -- Scheme Procedure: string<> s1 s2 [start1 [end1 [start2 [end2]]]] 2454 -- C Function: scm_string_neq (s1, s2, start1, end1, start2, end2) 2455 Return ‘#f’ if S1 and S2 are equal, a true value otherwise. 2456 2457 -- Scheme Procedure: string< s1 s2 [start1 [end1 [start2 [end2]]]] 2458 -- C Function: scm_string_lt (s1, s2, start1, end1, start2, end2) 2459 Return ‘#f’ if S1 is greater or equal to S2, a true value 2460 otherwise. 2461 2462 -- Scheme Procedure: string> s1 s2 [start1 [end1 [start2 [end2]]]] 2463 -- C Function: scm_string_gt (s1, s2, start1, end1, start2, end2) 2464 Return ‘#f’ if S1 is less or equal to S2, a true value otherwise. 2465 2466 -- Scheme Procedure: string<= s1 s2 [start1 [end1 [start2 [end2]]]] 2467 -- C Function: scm_string_le (s1, s2, start1, end1, start2, end2) 2468 Return ‘#f’ if S1 is greater to S2, a true value otherwise. 2469 2470 -- Scheme Procedure: string>= s1 s2 [start1 [end1 [start2 [end2]]]] 2471 -- C Function: scm_string_ge (s1, s2, start1, end1, start2, end2) 2472 Return ‘#f’ if S1 is less to S2, a true value otherwise. 2473 2474 -- Scheme Procedure: string-ci= s1 s2 [start1 [end1 [start2 [end2]]]] 2475 -- C Function: scm_string_ci_eq (s1, s2, start1, end1, start2, end2) 2476 Return ‘#f’ if S1 and S2 are not equal, a true value otherwise. 2477 The character comparison is done case-insensitively. 2478 2479 -- Scheme Procedure: string-ci<> s1 s2 [start1 [end1 [start2 [end2]]]] 2480 -- C Function: scm_string_ci_neq (s1, s2, start1, end1, start2, end2) 2481 Return ‘#f’ if S1 and S2 are equal, a true value otherwise. The 2482 character comparison is done case-insensitively. 2483 2484 -- Scheme Procedure: string-ci< s1 s2 [start1 [end1 [start2 [end2]]]] 2485 -- C Function: scm_string_ci_lt (s1, s2, start1, end1, start2, end2) 2486 Return ‘#f’ if S1 is greater or equal to S2, a true value 2487 otherwise. The character comparison is done case-insensitively. 2488 2489 -- Scheme Procedure: string-ci> s1 s2 [start1 [end1 [start2 [end2]]]] 2490 -- C Function: scm_string_ci_gt (s1, s2, start1, end1, start2, end2) 2491 Return ‘#f’ if S1 is less or equal to S2, a true value otherwise. 2492 The character comparison is done case-insensitively. 2493 2494 -- Scheme Procedure: string-ci<= s1 s2 [start1 [end1 [start2 [end2]]]] 2495 -- C Function: scm_string_ci_le (s1, s2, start1, end1, start2, end2) 2496 Return ‘#f’ if S1 is greater to S2, a true value otherwise. The 2497 character comparison is done case-insensitively. 2498 2499 -- Scheme Procedure: string-ci>= s1 s2 [start1 [end1 [start2 [end2]]]] 2500 -- C Function: scm_string_ci_ge (s1, s2, start1, end1, start2, end2) 2501 Return ‘#f’ if S1 is less to S2, a true value otherwise. The 2502 character comparison is done case-insensitively. 2503 2504 -- Scheme Procedure: string-hash s [bound [start [end]]] 2505 -- C Function: scm_substring_hash (s, bound, start, end) 2506 Compute a hash value for S. The optional argument BOUND is a 2507 non-negative exact integer specifying the range of the hash 2508 function. A positive value restricts the return value to the range 2509 [0,bound). 2510 2511 -- Scheme Procedure: string-hash-ci s [bound [start [end]]] 2512 -- C Function: scm_substring_hash_ci (s, bound, start, end) 2513 Compute a hash value for S. The optional argument BOUND is a 2514 non-negative exact integer specifying the range of the hash 2515 function. A positive value restricts the return value to the range 2516 [0,bound). 2517 2518 Because the same visual appearance of an abstract Unicode character 2519can be obtained via multiple sequences of Unicode characters, even the 2520case-insensitive string comparison functions described above may return 2521‘#f’ when presented with strings containing different representations of 2522the same character. For example, the Unicode character “LATIN SMALL 2523LETTER S WITH DOT BELOW AND DOT ABOVE” can be represented with a single 2524character (U+1E69) or by the character “LATIN SMALL LETTER S” (U+0073) 2525followed by the combining marks “COMBINING DOT BELOW” (U+0323) and 2526“COMBINING DOT ABOVE” (U+0307). 2527 2528 For this reason, it is often desirable to ensure that the strings to 2529be compared are using a mutually consistent representation for every 2530character. The Unicode standard defines two methods of normalizing the 2531contents of strings: Decomposition, which breaks composite characters 2532into a set of constituent characters with an ordering defined by the 2533Unicode Standard; and composition, which performs the converse. 2534 2535 There are two decomposition operations. “Canonical decomposition” 2536produces character sequences that share the same visual appearance as 2537the original characters, while “compatibility decomposition” produces 2538ones whose visual appearances may differ from the originals but which 2539represent the same abstract character. 2540 2541 These operations are encapsulated in the following set of 2542normalization forms: 2543 2544“NFD” 2545 Characters are decomposed to their canonical forms. 2546 2547“NFKD” 2548 Characters are decomposed to their compatibility forms. 2549 2550“NFC” 2551 Characters are decomposed to their canonical forms, then composed. 2552 2553“NFKC” 2554 Characters are decomposed to their compatibility forms, then 2555 composed. 2556 2557 The functions below put their arguments into one of the forms 2558described above. 2559 2560 -- Scheme Procedure: string-normalize-nfd s 2561 -- C Function: scm_string_normalize_nfd (s) 2562 Return the ‘NFD’ normalized form of S. 2563 2564 -- Scheme Procedure: string-normalize-nfkd s 2565 -- C Function: scm_string_normalize_nfkd (s) 2566 Return the ‘NFKD’ normalized form of S. 2567 2568 -- Scheme Procedure: string-normalize-nfc s 2569 -- C Function: scm_string_normalize_nfc (s) 2570 Return the ‘NFC’ normalized form of S. 2571 2572 -- Scheme Procedure: string-normalize-nfkc s 2573 -- C Function: scm_string_normalize_nfkc (s) 2574 Return the ‘NFKC’ normalized form of S. 2575 2576 2577File: guile.info, Node: String Searching, Next: Alphabetic Case Mapping, Prev: String Comparison, Up: Strings 2578 25796.6.5.8 String Searching 2580........................ 2581 2582 -- Scheme Procedure: string-index s char_pred [start [end]] 2583 -- C Function: scm_string_index (s, char_pred, start, end) 2584 Search through the string S from left to right, returning the index 2585 of the first occurrence of a character which 2586 2587 • equals CHAR_PRED, if it is character, 2588 2589 • satisfies the predicate CHAR_PRED, if it is a procedure, 2590 2591 • is in the set CHAR_PRED, if it is a character set. 2592 2593 Return ‘#f’ if no match is found. 2594 2595 -- Scheme Procedure: string-rindex s char_pred [start [end]] 2596 -- C Function: scm_string_rindex (s, char_pred, start, end) 2597 Search through the string S from right to left, returning the index 2598 of the last occurrence of a character which 2599 2600 • equals CHAR_PRED, if it is character, 2601 2602 • satisfies the predicate CHAR_PRED, if it is a procedure, 2603 2604 • is in the set if CHAR_PRED is a character set. 2605 2606 Return ‘#f’ if no match is found. 2607 2608 -- Scheme Procedure: string-prefix-length s1 s2 [start1 [end1 [start2 2609 [end2]]]] 2610 -- C Function: scm_string_prefix_length (s1, s2, start1, end1, start2, 2611 end2) 2612 Return the length of the longest common prefix of the two strings. 2613 2614 -- Scheme Procedure: string-prefix-length-ci s1 s2 [start1 [end1 2615 [start2 [end2]]]] 2616 -- C Function: scm_string_prefix_length_ci (s1, s2, start1, end1, 2617 start2, end2) 2618 Return the length of the longest common prefix of the two strings, 2619 ignoring character case. 2620 2621 -- Scheme Procedure: string-suffix-length s1 s2 [start1 [end1 [start2 2622 [end2]]]] 2623 -- C Function: scm_string_suffix_length (s1, s2, start1, end1, start2, 2624 end2) 2625 Return the length of the longest common suffix of the two strings. 2626 2627 -- Scheme Procedure: string-suffix-length-ci s1 s2 [start1 [end1 2628 [start2 [end2]]]] 2629 -- C Function: scm_string_suffix_length_ci (s1, s2, start1, end1, 2630 start2, end2) 2631 Return the length of the longest common suffix of the two strings, 2632 ignoring character case. 2633 2634 -- Scheme Procedure: string-prefix? s1 s2 [start1 [end1 [start2 2635 [end2]]]] 2636 -- C Function: scm_string_prefix_p (s1, s2, start1, end1, start2, end2) 2637 Is S1 a prefix of S2? 2638 2639 -- Scheme Procedure: string-prefix-ci? s1 s2 [start1 [end1 [start2 2640 [end2]]]] 2641 -- C Function: scm_string_prefix_ci_p (s1, s2, start1, end1, start2, 2642 end2) 2643 Is S1 a prefix of S2, ignoring character case? 2644 2645 -- Scheme Procedure: string-suffix? s1 s2 [start1 [end1 [start2 2646 [end2]]]] 2647 -- C Function: scm_string_suffix_p (s1, s2, start1, end1, start2, end2) 2648 Is S1 a suffix of S2? 2649 2650 -- Scheme Procedure: string-suffix-ci? s1 s2 [start1 [end1 [start2 2651 [end2]]]] 2652 -- C Function: scm_string_suffix_ci_p (s1, s2, start1, end1, start2, 2653 end2) 2654 Is S1 a suffix of S2, ignoring character case? 2655 2656 -- Scheme Procedure: string-index-right s char_pred [start [end]] 2657 -- C Function: scm_string_index_right (s, char_pred, start, end) 2658 Search through the string S from right to left, returning the index 2659 of the last occurrence of a character which 2660 2661 • equals CHAR_PRED, if it is character, 2662 2663 • satisfies the predicate CHAR_PRED, if it is a procedure, 2664 2665 • is in the set if CHAR_PRED is a character set. 2666 2667 Return ‘#f’ if no match is found. 2668 2669 -- Scheme Procedure: string-skip s char_pred [start [end]] 2670 -- C Function: scm_string_skip (s, char_pred, start, end) 2671 Search through the string S from left to right, returning the index 2672 of the first occurrence of a character which 2673 2674 • does not equal CHAR_PRED, if it is character, 2675 2676 • does not satisfy the predicate CHAR_PRED, if it is a 2677 procedure, 2678 2679 • is not in the set if CHAR_PRED is a character set. 2680 2681 -- Scheme Procedure: string-skip-right s char_pred [start [end]] 2682 -- C Function: scm_string_skip_right (s, char_pred, start, end) 2683 Search through the string S from right to left, returning the index 2684 of the last occurrence of a character which 2685 2686 • does not equal CHAR_PRED, if it is character, 2687 2688 • does not satisfy the predicate CHAR_PRED, if it is a 2689 procedure, 2690 2691 • is not in the set if CHAR_PRED is a character set. 2692 2693 -- Scheme Procedure: string-count s char_pred [start [end]] 2694 -- C Function: scm_string_count (s, char_pred, start, end) 2695 Return the count of the number of characters in the string S which 2696 2697 • equals CHAR_PRED, if it is character, 2698 2699 • satisfies the predicate CHAR_PRED, if it is a procedure. 2700 2701 • is in the set CHAR_PRED, if it is a character set. 2702 2703 -- Scheme Procedure: string-contains s1 s2 [start1 [end1 [start2 2704 [end2]]]] 2705 -- C Function: scm_string_contains (s1, s2, start1, end1, start2, end2) 2706 Does string S1 contain string S2? Return the index in S1 where S2 2707 occurs as a substring, or false. The optional start/end indices 2708 restrict the operation to the indicated substrings. 2709 2710 -- Scheme Procedure: string-contains-ci s1 s2 [start1 [end1 [start2 2711 [end2]]]] 2712 -- C Function: scm_string_contains_ci (s1, s2, start1, end1, start2, 2713 end2) 2714 Does string S1 contain string S2? Return the index in S1 where S2 2715 occurs as a substring, or false. The optional start/end indices 2716 restrict the operation to the indicated substrings. Character 2717 comparison is done case-insensitively. 2718 2719 2720File: guile.info, Node: Alphabetic Case Mapping, Next: Reversing and Appending Strings, Prev: String Searching, Up: Strings 2721 27226.6.5.9 Alphabetic Case Mapping 2723............................... 2724 2725These are procedures for mapping strings to their upper- or lower-case 2726equivalents, respectively, or for capitalizing strings. 2727 2728 They use the basic case mapping rules for Unicode characters. No 2729special language or context rules are considered. The resulting strings 2730are guaranteed to be the same length as the input strings. 2731 2732 *Note the ‘(ice-9 i18n)’ module: Character Case Mapping, for 2733locale-dependent case conversions. 2734 2735 -- Scheme Procedure: string-upcase str [start [end]] 2736 -- C Function: scm_substring_upcase (str, start, end) 2737 -- C Function: scm_string_upcase (str) 2738 Upcase every character in ‘str’. 2739 2740 -- Scheme Procedure: string-upcase! str [start [end]] 2741 -- C Function: scm_substring_upcase_x (str, start, end) 2742 -- C Function: scm_string_upcase_x (str) 2743 Destructively upcase every character in ‘str’. 2744 2745 (string-upcase! y) 2746 ⇒ "ARRDEFG" 2747 y 2748 ⇒ "ARRDEFG" 2749 2750 -- Scheme Procedure: string-downcase str [start [end]] 2751 -- C Function: scm_substring_downcase (str, start, end) 2752 -- C Function: scm_string_downcase (str) 2753 Downcase every character in STR. 2754 2755 -- Scheme Procedure: string-downcase! str [start [end]] 2756 -- C Function: scm_substring_downcase_x (str, start, end) 2757 -- C Function: scm_string_downcase_x (str) 2758 Destructively downcase every character in STR. 2759 2760 y 2761 ⇒ "ARRDEFG" 2762 (string-downcase! y) 2763 ⇒ "arrdefg" 2764 y 2765 ⇒ "arrdefg" 2766 2767 -- Scheme Procedure: string-capitalize str 2768 -- C Function: scm_string_capitalize (str) 2769 Return a freshly allocated string with the characters in STR, where 2770 the first character of every word is capitalized. 2771 2772 -- Scheme Procedure: string-capitalize! str 2773 -- C Function: scm_string_capitalize_x (str) 2774 Upcase the first character of every word in STR destructively and 2775 return STR. 2776 2777 y ⇒ "hello world" 2778 (string-capitalize! y) ⇒ "Hello World" 2779 y ⇒ "Hello World" 2780 2781 -- Scheme Procedure: string-titlecase str [start [end]] 2782 -- C Function: scm_string_titlecase (str, start, end) 2783 Titlecase every first character in a word in STR. 2784 2785 -- Scheme Procedure: string-titlecase! str [start [end]] 2786 -- C Function: scm_string_titlecase_x (str, start, end) 2787 Destructively titlecase every first character in a word in STR. 2788 2789 2790File: guile.info, Node: Reversing and Appending Strings, Next: Mapping Folding and Unfolding, Prev: Alphabetic Case Mapping, Up: Strings 2791 27926.6.5.10 Reversing and Appending Strings 2793........................................ 2794 2795 -- Scheme Procedure: string-reverse str [start [end]] 2796 -- C Function: scm_string_reverse (str, start, end) 2797 Reverse the string STR. The optional arguments START and END 2798 delimit the region of STR to operate on. 2799 2800 -- Scheme Procedure: string-reverse! str [start [end]] 2801 -- C Function: scm_string_reverse_x (str, start, end) 2802 Reverse the string STR in-place. The optional arguments START and 2803 END delimit the region of STR to operate on. The return value is 2804 unspecified. 2805 2806 -- Scheme Procedure: string-append arg ... 2807 -- C Function: scm_string_append (args) 2808 Return a newly allocated string whose characters form the 2809 concatenation of the given strings, ARG .... 2810 2811 (let ((h "hello ")) 2812 (string-append h "world")) 2813 ⇒ "hello world" 2814 2815 -- Scheme Procedure: string-append/shared arg ... 2816 -- C Function: scm_string_append_shared (args) 2817 Like ‘string-append’, but the result may share memory with the 2818 argument strings. 2819 2820 -- Scheme Procedure: string-concatenate ls 2821 -- C Function: scm_string_concatenate (ls) 2822 Append the elements (which must be strings) of LS together into a 2823 single string. Guaranteed to return a freshly allocated string. 2824 2825 -- Scheme Procedure: string-concatenate-reverse ls [final_string [end]] 2826 -- C Function: scm_string_concatenate_reverse (ls, final_string, end) 2827 Without optional arguments, this procedure is equivalent to 2828 2829 (string-concatenate (reverse ls)) 2830 2831 If the optional argument FINAL_STRING is specified, it is consed 2832 onto the beginning to LS before performing the list-reverse and 2833 string-concatenate operations. If END is given, only the 2834 characters of FINAL_STRING up to index END are used. 2835 2836 Guaranteed to return a freshly allocated string. 2837 2838 -- Scheme Procedure: string-concatenate/shared ls 2839 -- C Function: scm_string_concatenate_shared (ls) 2840 Like ‘string-concatenate’, but the result may share memory with the 2841 strings in the list LS. 2842 2843 -- Scheme Procedure: string-concatenate-reverse/shared ls [final_string 2844 [end]] 2845 -- C Function: scm_string_concatenate_reverse_shared (ls, final_string, 2846 end) 2847 Like ‘string-concatenate-reverse’, but the result may share memory 2848 with the strings in the LS arguments. 2849 2850 2851File: guile.info, Node: Mapping Folding and Unfolding, Next: Miscellaneous String Operations, Prev: Reversing and Appending Strings, Up: Strings 2852 28536.6.5.11 Mapping, Folding, and Unfolding 2854........................................ 2855 2856 -- Scheme Procedure: string-map proc s [start [end]] 2857 -- C Function: scm_string_map (proc, s, start, end) 2858 PROC is a char->char procedure, it is mapped over S. The order in 2859 which the procedure is applied to the string elements is not 2860 specified. 2861 2862 -- Scheme Procedure: string-map! proc s [start [end]] 2863 -- C Function: scm_string_map_x (proc, s, start, end) 2864 PROC is a char->char procedure, it is mapped over S. The order in 2865 which the procedure is applied to the string elements is not 2866 specified. The string S is modified in-place, the return value is 2867 not specified. 2868 2869 -- Scheme Procedure: string-for-each proc s [start [end]] 2870 -- C Function: scm_string_for_each (proc, s, start, end) 2871 PROC is mapped over S in left-to-right order. The return value is 2872 not specified. 2873 2874 -- Scheme Procedure: string-for-each-index proc s [start [end]] 2875 -- C Function: scm_string_for_each_index (proc, s, start, end) 2876 Call ‘(PROC i)’ for each index i in S, from left to right. 2877 2878 For example, to change characters to alternately upper and lower 2879 case, 2880 2881 (define str (string-copy "studly")) 2882 (string-for-each-index 2883 (lambda (i) 2884 (string-set! str i 2885 ((if (even? i) char-upcase char-downcase) 2886 (string-ref str i)))) 2887 str) 2888 str ⇒ "StUdLy" 2889 2890 -- Scheme Procedure: string-fold kons knil s [start [end]] 2891 -- C Function: scm_string_fold (kons, knil, s, start, end) 2892 Fold KONS over the characters of S, with KNIL as the terminating 2893 element, from left to right. KONS must expect two arguments: The 2894 actual character and the last result of KONS’ application. 2895 2896 -- Scheme Procedure: string-fold-right kons knil s [start [end]] 2897 -- C Function: scm_string_fold_right (kons, knil, s, start, end) 2898 Fold KONS over the characters of S, with KNIL as the terminating 2899 element, from right to left. KONS must expect two arguments: The 2900 actual character and the last result of KONS’ application. 2901 2902 -- Scheme Procedure: string-unfold p f g seed [base [make_final]] 2903 -- C Function: scm_string_unfold (p, f, g, seed, base, make_final) 2904 • G is used to generate a series of _seed_ values from the 2905 initial SEED: SEED, (G SEED), (G^2 SEED), (G^3 SEED), ... 2906 • P tells us when to stop – when it returns true when applied to 2907 one of these seed values. 2908 • F maps each seed value to the corresponding character in the 2909 result string. These chars are assembled into the string in a 2910 left-to-right order. 2911 • BASE is the optional initial/leftmost portion of the 2912 constructed string; it default to the empty string. 2913 • MAKE_FINAL is applied to the terminal seed value (on which P 2914 returns true) to produce the final/rightmost portion of the 2915 constructed string. The default is nothing extra. 2916 2917 -- Scheme Procedure: string-unfold-right p f g seed [base [make_final]] 2918 -- C Function: scm_string_unfold_right (p, f, g, seed, base, 2919 make_final) 2920 • G is used to generate a series of _seed_ values from the 2921 initial SEED: SEED, (G SEED), (G^2 SEED), (G^3 SEED), ... 2922 • P tells us when to stop – when it returns true when applied to 2923 one of these seed values. 2924 • F maps each seed value to the corresponding character in the 2925 result string. These chars are assembled into the string in a 2926 right-to-left order. 2927 • BASE is the optional initial/rightmost portion of the 2928 constructed string; it default to the empty string. 2929 • MAKE_FINAL is applied to the terminal seed value (on which P 2930 returns true) to produce the final/leftmost portion of the 2931 constructed string. It defaults to ‘(lambda (x) )’. 2932 2933 2934File: guile.info, Node: Miscellaneous String Operations, Next: Representing Strings as Bytes, Prev: Mapping Folding and Unfolding, Up: Strings 2935 29366.6.5.12 Miscellaneous String Operations 2937........................................ 2938 2939 -- Scheme Procedure: xsubstring s from [to [start [end]]] 2940 -- C Function: scm_xsubstring (s, from, to, start, end) 2941 This is the _extended substring_ procedure that implements 2942 replicated copying of a substring of some string. 2943 2944 S is a string, START and END are optional arguments that demarcate 2945 a substring of S, defaulting to 0 and the length of S. Replicate 2946 this substring up and down index space, in both the positive and 2947 negative directions. ‘xsubstring’ returns the substring of this 2948 string beginning at index FROM, and ending at TO, which defaults to 2949 FROM + (END - START). 2950 2951 -- Scheme Procedure: string-xcopy! target tstart s sfrom [sto [start 2952 [end]]] 2953 -- C Function: scm_string_xcopy_x (target, tstart, s, sfrom, sto, 2954 start, end) 2955 Exactly the same as ‘xsubstring’, but the extracted text is written 2956 into the string TARGET starting at index TSTART. The operation is 2957 not defined if ‘(eq? TARGET S)’ or these arguments share storage – 2958 you cannot copy a string on top of itself. 2959 2960 -- Scheme Procedure: string-replace s1 s2 [start1 [end1 [start2 2961 [end2]]]] 2962 -- C Function: scm_string_replace (s1, s2, start1, end1, start2, end2) 2963 Return the string S1, but with the characters START1 ... END1 2964 replaced by the characters START2 ... END2 from S2. 2965 2966 -- Scheme Procedure: string-tokenize s [token_set [start [end]]] 2967 -- C Function: scm_string_tokenize (s, token_set, start, end) 2968 Split the string S into a list of substrings, where each substring 2969 is a maximal non-empty contiguous sequence of characters from the 2970 character set TOKEN_SET, which defaults to ‘char-set:graphic’. If 2971 START or END indices are provided, they restrict ‘string-tokenize’ 2972 to operating on the indicated substring of S. 2973 2974 -- Scheme Procedure: string-filter char_pred s [start [end]] 2975 -- C Function: scm_string_filter (char_pred, s, start, end) 2976 Filter the string S, retaining only those characters which satisfy 2977 CHAR_PRED. 2978 2979 If CHAR_PRED is a procedure, it is applied to each character as a 2980 predicate, if it is a character, it is tested for equality and if 2981 it is a character set, it is tested for membership. 2982 2983 -- Scheme Procedure: string-delete char_pred s [start [end]] 2984 -- C Function: scm_string_delete (char_pred, s, start, end) 2985 Delete characters satisfying CHAR_PRED from S. 2986 2987 If CHAR_PRED is a procedure, it is applied to each character as a 2988 predicate, if it is a character, it is tested for equality and if 2989 it is a character set, it is tested for membership. 2990 2991 The following additional functions are available in the module 2992‘(ice-9 string-fun)’. They can be used with: 2993 2994 (use-modules (ice-9 string-fun)) 2995 2996 -- Scheme Procedure: string-replace-substring str substring replacement 2997 Return a new string where every instance of SUBSTRING in string STR 2998 has been replaced by REPLACEMENT. For example: 2999 3000 (string-replace-substring "a ring of strings" "ring" "rut") 3001 ⇒ "a rut of struts" 3002 3003 3004File: guile.info, Node: Representing Strings as Bytes, Next: Conversion to/from C, Prev: Miscellaneous String Operations, Up: Strings 3005 30066.6.5.13 Representing Strings as Bytes 3007...................................... 3008 3009Out in the cold world outside of Guile, not all strings are treated in 3010the same way. Out there there are only bytes, and there are many ways 3011of representing a strings (sequences of characters) as binary data 3012(sequences of bytes). 3013 3014 As a user, usually you don’t have to think about this very much. 3015When you type on your keyboard, your system encodes your keystrokes as 3016bytes according to the locale that you have configured on your computer. 3017Guile uses the locale to decode those bytes back into characters – 3018hopefully the same characters that you typed in. 3019 3020 All is not so clear when dealing with a system with multiple users, 3021such as a web server. Your web server might get a request from one user 3022for data encoded in the ISO-8859-1 character set, and then another 3023request from a different user for UTF-8 data. 3024 3025 Guile provides an “iconv” module for converting between strings and 3026sequences of bytes. *Note Bytevectors::, for more on how Guile 3027represents raw byte sequences. This module gets its name from the 3028common UNIX command of the same name. 3029 3030 Note that often it is sufficient to just read and write strings from 3031ports instead of using these functions. To do this, specify the port 3032encoding using ‘set-port-encoding!’. *Note Ports::, for more on ports 3033and character encodings. 3034 3035 Unlike the rest of the procedures in this section, you have to load 3036the ‘iconv’ module before having access to these procedures: 3037 3038 (use-modules (ice-9 iconv)) 3039 3040 -- Scheme Procedure: string->bytevector string encoding 3041 [conversion-strategy] 3042 Encode STRING as a sequence of bytes. 3043 3044 The string will be encoded in the character set specified by the 3045 ENCODING string. If the string has characters that cannot be 3046 represented in the encoding, by default this procedure raises an 3047 ‘encoding-error’. Pass a CONVERSION-STRATEGY argument to specify 3048 other behaviors. 3049 3050 The return value is a bytevector. *Note Bytevectors::, for more on 3051 bytevectors. *Note Ports::, for more on character encodings and 3052 conversion strategies. 3053 3054 -- Scheme Procedure: bytevector->string bytevector encoding 3055 [conversion-strategy] 3056 Decode BYTEVECTOR into a string. 3057 3058 The bytes will be decoded from the character set by the ENCODING 3059 string. If the bytes do not form a valid encoding, by default this 3060 procedure raises an ‘decoding-error’. As with 3061 ‘string->bytevector’, pass the optional CONVERSION-STRATEGY 3062 argument to modify this behavior. *Note Ports::, for more on 3063 character encodings and conversion strategies. 3064 3065 -- Scheme Procedure: call-with-output-encoded-string encoding proc 3066 [conversion-strategy] 3067 Like ‘call-with-output-string’, but instead of returning a string, 3068 returns a encoding of the string according to ENCODING, as a 3069 bytevector. This procedure can be more efficient than collecting a 3070 string and then converting it via ‘string->bytevector’. 3071 3072 3073File: guile.info, Node: Conversion to/from C, Next: String Internals, Prev: Representing Strings as Bytes, Up: Strings 3074 30756.6.5.14 Conversion to/from C 3076............................. 3077 3078When creating a Scheme string from a C string or when converting a 3079Scheme string to a C string, the concept of character encoding becomes 3080important. 3081 3082 In C, a string is just a sequence of bytes, and the character 3083encoding describes the relation between these bytes and the actual 3084characters that make up the string. For Scheme strings, character 3085encoding is not an issue (most of the time), since in Scheme you usually 3086treat strings as character sequences, not byte sequences. 3087 3088 Converting to C and converting from C each have their own challenges. 3089 3090 When converting from C to Scheme, it is important that the sequence 3091of bytes in the C string be valid with respect to its encoding. ASCII 3092strings, for example, can’t have any bytes greater than 127. An ASCII 3093byte greater than 127 is considered _ill-formed_ and cannot be converted 3094into a Scheme character. 3095 3096 Problems can occur in the reverse operation as well. Not all 3097character encodings can hold all possible Scheme characters. Some 3098encodings, like ASCII for example, can only describe a small subset of 3099all possible characters. So, when converting to C, one must first 3100decide what to do with Scheme characters that can’t be represented in 3101the C string. 3102 3103 Converting a Scheme string to a C string will often allocate fresh 3104memory to hold the result. You must take care that this memory is 3105properly freed eventually. In many cases, this can be achieved by using 3106‘scm_dynwind_free’ inside an appropriate dynwind context, *Note Dynamic 3107Wind::. 3108 3109 -- C Function: SCM scm_from_locale_string (const char *str) 3110 -- C Function: SCM scm_from_locale_stringn (const char *str, size_t 3111 len) 3112 Creates a new Scheme string that has the same contents as STR when 3113 interpreted in the character encoding of the current locale. 3114 3115 For ‘scm_from_locale_string’, STR must be null-terminated. 3116 3117 For ‘scm_from_locale_stringn’, LEN specifies the length of STR in 3118 bytes, and STR does not need to be null-terminated. If LEN is 3119 ‘(size_t)-1’, then STR does need to be null-terminated and the real 3120 length will be found with ‘strlen’. 3121 3122 If the C string is ill-formed, an error will be raised. 3123 3124 Note that these functions should _not_ be used to convert C string 3125 constants, because there is no guarantee that the current locale 3126 will match that of the execution character set, used for string and 3127 character constants. Most modern C compilers use UTF-8 by default, 3128 so to convert C string constants we recommend 3129 ‘scm_from_utf8_string’. 3130 3131 -- C Function: SCM scm_take_locale_string (char *str) 3132 -- C Function: SCM scm_take_locale_stringn (char *str, size_t len) 3133 Like ‘scm_from_locale_string’ and ‘scm_from_locale_stringn’, 3134 respectively, but also frees STR with ‘free’ eventually. Thus, you 3135 can use this function when you would free STR anyway immediately 3136 after creating the Scheme string. In certain cases, Guile can then 3137 use STR directly as its internal representation. 3138 3139 -- C Function: char * scm_to_locale_string (SCM str) 3140 -- C Function: char * scm_to_locale_stringn (SCM str, size_t *lenp) 3141 Returns a C string with the same contents as STR in the character 3142 encoding of the current locale. The C string must be freed with 3143 ‘free’ eventually, maybe by using ‘scm_dynwind_free’, *Note Dynamic 3144 Wind::. 3145 3146 For ‘scm_to_locale_string’, the returned string is null-terminated 3147 and an error is signalled when STR contains ‘#\nul’ characters. 3148 3149 For ‘scm_to_locale_stringn’ and LENP not ‘NULL’, STR might contain 3150 ‘#\nul’ characters and the length of the returned string in bytes 3151 is stored in ‘*LENP’. The returned string will not be 3152 null-terminated in this case. If LENP is ‘NULL’, 3153 ‘scm_to_locale_stringn’ behaves like ‘scm_to_locale_string’. 3154 3155 If a character in STR cannot be represented in the character 3156 encoding of the current locale, the default port conversion 3157 strategy is used. *Note Ports::, for more on conversion 3158 strategies. 3159 3160 If the conversion strategy is ‘error’, an error will be raised. If 3161 it is ‘substitute’, a replacement character, such as a question 3162 mark, will be inserted in its place. If it is ‘escape’, a hex 3163 escape will be inserted in its place. 3164 3165 -- C Function: size_t scm_to_locale_stringbuf (SCM str, char *buf, 3166 size_t max_len) 3167 Puts STR as a C string in the current locale encoding into the 3168 memory pointed to by BUF. The buffer at BUF has room for MAX_LEN 3169 bytes and ‘scm_to_local_stringbuf’ will never store more than that. 3170 No terminating ‘'\0'’ will be stored. 3171 3172 The return value of ‘scm_to_locale_stringbuf’ is the number of 3173 bytes that are needed for all of STR, regardless of whether BUF was 3174 large enough to hold them. Thus, when the return value is larger 3175 than MAX_LEN, only MAX_LEN bytes have been stored and you probably 3176 need to try again with a larger buffer. 3177 3178 For most situations, string conversion should occur using the current 3179locale, such as with the functions above. But there may be cases where 3180one wants to convert strings from a character encoding other than the 3181locale’s character encoding. For these cases, the lower-level functions 3182‘scm_to_stringn’ and ‘scm_from_stringn’ are provided. These functions 3183should seldom be necessary if one is properly using locales. 3184 3185 -- C Type: scm_t_string_failed_conversion_handler 3186 This is an enumerated type that can take one of three values: 3187 ‘SCM_FAILED_CONVERSION_ERROR’, 3188 ‘SCM_FAILED_CONVERSION_QUESTION_MARK’, and 3189 ‘SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE’. They are used to indicate 3190 a strategy for handling characters that cannot be converted to or 3191 from a given character encoding. ‘SCM_FAILED_CONVERSION_ERROR’ 3192 indicates that a conversion should throw an error if some 3193 characters cannot be converted. 3194 ‘SCM_FAILED_CONVERSION_QUESTION_MARK’ indicates that a conversion 3195 should replace unconvertable characters with the question mark 3196 character. And, ‘SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE’ requests 3197 that a conversion should replace an unconvertable character with an 3198 escape sequence. 3199 3200 While all three strategies apply when converting Scheme strings to 3201 C, only ‘SCM_FAILED_CONVERSION_ERROR’ and 3202 ‘SCM_FAILED_CONVERSION_QUESTION_MARK’ can be used when converting C 3203 strings to Scheme. 3204 3205 -- C Function: char *scm_to_stringn (SCM str, size_t *lenp, const char 3206 *encoding, scm_t_string_failed_conversion_handler handler) 3207 This function returns a newly allocated C string from the Guile 3208 string STR. The length of the returned string in bytes will be 3209 returned in LENP. The character encoding of the C string is passed 3210 as the ASCII, null-terminated C string ENCODING. The HANDLER 3211 parameter gives a strategy for dealing with characters that cannot 3212 be converted into ENCODING. 3213 3214 If LENP is ‘NULL’, this function will return a null-terminated C 3215 string. It will throw an error if the string contains a null 3216 character. 3217 3218 The Scheme interface to this function is ‘string->bytevector’, from 3219 the ‘ice-9 iconv’ module. *Note Representing Strings as Bytes::. 3220 3221 -- C Function: SCM scm_from_stringn (const char *str, size_t len, const 3222 char *encoding, scm_t_string_failed_conversion_handler 3223 handler) 3224 This function returns a scheme string from the C string STR. The 3225 length in bytes of the C string is input as LEN. The encoding of 3226 the C string is passed as the ASCII, null-terminated C string 3227 ‘encoding’. The HANDLER parameters suggests a strategy for dealing 3228 with unconvertable characters. 3229 3230 The Scheme interface to this function is ‘bytevector->string’. 3231 *Note Representing Strings as Bytes::. 3232 3233 The following conversion functions are provided as a convenience for 3234the most commonly used encodings. 3235 3236 -- C Function: SCM scm_from_latin1_string (const char *str) 3237 -- C Function: SCM scm_from_utf8_string (const char *str) 3238 -- C Function: SCM scm_from_utf32_string (const scm_t_wchar *str) 3239 Return a scheme string from the null-terminated C string STR, which 3240 is ISO-8859-1-, UTF-8-, or UTF-32-encoded. These functions should 3241 be used to convert hard-coded C string constants into Scheme 3242 strings. 3243 3244 -- C Function: SCM scm_from_latin1_stringn (const char *str, size_t 3245 len) 3246 -- C Function: SCM scm_from_utf8_stringn (const char *str, size_t len) 3247 -- C Function: SCM scm_from_utf32_stringn (const scm_t_wchar *str, 3248 size_t len) 3249 Return a scheme string from C string STR, which is ISO-8859-1-, 3250 UTF-8-, or UTF-32-encoded, of length LEN. LEN is the number of 3251 bytes pointed to by STR for ‘scm_from_latin1_stringn’ and 3252 ‘scm_from_utf8_stringn’; it is the number of elements (code points) 3253 in STR in the case of ‘scm_from_utf32_stringn’. 3254 3255 -- C function: char *scm_to_latin1_stringn (SCM str, size_t *lenp) 3256 -- C function: char *scm_to_utf8_stringn (SCM str, size_t *lenp) 3257 -- C function: scm_t_wchar *scm_to_utf32_stringn (SCM str, size_t 3258 *lenp) 3259 Return a newly allocated, ISO-8859-1-, UTF-8-, or UTF-32-encoded C 3260 string from Scheme string STR. An error is thrown when STR cannot 3261 be converted to the specified encoding. If LENP is ‘NULL’, the 3262 returned C string will be null terminated, and an error will be 3263 thrown if the C string would otherwise contain null characters. If 3264 LENP is not ‘NULL’, the string is not null terminated, and the 3265 length of the returned string is returned in LENP. The length 3266 returned is the number of bytes for ‘scm_to_latin1_stringn’ and 3267 ‘scm_to_utf8_stringn’; it is the number of elements (code points) 3268 for ‘scm_to_utf32_stringn’. 3269 3270 It is not often the case, but sometimes when you are dealing with the 3271implementation details of a port, you need to encode and decode strings 3272according to the encoding and conversion strategy of the port. There 3273are some convenience functions for that purpose as well. 3274 3275 -- C Function: SCM scm_from_port_string (const char *str, SCM port) 3276 -- C Function: SCM scm_from_port_stringn (const char *str, size_t len, 3277 SCM port) 3278 -- C Function: char* scm_to_port_string (SCM str, SCM port) 3279 -- C Function: char* scm_to_port_stringn (SCM str, size_t *lenp, SCM 3280 port) 3281 Like ‘scm_from_stringn’ and friends, except they take their 3282 encoding and conversion strategy from a given port object. 3283 3284 3285File: guile.info, Node: String Internals, Prev: Conversion to/from C, Up: Strings 3286 32876.6.5.15 String Internals 3288......................... 3289 3290Guile stores each string in memory as a contiguous array of Unicode code 3291points along with an associated set of attributes. If all of the code 3292points of a string have an integer range between 0 and 255 inclusive, 3293the code point array is stored as one byte per code point: it is stored 3294as an ISO-8859-1 (aka Latin-1) string. If any of the code points of the 3295string has an integer value greater that 255, the code point array is 3296stored as four bytes per code point: it is stored as a UTF-32 string. 3297 3298 Conversion between the one-byte-per-code-point and 3299four-bytes-per-code-point representations happens automatically as 3300necessary. 3301 3302 No API is provided to set the internal representation of strings; 3303however, there are pair of procedures available to query it. These are 3304debugging procedures. Using them in production code is discouraged, 3305since the details of Guile’s internal representation of strings may 3306change from release to release. 3307 3308 -- Scheme Procedure: string-bytes-per-char str 3309 -- C Function: scm_string_bytes_per_char (str) 3310 Return the number of bytes used to encode a Unicode code point in 3311 string STR. The result is one or four. 3312 3313 -- Scheme Procedure: %string-dump str 3314 -- C Function: scm_sys_string_dump (str) 3315 Returns an association list containing debugging information for 3316 STR. The association list has the following entries. 3317 3318 ‘string’ 3319 The string itself. 3320 3321 ‘start’ 3322 The start index of the string into its stringbuf 3323 3324 ‘length’ 3325 The length of the string 3326 3327 ‘shared’ 3328 If this string is a substring, it returns its parent string. 3329 Otherwise, it returns ‘#f’ 3330 3331 ‘read-only’ 3332 ‘#t’ if the string is read-only 3333 3334 ‘stringbuf-chars’ 3335 A new string containing this string’s stringbuf’s characters 3336 3337 ‘stringbuf-length’ 3338 The number of characters in this stringbuf 3339 3340 ‘stringbuf-shared’ 3341 ‘#t’ if this stringbuf is shared 3342 3343 ‘stringbuf-wide’ 3344 ‘#t’ if this stringbuf’s characters are stored in a 32-bit 3345 buffer, or ‘#f’ if they are stored in an 8-bit buffer 3346 3347 3348File: guile.info, Node: Symbols, Next: Keywords, Prev: Strings, Up: Data Types 3349 33506.6.6 Symbols 3351------------- 3352 3353Symbols in Scheme are widely used in three ways: as items of discrete 3354data, as lookup keys for alists and hash tables, and to denote variable 3355references. 3356 3357 A “symbol” is similar to a string in that it is defined by a sequence 3358of characters. The sequence of characters is known as the symbol’s 3359“name”. In the usual case — that is, where the symbol’s name doesn’t 3360include any characters that could be confused with other elements of 3361Scheme syntax — a symbol is written in a Scheme program by writing the 3362sequence of characters that make up the name, _without_ any quotation 3363marks or other special syntax. For example, the symbol whose name is 3364“multiply-by-2” is written, simply: 3365 3366 multiply-by-2 3367 3368 Notice how this differs from a _string_ with contents 3369“multiply-by-2”, which is written with double quotation marks, like 3370this: 3371 3372 "multiply-by-2" 3373 3374 Looking beyond how they are written, symbols are different from 3375strings in two important respects. 3376 3377 The first important difference is uniqueness. If the same-looking 3378string is read twice from two different places in a program, the result 3379is two _different_ string objects whose contents just happen to be the 3380same. If, on the other hand, the same-looking symbol is read twice from 3381two different places in a program, the result is the _same_ symbol 3382object both times. 3383 3384 Given two read symbols, you can use ‘eq?’ to test whether they are 3385the same (that is, have the same name). ‘eq?’ is the most efficient 3386comparison operator in Scheme, and comparing two symbols like this is as 3387fast as comparing, for example, two numbers. Given two strings, on the 3388other hand, you must use ‘equal?’ or ‘string=?’, which are much slower 3389comparison operators, to determine whether the strings have the same 3390contents. 3391 3392 (define sym1 (quote hello)) 3393 (define sym2 (quote hello)) 3394 (eq? sym1 sym2) ⇒ #t 3395 3396 (define str1 "hello") 3397 (define str2 "hello") 3398 (eq? str1 str2) ⇒ #f 3399 (equal? str1 str2) ⇒ #t 3400 3401 The second important difference is that symbols, unlike strings, are 3402not self-evaluating. This is why we need the ‘(quote ...)’s in the 3403example above: ‘(quote hello)’ evaluates to the symbol named "hello" 3404itself, whereas an unquoted ‘hello’ is _read_ as the symbol named 3405"hello" and evaluated as a variable reference ... about which more below 3406(*note Symbol Variables::). 3407 3408* Menu: 3409 3410* Symbol Data:: Symbols as discrete data. 3411* Symbol Keys:: Symbols as lookup keys. 3412* Symbol Variables:: Symbols as denoting variables. 3413* Symbol Primitives:: Operations related to symbols. 3414* Symbol Props:: Function slots and property lists. 3415* Symbol Read Syntax:: Extended read syntax for symbols. 3416* Symbol Uninterned:: Uninterned symbols. 3417 3418 3419File: guile.info, Node: Symbol Data, Next: Symbol Keys, Up: Symbols 3420 34216.6.6.1 Symbols as Discrete Data 3422................................ 3423 3424Numbers and symbols are similar to the extent that they both lend 3425themselves to ‘eq?’ comparison. But symbols are more descriptive than 3426numbers, because a symbol’s name can be used directly to describe the 3427concept for which that symbol stands. 3428 3429 For example, imagine that you need to represent some colours in a 3430computer program. Using numbers, you would have to choose arbitrarily 3431some mapping between numbers and colours, and then take care to use that 3432mapping consistently: 3433 3434 ;; 1=red, 2=green, 3=purple 3435 3436 (if (eq? (colour-of vehicle) 1) 3437 ...) 3438 3439You can make the mapping more explicit and the code more readable by 3440defining constants: 3441 3442 (define red 1) 3443 (define green 2) 3444 (define purple 3) 3445 3446 (if (eq? (colour-of vehicle) red) 3447 ...) 3448 3449But the simplest and clearest approach is not to use numbers at all, but 3450symbols whose names specify the colours that they refer to: 3451 3452 (if (eq? (colour-of vehicle) 'red) 3453 ...) 3454 3455 The descriptive advantages of symbols over numbers increase as the 3456set of concepts that you want to describe grows. Suppose that a car 3457object can have other properties as well, such as whether it has or 3458uses: 3459 3460 • automatic or manual transmission 3461 • leaded or unleaded fuel 3462 • power steering (or not). 3463 3464Then a car’s combined property set could be naturally represented and 3465manipulated as a list of symbols: 3466 3467 (properties-of vehicle1) 3468 ⇒ 3469 (red manual unleaded power-steering) 3470 3471 (if (memq 'power-steering (properties-of vehicle1)) 3472 (display "Unfit people can drive this vehicle.\n") 3473 (display "You'll need strong arms to drive this vehicle!\n")) 3474 ⊣ 3475 Unfit people can drive this vehicle. 3476 3477 Remember, the fundamental property of symbols that we are relying on 3478here is that an occurrence of ‘'red’ in one part of a program is an 3479_indistinguishable_ symbol from an occurrence of ‘'red’ in another part 3480of a program; this means that symbols can usefully be compared using 3481‘eq?’. At the same time, symbols have naturally descriptive names. 3482This combination of efficiency and descriptive power makes them ideal 3483for use as discrete data. 3484 3485 3486File: guile.info, Node: Symbol Keys, Next: Symbol Variables, Prev: Symbol Data, Up: Symbols 3487 34886.6.6.2 Symbols as Lookup Keys 3489.............................. 3490 3491Given their efficiency and descriptive power, it is natural to use 3492symbols as the keys in an association list or hash table. 3493 3494 To illustrate this, consider a more structured representation of the 3495car properties example from the preceding subsection. Rather than 3496mixing all the properties up together in a flat list, we could use an 3497association list like this: 3498 3499 (define car1-properties '((colour . red) 3500 (transmission . manual) 3501 (fuel . unleaded) 3502 (steering . power-assisted))) 3503 3504 Notice how this structure is more explicit and extensible than the 3505flat list. For example it makes clear that ‘manual’ refers to the 3506transmission rather than, say, the windows or the locking of the car. 3507It also allows further properties to use the same symbols among their 3508possible values without becoming ambiguous: 3509 3510 (define car1-properties '((colour . red) 3511 (transmission . manual) 3512 (fuel . unleaded) 3513 (steering . power-assisted) 3514 (seat-colour . red) 3515 (locking . manual))) 3516 3517 With a representation like this, it is easy to use the efficient 3518‘assq-XXX’ family of procedures (*note Association Lists::) to extract 3519or change individual pieces of information: 3520 3521 (assq-ref car1-properties 'fuel) ⇒ unleaded 3522 (assq-ref car1-properties 'transmission) ⇒ manual 3523 3524 (assq-set! car1-properties 'seat-colour 'black) 3525 ⇒ 3526 ((colour . red) 3527 (transmission . manual) 3528 (fuel . unleaded) 3529 (steering . power-assisted) 3530 (seat-colour . black) 3531 (locking . manual))) 3532 3533 Hash tables also have keys, and exactly the same arguments apply to 3534the use of symbols in hash tables as in association lists. The hash 3535value that Guile uses to decide where to add a symbol-keyed entry to a 3536hash table can be obtained by calling the ‘symbol-hash’ procedure: 3537 3538 -- Scheme Procedure: symbol-hash symbol 3539 -- C Function: scm_symbol_hash (symbol) 3540 Return a hash value for SYMBOL. 3541 3542 See *note Hash Tables:: for information about hash tables in general, 3543and for why you might choose to use a hash table rather than an 3544association list. 3545 3546 3547File: guile.info, Node: Symbol Variables, Next: Symbol Primitives, Prev: Symbol Keys, Up: Symbols 3548 35496.6.6.3 Symbols as Denoting Variables 3550..................................... 3551 3552When an unquoted symbol in a Scheme program is evaluated, it is 3553interpreted as a variable reference, and the result of the evaluation is 3554the appropriate variable’s value. 3555 3556 For example, when the expression ‘(string-length "abcd")’ is read and 3557evaluated, the sequence of characters ‘string-length’ is read as the 3558symbol whose name is "string-length". This symbol is associated with a 3559variable whose value is the procedure that implements string length 3560calculation. Therefore evaluation of the ‘string-length’ symbol results 3561in that procedure. 3562 3563 The details of the connection between an unquoted symbol and the 3564variable to which it refers are explained elsewhere. See *note Binding 3565Constructs::, for how associations between symbols and variables are 3566created, and *note Modules::, for how those associations are affected by 3567Guile’s module system. 3568 3569 3570File: guile.info, Node: Symbol Primitives, Next: Symbol Props, Prev: Symbol Variables, Up: Symbols 3571 35726.6.6.4 Operations Related to Symbols 3573..................................... 3574 3575Given any Scheme value, you can determine whether it is a symbol using 3576the ‘symbol?’ primitive: 3577 3578 -- Scheme Procedure: symbol? obj 3579 -- C Function: scm_symbol_p (obj) 3580 Return ‘#t’ if OBJ is a symbol, otherwise return ‘#f’. 3581 3582 -- C Function: int scm_is_symbol (SCM val) 3583 Equivalent to ‘scm_is_true (scm_symbol_p (val))’. 3584 3585 Once you know that you have a symbol, you can obtain its name as a 3586string by calling ‘symbol->string’. Note that Guile differs by default 3587from R5RS on the details of ‘symbol->string’ as regards 3588case-sensitivity: 3589 3590 -- Scheme Procedure: symbol->string s 3591 -- C Function: scm_symbol_to_string (s) 3592 Return the name of symbol S as a string. By default, Guile reads 3593 symbols case-sensitively, so the string returned will have the same 3594 case variation as the sequence of characters that caused S to be 3595 created. 3596 3597 If Guile is set to read symbols case-insensitively (as specified by 3598 R5RS), and S comes into being as part of a literal expression 3599 (*note (r5rs)Literal expressions::) or by a call to the ‘read’ or 3600 ‘string-ci->symbol’ procedures, Guile converts any alphabetic 3601 characters in the symbol’s name to lower case before creating the 3602 symbol object, so the string returned here will be in lower case. 3603 3604 If S was created by ‘string->symbol’, the case of characters in the 3605 string returned will be the same as that in the string that was 3606 passed to ‘string->symbol’, regardless of Guile’s case-sensitivity 3607 setting at the time S was created. 3608 3609 It is an error to apply mutation procedures like ‘string-set!’ to 3610 strings returned by this procedure. 3611 3612 Most symbols are created by writing them literally in code. However 3613it is also possible to create symbols programmatically using the 3614following procedures: 3615 3616 -- Scheme Procedure: symbol char... 3617 Return a newly allocated symbol made from the given character 3618 arguments. 3619 3620 (symbol #\x #\y #\z) ⇒ xyz 3621 3622 -- Scheme Procedure: list->symbol lst 3623 Return a newly allocated symbol made from a list of characters. 3624 3625 (list->symbol '(#\a #\b #\c)) ⇒ abc 3626 3627 -- Scheme Procedure: symbol-append arg ... 3628 Return a newly allocated symbol whose characters form the 3629 concatenation of the given symbols, ARG .... 3630 3631 (let ((h 'hello)) 3632 (symbol-append h 'world)) 3633 ⇒ helloworld 3634 3635 -- Scheme Procedure: string->symbol string 3636 -- C Function: scm_string_to_symbol (string) 3637 Return the symbol whose name is STRING. This procedure can create 3638 symbols with names containing special characters or letters in the 3639 non-standard case, but it is usually a bad idea to create such 3640 symbols because in some implementations of Scheme they cannot be 3641 read as themselves. 3642 3643 -- Scheme Procedure: string-ci->symbol str 3644 -- C Function: scm_string_ci_to_symbol (str) 3645 Return the symbol whose name is STR. If Guile is currently reading 3646 symbols case-insensitively, STR is converted to lowercase before 3647 the returned symbol is looked up or created. 3648 3649 The following examples illustrate Guile’s detailed behaviour as 3650regards the case-sensitivity of symbols: 3651 3652 (read-enable 'case-insensitive) ; R5RS compliant behaviour 3653 3654 (symbol->string 'flying-fish) ⇒ "flying-fish" 3655 (symbol->string 'Martin) ⇒ "martin" 3656 (symbol->string 3657 (string->symbol "Malvina")) ⇒ "Malvina" 3658 3659 (eq? 'mISSISSIppi 'mississippi) ⇒ #t 3660 (string->symbol "mISSISSIppi") ⇒ mISSISSIppi 3661 (eq? 'bitBlt (string->symbol "bitBlt")) ⇒ #f 3662 (eq? 'LolliPop 3663 (string->symbol (symbol->string 'LolliPop))) ⇒ #t 3664 (string=? "K. Harper, M.D." 3665 (symbol->string 3666 (string->symbol "K. Harper, M.D."))) ⇒ #t 3667 3668 (read-disable 'case-insensitive) ; Guile default behaviour 3669 3670 (symbol->string 'flying-fish) ⇒ "flying-fish" 3671 (symbol->string 'Martin) ⇒ "Martin" 3672 (symbol->string 3673 (string->symbol "Malvina")) ⇒ "Malvina" 3674 3675 (eq? 'mISSISSIppi 'mississippi) ⇒ #f 3676 (string->symbol "mISSISSIppi") ⇒ mISSISSIppi 3677 (eq? 'bitBlt (string->symbol "bitBlt")) ⇒ #t 3678 (eq? 'LolliPop 3679 (string->symbol (symbol->string 'LolliPop))) ⇒ #t 3680 (string=? "K. Harper, M.D." 3681 (symbol->string 3682 (string->symbol "K. Harper, M.D."))) ⇒ #t 3683 3684 From C, there are lower level functions that construct a Scheme 3685symbol from a C string in the current locale encoding. 3686 3687 When you want to do more from C, you should convert between symbols 3688and strings using ‘scm_symbol_to_string’ and ‘scm_string_to_symbol’ and 3689work with the strings. 3690 3691 -- C Function: SCM scm_from_latin1_symbol (const char *name) 3692 -- C Function: SCM scm_from_utf8_symbol (const char *name) 3693 Construct and return a Scheme symbol whose name is specified by the 3694 null-terminated C string NAME. These are appropriate when the C 3695 string is hard-coded in the source code. 3696 3697 -- C Function: SCM scm_from_locale_symbol (const char *name) 3698 -- C Function: SCM scm_from_locale_symboln (const char *name, size_t 3699 len) 3700 Construct and return a Scheme symbol whose name is specified by 3701 NAME. For ‘scm_from_locale_symbol’, NAME must be null terminated; 3702 for ‘scm_from_locale_symboln’ the length of NAME is specified 3703 explicitly by LEN. 3704 3705 Note that these functions should _not_ be used when NAME is a C 3706 string constant, because there is no guarantee that the current 3707 locale will match that of the execution character set, used for 3708 string and character constants. Most modern C compilers use UTF-8 3709 by default, so in such cases we recommend ‘scm_from_utf8_symbol’. 3710 3711 -- C Function: SCM scm_take_locale_symbol (char *str) 3712 -- C Function: SCM scm_take_locale_symboln (char *str, size_t len) 3713 Like ‘scm_from_locale_symbol’ and ‘scm_from_locale_symboln’, 3714 respectively, but also frees STR with ‘free’ eventually. Thus, you 3715 can use this function when you would free STR anyway immediately 3716 after creating the Scheme string. In certain cases, Guile can then 3717 use STR directly as its internal representation. 3718 3719 The size of a symbol can also be obtained from C: 3720 3721 -- C Function: size_t scm_c_symbol_length (SCM sym) 3722 Return the number of characters in SYM. 3723 3724 Finally, some applications, especially those that generate new Scheme 3725code dynamically, need to generate symbols for use in the generated 3726code. The ‘gensym’ primitive meets this need: 3727 3728 -- Scheme Procedure: gensym [prefix] 3729 -- C Function: scm_gensym (prefix) 3730 Create a new symbol with a name constructed from a prefix and a 3731 counter value. The string PREFIX can be specified as an optional 3732 argument. Default prefix is ‘ g’. The counter is increased by 1 3733 at each call. There is no provision for resetting the counter. 3734 3735 The symbols generated by ‘gensym’ are _likely_ to be unique, since 3736their names begin with a space and it is only otherwise possible to 3737generate such symbols if a programmer goes out of their way to do so. 3738Uniqueness can be guaranteed by instead using uninterned symbols (*note 3739Symbol Uninterned::), though they can’t be usefully written out and read 3740back in. 3741 3742 3743File: guile.info, Node: Symbol Props, Next: Symbol Read Syntax, Prev: Symbol Primitives, Up: Symbols 3744 37456.6.6.5 Function Slots and Property Lists 3746......................................... 3747 3748In traditional Lisp dialects, symbols are often understood as having 3749three kinds of value at once: 3750 3751 • a “variable” value, which is used when the symbol appears in code 3752 in a variable reference context 3753 3754 • a “function” value, which is used when the symbol appears in code 3755 in a function name position (i.e. as the first element in an 3756 unquoted list) 3757 3758 • a “property list” value, which is used when the symbol is given as 3759 the first argument to Lisp’s ‘put’ or ‘get’ functions. 3760 3761 Although Scheme (as one of its simplifications with respect to Lisp) 3762does away with the distinction between variable and function namespaces, 3763Guile currently retains some elements of the traditional structure in 3764case they turn out to be useful when implementing translators for other 3765languages, in particular Emacs Lisp. 3766 3767 Specifically, Guile symbols have two extra slots, one for a symbol’s 3768property list, and one for its “function value.” The following 3769procedures are provided to access these slots. 3770 3771 -- Scheme Procedure: symbol-fref symbol 3772 -- C Function: scm_symbol_fref (symbol) 3773 Return the contents of SYMBOL’s “function slot”. 3774 3775 -- Scheme Procedure: symbol-fset! symbol value 3776 -- C Function: scm_symbol_fset_x (symbol, value) 3777 Set the contents of SYMBOL’s function slot to VALUE. 3778 3779 -- Scheme Procedure: symbol-pref symbol 3780 -- C Function: scm_symbol_pref (symbol) 3781 Return the “property list” currently associated with SYMBOL. 3782 3783 -- Scheme Procedure: symbol-pset! symbol value 3784 -- C Function: scm_symbol_pset_x (symbol, value) 3785 Set SYMBOL’s property list to VALUE. 3786 3787 -- Scheme Procedure: symbol-property sym prop 3788 From SYM’s property list, return the value for property PROP. The 3789 assumption is that SYM’s property list is an association list whose 3790 keys are distinguished from each other using ‘equal?’; PROP should 3791 be one of the keys in that list. If the property list has no entry 3792 for PROP, ‘symbol-property’ returns ‘#f’. 3793 3794 -- Scheme Procedure: set-symbol-property! sym prop val 3795 In SYM’s property list, set the value for property PROP to VAL, or 3796 add a new entry for PROP, with value VAL, if none already exists. 3797 For the structure of the property list, see ‘symbol-property’. 3798 3799 -- Scheme Procedure: symbol-property-remove! sym prop 3800 From SYM’s property list, remove the entry for property PROP, if 3801 there is one. For the structure of the property list, see 3802 ‘symbol-property’. 3803 3804 Support for these extra slots may be removed in a future release, and 3805it is probably better to avoid using them. For a more modern and 3806Schemely approach to properties, see *note Object Properties::. 3807 3808 3809File: guile.info, Node: Symbol Read Syntax, Next: Symbol Uninterned, Prev: Symbol Props, Up: Symbols 3810 38116.6.6.6 Extended Read Syntax for Symbols 3812........................................ 3813 3814The read syntax for a symbol is a sequence of letters, digits, and 3815“extended alphabetic characters”, beginning with a character that cannot 3816begin a number. In addition, the special cases of ‘+’, ‘-’, and ‘...’ 3817are read as symbols even though numbers can begin with ‘+’, ‘-’ or ‘.’. 3818 3819 Extended alphabetic characters may be used within identifiers as if 3820they were letters. The set of extended alphabetic characters is: 3821 3822 ! $ % & * + - . / : < = > ? @ ^ _ ~ 3823 3824 In addition to the standard read syntax defined above (which is taken 3825from R5RS (*note (r5rs)Formal syntax::)), Guile provides an extended 3826symbol read syntax that allows the inclusion of unusual characters such 3827as space characters, newlines and parentheses. If (for whatever reason) 3828you need to write a symbol containing characters not mentioned above, 3829you can do so as follows. 3830 3831 • Begin the symbol with the characters ‘#{’, 3832 3833 • write the characters of the symbol and 3834 3835 • finish the symbol with the characters ‘}#’. 3836 3837 Here are a few examples of this form of read syntax. The first 3838symbol needs to use extended syntax because it contains a space 3839character, the second because it contains a line break, and the last 3840because it looks like a number. 3841 3842 #{foo bar}# 3843 3844 #{what 3845 ever}# 3846 3847 #{4242}# 3848 3849 Although Guile provides this extended read syntax for symbols, 3850widespread usage of it is discouraged because it is not portable and not 3851very readable. 3852 3853 Alternatively, if you enable the ‘r7rs-symbols’ read option (see 3854*note Scheme Read::), you can write arbitrary symbols using the same 3855notation used for strings, except delimited by vertical bars instead of 3856double quotes. 3857 3858 |foo bar| 3859 |\x3BB; is a greek lambda| 3860 |\| is a vertical bar| 3861 3862 Note that there’s also an ‘r7rs-symbols’ print option (*note Scheme 3863Write::). To enable the use of this notation, evaluate one or both of 3864the following expressions: 3865 3866 (read-enable 'r7rs-symbols) 3867 (print-enable 'r7rs-symbols) 3868 3869 3870File: guile.info, Node: Symbol Uninterned, Prev: Symbol Read Syntax, Up: Symbols 3871 38726.6.6.7 Uninterned Symbols 3873.......................... 3874 3875What makes symbols useful is that they are automatically kept unique. 3876There are no two symbols that are distinct objects but have the same 3877name. But of course, there is no rule without exception. In addition 3878to the normal symbols that have been discussed up to now, you can also 3879create special “uninterned” symbols that behave slightly differently. 3880 3881 To understand what is different about them and why they might be 3882useful, we look at how normal symbols are actually kept unique. 3883 3884 Whenever Guile wants to find the symbol with a specific name, for 3885example during ‘read’ or when executing ‘string->symbol’, it first looks 3886into a table of all existing symbols to find out whether a symbol with 3887the given name already exists. When this is the case, Guile just 3888returns that symbol. When not, a new symbol with the name is created 3889and entered into the table so that it can be found later. 3890 3891 Sometimes you might want to create a symbol that is guaranteed 3892‘fresh’, i.e. a symbol that did not exist previously. You might also 3893want to somehow guarantee that no one else will ever unintentionally 3894stumble across your symbol in the future. These properties of a symbol 3895are often needed when generating code during macro expansion. When 3896introducing new temporary variables, you want to guarantee that they 3897don’t conflict with variables in other people’s code. 3898 3899 The simplest way to arrange for this is to create a new symbol but 3900not enter it into the global table of all symbols. That way, no one 3901will ever get access to your symbol by chance. Symbols that are not in 3902the table are called “uninterned”. Of course, symbols that _are_ in the 3903table are called “interned”. 3904 3905 You create new uninterned symbols with the function ‘make-symbol’. 3906You can test whether a symbol is interned or not with 3907‘symbol-interned?’. 3908 3909 Uninterned symbols break the rule that the name of a symbol uniquely 3910identifies the symbol object. Because of this, they can not be written 3911out and read back in like interned symbols. Currently, Guile has no 3912support for reading uninterned symbols. Note that the function ‘gensym’ 3913does not return uninterned symbols for this reason. 3914 3915 -- Scheme Procedure: make-symbol name 3916 -- C Function: scm_make_symbol (name) 3917 Return a new uninterned symbol with the name NAME. The returned 3918 symbol is guaranteed to be unique and future calls to 3919 ‘string->symbol’ will not return it. 3920 3921 -- Scheme Procedure: symbol-interned? symbol 3922 -- C Function: scm_symbol_interned_p (symbol) 3923 Return ‘#t’ if SYMBOL is interned, otherwise return ‘#f’. 3924 3925 For example: 3926 3927 (define foo-1 (string->symbol "foo")) 3928 (define foo-2 (string->symbol "foo")) 3929 (define foo-3 (make-symbol "foo")) 3930 (define foo-4 (make-symbol "foo")) 3931 3932 (eq? foo-1 foo-2) 3933 ⇒ #t 3934 ; Two interned symbols with the same name are the same object, 3935 3936 (eq? foo-1 foo-3) 3937 ⇒ #f 3938 ; but a call to make-symbol with the same name returns a 3939 ; distinct object. 3940 3941 (eq? foo-3 foo-4) 3942 ⇒ #f 3943 ; A call to make-symbol always returns a new object, even for 3944 ; the same name. 3945 3946 foo-3 3947 ⇒ #<uninterned-symbol foo 8085290> 3948 ; Uninterned symbols print differently from interned symbols, 3949 3950 (symbol? foo-3) 3951 ⇒ #t 3952 ; but they are still symbols, 3953 3954 (symbol-interned? foo-3) 3955 ⇒ #f 3956 ; just not interned. 3957 3958 3959File: guile.info, Node: Keywords, Next: Pairs, Prev: Symbols, Up: Data Types 3960 39616.6.7 Keywords 3962-------------- 3963 3964Keywords are self-evaluating objects with a convenient read syntax that 3965makes them easy to type. 3966 3967 Guile’s keyword support conforms to R5RS, and adds a (switchable) 3968read syntax extension to permit keywords to begin with ‘:’ as well as 3969‘#:’, or to end with ‘:’. 3970 3971* Menu: 3972 3973* Why Use Keywords?:: Motivation for keyword usage. 3974* Coding With Keywords:: How to use keywords. 3975* Keyword Read Syntax:: Read syntax for keywords. 3976* Keyword Procedures:: Procedures for dealing with keywords. 3977 3978 3979File: guile.info, Node: Why Use Keywords?, Next: Coding With Keywords, Up: Keywords 3980 39816.6.7.1 Why Use Keywords? 3982......................... 3983 3984Keywords are useful in contexts where a program or procedure wants to be 3985able to accept a large number of optional arguments without making its 3986interface unmanageable. 3987 3988 To illustrate this, consider a hypothetical ‘make-window’ procedure, 3989which creates a new window on the screen for drawing into using some 3990graphical toolkit. There are many parameters that the caller might like 3991to specify, but which could also be sensibly defaulted, for example: 3992 3993 • color depth – Default: the color depth for the screen 3994 3995 • background color – Default: white 3996 3997 • width – Default: 600 3998 3999 • height – Default: 400 4000 4001 If ‘make-window’ did not use keywords, the caller would have to pass 4002in a value for each possible argument, remembering the correct argument 4003order and using a special value to indicate the default value for that 4004argument: 4005 4006 (make-window 'default ;; Color depth 4007 'default ;; Background color 4008 800 ;; Width 4009 100 ;; Height 4010 ...) ;; More make-window arguments 4011 4012 With keywords, on the other hand, defaulted arguments are omitted, 4013and non-default arguments are clearly tagged by the appropriate keyword. 4014As a result, the invocation becomes much clearer: 4015 4016 (make-window #:width 800 #:height 100) 4017 4018 On the other hand, for a simpler procedure with few arguments, the 4019use of keywords would be a hindrance rather than a help. The primitive 4020procedure ‘cons’, for example, would not be improved if it had to be 4021invoked as 4022 4023 (cons #:car x #:cdr y) 4024 4025 So the decision whether to use keywords or not is purely pragmatic: 4026use them if they will clarify the procedure invocation at point of call. 4027 4028 4029File: guile.info, Node: Coding With Keywords, Next: Keyword Read Syntax, Prev: Why Use Keywords?, Up: Keywords 4030 40316.6.7.2 Coding With Keywords 4032............................ 4033 4034If a procedure wants to support keywords, it should take a rest argument 4035and then use whatever means is convenient to extract keywords and their 4036corresponding arguments from the contents of that rest argument. 4037 4038 The following example illustrates the principle: the code for 4039‘make-window’ uses a helper procedure called ‘get-keyword-value’ to 4040extract individual keyword arguments from the rest argument. 4041 4042 (define (get-keyword-value args keyword default) 4043 (let ((kv (memq keyword args))) 4044 (if (and kv (>= (length kv) 2)) 4045 (cadr kv) 4046 default))) 4047 4048 (define (make-window . args) 4049 (let ((depth (get-keyword-value args #:depth screen-depth)) 4050 (bg (get-keyword-value args #:bg "white")) 4051 (width (get-keyword-value args #:width 800)) 4052 (height (get-keyword-value args #:height 100)) 4053 ...) 4054 ...)) 4055 4056 But you don’t need to write ‘get-keyword-value’. The ‘(ice-9 4057optargs)’ module provides a set of powerful macros that you can use to 4058implement keyword-supporting procedures like this: 4059 4060 (use-modules (ice-9 optargs)) 4061 4062 (define (make-window . args) 4063 (let-keywords args #f ((depth screen-depth) 4064 (bg "white") 4065 (width 800) 4066 (height 100)) 4067 ...)) 4068 4069Or, even more economically, like this: 4070 4071 (use-modules (ice-9 optargs)) 4072 4073 (define* (make-window #:key (depth screen-depth) 4074 (bg "white") 4075 (width 800) 4076 (height 100)) 4077 ...) 4078 4079 For further details on ‘let-keywords’, ‘define*’ and other facilities 4080provided by the ‘(ice-9 optargs)’ module, see *note Optional 4081Arguments::. 4082 4083 To handle keyword arguments from procedures implemented in C, use 4084‘scm_c_bind_keyword_arguments’ (*note Keyword Procedures::). 4085 4086 4087File: guile.info, Node: Keyword Read Syntax, Next: Keyword Procedures, Prev: Coding With Keywords, Up: Keywords 4088 40896.6.7.3 Keyword Read Syntax 4090........................... 4091 4092Guile, by default, only recognizes a keyword syntax that is compatible 4093with R5RS. A token of the form ‘#:NAME’, where ‘NAME’ has the same 4094syntax as a Scheme symbol (*note Symbol Read Syntax::), is the external 4095representation of the keyword named ‘NAME’. Keyword objects print using 4096this syntax as well, so values containing keyword objects can be read 4097back into Guile. When used in an expression, keywords are self-quoting 4098objects. 4099 4100 If the ‘keywords’ read option is set to ‘'prefix’, Guile also 4101recognizes the alternative read syntax ‘:NAME’. Otherwise, tokens of 4102the form ‘:NAME’ are read as symbols, as required by R5RS. 4103 4104 If the ‘keywords’ read option is set to ‘'postfix’, Guile recognizes 4105the SRFI-88 read syntax ‘NAME:’ (*note SRFI-88::). Otherwise, tokens of 4106this form are read as symbols. 4107 4108 To enable and disable the alternative non-R5RS keyword syntax, you 4109use the ‘read-set!’ procedure documented *note Scheme Read::. Note that 4110the ‘prefix’ and ‘postfix’ syntax are mutually exclusive. 4111 4112 (read-set! keywords 'prefix) 4113 4114 #:type 4115 ⇒ 4116 #:type 4117 4118 :type 4119 ⇒ 4120 #:type 4121 4122 (read-set! keywords 'postfix) 4123 4124 type: 4125 ⇒ 4126 #:type 4127 4128 :type 4129 ⇒ 4130 :type 4131 4132 (read-set! keywords #f) 4133 4134 #:type 4135 ⇒ 4136 #:type 4137 4138 :type 4139 ⊣ 4140 ERROR: In expression :type: 4141 ERROR: Unbound variable: :type 4142 ABORT: (unbound-variable) 4143 4144 4145File: guile.info, Node: Keyword Procedures, Prev: Keyword Read Syntax, Up: Keywords 4146 41476.6.7.4 Keyword Procedures 4148.......................... 4149 4150 -- Scheme Procedure: keyword? obj 4151 -- C Function: scm_keyword_p (obj) 4152 Return ‘#t’ if the argument OBJ is a keyword, else ‘#f’. 4153 4154 -- Scheme Procedure: keyword->symbol keyword 4155 -- C Function: scm_keyword_to_symbol (keyword) 4156 Return the symbol with the same name as KEYWORD. 4157 4158 -- Scheme Procedure: symbol->keyword symbol 4159 -- C Function: scm_symbol_to_keyword (symbol) 4160 Return the keyword with the same name as SYMBOL. 4161 4162 -- C Function: int scm_is_keyword (SCM obj) 4163 Equivalent to ‘scm_is_true (scm_keyword_p (OBJ))’. 4164 4165 -- C Function: SCM scm_from_locale_keyword (const char *name) 4166 -- C Function: SCM scm_from_locale_keywordn (const char *name, size_t 4167 len) 4168 Equivalent to ‘scm_symbol_to_keyword (scm_from_locale_symbol 4169 (NAME))’ and ‘scm_symbol_to_keyword (scm_from_locale_symboln (NAME, 4170 LEN))’, respectively. 4171 4172 Note that these functions should _not_ be used when NAME is a C 4173 string constant, because there is no guarantee that the current 4174 locale will match that of the execution character set, used for 4175 string and character constants. Most modern C compilers use UTF-8 4176 by default, so in such cases we recommend ‘scm_from_utf8_keyword’. 4177 4178 -- C Function: SCM scm_from_latin1_keyword (const char *name) 4179 -- C Function: SCM scm_from_utf8_keyword (const char *name) 4180 Equivalent to ‘scm_symbol_to_keyword (scm_from_latin1_symbol 4181 (NAME))’ and ‘scm_symbol_to_keyword (scm_from_utf8_symbol (NAME))’, 4182 respectively. 4183 4184 -- C Function: void scm_c_bind_keyword_arguments (const char *subr, SCM 4185 rest, scm_t_keyword_arguments_flags flags, SCM keyword1, SCM 4186 *argp1, ..., SCM keywordN, SCM *argpN, SCM_UNDEFINED) 4187 4188 Extract the specified keyword arguments from REST, which is not 4189 modified. If the keyword argument KEYWORD1 is present in REST with 4190 an associated value, that value is stored in the variable pointed 4191 to by ARGP1, otherwise the variable is left unchanged. Similarly 4192 for the other keywords and argument pointers up to KEYWORDN and 4193 ARGPN. The argument list to ‘scm_c_bind_keyword_arguments’ must be 4194 terminated by ‘SCM_UNDEFINED’. 4195 4196 Note that since the variables pointed to by ARGP1 through ARGPN are 4197 left unchanged if the associated keyword argument is not present, 4198 they should be initialized to their default values before calling 4199 ‘scm_c_bind_keyword_arguments’. Alternatively, you can initialize 4200 them to ‘SCM_UNDEFINED’ before the call, and then use ‘SCM_UNBNDP’ 4201 after the call to see which ones were provided. 4202 4203 If an unrecognized keyword argument is present in REST and FLAGS 4204 does not contain ‘SCM_ALLOW_OTHER_KEYS’, or if non-keyword 4205 arguments are present and FLAGS does not contain 4206 ‘SCM_ALLOW_NON_KEYWORD_ARGUMENTS’, an exception is raised. SUBR 4207 should be the name of the procedure receiving the keyword 4208 arguments, for purposes of error reporting. 4209 4210 For example: 4211 4212 SCM k_delimiter; 4213 SCM k_grammar; 4214 SCM sym_infix; 4215 4216 SCM my_string_join (SCM strings, SCM rest) 4217 { 4218 SCM delimiter = SCM_UNDEFINED; 4219 SCM grammar = sym_infix; 4220 4221 scm_c_bind_keyword_arguments ("my-string-join", rest, 0, 4222 k_delimiter, &delimiter, 4223 k_grammar, &grammar, 4224 SCM_UNDEFINED); 4225 4226 if (SCM_UNBNDP (delimiter)) 4227 delimiter = scm_from_utf8_string (" "); 4228 4229 return scm_string_join (strings, delimiter, grammar); 4230 } 4231 4232 void my_init () 4233 { 4234 k_delimiter = scm_from_utf8_keyword ("delimiter"); 4235 k_grammar = scm_from_utf8_keyword ("grammar"); 4236 sym_infix = scm_from_utf8_symbol ("infix"); 4237 scm_c_define_gsubr ("my-string-join", 1, 0, 1, my_string_join); 4238 } 4239 4240 4241File: guile.info, Node: Pairs, Next: Lists, Prev: Keywords, Up: Data Types 4242 42436.6.8 Pairs 4244----------- 4245 4246Pairs are used to combine two Scheme objects into one compound object. 4247Hence the name: A pair stores a pair of objects. 4248 4249 The data type “pair” is extremely important in Scheme, just like in 4250any other Lisp dialect. The reason is that pairs are not only used to 4251make two values available as one object, but that pairs are used for 4252constructing lists of values. Because lists are so important in Scheme, 4253they are described in a section of their own (*note Lists::). 4254 4255 Pairs can literally get entered in source code or at the REPL, in the 4256so-called “dotted list” syntax. This syntax consists of an opening 4257parentheses, the first element of the pair, a dot, the second element 4258and a closing parentheses. The following example shows how a pair 4259consisting of the two numbers 1 and 2, and a pair containing the symbols 4260‘foo’ and ‘bar’ can be entered. It is very important to write the 4261whitespace before and after the dot, because otherwise the Scheme parser 4262would not be able to figure out where to split the tokens. 4263 4264 (1 . 2) 4265 (foo . bar) 4266 4267 But beware, if you want to try out these examples, you have to 4268“quote” the expressions. More information about quotation is available 4269in the section *note Expression Syntax::. The correct way to try these 4270examples is as follows. 4271 4272 '(1 . 2) 4273 ⇒ 4274 (1 . 2) 4275 '(foo . bar) 4276 ⇒ 4277 (foo . bar) 4278 4279 A new pair is made by calling the procedure ‘cons’ with two 4280arguments. Then the argument values are stored into a newly allocated 4281pair, and the pair is returned. The name ‘cons’ stands for "construct". 4282Use the procedure ‘pair?’ to test whether a given Scheme object is a 4283pair or not. 4284 4285 -- Scheme Procedure: cons x y 4286 -- C Function: scm_cons (x, y) 4287 Return a newly allocated pair whose car is X and whose cdr is Y. 4288 The pair is guaranteed to be different (in the sense of ‘eq?’) from 4289 every previously existing object. 4290 4291 -- Scheme Procedure: pair? x 4292 -- C Function: scm_pair_p (x) 4293 Return ‘#t’ if X is a pair; otherwise return ‘#f’. 4294 4295 -- C Function: int scm_is_pair (SCM x) 4296 Return 1 when X is a pair; otherwise return 0. 4297 4298 The two parts of a pair are traditionally called “car” and “cdr”. 4299They can be retrieved with procedures of the same name (‘car’ and 4300‘cdr’), and can be modified with the procedures ‘set-car!’ and 4301‘set-cdr!’. 4302 4303 Since a very common operation in Scheme programs is to access the car 4304of a car of a pair, or the car of the cdr of a pair, etc., the 4305procedures called ‘caar’, ‘cadr’ and so on are also predefined. 4306However, using these procedures is often detrimental to readability, and 4307error-prone. Thus, accessing the contents of a list is usually better 4308achieved using pattern matching techniques (*note Pattern Matching::). 4309 4310 -- Scheme Procedure: car pair 4311 -- Scheme Procedure: cdr pair 4312 -- C Function: scm_car (pair) 4313 -- C Function: scm_cdr (pair) 4314 Return the car or the cdr of PAIR, respectively. 4315 4316 -- C Macro: SCM SCM_CAR (SCM pair) 4317 -- C Macro: SCM SCM_CDR (SCM pair) 4318 These two macros are the fastest way to access the car or cdr of a 4319 pair; they can be thought of as compiling into a single memory 4320 reference. 4321 4322 These macros do no checking at all. The argument PAIR must be a 4323 valid pair. 4324 4325 -- Scheme Procedure: cddr pair 4326 -- Scheme Procedure: cdar pair 4327 -- Scheme Procedure: cadr pair 4328 -- Scheme Procedure: caar pair 4329 -- Scheme Procedure: cdddr pair 4330 -- Scheme Procedure: cddar pair 4331 -- Scheme Procedure: cdadr pair 4332 -- Scheme Procedure: cdaar pair 4333 -- Scheme Procedure: caddr pair 4334 -- Scheme Procedure: cadar pair 4335 -- Scheme Procedure: caadr pair 4336 -- Scheme Procedure: caaar pair 4337 -- Scheme Procedure: cddddr pair 4338 -- Scheme Procedure: cdddar pair 4339 -- Scheme Procedure: cddadr pair 4340 -- Scheme Procedure: cddaar pair 4341 -- Scheme Procedure: cdaddr pair 4342 -- Scheme Procedure: cdadar pair 4343 -- Scheme Procedure: cdaadr pair 4344 -- Scheme Procedure: cdaaar pair 4345 -- Scheme Procedure: cadddr pair 4346 -- Scheme Procedure: caddar pair 4347 -- Scheme Procedure: cadadr pair 4348 -- Scheme Procedure: cadaar pair 4349 -- Scheme Procedure: caaddr pair 4350 -- Scheme Procedure: caadar pair 4351 -- Scheme Procedure: caaadr pair 4352 -- Scheme Procedure: caaaar pair 4353 -- C Function: scm_cddr (pair) 4354 -- C Function: scm_cdar (pair) 4355 -- C Function: scm_cadr (pair) 4356 -- C Function: scm_caar (pair) 4357 -- C Function: scm_cdddr (pair) 4358 -- C Function: scm_cddar (pair) 4359 -- C Function: scm_cdadr (pair) 4360 -- C Function: scm_cdaar (pair) 4361 -- C Function: scm_caddr (pair) 4362 -- C Function: scm_cadar (pair) 4363 -- C Function: scm_caadr (pair) 4364 -- C Function: scm_caaar (pair) 4365 -- C Function: scm_cddddr (pair) 4366 -- C Function: scm_cdddar (pair) 4367 -- C Function: scm_cddadr (pair) 4368 -- C Function: scm_cddaar (pair) 4369 -- C Function: scm_cdaddr (pair) 4370 -- C Function: scm_cdadar (pair) 4371 -- C Function: scm_cdaadr (pair) 4372 -- C Function: scm_cdaaar (pair) 4373 -- C Function: scm_cadddr (pair) 4374 -- C Function: scm_caddar (pair) 4375 -- C Function: scm_cadadr (pair) 4376 -- C Function: scm_cadaar (pair) 4377 -- C Function: scm_caaddr (pair) 4378 -- C Function: scm_caadar (pair) 4379 -- C Function: scm_caaadr (pair) 4380 -- C Function: scm_caaaar (pair) 4381 These procedures are compositions of ‘car’ and ‘cdr’, where for 4382 example ‘caddr’ could be defined by 4383 4384 (define caddr (lambda (x) (car (cdr (cdr x))))) 4385 4386 ‘cadr’, ‘caddr’ and ‘cadddr’ pick out the second, third or fourth 4387 elements of a list, respectively. SRFI-1 provides the same under 4388 the names ‘second’, ‘third’ and ‘fourth’ (*note SRFI-1 4389 Selectors::). 4390 4391 -- Scheme Procedure: set-car! pair value 4392 -- C Function: scm_set_car_x (pair, value) 4393 Stores VALUE in the car field of PAIR. The value returned by 4394 ‘set-car!’ is unspecified. 4395 4396 -- Scheme Procedure: set-cdr! pair value 4397 -- C Function: scm_set_cdr_x (pair, value) 4398 Stores VALUE in the cdr field of PAIR. The value returned by 4399 ‘set-cdr!’ is unspecified. 4400 4401 4402File: guile.info, Node: Lists, Next: Vectors, Prev: Pairs, Up: Data Types 4403 44046.6.9 Lists 4405----------- 4406 4407A very important data type in Scheme—as well as in all other Lisp 4408dialects—is the data type “list”.(1) 4409 4410 This is the short definition of what a list is: 4411 4412 • Either the empty list ‘()’, 4413 4414 • or a pair which has a list in its cdr. 4415 4416* Menu: 4417 4418* List Syntax:: Writing literal lists. 4419* List Predicates:: Testing lists. 4420* List Constructors:: Creating new lists. 4421* List Selection:: Selecting from lists, getting their length. 4422* Append/Reverse:: Appending and reversing lists. 4423* List Modification:: Modifying existing lists. 4424* List Searching:: Searching for list elements 4425* List Mapping:: Applying procedures to lists. 4426 4427 ---------- Footnotes ---------- 4428 4429 (1) Strictly speaking, Scheme does not have a real datatype “list”. 4430Lists are made up of “chained pairs”, and only exist by definition—a 4431list is a chain of pairs which looks like a list. 4432 4433 4434File: guile.info, Node: List Syntax, Next: List Predicates, Up: Lists 4435 44366.6.9.1 List Read Syntax 4437........................ 4438 4439The syntax for lists is an opening parentheses, then all the elements of 4440the list (separated by whitespace) and finally a closing 4441parentheses.(1). 4442 4443 (1 2 3) ; a list of the numbers 1, 2 and 3 4444 ("foo" bar 3.1415) ; a string, a symbol and a real number 4445 () ; the empty list 4446 4447 The last example needs a bit more explanation. A list with no 4448elements, called the “empty list”, is special in some ways. It is used 4449for terminating lists by storing it into the cdr of the last pair that 4450makes up a list. An example will clear that up: 4451 4452 (car '(1)) 4453 ⇒ 4454 1 4455 (cdr '(1)) 4456 ⇒ 4457 () 4458 4459 This example also shows that lists have to be quoted when written 4460(*note Expression Syntax::), because they would otherwise be mistakingly 4461taken as procedure applications (*note Simple Invocation::). 4462 4463 ---------- Footnotes ---------- 4464 4465 (1) Note that there is no separation character between the list 4466elements, like a comma or a semicolon. 4467 4468 4469File: guile.info, Node: List Predicates, Next: List Constructors, Prev: List Syntax, Up: Lists 4470 44716.6.9.2 List Predicates 4472....................... 4473 4474Often it is useful to test whether a given Scheme object is a list or 4475not. List-processing procedures could use this information to test 4476whether their input is valid, or they could do different things 4477depending on the datatype of their arguments. 4478 4479 -- Scheme Procedure: list? x 4480 -- C Function: scm_list_p (x) 4481 Return ‘#t’ if X is a proper list, else ‘#f’. 4482 4483 The predicate ‘null?’ is often used in list-processing code to tell 4484whether a given list has run out of elements. That is, a loop somehow 4485deals with the elements of a list until the list satisfies ‘null?’. 4486Then, the algorithm terminates. 4487 4488 -- Scheme Procedure: null? x 4489 -- C Function: scm_null_p (x) 4490 Return ‘#t’ if X is the empty list, else ‘#f’. 4491 4492 -- C Function: int scm_is_null (SCM x) 4493 Return 1 when X is the empty list; otherwise return 0. 4494 4495 4496File: guile.info, Node: List Constructors, Next: List Selection, Prev: List Predicates, Up: Lists 4497 44986.6.9.3 List Constructors 4499......................... 4500 4501This section describes the procedures for constructing new lists. 4502‘list’ simply returns a list where the elements are the arguments, 4503‘cons*’ is similar, but the last argument is stored in the cdr of the 4504last pair of the list. 4505 4506 -- Scheme Procedure: list elem ... 4507 -- C Function: scm_list_1 (elem1) 4508 -- C Function: scm_list_2 (elem1, elem2) 4509 -- C Function: scm_list_3 (elem1, elem2, elem3) 4510 -- C Function: scm_list_4 (elem1, elem2, elem3, elem4) 4511 -- C Function: scm_list_5 (elem1, elem2, elem3, elem4, elem5) 4512 -- C Function: scm_list_n (elem1, ..., elemN, SCM_UNDEFINED) 4513 Return a new list containing elements ELEM .... 4514 4515 ‘scm_list_n’ takes a variable number of arguments, terminated by 4516 the special ‘SCM_UNDEFINED’. That final ‘SCM_UNDEFINED’ is not 4517 included in the list. None of ELEM ... can themselves be 4518 ‘SCM_UNDEFINED’, or ‘scm_list_n’ will terminate at that point. 4519 4520 -- Scheme Procedure: cons* arg1 arg2 ... 4521 Like ‘list’, but the last arg provides the tail of the constructed 4522 list, returning ‘(cons ARG1 (cons ARG2 (cons ... ARGN)))’. 4523 Requires at least one argument. If given one argument, that 4524 argument is returned as result. This function is called ‘list*’ in 4525 some other Schemes and in Common LISP. 4526 4527 -- Scheme Procedure: list-copy lst 4528 -- C Function: scm_list_copy (lst) 4529 Return a (newly-created) copy of LST. 4530 4531 -- Scheme Procedure: make-list n [init] 4532 Create a list containing of N elements, where each element is 4533 initialized to INIT. INIT defaults to the empty list ‘()’ if not 4534 given. 4535 4536 Note that ‘list-copy’ only makes a copy of the pairs which make up 4537the spine of the lists. The list elements are not copied, which means 4538that modifying the elements of the new list also modifies the elements 4539of the old list. On the other hand, applying procedures like ‘set-cdr!’ 4540or ‘delv!’ to the new list will not alter the old list. If you also 4541need to copy the list elements (making a deep copy), use the procedure 4542‘copy-tree’ from ‘(ice-9 copy-tree)’ (*note Copying::). 4543 4544 4545File: guile.info, Node: List Selection, Next: Append/Reverse, Prev: List Constructors, Up: Lists 4546 45476.6.9.4 List Selection 4548...................... 4549 4550These procedures are used to get some information about a list, or to 4551retrieve one or more elements of a list. 4552 4553 -- Scheme Procedure: length lst 4554 -- C Function: scm_length (lst) 4555 Return the number of elements in list LST. 4556 4557 -- Scheme Procedure: last-pair lst 4558 -- C Function: scm_last_pair (lst) 4559 Return the last pair in LST, signalling an error if LST is 4560 circular. 4561 4562 -- Scheme Procedure: list-ref list k 4563 -- C Function: scm_list_ref (list, k) 4564 Return the Kth element from LIST. 4565 4566 -- Scheme Procedure: list-tail lst k 4567 -- Scheme Procedure: list-cdr-ref lst k 4568 -- C Function: scm_list_tail (lst, k) 4569 Return the "tail" of LST beginning with its Kth element. The first 4570 element of the list is considered to be element 0. 4571 4572 ‘list-tail’ and ‘list-cdr-ref’ are identical. It may help to think 4573 of ‘list-cdr-ref’ as accessing the Kth cdr of the list, or 4574 returning the results of cdring K times down LST. 4575 4576 -- Scheme Procedure: list-head lst k 4577 -- C Function: scm_list_head (lst, k) 4578 Copy the first K elements from LST into a new list, and return it. 4579 4580 4581File: guile.info, Node: Append/Reverse, Next: List Modification, Prev: List Selection, Up: Lists 4582 45836.6.9.5 Append and Reverse 4584.......................... 4585 4586‘append’ and ‘append!’ are used to concatenate two or more lists in 4587order to form a new list. ‘reverse’ and ‘reverse!’ return lists with 4588the same elements as their arguments, but in reverse order. The 4589procedure variants with an ‘!’ directly modify the pairs which form the 4590list, whereas the other procedures create new pairs. This is why you 4591should be careful when using the side-effecting variants. 4592 4593 -- Scheme Procedure: append lst ... obj 4594 -- Scheme Procedure: append 4595 -- Scheme Procedure: append! lst ... obj 4596 -- Scheme Procedure: append! 4597 -- C Function: scm_append (lstlst) 4598 -- C Function: scm_append_x (lstlst) 4599 Return a list comprising all the elements of lists LST ... OBJ. If 4600 called with no arguments, return the empty list. 4601 4602 (append '(x) '(y)) ⇒ (x y) 4603 (append '(a) '(b c d)) ⇒ (a b c d) 4604 (append '(a (b)) '((c))) ⇒ (a (b) (c)) 4605 4606 The last argument OBJ may actually be any object; an improper list 4607 results if the last argument is not a proper list. 4608 4609 (append '(a b) '(c . d)) ⇒ (a b c . d) 4610 (append '() 'a) ⇒ a 4611 4612 ‘append’ doesn’t modify the given lists, but the return may share 4613 structure with the final OBJ. ‘append!’ is permitted, but not 4614 required, to modify the given lists to form its return. 4615 4616 For ‘scm_append’ and ‘scm_append_x’, LSTLST is a list of the list 4617 operands LST ... OBJ. That LSTLST itself is not modified or used 4618 in the return. 4619 4620 -- Scheme Procedure: reverse lst 4621 -- Scheme Procedure: reverse! lst [newtail] 4622 -- C Function: scm_reverse (lst) 4623 -- C Function: scm_reverse_x (lst, newtail) 4624 Return a list comprising the elements of LST, in reverse order. 4625 4626 ‘reverse’ constructs a new list. ‘reverse!’ is permitted, but not 4627 required, to modify LST in constructing its return. 4628 4629 For ‘reverse!’, the optional NEWTAIL is appended to the result. 4630 NEWTAIL isn’t reversed, it simply becomes the list tail. For 4631 ‘scm_reverse_x’, the NEWTAIL parameter is mandatory, but can be 4632 ‘SCM_EOL’ if no further tail is required. 4633 4634 4635File: guile.info, Node: List Modification, Next: List Searching, Prev: Append/Reverse, Up: Lists 4636 46376.6.9.6 List Modification 4638......................... 4639 4640The following procedures modify an existing list, either by changing 4641elements of the list, or by changing the list structure itself. 4642 4643 -- Scheme Procedure: list-set! list k val 4644 -- C Function: scm_list_set_x (list, k, val) 4645 Set the Kth element of LIST to VAL. 4646 4647 -- Scheme Procedure: list-cdr-set! list k val 4648 -- C Function: scm_list_cdr_set_x (list, k, val) 4649 Set the Kth cdr of LIST to VAL. 4650 4651 -- Scheme Procedure: delq item lst 4652 -- C Function: scm_delq (item, lst) 4653 Return a newly-created copy of LST with elements ‘eq?’ to ITEM 4654 removed. This procedure mirrors ‘memq’: ‘delq’ compares elements 4655 of LST against ITEM with ‘eq?’. 4656 4657 -- Scheme Procedure: delv item lst 4658 -- C Function: scm_delv (item, lst) 4659 Return a newly-created copy of LST with elements ‘eqv?’ to ITEM 4660 removed. This procedure mirrors ‘memv’: ‘delv’ compares elements 4661 of LST against ITEM with ‘eqv?’. 4662 4663 -- Scheme Procedure: delete item lst 4664 -- C Function: scm_delete (item, lst) 4665 Return a newly-created copy of LST with elements ‘equal?’ to ITEM 4666 removed. This procedure mirrors ‘member’: ‘delete’ compares 4667 elements of LST against ITEM with ‘equal?’. 4668 4669 See also SRFI-1 which has an extended ‘delete’ (*note SRFI-1 4670 Deleting::), and also an ‘lset-difference’ which can delete 4671 multiple ITEMs in one call (*note SRFI-1 Set Operations::). 4672 4673 -- Scheme Procedure: delq! item lst 4674 -- Scheme Procedure: delv! item lst 4675 -- Scheme Procedure: delete! item lst 4676 -- C Function: scm_delq_x (item, lst) 4677 -- C Function: scm_delv_x (item, lst) 4678 -- C Function: scm_delete_x (item, lst) 4679 These procedures are destructive versions of ‘delq’, ‘delv’ and 4680 ‘delete’: they modify the pointers in the existing LST rather than 4681 creating a new list. Caveat evaluator: Like other destructive list 4682 functions, these functions cannot modify the binding of LST, and so 4683 cannot be used to delete the first element of LST destructively. 4684 4685 -- Scheme Procedure: delq1! item lst 4686 -- C Function: scm_delq1_x (item, lst) 4687 Like ‘delq!’, but only deletes the first occurrence of ITEM from 4688 LST. Tests for equality using ‘eq?’. See also ‘delv1!’ and 4689 ‘delete1!’. 4690 4691 -- Scheme Procedure: delv1! item lst 4692 -- C Function: scm_delv1_x (item, lst) 4693 Like ‘delv!’, but only deletes the first occurrence of ITEM from 4694 LST. Tests for equality using ‘eqv?’. See also ‘delq1!’ and 4695 ‘delete1!’. 4696 4697 -- Scheme Procedure: delete1! item lst 4698 -- C Function: scm_delete1_x (item, lst) 4699 Like ‘delete!’, but only deletes the first occurrence of ITEM from 4700 LST. Tests for equality using ‘equal?’. See also ‘delq1!’ and 4701 ‘delv1!’. 4702 4703 -- Scheme Procedure: filter pred lst 4704 -- Scheme Procedure: filter! pred lst 4705 Return a list containing all elements from LST which satisfy the 4706 predicate PRED. The elements in the result list have the same 4707 order as in LST. The order in which PRED is applied to the list 4708 elements is not specified. 4709 4710 ‘filter’ does not change LST, but the result may share a tail with 4711 it. ‘filter!’ may modify LST to construct its return. 4712 4713 4714File: guile.info, Node: List Searching, Next: List Mapping, Prev: List Modification, Up: Lists 4715 47166.6.9.7 List Searching 4717...................... 4718 4719The following procedures search lists for particular elements. They use 4720different comparison predicates for comparing list elements with the 4721object to be searched. When they fail, they return ‘#f’, otherwise they 4722return the sublist whose car is equal to the search object, where 4723equality depends on the equality predicate used. 4724 4725 -- Scheme Procedure: memq x lst 4726 -- C Function: scm_memq (x, lst) 4727 Return the first sublist of LST whose car is ‘eq?’ to X where the 4728 sublists of LST are the non-empty lists returned by ‘(list-tail LST 4729 K)’ for K less than the length of LST. If X does not occur in LST, 4730 then ‘#f’ (not the empty list) is returned. 4731 4732 -- Scheme Procedure: memv x lst 4733 -- C Function: scm_memv (x, lst) 4734 Return the first sublist of LST whose car is ‘eqv?’ to X where the 4735 sublists of LST are the non-empty lists returned by ‘(list-tail LST 4736 K)’ for K less than the length of LST. If X does not occur in LST, 4737 then ‘#f’ (not the empty list) is returned. 4738 4739 -- Scheme Procedure: member x lst 4740 -- C Function: scm_member (x, lst) 4741 Return the first sublist of LST whose car is ‘equal?’ to X where 4742 the sublists of LST are the non-empty lists returned by ‘(list-tail 4743 LST K)’ for K less than the length of LST. If X does not occur in 4744 LST, then ‘#f’ (not the empty list) is returned. 4745 4746 See also SRFI-1 which has an extended ‘member’ function (*note 4747 SRFI-1 Searching::). 4748 4749 4750File: guile.info, Node: List Mapping, Prev: List Searching, Up: Lists 4751 47526.6.9.8 List Mapping 4753.................... 4754 4755List processing is very convenient in Scheme because the process of 4756iterating over the elements of a list can be highly abstracted. The 4757procedures in this section are the most basic iterating procedures for 4758lists. They take a procedure and one or more lists as arguments, and 4759apply the procedure to each element of the list. They differ in their 4760return value. 4761 4762 -- Scheme Procedure: map proc arg1 arg2 ... 4763 -- Scheme Procedure: map-in-order proc arg1 arg2 ... 4764 -- C Function: scm_map (proc, arg1, args) 4765 Apply PROC to each element of the list ARG1 (if only two arguments 4766 are given), or to the corresponding elements of the argument lists 4767 (if more than two arguments are given). The result(s) of the 4768 procedure applications are saved and returned in a list. For 4769 ‘map’, the order of procedure applications is not specified, 4770 ‘map-in-order’ applies the procedure from left to right to the list 4771 elements. 4772 4773 -- Scheme Procedure: for-each proc arg1 arg2 ... 4774 Like ‘map’, but the procedure is always applied from left to right, 4775 and the result(s) of the procedure applications are thrown away. 4776 The return value is not specified. 4777 4778 See also SRFI-1 which extends these functions to take lists of 4779unequal lengths (*note SRFI-1 Fold and Map::). 4780 4781 4782File: guile.info, Node: Vectors, Next: Bit Vectors, Prev: Lists, Up: Data Types 4783 47846.6.10 Vectors 4785-------------- 4786 4787Vectors are sequences of Scheme objects. Unlike lists, the length of a 4788vector, once the vector is created, cannot be changed. The advantage of 4789vectors over lists is that the time required to access one element of a 4790vector given its “position” (synonymous with “index”), a zero-origin 4791number, is constant, whereas lists have an access time linear to the 4792position of the accessed element in the list. 4793 4794 Vectors can contain any kind of Scheme object; it is even possible to 4795have different types of objects in the same vector. For vectors 4796containing vectors, you may wish to use arrays, instead. Note, too, 4797that vectors are the special case of one dimensional non-uniform arrays 4798and that most array procedures operate happily on vectors (*note 4799Arrays::). 4800 4801 Also see *note SRFI-43::, for a comprehensive vector library. 4802 4803* Menu: 4804 4805* Vector Syntax:: Read syntax for vectors. 4806* Vector Creation:: Dynamic vector creation and validation. 4807* Vector Accessors:: Accessing and modifying vector contents. 4808* Vector Accessing from C:: Ways to work with vectors from C. 4809* Uniform Numeric Vectors:: Vectors of unboxed numeric values. 4810 4811 4812File: guile.info, Node: Vector Syntax, Next: Vector Creation, Up: Vectors 4813 48146.6.10.1 Read Syntax for Vectors 4815................................ 4816 4817Vectors can literally be entered in source code, just like strings, 4818characters or some of the other data types. The read syntax for vectors 4819is as follows: A sharp sign (‘#’), followed by an opening parentheses, 4820all elements of the vector in their respective read syntax, and finally 4821a closing parentheses. Like strings, vectors do not have to be quoted. 4822 4823 The following are examples of the read syntax for vectors; where the 4824first vector only contains numbers and the second three different object 4825types: a string, a symbol and a number in hexadecimal notation. 4826 4827 #(1 2 3) 4828 #("Hello" foo #xdeadbeef) 4829 4830 4831File: guile.info, Node: Vector Creation, Next: Vector Accessors, Prev: Vector Syntax, Up: Vectors 4832 48336.6.10.2 Dynamic Vector Creation and Validation 4834............................................... 4835 4836Instead of creating a vector implicitly by using the read syntax just 4837described, you can create a vector dynamically by calling one of the 4838‘vector’ and ‘list->vector’ primitives with the list of Scheme values 4839that you want to place into a vector. The size of the vector thus 4840created is determined implicitly by the number of arguments given. 4841 4842 -- Scheme Procedure: vector arg ... 4843 -- Scheme Procedure: list->vector l 4844 -- C Function: scm_vector (l) 4845 Return a newly allocated vector composed of the given arguments. 4846 Analogous to ‘list’. 4847 4848 (vector 'a 'b 'c) ⇒ #(a b c) 4849 4850 The inverse operation is ‘vector->list’: 4851 4852 -- Scheme Procedure: vector->list v 4853 -- C Function: scm_vector_to_list (v) 4854 Return a newly allocated list composed of the elements of V. 4855 4856 (vector->list #(dah dah didah)) ⇒ (dah dah didah) 4857 (list->vector '(dididit dah)) ⇒ #(dididit dah) 4858 4859 To allocate a vector with an explicitly specified size, use 4860‘make-vector’. With this primitive you can also specify an initial 4861value for the vector elements (the same value for all elements, that 4862is): 4863 4864 -- Scheme Procedure: make-vector len [fill] 4865 -- C Function: scm_make_vector (len, fill) 4866 Return a newly allocated vector of LEN elements. If a second 4867 argument is given, then each position is initialized to FILL. 4868 Otherwise the initial contents of each position is unspecified. 4869 4870 -- C Function: SCM scm_c_make_vector (size_t k, SCM fill) 4871 Like ‘scm_make_vector’, but the length is given as a ‘size_t’. 4872 4873 To check whether an arbitrary Scheme value _is_ a vector, use the 4874‘vector?’ primitive: 4875 4876 -- Scheme Procedure: vector? obj 4877 -- C Function: scm_vector_p (obj) 4878 Return ‘#t’ if OBJ is a vector, otherwise return ‘#f’. 4879 4880 -- C Function: int scm_is_vector (SCM obj) 4881 Return non-zero when OBJ is a vector, otherwise return ‘zero’. 4882 4883 4884File: guile.info, Node: Vector Accessors, Next: Vector Accessing from C, Prev: Vector Creation, Up: Vectors 4885 48866.6.10.3 Accessing and Modifying Vector Contents 4887................................................ 4888 4889‘vector-length’ and ‘vector-ref’ return information about a given 4890vector, respectively its size and the elements that are contained in the 4891vector. 4892 4893 -- Scheme Procedure: vector-length vector 4894 -- C Function: scm_vector_length (vector) 4895 Return the number of elements in VECTOR as an exact integer. 4896 4897 -- C Function: size_t scm_c_vector_length (SCM vec) 4898 Return the number of elements in VEC as a ‘size_t’. 4899 4900 -- Scheme Procedure: vector-ref vec k 4901 -- C Function: scm_vector_ref (vec, k) 4902 Return the contents of position K of VEC. K must be a valid index 4903 of VEC. 4904 (vector-ref #(1 1 2 3 5 8 13 21) 5) ⇒ 8 4905 (vector-ref #(1 1 2 3 5 8 13 21) 4906 (let ((i (round (* 2 (acos -1))))) 4907 (if (inexact? i) 4908 (inexact->exact i) 4909 i))) ⇒ 13 4910 4911 -- C Function: SCM scm_c_vector_ref (SCM vec, size_t k) 4912 Return the contents of position K (a ‘size_t’) of VEC. 4913 4914 A vector created by one of the dynamic vector constructor procedures 4915(*note Vector Creation::) can be modified using the following 4916procedures. 4917 4918 _NOTE:_ According to R5RS, it is an error to use any of these 4919procedures on a literally read vector, because such vectors should be 4920considered as constants. Currently, however, Guile does not detect this 4921error. 4922 4923 -- Scheme Procedure: vector-set! vec k obj 4924 -- C Function: scm_vector_set_x (vec, k, obj) 4925 Store OBJ in position K of VEC. K must be a valid index of VEC. 4926 The value returned by ‘vector-set!’ is unspecified. 4927 (let ((vec (vector 0 '(2 2 2 2) "Anna"))) 4928 (vector-set! vec 1 '("Sue" "Sue")) 4929 vec) ⇒ #(0 ("Sue" "Sue") "Anna") 4930 4931 -- C Function: void scm_c_vector_set_x (SCM vec, size_t k, SCM obj) 4932 Store OBJ in position K (a ‘size_t’) of VEC. 4933 4934 -- Scheme Procedure: vector-fill! vec fill 4935 -- C Function: scm_vector_fill_x (vec, fill) 4936 Store FILL in every position of VEC. The value returned by 4937 ‘vector-fill!’ is unspecified. 4938 4939 -- Scheme Procedure: vector-copy vec 4940 -- C Function: scm_vector_copy (vec) 4941 Return a copy of VEC. 4942 4943 -- Scheme Procedure: vector-move-left! vec1 start1 end1 vec2 start2 4944 -- C Function: scm_vector_move_left_x (vec1, start1, end1, vec2, 4945 start2) 4946 Copy elements from VEC1, positions START1 to END1, to VEC2 starting 4947 at position START2. START1 and START2 are inclusive indices; END1 4948 is exclusive. 4949 4950 ‘vector-move-left!’ copies elements in leftmost order. Therefore, 4951 in the case where VEC1 and VEC2 refer to the same vector, 4952 ‘vector-move-left!’ is usually appropriate when START1 is greater 4953 than START2. 4954 4955 -- Scheme Procedure: vector-move-right! vec1 start1 end1 vec2 start2 4956 -- C Function: scm_vector_move_right_x (vec1, start1, end1, vec2, 4957 start2) 4958 Copy elements from VEC1, positions START1 to END1, to VEC2 starting 4959 at position START2. START1 and START2 are inclusive indices; END1 4960 is exclusive. 4961 4962 ‘vector-move-right!’ copies elements in rightmost order. 4963 Therefore, in the case where VEC1 and VEC2 refer to the same 4964 vector, ‘vector-move-right!’ is usually appropriate when START1 is 4965 less than START2. 4966 4967 4968File: guile.info, Node: Vector Accessing from C, Next: Uniform Numeric Vectors, Prev: Vector Accessors, Up: Vectors 4969 49706.6.10.4 Vector Accessing from C 4971................................ 4972 4973A vector can be read and modified from C with the functions 4974‘scm_c_vector_ref’ and ‘scm_c_vector_set_x’, for example. In addition 4975to these functions, there are two more ways to access vectors from C 4976that might be more efficient in certain situations: you can restrict 4977yourself to “simple vectors” and then use the very fast _simple vector 4978macros_; or you can use the very general framework for accessing all 4979kinds of arrays (*note Accessing Arrays from C::), which is more 4980verbose, but can deal efficiently with all kinds of vectors (and 4981arrays). For vectors, you can use the ‘scm_vector_elements’ and 4982‘scm_vector_writable_elements’ functions as shortcuts. 4983 4984 -- C Function: int scm_is_simple_vector (SCM obj) 4985 Return non-zero if OBJ is a simple vector, else return zero. A 4986 simple vector is a vector that can be used with the ‘SCM_SIMPLE_*’ 4987 macros below. 4988 4989 The following functions are guaranteed to return simple vectors: 4990 ‘scm_make_vector’, ‘scm_c_make_vector’, ‘scm_vector’, 4991 ‘scm_list_to_vector’. 4992 4993 -- C Macro: size_t SCM_SIMPLE_VECTOR_LENGTH (SCM vec) 4994 Evaluates to the length of the simple vector VEC. No type checking 4995 is done. 4996 4997 -- C Macro: SCM SCM_SIMPLE_VECTOR_REF (SCM vec, size_t idx) 4998 Evaluates to the element at position IDX in the simple vector VEC. 4999 No type or range checking is done. 5000 5001 -- C Macro: void SCM_SIMPLE_VECTOR_SET (SCM vec, size_t idx, SCM val) 5002 Sets the element at position IDX in the simple vector VEC to VAL. 5003 No type or range checking is done. 5004 5005 -- C Function: const SCM * scm_vector_elements (SCM vec, 5006 scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) 5007 Acquire a handle for the vector VEC and return a pointer to the 5008 elements of it. This pointer can only be used to read the elements 5009 of VEC. When VEC is not a vector, an error is signaled. The 5010 handle must eventually be released with ‘scm_array_handle_release’. 5011 5012 The variables pointed to by LENP and INCP are filled with the 5013 number of elements of the vector and the increment (number of 5014 elements) between successive elements, respectively. Successive 5015 elements of VEC need not be contiguous in their underlying “root 5016 vector” returned here; hence the increment is not necessarily equal 5017 to 1 and may well be negative too (*note Shared Arrays::). 5018 5019 The following example shows the typical way to use this function. 5020 It creates a list of all elements of VEC (in reverse order). 5021 5022 scm_t_array_handle handle; 5023 size_t i, len; 5024 ssize_t inc; 5025 const SCM *elt; 5026 SCM list; 5027 5028 elt = scm_vector_elements (vec, &handle, &len, &inc); 5029 list = SCM_EOL; 5030 for (i = 0; i < len; i++, elt += inc) 5031 list = scm_cons (*elt, list); 5032 scm_array_handle_release (&handle); 5033 5034 -- C Function: SCM * scm_vector_writable_elements (SCM vec, 5035 scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) 5036 Like ‘scm_vector_elements’ but the pointer can be used to modify 5037 the vector. 5038 5039 The following example shows the typical way to use this function. 5040 It fills a vector with ‘#t’. 5041 5042 scm_t_array_handle handle; 5043 size_t i, len; 5044 ssize_t inc; 5045 SCM *elt; 5046 5047 elt = scm_vector_writable_elements (vec, &handle, &len, &inc); 5048 for (i = 0; i < len; i++, elt += inc) 5049 *elt = SCM_BOOL_T; 5050 scm_array_handle_release (&handle); 5051 5052 5053File: guile.info, Node: Uniform Numeric Vectors, Prev: Vector Accessing from C, Up: Vectors 5054 50556.6.10.5 Uniform Numeric Vectors 5056................................ 5057 5058A uniform numeric vector is a vector whose elements are all of a single 5059numeric type. Guile offers uniform numeric vectors for signed and 5060unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of 5061floating point values, and complex floating-point numbers of these two 5062sizes. *Note SRFI-4::, for more information. 5063 5064 For many purposes, bytevectors work just as well as uniform vectors, 5065and have the advantage that they integrate well with binary input and 5066output. *Note Bytevectors::, for more information on bytevectors. 5067 5068 5069File: guile.info, Node: Bit Vectors, Next: Bytevectors, Prev: Vectors, Up: Data Types 5070 50716.6.11 Bit Vectors 5072------------------ 5073 5074Bit vectors are zero-origin, one-dimensional arrays of booleans. They 5075are displayed as a sequence of ‘0’s and ‘1’s prefixed by ‘#*’, e.g., 5076 5077 (make-bitvector 8 #f) ⇒ 5078 #*00000000 5079 5080 Bit vectors are the special case of one dimensional bit arrays, and 5081can thus be used with the array procedures, *Note Arrays::. 5082 5083 -- Scheme Procedure: bitvector? obj 5084 Return ‘#t’ when OBJ is a bitvector, else return ‘#f’. 5085 5086 -- Scheme Procedure: make-bitvector len [fill] 5087 Create a new bitvector of length LEN and optionally initialize all 5088 elements to FILL. 5089 5090 -- Scheme Procedure: bitvector bit ... 5091 Create a new bitvector with the arguments as elements. 5092 5093 -- Scheme Procedure: bitvector-length vec 5094 Return the length of the bitvector VEC. 5095 5096 -- Scheme Procedure: bitvector-bit-set? vec idx 5097 -- Scheme Procedure: bitvector-bit-clear? vec idx 5098 Return ‘#t’ if the bit at index IDX of the bitvector VEC is set 5099 (for ‘bitvector-bit-set?’) or clear (for ‘bitvector-bit-clear?’). 5100 5101 -- Scheme Procedure: bitvector-set-bit! vec idx 5102 -- Scheme Procedure: bitvector-clear-bit! vec idx 5103 Set (for ‘bitvector-set-bit!’) or clear (for 5104 ‘bitvector-clear-bit!’) the bit at index IDX of the bitvector VEC. 5105 5106 -- Scheme Procedure: bitvector-set-all-bits! vec 5107 -- Scheme Procedure: bitvector-clear-all-bits! vec 5108 -- Scheme Procedure: bitvector-flip-all-bits! vec 5109 Set, clear, or flip all bits of VEC. 5110 5111 -- Scheme Procedure: list->bitvector list 5112 -- C Function: scm_list_to_bitvector (list) 5113 Return a new bitvector initialized with the elements of LIST. 5114 5115 -- Scheme Procedure: bitvector->list vec 5116 -- C Function: scm_bitvector_to_list (vec) 5117 Return a new list initialized with the elements of the bitvector 5118 VEC. 5119 5120 -- Scheme Procedure: bitvector-count bitvector 5121 Return a count of how many entries in BITVECTOR are set. 5122 5123 (bitvector-count #*000111000) ⇒ 3 5124 5125 -- Scheme Procedure: bitvector-count-bits bitvector bits 5126 Return a count of how many entries in BITVECTOR are set, with the 5127 bitvector BITS selecting the entries to consider. BITVECTOR must 5128 be at least as long as BITS. 5129 5130 For example, 5131 5132 (bitvector-count-bits #*01110111 #*11001101) ⇒ 3 5133 5134 -- Scheme Procedure: bitvector-position bitvector bool start 5135 -- C Function: scm_bitvector_position (bitvector, bool, start) 5136 Return the index of the first occurrence of BOOL in BITVECTOR, 5137 starting from START. If there is no BOOL entry between START and 5138 the end of BITVECTOR, then return ‘#f’. For example, 5139 5140 (bitvector-position #*000101 #t 0) ⇒ 3 5141 (bitvector-position #*0001111 #f 3) ⇒ #f 5142 5143 -- Scheme Procedure: bitvector-set-bits! bitvector bits 5144 Set entries of BITVECTOR to ‘#t’, with BITS selecting the bits to 5145 set. The return value is unspecified. BITVECTOR must be at least 5146 as long as BITS. 5147 5148 (define bv (bitvector-copy #*11000010)) 5149 (bitvector-set-bits! bv #*10010001) 5150 bv 5151 ⇒ #*11010011 5152 5153 -- Scheme Procedure: bitvector-clear-bits! bitvector bits 5154 Set entries of BITVECTOR to ‘#f’, with BITS selecting the bits to 5155 clear. The return value is unspecified. BITVECTOR must be at 5156 least as long as BITS. 5157 5158 (define bv (bitvector-copy #*11000010)) 5159 (bitvector-clear-bits! bv #*10010001) 5160 bv 5161 ⇒ #*01000010 5162 5163 -- C Function: int scm_is_bitvector (SCM obj) 5164 -- C Function: SCM scm_c_make_bitvector (size_t len, SCM fill) 5165 -- C Function: int scm_bitvector_bit_is_set (SCM vec, size_t idx) 5166 -- C Function: int scm_bitvector_bit_is_clear (SCM vec, size_t idx) 5167 -- C Function: void scm_c_bitvector_set_bit_x (SCM vec, size_t idx) 5168 -- C Function: void scm_c_bitvector_clear_bit_x (SCM vec, size_t idx) 5169 -- C Function: void scm_c_bitvector_set_bits_x (SCM vec, SCM bits) 5170 -- C Function: void scm_c_bitvector_clear_bits_x (SCM vec, SCM bits) 5171 -- C Function: void scm_c_bitvector_set_all_bits_x (SCM vec) 5172 -- C Function: void scm_c_bitvector_clear_all_bits_x (SCM vec) 5173 -- C Function: void scm_c_bitvector_flip_all_bits_x (SCM vec) 5174 -- C Function: size_t scm_c_bitvector_length (SCM bitvector) 5175 -- C Function: size_t scm_c_bitvector_count (SCM bitvector) 5176 -- C Function: size_t scm_c_bitvector_count_bits (SCM bitvector, SCM 5177 bits) 5178 C API for the corresponding Scheme bitvector interfaces. 5179 5180 -- C Function: const scm_t_uint32 * scm_bitvector_elements (SCM vec, 5181 scm_t_array_handle *handle, size_t *offp, size_t *lenp, 5182 ssize_t *incp) 5183 Like ‘scm_vector_elements’ (*note Vector Accessing from C::), but 5184 for bitvectors. The variable pointed to by OFFP is set to the 5185 value returned by ‘scm_array_handle_bit_elements_offset’. See 5186 ‘scm_array_handle_bit_elements’ for how to use the returned pointer 5187 and the offset. 5188 5189 -- C Function: scm_t_uint32 * scm_bitvector_writable_elements (SCM vec, 5190 scm_t_array_handle *handle, size_t *offp, size_t *lenp, 5191 ssize_t *incp) 5192 Like ‘scm_bitvector_elements’, but the pointer is good for reading 5193 and writing. 5194 5195 5196File: guile.info, Node: Bytevectors, Next: Arrays, Prev: Bit Vectors, Up: Data Types 5197 51986.6.12 Bytevectors 5199------------------ 5200 5201A “bytevector” is a raw bit string. The ‘(rnrs bytevectors)’ module 5202provides the programming interface specified by the Revised^6 Report on 5203the Algorithmic Language Scheme (R6RS) (http://www.r6rs.org/). It 5204contains procedures to manipulate bytevectors and interpret their 5205contents in a number of ways: bytevector contents can be accessed as 5206signed or unsigned integer of various sizes and endianness, as IEEE-754 5207floating point numbers, or as strings. It is a useful tool to encode 5208and decode binary data. 5209 5210 The R6RS (Section 4.3.4) specifies an external representation for 5211bytevectors, whereby the octets (integers in the range 0–255) contained 5212in the bytevector are represented as a list prefixed by ‘#vu8’: 5213 5214 #vu8(1 53 204) 5215 5216 denotes a 3-byte bytevector containing the octets 1, 53, and 204. 5217Like string literals, booleans, etc., bytevectors are “self-quoting”, 5218i.e., they do not need to be quoted: 5219 5220 #vu8(1 53 204) 5221 ⇒ #vu8(1 53 204) 5222 5223 Bytevectors can be used with the binary input/output primitives 5224(*note Binary I/O::). 5225 5226* Menu: 5227 5228* Bytevector Endianness:: Dealing with byte order. 5229* Bytevector Manipulation:: Creating, copying, manipulating bytevectors. 5230* Bytevectors as Integers:: Interpreting bytes as integers. 5231* Bytevectors and Integer Lists:: Converting to/from an integer list. 5232* Bytevectors as Floats:: Interpreting bytes as real numbers. 5233* Bytevectors as Strings:: Interpreting bytes as Unicode strings. 5234* Bytevectors as Arrays:: Guile extension to the bytevector API. 5235* Bytevectors as Uniform Vectors:: Bytevectors and SRFI-4. 5236 5237 5238File: guile.info, Node: Bytevector Endianness, Next: Bytevector Manipulation, Up: Bytevectors 5239 52406.6.12.1 Endianness 5241................... 5242 5243Some of the following procedures take an ENDIANNESS parameter. The 5244“endianness” is defined as the order of bytes in multi-byte numbers: 5245numbers encoded in “big endian” have their most significant bytes 5246written first, whereas numbers encoded in “little endian” have their 5247least significant bytes first(1). 5248 5249 Little-endian is the native endianness of the IA32 architecture and 5250its derivatives, while big-endian is native to SPARC and PowerPC, among 5251others. The ‘native-endianness’ procedure returns the native endianness 5252of the machine it runs on. 5253 5254 -- Scheme Procedure: native-endianness 5255 -- C Function: scm_native_endianness () 5256 Return a value denoting the native endianness of the host machine. 5257 5258 -- Scheme Macro: endianness symbol 5259 Return an object denoting the endianness specified by SYMBOL. If 5260 SYMBOL is neither ‘big’ nor ‘little’ then an error is raised at 5261 expand-time. 5262 5263 -- C Variable: scm_endianness_big 5264 -- C Variable: scm_endianness_little 5265 The objects denoting big- and little-endianness, respectively. 5266 5267 ---------- Footnotes ---------- 5268 5269 (1) Big-endian and little-endian are the most common “endiannesses”, 5270but others do exist. For instance, the GNU MP library allows “word 5271order” to be specified independently of “byte order” (*note (gmp)Integer 5272Import and Export::). 5273 5274 5275File: guile.info, Node: Bytevector Manipulation, Next: Bytevectors as Integers, Prev: Bytevector Endianness, Up: Bytevectors 5276 52776.6.12.2 Manipulating Bytevectors 5278................................. 5279 5280Bytevectors can be created, copied, and analyzed with the following 5281procedures and C functions. 5282 5283 -- Scheme Procedure: make-bytevector len [fill] 5284 -- C Function: scm_make_bytevector (len, fill) 5285 -- C Function: scm_c_make_bytevector (size_t len) 5286 Return a new bytevector of LEN bytes. Optionally, if FILL is 5287 given, fill it with FILL; FILL must be in the range [-128,255]. 5288 5289 -- Scheme Procedure: bytevector? obj 5290 -- C Function: scm_bytevector_p (obj) 5291 Return true if OBJ is a bytevector. 5292 5293 -- C Function: int scm_is_bytevector (SCM obj) 5294 Equivalent to ‘scm_is_true (scm_bytevector_p (obj))’. 5295 5296 -- Scheme Procedure: bytevector-length bv 5297 -- C Function: scm_bytevector_length (bv) 5298 Return the length in bytes of bytevector BV. 5299 5300 -- C Function: size_t scm_c_bytevector_length (SCM bv) 5301 Likewise, return the length in bytes of bytevector BV. 5302 5303 -- Scheme Procedure: bytevector=? bv1 bv2 5304 -- C Function: scm_bytevector_eq_p (bv1, bv2) 5305 Return is BV1 equals to BV2—i.e., if they have the same length and 5306 contents. 5307 5308 -- Scheme Procedure: bytevector-fill! bv fill 5309 -- C Function: scm_bytevector_fill_x (bv, fill) 5310 Fill bytevector BV with FILL, a byte. 5311 5312 -- Scheme Procedure: bytevector-copy! source source-start target 5313 target-start len 5314 -- C Function: scm_bytevector_copy_x (source, source_start, target, 5315 target_start, len) 5316 Copy LEN bytes from SOURCE into TARGET, starting reading from 5317 SOURCE-START (a positive index within SOURCE) and start writing at 5318 TARGET-START. It is permitted for the SOURCE and TARGET regions to 5319 overlap. 5320 5321 -- Scheme Procedure: bytevector-copy bv 5322 -- C Function: scm_bytevector_copy (bv) 5323 Return a newly allocated copy of BV. 5324 5325 -- C Function: scm_t_uint8 scm_c_bytevector_ref (SCM bv, size_t index) 5326 Return the byte at INDEX in bytevector BV. 5327 5328 -- C Function: void scm_c_bytevector_set_x (SCM bv, size_t index, 5329 scm_t_uint8 value) 5330 Set the byte at INDEX in BV to VALUE. 5331 5332 Low-level C macros are available. They do not perform any 5333type-checking; as such they should be used with care. 5334 5335 -- C Macro: size_t SCM_BYTEVECTOR_LENGTH (bv) 5336 Return the length in bytes of bytevector BV. 5337 5338 -- C Macro: signed char * SCM_BYTEVECTOR_CONTENTS (bv) 5339 Return a pointer to the contents of bytevector BV. 5340 5341 5342File: guile.info, Node: Bytevectors as Integers, Next: Bytevectors and Integer Lists, Prev: Bytevector Manipulation, Up: Bytevectors 5343 53446.6.12.3 Interpreting Bytevector Contents as Integers 5345..................................................... 5346 5347The contents of a bytevector can be interpreted as a sequence of 5348integers of any given size, sign, and endianness. 5349 5350 (let ((bv (make-bytevector 4))) 5351 (bytevector-u8-set! bv 0 #x12) 5352 (bytevector-u8-set! bv 1 #x34) 5353 (bytevector-u8-set! bv 2 #x56) 5354 (bytevector-u8-set! bv 3 #x78) 5355 5356 (map (lambda (number) 5357 (number->string number 16)) 5358 (list (bytevector-u8-ref bv 0) 5359 (bytevector-u16-ref bv 0 (endianness big)) 5360 (bytevector-u32-ref bv 0 (endianness little))))) 5361 5362 ⇒ ("12" "1234" "78563412") 5363 5364 The most generic procedures to interpret bytevector contents as 5365integers are described below. 5366 5367 -- Scheme Procedure: bytevector-uint-ref bv index endianness size 5368 -- C Function: scm_bytevector_uint_ref (bv, index, endianness, size) 5369 Return the SIZE-byte long unsigned integer at index INDEX in BV, 5370 decoded according to ENDIANNESS. 5371 5372 -- Scheme Procedure: bytevector-sint-ref bv index endianness size 5373 -- C Function: scm_bytevector_sint_ref (bv, index, endianness, size) 5374 Return the SIZE-byte long signed integer at index INDEX in BV, 5375 decoded according to ENDIANNESS. 5376 5377 -- Scheme Procedure: bytevector-uint-set! bv index value endianness 5378 size 5379 -- C Function: scm_bytevector_uint_set_x (bv, index, value, endianness, 5380 size) 5381 Set the SIZE-byte long unsigned integer at INDEX to VALUE, encoded 5382 according to ENDIANNESS. 5383 5384 -- Scheme Procedure: bytevector-sint-set! bv index value endianness 5385 size 5386 -- C Function: scm_bytevector_sint_set_x (bv, index, value, endianness, 5387 size) 5388 Set the SIZE-byte long signed integer at INDEX to VALUE, encoded 5389 according to ENDIANNESS. 5390 5391 The following procedures are similar to the ones above, but 5392specialized to a given integer size: 5393 5394 -- Scheme Procedure: bytevector-u8-ref bv index 5395 -- Scheme Procedure: bytevector-s8-ref bv index 5396 -- Scheme Procedure: bytevector-u16-ref bv index endianness 5397 -- Scheme Procedure: bytevector-s16-ref bv index endianness 5398 -- Scheme Procedure: bytevector-u32-ref bv index endianness 5399 -- Scheme Procedure: bytevector-s32-ref bv index endianness 5400 -- Scheme Procedure: bytevector-u64-ref bv index endianness 5401 -- Scheme Procedure: bytevector-s64-ref bv index endianness 5402 -- C Function: scm_bytevector_u8_ref (bv, index) 5403 -- C Function: scm_bytevector_s8_ref (bv, index) 5404 -- C Function: scm_bytevector_u16_ref (bv, index, endianness) 5405 -- C Function: scm_bytevector_s16_ref (bv, index, endianness) 5406 -- C Function: scm_bytevector_u32_ref (bv, index, endianness) 5407 -- C Function: scm_bytevector_s32_ref (bv, index, endianness) 5408 -- C Function: scm_bytevector_u64_ref (bv, index, endianness) 5409 -- C Function: scm_bytevector_s64_ref (bv, index, endianness) 5410 Return the unsigned N-bit (signed) integer (where N is 8, 16, 32 or 5411 64) from BV at INDEX, decoded according to ENDIANNESS. 5412 5413 -- Scheme Procedure: bytevector-u8-set! bv index value 5414 -- Scheme Procedure: bytevector-s8-set! bv index value 5415 -- Scheme Procedure: bytevector-u16-set! bv index value endianness 5416 -- Scheme Procedure: bytevector-s16-set! bv index value endianness 5417 -- Scheme Procedure: bytevector-u32-set! bv index value endianness 5418 -- Scheme Procedure: bytevector-s32-set! bv index value endianness 5419 -- Scheme Procedure: bytevector-u64-set! bv index value endianness 5420 -- Scheme Procedure: bytevector-s64-set! bv index value endianness 5421 -- C Function: scm_bytevector_u8_set_x (bv, index, value) 5422 -- C Function: scm_bytevector_s8_set_x (bv, index, value) 5423 -- C Function: scm_bytevector_u16_set_x (bv, index, value, endianness) 5424 -- C Function: scm_bytevector_s16_set_x (bv, index, value, endianness) 5425 -- C Function: scm_bytevector_u32_set_x (bv, index, value, endianness) 5426 -- C Function: scm_bytevector_s32_set_x (bv, index, value, endianness) 5427 -- C Function: scm_bytevector_u64_set_x (bv, index, value, endianness) 5428 -- C Function: scm_bytevector_s64_set_x (bv, index, value, endianness) 5429 Store VALUE as an N-bit (signed) integer (where N is 8, 16, 32 or 5430 64) in BV at INDEX, encoded according to ENDIANNESS. 5431 5432 Finally, a variant specialized for the host’s endianness is available 5433for each of these functions (with the exception of the ‘u8’ and ‘s8’ 5434accessors, as endianness is about byte order and there is only 1 byte): 5435 5436 -- Scheme Procedure: bytevector-u16-native-ref bv index 5437 -- Scheme Procedure: bytevector-s16-native-ref bv index 5438 -- Scheme Procedure: bytevector-u32-native-ref bv index 5439 -- Scheme Procedure: bytevector-s32-native-ref bv index 5440 -- Scheme Procedure: bytevector-u64-native-ref bv index 5441 -- Scheme Procedure: bytevector-s64-native-ref bv index 5442 -- C Function: scm_bytevector_u16_native_ref (bv, index) 5443 -- C Function: scm_bytevector_s16_native_ref (bv, index) 5444 -- C Function: scm_bytevector_u32_native_ref (bv, index) 5445 -- C Function: scm_bytevector_s32_native_ref (bv, index) 5446 -- C Function: scm_bytevector_u64_native_ref (bv, index) 5447 -- C Function: scm_bytevector_s64_native_ref (bv, index) 5448 Return the unsigned N-bit (signed) integer (where N is 8, 16, 32 or 5449 64) from BV at INDEX, decoded according to the host’s native 5450 endianness. 5451 5452 -- Scheme Procedure: bytevector-u16-native-set! bv index value 5453 -- Scheme Procedure: bytevector-s16-native-set! bv index value 5454 -- Scheme Procedure: bytevector-u32-native-set! bv index value 5455 -- Scheme Procedure: bytevector-s32-native-set! bv index value 5456 -- Scheme Procedure: bytevector-u64-native-set! bv index value 5457 -- Scheme Procedure: bytevector-s64-native-set! bv index value 5458 -- C Function: scm_bytevector_u16_native_set_x (bv, index, value) 5459 -- C Function: scm_bytevector_s16_native_set_x (bv, index, value) 5460 -- C Function: scm_bytevector_u32_native_set_x (bv, index, value) 5461 -- C Function: scm_bytevector_s32_native_set_x (bv, index, value) 5462 -- C Function: scm_bytevector_u64_native_set_x (bv, index, value) 5463 -- C Function: scm_bytevector_s64_native_set_x (bv, index, value) 5464 Store VALUE as an N-bit (signed) integer (where N is 8, 16, 32 or 5465 64) in BV at INDEX, encoded according to the host’s native 5466 endianness. 5467 5468 5469File: guile.info, Node: Bytevectors and Integer Lists, Next: Bytevectors as Floats, Prev: Bytevectors as Integers, Up: Bytevectors 5470 54716.6.12.4 Converting Bytevectors to/from Integer Lists 5472..................................................... 5473 5474Bytevector contents can readily be converted to/from lists of signed or 5475unsigned integers: 5476 5477 (bytevector->sint-list (u8-list->bytevector (make-list 4 255)) 5478 (endianness little) 2) 5479 ⇒ (-1 -1) 5480 5481 -- Scheme Procedure: bytevector->u8-list bv 5482 -- C Function: scm_bytevector_to_u8_list (bv) 5483 Return a newly allocated list of unsigned 8-bit integers from the 5484 contents of BV. 5485 5486 -- Scheme Procedure: u8-list->bytevector lst 5487 -- C Function: scm_u8_list_to_bytevector (lst) 5488 Return a newly allocated bytevector consisting of the unsigned 5489 8-bit integers listed in LST. 5490 5491 -- Scheme Procedure: bytevector->uint-list bv endianness size 5492 -- C Function: scm_bytevector_to_uint_list (bv, endianness, size) 5493 Return a list of unsigned integers of SIZE bytes representing the 5494 contents of BV, decoded according to ENDIANNESS. 5495 5496 -- Scheme Procedure: bytevector->sint-list bv endianness size 5497 -- C Function: scm_bytevector_to_sint_list (bv, endianness, size) 5498 Return a list of signed integers of SIZE bytes representing the 5499 contents of BV, decoded according to ENDIANNESS. 5500 5501 -- Scheme Procedure: uint-list->bytevector lst endianness size 5502 -- C Function: scm_uint_list_to_bytevector (lst, endianness, size) 5503 Return a new bytevector containing the unsigned integers listed in 5504 LST and encoded on SIZE bytes according to ENDIANNESS. 5505 5506 -- Scheme Procedure: sint-list->bytevector lst endianness size 5507 -- C Function: scm_sint_list_to_bytevector (lst, endianness, size) 5508 Return a new bytevector containing the signed integers listed in 5509 LST and encoded on SIZE bytes according to ENDIANNESS. 5510 5511 5512File: guile.info, Node: Bytevectors as Floats, Next: Bytevectors as Strings, Prev: Bytevectors and Integer Lists, Up: Bytevectors 5513 55146.6.12.5 Interpreting Bytevector Contents as Floating Point Numbers 5515................................................................... 5516 5517Bytevector contents can also be accessed as IEEE-754 single- or 5518double-precision floating point numbers (respectively 32 and 64-bit 5519long) using the procedures described here. 5520 5521 -- Scheme Procedure: bytevector-ieee-single-ref bv index endianness 5522 -- Scheme Procedure: bytevector-ieee-double-ref bv index endianness 5523 -- C Function: scm_bytevector_ieee_single_ref (bv, index, endianness) 5524 -- C Function: scm_bytevector_ieee_double_ref (bv, index, endianness) 5525 Return the IEEE-754 single-precision floating point number from BV 5526 at INDEX according to ENDIANNESS. 5527 5528 -- Scheme Procedure: bytevector-ieee-single-set! bv index value 5529 endianness 5530 -- Scheme Procedure: bytevector-ieee-double-set! bv index value 5531 endianness 5532 -- C Function: scm_bytevector_ieee_single_set_x (bv, index, value, 5533 endianness) 5534 -- C Function: scm_bytevector_ieee_double_set_x (bv, index, value, 5535 endianness) 5536 Store real number VALUE in BV at INDEX according to ENDIANNESS. 5537 5538 Specialized procedures are also available: 5539 5540 -- Scheme Procedure: bytevector-ieee-single-native-ref bv index 5541 -- Scheme Procedure: bytevector-ieee-double-native-ref bv index 5542 -- C Function: scm_bytevector_ieee_single_native_ref (bv, index) 5543 -- C Function: scm_bytevector_ieee_double_native_ref (bv, index) 5544 Return the IEEE-754 single-precision floating point number from BV 5545 at INDEX according to the host’s native endianness. 5546 5547 -- Scheme Procedure: bytevector-ieee-single-native-set! bv index value 5548 -- Scheme Procedure: bytevector-ieee-double-native-set! bv index value 5549 -- C Function: scm_bytevector_ieee_single_native_set_x (bv, index, 5550 value) 5551 -- C Function: scm_bytevector_ieee_double_native_set_x (bv, index, 5552 value) 5553 Store real number VALUE in BV at INDEX according to the host’s 5554 native endianness. 5555 5556 5557File: guile.info, Node: Bytevectors as Strings, Next: Bytevectors as Arrays, Prev: Bytevectors as Floats, Up: Bytevectors 5558 55596.6.12.6 Interpreting Bytevector Contents as Unicode Strings 5560............................................................ 5561 5562Bytevector contents can also be interpreted as Unicode strings encoded 5563in one of the most commonly available encoding formats. *Note 5564Representing Strings as Bytes::, for a more generic interface. 5565 5566 (utf8->string (u8-list->bytevector '(99 97 102 101))) 5567 ⇒ "cafe" 5568 5569 (string->utf8 "café") ;; SMALL LATIN LETTER E WITH ACUTE ACCENT 5570 ⇒ #vu8(99 97 102 195 169) 5571 5572 -- Scheme Procedure: string-utf8-length str 5573 -- C function: SCM scm_string_utf8_length (str) 5574 -- C function: size_t scm_c_string_utf8_length (str) 5575 Return the number of bytes in the UTF-8 representation of STR. 5576 5577 -- Scheme Procedure: string->utf8 str 5578 -- Scheme Procedure: string->utf16 str [endianness] 5579 -- Scheme Procedure: string->utf32 str [endianness] 5580 -- C Function: scm_string_to_utf8 (str) 5581 -- C Function: scm_string_to_utf16 (str, endianness) 5582 -- C Function: scm_string_to_utf32 (str, endianness) 5583 Return a newly allocated bytevector that contains the UTF-8, 5584 UTF-16, or UTF-32 (aka. UCS-4) encoding of STR. For UTF-16 and 5585 UTF-32, ENDIANNESS should be the symbol ‘big’ or ‘little’; when 5586 omitted, it defaults to big endian. 5587 5588 -- Scheme Procedure: utf8->string utf 5589 -- Scheme Procedure: utf16->string utf [endianness] 5590 -- Scheme Procedure: utf32->string utf [endianness] 5591 -- C Function: scm_utf8_to_string (utf) 5592 -- C Function: scm_utf16_to_string (utf, endianness) 5593 -- C Function: scm_utf32_to_string (utf, endianness) 5594 Return a newly allocated string that contains from the UTF-8-, 5595 UTF-16-, or UTF-32-decoded contents of bytevector UTF. For UTF-16 5596 and UTF-32, ENDIANNESS should be the symbol ‘big’ or ‘little’; when 5597 omitted, it defaults to big endian. 5598 5599 5600File: guile.info, Node: Bytevectors as Arrays, Next: Bytevectors as Uniform Vectors, Prev: Bytevectors as Strings, Up: Bytevectors 5601 56026.6.12.7 Accessing Bytevectors with the Array API 5603................................................. 5604 5605As an extension to the R6RS, Guile allows bytevectors to be manipulated 5606with the “array” procedures (*note Arrays::). When using these APIs, 5607bytes are accessed one at a time as 8-bit unsigned integers: 5608 5609 (define bv #vu8(0 1 2 3)) 5610 5611 (array? bv) 5612 ⇒ #t 5613 5614 (array-rank bv) 5615 ⇒ 1 5616 5617 (array-ref bv 2) 5618 ⇒ 2 5619 5620 ;; Note the different argument order on array-set!. 5621 (array-set! bv 77 2) 5622 (array-ref bv 2) 5623 ⇒ 77 5624 5625 (array-type bv) 5626 ⇒ vu8 5627 5628 5629File: guile.info, Node: Bytevectors as Uniform Vectors, Prev: Bytevectors as Arrays, Up: Bytevectors 5630 56316.6.12.8 Accessing Bytevectors with the SRFI-4 API 5632.................................................. 5633 5634Bytevectors may also be accessed with the SRFI-4 API. *Note SRFI-4 and 5635Bytevectors::, for more information. 5636 5637 5638File: guile.info, Node: Arrays, Next: VLists, Prev: Bytevectors, Up: Data Types 5639 56406.6.13 Arrays 5641------------- 5642 5643“Arrays” are a collection of cells organized into an arbitrary number of 5644dimensions. Each cell can be accessed in constant time by supplying an 5645index for each dimension. 5646 5647 In the current implementation, an array uses a vector of some kind 5648for the actual storage of its elements. Any kind of vector will do, so 5649you can have arrays of uniform numeric values, arrays of characters, 5650arrays of bits, and of course, arrays of arbitrary Scheme values. For 5651example, arrays with an underlying ‘c64vector’ might be nice for digital 5652signal processing, while arrays made from a ‘u8vector’ might be used to 5653hold gray-scale images. 5654 5655 The number of dimensions of an array is called its “rank”. Thus, a 5656matrix is an array of rank 2, while a vector has rank 1. When accessing 5657an array element, you have to specify one exact integer for each 5658dimension. These integers are called the “indices” of the element. An 5659array specifies the allowed range of indices for each dimension via an 5660inclusive lower and upper bound. These bounds can well be negative, but 5661the upper bound must be greater than or equal to the lower bound minus 5662one. When all lower bounds of an array are zero, it is called a 5663“zero-origin” array. 5664 5665 Arrays can be of rank 0, which could be interpreted as a scalar. 5666Thus, a zero-rank array can store exactly one object and the list of 5667indices of this element is the empty list. 5668 5669 Arrays contain zero elements when one of their dimensions has a zero 5670length. These empty arrays maintain information about their shape: a 5671matrix with zero columns and 3 rows is different from a matrix with 3 5672columns and zero rows, which again is different from a vector of length 5673zero. 5674 5675 The array procedures are all polymorphic, treating strings, uniform 5676numeric vectors, bytevectors, bit vectors and ordinary vectors as one 5677dimensional arrays. 5678 5679* Menu: 5680 5681* Array Syntax:: 5682* Array Procedures:: 5683* Shared Arrays:: 5684* Arrays as arrays of arrays:: 5685* Accessing Arrays from C:: 5686 5687 5688File: guile.info, Node: Array Syntax, Next: Array Procedures, Up: Arrays 5689 56906.6.13.1 Array Syntax 5691..................... 5692 5693An array is displayed as ‘#’ followed by its rank, followed by a tag 5694that describes the underlying vector, optionally followed by information 5695about its shape, and finally followed by the cells, organized into 5696dimensions using parentheses. 5697 5698 In more words, the array tag is of the form 5699 5700 #<rank><vectag><@lower><:len><@lower><:len>... 5701 5702 where ‘<rank>’ is a positive integer in decimal giving the rank of 5703the array. It is omitted when the rank is 1 and the array is non-shared 5704and has zero-origin (see below). For shared arrays and for a non-zero 5705origin, the rank is always printed even when it is 1 to distinguish them 5706from ordinary vectors. 5707 5708 The ‘<vectag>’ part is the tag for a uniform numeric vector, like 5709‘u8’, ‘s16’, etc, ‘b’ for bitvectors, or ‘a’ for strings. It is empty 5710for ordinary vectors. 5711 5712 The ‘<@lower>’ part is a ‘@’ character followed by a signed integer 5713in decimal giving the lower bound of a dimension. There is one 5714‘<@lower>’ for each dimension. When all lower bounds are zero, all 5715‘<@lower>’ parts are omitted. 5716 5717 The ‘<:len>’ part is a ‘:’ character followed by an unsigned integer 5718in decimal giving the length of a dimension. Like for the lower bounds, 5719there is one ‘<:len>’ for each dimension, and the ‘<:len>’ part always 5720follows the ‘<@lower>’ part for a dimension. Lengths are only then 5721printed when they can’t be deduced from the nested lists of elements of 5722the array literal, which can happen when at least one length is zero. 5723 5724 As a special case, an array of rank 0 is printed as 5725‘#0<vectag>(<scalar>)’, where ‘<scalar>’ is the result of printing the 5726single element of the array. 5727 5728 Thus, 5729 5730‘#(1 2 3)’ 5731 is an ordinary array of rank 1 with lower bound 0 in dimension 0. 5732 (I.e., a regular vector.) 5733 5734‘#@2(1 2 3)’ 5735 is an ordinary array of rank 1 with lower bound 2 in dimension 0. 5736 5737‘#2((1 2 3) (4 5 6))’ 5738 is a non-uniform array of rank 2; a 2x3 matrix with index ranges 5739 0..1 and 0..2. 5740 5741‘#u8(0 1 2)’ 5742 is a uniform u8 array of rank 1. 5743 5744‘#2u32@2@3((1 2) (2 3))’ 5745 is a uniform u32 array of rank 2 with index ranges 2..3 and 3..4. 5746 5747‘#2()’ 5748 is a two-dimensional array with index ranges 0..-1 and 0..-1, i.e. 5749 both dimensions have length zero. 5750 5751‘#2:0:2()’ 5752 is a two-dimensional array with index ranges 0..-1 and 0..1, i.e. 5753 the first dimension has length zero, but the second has length 2. 5754 5755‘#0(12)’ 5756 is a rank-zero array with contents 12. 5757 5758 In addition, bytevectors are also arrays, but use a different syntax 5759(*note Bytevectors::): 5760 5761‘#vu8(1 2 3)’ 5762 is a 3-byte long bytevector, with contents 1, 2, 3. 5763 5764 5765File: guile.info, Node: Array Procedures, Next: Shared Arrays, Prev: Array Syntax, Up: Arrays 5766 57676.6.13.2 Array Procedures 5768......................... 5769 5770When an array is created, the range of each dimension must be specified, 5771e.g., to create a 2x3 array with a zero-based index: 5772 5773 (make-array 'ho 2 3) ⇒ #2((ho ho ho) (ho ho ho)) 5774 5775 The range of each dimension can also be given explicitly, e.g., 5776another way to create the same array: 5777 5778 (make-array 'ho '(0 1) '(0 2)) ⇒ #2((ho ho ho) (ho ho ho)) 5779 5780 The following procedures can be used with arrays (or vectors). An 5781argument shown as IDX... means one parameter for each dimension in the 5782array. A IDXLIST argument means a list of such values, one for each 5783dimension. 5784 5785 -- Scheme Procedure: array? obj 5786 -- C Function: scm_array_p (obj, unused) 5787 Return ‘#t’ if the OBJ is an array, and ‘#f’ if not. 5788 5789 The second argument to scm_array_p is there for historical reasons, 5790 but it is not used. You should always pass ‘SCM_UNDEFINED’ as its 5791 value. 5792 5793 -- Scheme Procedure: typed-array? obj type 5794 -- C Function: scm_typed_array_p (obj, type) 5795 Return ‘#t’ if the OBJ is an array of type TYPE, and ‘#f’ if not. 5796 5797 -- C Function: int scm_is_array (SCM obj) 5798 Return ‘1’ if the OBJ is an array and ‘0’ if not. 5799 5800 -- C Function: int scm_is_typed_array (SCM obj, SCM type) 5801 Return ‘0’ if the OBJ is an array of type TYPE, and ‘1’ if not. 5802 5803 -- Scheme Procedure: make-array fill bound ... 5804 -- C Function: scm_make_array (fill, bounds) 5805 Equivalent to ‘(make-typed-array #t FILL BOUND ...)’. 5806 5807 -- Scheme Procedure: make-typed-array type fill bound ... 5808 -- C Function: scm_make_typed_array (type, fill, bounds) 5809 Create and return an array that has as many dimensions as there are 5810 BOUNDs and (maybe) fill it with FILL. 5811 5812 The underlying storage vector is created according to TYPE, which 5813 must be a symbol whose name is the ‘vectag’ of the array as 5814 explained above, or ‘#t’ for ordinary, non-specialized arrays. 5815 5816 For example, using the symbol ‘f64’ for TYPE will create an array 5817 that uses a ‘f64vector’ for storing its elements, and ‘a’ will use 5818 a string. 5819 5820 When FILL is not the special _unspecified_ value, the new array is 5821 filled with FILL. Otherwise, the initial contents of the array is 5822 unspecified. The special _unspecified_ value is stored in the 5823 variable ‘*unspecified*’ so that for example ‘(make-typed-array 5824 'u32 *unspecified* 4)’ creates a uninitialized ‘u32’ vector of 5825 length 4. 5826 5827 Each BOUND may be a positive non-zero integer N, in which case the 5828 index for that dimension can range from 0 through N-1; or an 5829 explicit index range specifier in the form ‘(LOWER UPPER)’, where 5830 both LOWER and UPPER are integers, possibly less than zero, and 5831 possibly the same number (however, LOWER cannot be greater than 5832 UPPER). 5833 5834 -- Scheme Procedure: list->array dimspec list 5835 Equivalent to ‘(list->typed-array #t DIMSPEC LIST)’. 5836 5837 -- Scheme Procedure: list->typed-array type dimspec list 5838 -- C Function: scm_list_to_typed_array (type, dimspec, list) 5839 Return an array of the type indicated by TYPE with elements the 5840 same as those of LIST. 5841 5842 The argument DIMSPEC determines the number of dimensions of the 5843 array and their lower bounds. When DIMSPEC is an exact integer, it 5844 gives the number of dimensions directly and all lower bounds are 5845 zero. When it is a list of exact integers, then each element is 5846 the lower index bound of a dimension, and there will be as many 5847 dimensions as elements in the list. 5848 5849 -- Scheme Procedure: array-type array 5850 -- C Function: scm_array_type (array) 5851 Return the type of ARRAY. This is the ‘vectag’ used for printing 5852 ARRAY (or ‘#t’ for ordinary arrays) and can be used with 5853 ‘make-typed-array’ to create an array of the same kind as ARRAY. 5854 5855 -- Scheme Procedure: array-ref array idx ... 5856 -- C Function: scm_array_ref (array, idxlist) 5857 Return the element at ‘(idx ...)’ in ARRAY. 5858 5859 (define a (make-array 999 '(1 2) '(3 4))) 5860 (array-ref a 2 4) ⇒ 999 5861 5862 -- Scheme Procedure: array-in-bounds? array idx ... 5863 -- C Function: scm_array_in_bounds_p (array, idxlist) 5864 Return ‘#t’ if the given indices would be acceptable to 5865 ‘array-ref’. 5866 5867 (define a (make-array #f '(1 2) '(3 4))) 5868 (array-in-bounds? a 2 3) ⇒ #t 5869 (array-in-bounds? a 0 0) ⇒ #f 5870 5871 -- Scheme Procedure: array-set! array obj idx ... 5872 -- C Function: scm_array_set_x (array, obj, idxlist) 5873 Set the element at ‘(idx ...)’ in ARRAY to OBJ. The return value 5874 is unspecified. 5875 5876 (define a (make-array #f '(0 1) '(0 1))) 5877 (array-set! a #t 1 1) 5878 a ⇒ #2((#f #f) (#f #t)) 5879 5880 -- Scheme Procedure: array-shape array 5881 -- Scheme Procedure: array-dimensions array 5882 -- C Function: scm_array_dimensions (array) 5883 Return a list of the bounds for each dimension of ARRAY. 5884 5885 ‘array-shape’ gives ‘(LOWER UPPER)’ for each dimension. 5886 ‘array-dimensions’ instead returns just UPPER+1 for dimensions with 5887 a 0 lower bound. Both are suitable as input to ‘make-array’. 5888 5889 For example, 5890 5891 (define a (make-array 'foo '(-1 3) 5)) 5892 (array-shape a) ⇒ ((-1 3) (0 4)) 5893 (array-dimensions a) ⇒ ((-1 3) 5) 5894 5895 -- Scheme Procedure: array-length array 5896 -- C Function: scm_array_length (array) 5897 -- C Function: size_t scm_c_array_length (array) 5898 Return the length of an array: its first dimension. It is an error 5899 to ask for the length of an array of rank 0. 5900 5901 -- Scheme Procedure: array-rank array 5902 -- C Function: scm_array_rank (array) 5903 Return the rank of ARRAY. 5904 5905 -- C Function: size_t scm_c_array_rank (SCM array) 5906 Return the rank of ARRAY as a ‘size_t’. 5907 5908 -- Scheme Procedure: array->list array 5909 -- C Function: scm_array_to_list (array) 5910 Return a list consisting of all the elements, in order, of ARRAY. 5911 5912 -- Scheme Procedure: array-copy! src dst 5913 -- Scheme Procedure: array-copy-in-order! src dst 5914 -- C Function: scm_array_copy_x (src, dst) 5915 Copy every element from vector or array SRC to the corresponding 5916 element of DST. DST must have the same rank as SRC, and be at 5917 least as large in each dimension. The return value is unspecified. 5918 5919 -- Scheme Procedure: array-fill! array fill 5920 -- C Function: scm_array_fill_x (array, fill) 5921 Store FILL in every element of ARRAY. The value returned is 5922 unspecified. 5923 5924 -- Scheme Procedure: array-equal? array ... 5925 Return ‘#t’ if all arguments are arrays with the same shape, the 5926 same type, and have corresponding elements which are either 5927 ‘equal?’ or ‘array-equal?’. This function differs from ‘equal?’ 5928 (*note Equality::) in that all arguments must be arrays. 5929 5930 -- Scheme Procedure: array-map! dst proc src ... 5931 -- Scheme Procedure: array-map-in-order! dst proc src ... 5932 -- C Function: scm_array_map_x (dst, proc, srclist) 5933 Set each element of the DST array to values obtained from calls to 5934 PROC. The list of SRC arguments may be empty. The value returned 5935 is unspecified. 5936 5937 Each call is ‘(PROC ELEM ...)’, where each ELEM is from the 5938 corresponding SRC array, at the DST index. ‘array-map-in-order!’ 5939 makes the calls in row-major order, ‘array-map!’ makes them in an 5940 unspecified order. 5941 5942 The SRC arrays must have the same number of dimensions as DST, and 5943 must have a range for each dimension which covers the range in DST. 5944 This ensures all DST indices are valid in each SRC. 5945 5946 -- Scheme Procedure: array-for-each proc src1 src2 ... 5947 -- C Function: scm_array_for_each (proc, src1, srclist) 5948 Apply PROC to each tuple of elements of SRC1 SRC2 ..., in row-major 5949 order. The value returned is unspecified. 5950 5951 -- Scheme Procedure: array-index-map! dst proc 5952 -- C Function: scm_array_index_map_x (dst, proc) 5953 Set each element of the DST array to values returned by calls to 5954 PROC. The value returned is unspecified. 5955 5956 Each call is ‘(PROC I1 ... IN)’, where I1...IN is the destination 5957 index, one parameter for each dimension. The order in which the 5958 calls are made is unspecified. 5959 5960 For example, to create a 4x4 matrix representing a cyclic group, 5961 5962 / 0 1 2 3 \ 5963 | 1 2 3 0 | 5964 | 2 3 0 1 | 5965 \ 3 0 1 2 / 5966 5967 (define a (make-array #f 4 4)) 5968 (array-index-map! a (lambda (i j) 5969 (modulo (+ i j) 4))) 5970 5971 An additional array function is available in the module ‘(ice-9 5972arrays)’. It can be used with: 5973 5974 (use-modules (ice-9 arrays)) 5975 5976 -- Scheme Procedure: array-copy src 5977 Return a new array with the same elements, type and shape as SRC. 5978 However, the array increments may not be the same as those of SRC. 5979 In the current implementation, the returned array will be in 5980 row-major order, but that might change in the future. Use 5981 ‘array-copy!’ on an array of known order if that is a concern. 5982 5983 5984File: guile.info, Node: Shared Arrays, Next: Arrays as arrays of arrays, Prev: Array Procedures, Up: Arrays 5985 59866.6.13.3 Shared Arrays 5987...................... 5988 5989 -- Scheme Procedure: make-shared-array oldarray mapfunc bound ... 5990 -- C Function: scm_make_shared_array (oldarray, mapfunc, boundlist) 5991 Return a new array which shares the storage of OLDARRAY. Changes 5992 made through either affect the same underlying storage. The BOUND 5993 ... arguments are the shape of the new array, the same as 5994 ‘make-array’ (*note Array Procedures::). 5995 5996 MAPFUNC translates coordinates from the new array to the OLDARRAY. 5997 It’s called as ‘(MAPFUNC newidx1 ...)’ with one parameter for each 5998 dimension of the new array, and should return a list of indices for 5999 OLDARRAY, one for each dimension of OLDARRAY. 6000 6001 MAPFUNC must be affine linear, meaning that each OLDARRAY index 6002 must be formed by adding integer multiples (possibly negative) of 6003 some or all of NEWIDX1 etc, plus a possible integer offset. The 6004 multiples and offset must be the same in each call. 6005 6006 6007 One good use for a shared array is to restrict the range of some 6008 dimensions, so as to apply say ‘array-for-each’ or ‘array-fill!’ to 6009 only part of an array. The plain ‘list’ function can be used for 6010 MAPFUNC in this case, making no changes to the index values. For 6011 example, 6012 6013 (make-shared-array #2((a b c) (d e f) (g h i)) list 3 2) 6014 ⇒ #2((a b) (d e) (g h)) 6015 6016 The new array can have fewer dimensions than OLDARRAY, for example 6017 to take a column from an array. 6018 6019 (make-shared-array #2((a b c) (d e f) (g h i)) 6020 (lambda (i) (list i 2)) 6021 '(0 2)) 6022 ⇒ #1(c f i) 6023 6024 A diagonal can be taken by using the single new array index for 6025 both row and column in the old array. For example, 6026 6027 (make-shared-array #2((a b c) (d e f) (g h i)) 6028 (lambda (i) (list i i)) 6029 '(0 2)) 6030 ⇒ #1(a e i) 6031 6032 Dimensions can be increased by for instance considering portions of 6033 a one dimensional array as rows in a two dimensional array. 6034 (‘array-contents’ below can do the opposite, flattening an array.) 6035 6036 (make-shared-array #1(a b c d e f g h i j k l) 6037 (lambda (i j) (list (+ (* i 3) j))) 6038 4 3) 6039 ⇒ #2((a b c) (d e f) (g h i) (j k l)) 6040 6041 By negating an index the order that elements appear can be 6042 reversed. The following just reverses the column order, 6043 6044 (make-shared-array #2((a b c) (d e f) (g h i)) 6045 (lambda (i j) (list i (- 2 j))) 6046 3 3) 6047 ⇒ #2((c b a) (f e d) (i h g)) 6048 6049 A fixed offset on indexes allows for instance a change from a 0 6050 based to a 1 based array, 6051 6052 (define x #2((a b c) (d e f) (g h i))) 6053 (define y (make-shared-array x 6054 (lambda (i j) (list (1- i) (1- j))) 6055 '(1 3) '(1 3))) 6056 (array-ref x 0 0) ⇒ a 6057 (array-ref y 1 1) ⇒ a 6058 6059 A multiple on an index allows every Nth element of an array to be 6060 taken. The following is every third element, 6061 6062 (make-shared-array #1(a b c d e f g h i j k l) 6063 (lambda (i) (list (* i 3))) 6064 4) 6065 ⇒ #1(a d g j) 6066 6067 The above examples can be combined to make weird and wonderful 6068 selections from an array, but it’s important to note that because 6069 MAPFUNC must be affine linear, arbitrary permutations are not 6070 possible. 6071 6072 In the current implementation, MAPFUNC is not called for every 6073 access to the new array but only on some sample points to establish 6074 a base and stride for new array indices in OLDARRAY data. A few 6075 sample points are enough because MAPFUNC is linear. 6076 6077 -- Scheme Procedure: shared-array-increments array 6078 -- C Function: scm_shared_array_increments (array) 6079 For each dimension, return the distance between elements in the 6080 root vector. 6081 6082 -- Scheme Procedure: shared-array-offset array 6083 -- C Function: scm_shared_array_offset (array) 6084 Return the root vector index of the first element in the array. 6085 6086 -- Scheme Procedure: shared-array-root array 6087 -- C Function: scm_shared_array_root (array) 6088 Return the root vector of a shared array. 6089 6090 -- Scheme Procedure: array-contents array [strict] 6091 -- C Function: scm_array_contents (array, strict) 6092 If ARRAY may be “unrolled” into a one dimensional shared array 6093 without changing their order (last subscript changing fastest), 6094 then ‘array-contents’ returns that shared array, otherwise it 6095 returns ‘#f’. All arrays made by ‘make-array’ and 6096 ‘make-typed-array’ may be unrolled, some arrays made by 6097 ‘make-shared-array’ may not be. 6098 6099 If the optional argument STRICT is provided, a shared array will be 6100 returned only if its elements are stored internally contiguous in 6101 memory. 6102 6103 -- Scheme Procedure: transpose-array array dim1 dim2 ... 6104 -- C Function: scm_transpose_array (array, dimlist) 6105 Return an array sharing contents with ARRAY, but with dimensions 6106 arranged in a different order. There must be one DIM argument for 6107 each dimension of ARRAY. DIM1, DIM2, ... should be integers 6108 between 0 and the rank of the array to be returned. Each integer 6109 in that range must appear at least once in the argument list. 6110 6111 The values of DIM1, DIM2, ... correspond to dimensions in the array 6112 to be returned, and their positions in the argument list to 6113 dimensions of ARRAY. Several DIMs may have the same value, in 6114 which case the returned array will have smaller rank than ARRAY. 6115 6116 (transpose-array '#2((a b) (c d)) 1 0) ⇒ #2((a c) (b d)) 6117 (transpose-array '#2((a b) (c d)) 0 0) ⇒ #1(a d) 6118 (transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) ⇒ 6119 #2((a 4) (b 5) (c 6)) 6120 6121 6122File: guile.info, Node: Arrays as arrays of arrays, Next: Accessing Arrays from C, Prev: Shared Arrays, Up: Arrays 6123 61246.6.13.4 Arrays as arrays of arrays 6125................................... 6126 6127Mathematically, one can see an array of rank n (an n-array) as an array 6128of lower rank where the elements are themselves arrays (‘cells’). 6129 6130 We speak of the first n-k dimensions of the array as the n-k-‘frame’ 6131of the array, while the last k dimensions are the dimensions of the 6132k-‘cells’. For example, a 3-array can be seen as a 2-array of vectors 6133(1-arrays) or as a 1-array of matrices (2-arrays). In each case, the 6134vectors or matrices are the 1-cells or 2-cells of the array. This 6135terminology originates in the J language. 6136 6137 The more vague concept of a ‘slice’ refers to a subset of the array 6138where some indices are fixed and others are left free. As a Guile data 6139object, a cell is the same as a ‘prefix slice’ (the first n-k indices 6140into the original array are fixed), except that a 0-cell is not a shared 6141array of the original array, but a 0-slice (where all the indices into 6142the original array are fixed) is. 6143 6144 Before version 2.0, Guile had a feature called ‘enclosed arrays’ to 6145create special ‘array of arrays’ objects. The functions in this section 6146do not need special types; instead, the frame rank is stated in each 6147function call, either implicitly or explicitly. 6148 6149 -- Scheme Procedure: array-cell-ref array idx ... 6150 -- C Function: scm_array_cell_ref (array, idxlist) 6151 If the length of IDXLIST equals the rank n of ARRAY, return the 6152 element at ‘(idx ...)’, just like ‘(array-ref array idx ...)’. If, 6153 however, the length k of IDXLIST is smaller than n, then return the 6154 (n-k)-cell of ARRAY given by IDXLIST, as a shared array. 6155 6156 For example: 6157 6158 (array-cell-ref #2((a b) (c d)) 0) ⇒ #(a b) 6159 (array-cell-ref #2((a b) (c d)) 1) ⇒ #(c d) 6160 (array-cell-ref #2((a b) (c d)) 1 1) ⇒ d 6161 (array-cell-ref #2((a b) (c d))) ⇒ #2((a b) (c d)) 6162 6163 ‘(apply array-cell-ref array indices)’ is equivalent to 6164 6165 (let ((len (length indices))) 6166 (if (= (array-rank a) len) 6167 (apply array-ref a indices) 6168 (apply make-shared-array a 6169 (lambda t (append indices t)) 6170 (drop (array-dimensions a) len)))) 6171 6172 -- Scheme Procedure: array-slice array idx ... 6173 -- C Function: scm_array_slice (array, idxlist) 6174 Like ‘(array-cell-ref array idx ...)’, but return a 0-rank shared 6175 array into ARRAY if the length of IDXLIST matches the rank of 6176 ARRAY. This can be useful when using ARRAY as a place to write to. 6177 6178 Compare: 6179 6180 (array-cell-ref #2((a b) (c d)) 1 1) ⇒ d 6181 (array-slice #2((a b) (c d)) 1 1) ⇒ #0(d) 6182 (define a (make-array 'a 2 2)) 6183 (array-fill! (array-slice a 1 1) 'b) 6184 a ⇒ #2((a a) (a b)). 6185 (array-fill! (array-cell-ref a 1 1) 'b) ⇒ error: not an array 6186 6187 ‘(apply array-slice array indices)’ is equivalent to 6188 6189 (apply make-shared-array a 6190 (lambda t (append indices t)) 6191 (drop (array-dimensions a) (length indices))) 6192 6193 -- Scheme Procedure: array-cell-set! array x idx ... 6194 -- C Function: scm_array_cell_set_x (array, x, idxlist) 6195 If the length of IDXLIST equals the rank n of ARRAY, set the 6196 element at ‘(idx ...)’ of ARRAY to X, just like ‘(array-set! array 6197 x idx ...)’. If, however, the length k of IDXLIST is smaller than 6198 n, then copy the (n-k)-rank array X into the (n-k)-cell of ARRAY 6199 given by IDXLIST. In this case, the last (n-k) dimensions of ARRAY 6200 and the dimensions of X must match exactly. 6201 6202 This function returns the modified ARRAY. 6203 6204 For example: 6205 6206 (array-cell-set! (make-array 'a 2 2) b 1 1) 6207 ⇒ #2((a a) (a b)) 6208 (array-cell-set! (make-array 'a 2 2) #(x y) 1) 6209 ⇒ #2((a a) (x y)) 6210 6211 Note that ‘array-cell-set!’ will expect elements, not arrays, when 6212 the destination has rank 0. Use ‘array-slice’ for the opposite 6213 behavior. 6214 6215 (array-cell-set! (make-array 'a 2 2) #0(b) 1 1) 6216 ⇒ #2((a a) (a #0(b))) 6217 (let ((a (make-array 'a 2 2))) 6218 (array-copy! #0(b) (array-slice a 1 1)) a) 6219 ⇒ #2((a a) (a b)) 6220 6221 ‘(apply array-cell-set! array x indices)’ is equivalent to 6222 6223 (let ((len (length indices))) 6224 (if (= (array-rank array) len) 6225 (apply array-set! array x indices) 6226 (array-copy! x (apply array-cell-ref array indices))) 6227 array) 6228 6229 -- Scheme Procedure: array-slice-for-each frame-rank op x ... 6230 -- C Function: scm_array_slice_for_each (array, frame_rank, op, xlist) 6231 Each X must be an array of rank ≥ FRAME-RANK, and the first 6232 FRAME-RANK dimensions of each X must all be the same. 6233 ARRAY-SLICE-FOR-EACH calls OP with each set of (rank(X) - 6234 FRAME-RANK)-cells from X, in unspecified order. 6235 6236 ARRAY-SLICE-FOR-EACH allows you to loop over cells of any rank 6237 without having to carry an index list or construct shared arrays 6238 manually. The slices passed to OP are always shared arrays of X, 6239 even if they are of rank 0, so it is possible to write to them. 6240 6241 This function returns an unspecified value. 6242 6243 For example, to sort the rows of rank-2 array ‘a’: 6244 6245 (array-slice-for-each 1 (lambda (x) (sort! x <)) a) 6246 6247 As another example, let ‘a’ be a rank-2 array where each row is a 6248 2-element vector (x,y). Let’s compute the arguments of these 6249 vectors and store them in rank-1 array ‘b’. 6250 (array-slice-for-each 1 6251 (lambda (a b) 6252 (array-set! b (atan (array-ref a 1) (array-ref a 0)))) 6253 a b) 6254 6255 ‘(apply array-slice-for-each frame-rank op x)’ is equivalent to 6256 6257 (let ((frame (take (array-dimensions (car x)) frank))) 6258 (unless (every (lambda (x) 6259 (equal? frame (take (array-dimensions x) frank))) 6260 (cdr x)) 6261 (error)) 6262 (array-index-map! 6263 (apply make-shared-array (make-array #t) (const '()) frame) 6264 (lambda i (apply op (map (lambda (x) (apply array-slice x i)) x))))) 6265 6266 -- Scheme Procedure: array-slice-for-each-in-order frame-rank op x ... 6267 -- C Function: scm_array_slice_for_each_in_order (array, frame_rank, 6268 op, xlist) 6269 Same as ‘array-slice-for-each’, but the arguments are traversed 6270 sequentially and in row-major order. 6271 6272 6273File: guile.info, Node: Accessing Arrays from C, Prev: Arrays as arrays of arrays, Up: Arrays 6274 62756.6.13.5 Accessing Arrays from C 6276................................ 6277 6278For interworking with external C code, Guile provides an API to allow C 6279code to access the elements of a Scheme array. In particular, for 6280uniform numeric arrays, the API exposes the underlying uniform data as a 6281C array of numbers of the relevant type. 6282 6283 While pointers to the elements of an array are in use, the array 6284itself must be protected so that the pointer remains valid. Such a 6285protected array is said to be “reserved”. A reserved array can be read 6286but modifications to it that would cause the pointer to its elements to 6287become invalid are prevented. When you attempt such a modification, an 6288error is signalled. 6289 6290 (This is similar to locking the array while it is in use, but without 6291the danger of a deadlock. In a multi-threaded program, you will need 6292additional synchronization to avoid modifying reserved arrays.) 6293 6294 You must take care to always unreserve an array after reserving it, 6295even in the presence of non-local exits. If a non-local exit can happen 6296between these two calls, you should install a dynwind context that 6297releases the array when it is left (*note Dynamic Wind::). 6298 6299 In addition, array reserving and unreserving must be properly paired. 6300For instance, when reserving two or more arrays in a certain order, you 6301need to unreserve them in the opposite order. 6302 6303 Once you have reserved an array and have retrieved the pointer to its 6304elements, you must figure out the layout of the elements in memory. 6305Guile allows slices to be taken out of arrays without actually making a 6306copy, such as making an alias for the diagonal of a matrix that can be 6307treated as a vector. Arrays that result from such an operation are not 6308stored contiguously in memory and when working with their elements 6309directly, you need to take this into account. 6310 6311 The layout of array elements in memory can be defined via a _mapping 6312function_ that computes a scalar position from a vector of indices. The 6313scalar position then is the offset of the element with the given indices 6314from the start of the storage block of the array. 6315 6316 In Guile, this mapping function is restricted to be “affine”: all 6317mapping functions of Guile arrays can be written as ‘p = b + c[0]*i[0] + 6318c[1]*i[1] + ... + c[n-1]*i[n-1]’ where ‘i[k]’ is the kth index and ‘n’ 6319is the rank of the array. For example, a matrix of size 3x3 would have 6320‘b == 0’, ‘c[0] == 3’ and ‘c[1] == 1’. When you transpose this matrix 6321(with ‘transpose-array’, say), you will get an array whose mapping 6322function has ‘b == 0’, ‘c[0] == 1’ and ‘c[1] == 3’. 6323 6324 The function ‘scm_array_handle_dims’ gives you (indirect) access to 6325the coefficients ‘c[k]’. 6326 6327 Note that there are no functions for accessing the elements of a 6328character array yet. Once the string implementation of Guile has been 6329changed to use Unicode, we will provide them. 6330 6331 -- C Type: scm_t_array_handle 6332 This is a structure type that holds all information necessary to 6333 manage the reservation of arrays as explained above. Structures of 6334 this type must be allocated on the stack and must only be accessed 6335 by the functions listed below. 6336 6337 -- C Function: void scm_array_get_handle (SCM array, scm_t_array_handle 6338 *handle) 6339 Reserve ARRAY, which must be an array, and prepare HANDLE to be 6340 used with the functions below. You must eventually call 6341 ‘scm_array_handle_release’ on HANDLE, and do this in a properly 6342 nested fashion, as explained above. The structure pointed to by 6343 HANDLE does not need to be initialized before calling this 6344 function. 6345 6346 -- C Function: void scm_array_handle_release (scm_t_array_handle 6347 *handle) 6348 End the array reservation represented by HANDLE. After a call to 6349 this function, HANDLE might be used for another reservation. 6350 6351 -- C Function: size_t scm_array_handle_rank (scm_t_array_handle 6352 *handle) 6353 Return the rank of the array represented by HANDLE. 6354 6355 -- C Type: scm_t_array_dim 6356 This structure type holds information about the layout of one 6357 dimension of an array. It includes the following fields: 6358 6359 ‘ssize_t lbnd’ 6360 ‘ssize_t ubnd’ 6361 The lower and upper bounds (both inclusive) of the permissible 6362 index range for the given dimension. Both values can be 6363 negative, but LBND is always less than or equal to UBND. 6364 6365 ‘ssize_t inc’ 6366 The distance from one element of this dimension to the next. 6367 Note, too, that this can be negative. 6368 6369 -- C Function: const scm_t_array_dim * scm_array_handle_dims 6370 (scm_t_array_handle *handle) 6371 Return a pointer to a C vector of information about the dimensions 6372 of the array represented by HANDLE. This pointer is valid as long 6373 as the array remains reserved. As explained above, the 6374 ‘scm_t_array_dim’ structures returned by this function can be used 6375 calculate the position of an element in the storage block of the 6376 array from its indices. 6377 6378 This position can then be used as an index into the C array pointer 6379 returned by the various ‘scm_array_handle_<foo>_elements’ 6380 functions, or with ‘scm_array_handle_ref’ and 6381 ‘scm_array_handle_set’. 6382 6383 Here is how one can compute the position POS of an element given 6384 its indices in the vector INDICES: 6385 6386 ssize_t indices[RANK]; 6387 scm_t_array_dim *dims; 6388 ssize_t pos; 6389 size_t i; 6390 6391 pos = 0; 6392 for (i = 0; i < RANK; i++) 6393 { 6394 if (indices[i] < dims[i].lbnd || indices[i] > dims[i].ubnd) 6395 out_of_range (); 6396 pos += (indices[i] - dims[i].lbnd) * dims[i].inc; 6397 } 6398 6399 -- C Function: ssize_t scm_array_handle_pos (scm_t_array_handle 6400 *handle, SCM indices) 6401 Compute the position corresponding to INDICES, a list of indices. 6402 The position is computed as described above for 6403 ‘scm_array_handle_dims’. The number of the indices and their range 6404 is checked and an appropriate error is signalled for invalid 6405 indices. 6406 6407 -- C Function: SCM scm_array_handle_ref (scm_t_array_handle *handle, 6408 ssize_t pos) 6409 Return the element at position POS in the storage block of the 6410 array represented by HANDLE. Any kind of array is acceptable. No 6411 range checking is done on POS. 6412 6413 -- C Function: void scm_array_handle_set (scm_t_array_handle *handle, 6414 ssize_t pos, SCM val) 6415 Set the element at position POS in the storage block of the array 6416 represented by HANDLE to VAL. Any kind of array is acceptable. No 6417 range checking is done on POS. An error is signalled when the 6418 array can not store VAL. 6419 6420 -- C Function: const SCM * scm_array_handle_elements 6421 (scm_t_array_handle *handle) 6422 Return a pointer to the elements of a ordinary array of general 6423 Scheme values (i.e., a non-uniform array) for reading. This 6424 pointer is valid as long as the array remains reserved. 6425 6426 -- C Function: SCM * scm_array_handle_writable_elements 6427 (scm_t_array_handle *handle) 6428 Like ‘scm_array_handle_elements’, but the pointer is good for 6429 reading and writing. 6430 6431 -- C Function: const void * scm_array_handle_uniform_elements 6432 (scm_t_array_handle *handle) 6433 Return a pointer to the elements of a uniform numeric array for 6434 reading. This pointer is valid as long as the array remains 6435 reserved. The size of each element is given by 6436 ‘scm_array_handle_uniform_element_size’. 6437 6438 -- C Function: void * scm_array_handle_uniform_writable_elements 6439 (scm_t_array_handle *handle) 6440 Like ‘scm_array_handle_uniform_elements’, but the pointer is good 6441 reading and writing. 6442 6443 -- C Function: size_t scm_array_handle_uniform_element_size 6444 (scm_t_array_handle *handle) 6445 Return the size of one element of the uniform numeric array 6446 represented by HANDLE. 6447 6448 -- C Function: const scm_t_uint8 * scm_array_handle_u8_elements 6449 (scm_t_array_handle *handle) 6450 -- C Function: const scm_t_int8 * scm_array_handle_s8_elements 6451 (scm_t_array_handle *handle) 6452 -- C Function: const scm_t_uint16 * scm_array_handle_u16_elements 6453 (scm_t_array_handle *handle) 6454 -- C Function: const scm_t_int16 * scm_array_handle_s16_elements 6455 (scm_t_array_handle *handle) 6456 -- C Function: const scm_t_uint32 * scm_array_handle_u32_elements 6457 (scm_t_array_handle *handle) 6458 -- C Function: const scm_t_int32 * scm_array_handle_s32_elements 6459 (scm_t_array_handle *handle) 6460 -- C Function: const scm_t_uint64 * scm_array_handle_u64_elements 6461 (scm_t_array_handle *handle) 6462 -- C Function: const scm_t_int64 * scm_array_handle_s64_elements 6463 (scm_t_array_handle *handle) 6464 -- C Function: const float * scm_array_handle_f32_elements 6465 (scm_t_array_handle *handle) 6466 -- C Function: const double * scm_array_handle_f64_elements 6467 (scm_t_array_handle *handle) 6468 -- C Function: const float * scm_array_handle_c32_elements 6469 (scm_t_array_handle *handle) 6470 -- C Function: const double * scm_array_handle_c64_elements 6471 (scm_t_array_handle *handle) 6472 Return a pointer to the elements of a uniform numeric array of the 6473 indicated kind for reading. This pointer is valid as long as the 6474 array remains reserved. 6475 6476 The pointers for ‘c32’ and ‘c64’ uniform numeric arrays point to 6477 pairs of floating point numbers. The even index holds the real 6478 part, the odd index the imaginary part of the complex number. 6479 6480 -- C Function: scm_t_uint8 * scm_array_handle_u8_writable_elements 6481 (scm_t_array_handle *handle) 6482 -- C Function: scm_t_int8 * scm_array_handle_s8_writable_elements 6483 (scm_t_array_handle *handle) 6484 -- C Function: scm_t_uint16 * scm_array_handle_u16_writable_elements 6485 (scm_t_array_handle *handle) 6486 -- C Function: scm_t_int16 * scm_array_handle_s16_writable_elements 6487 (scm_t_array_handle *handle) 6488 -- C Function: scm_t_uint32 * scm_array_handle_u32_writable_elements 6489 (scm_t_array_handle *handle) 6490 -- C Function: scm_t_int32 * scm_array_handle_s32_writable_elements 6491 (scm_t_array_handle *handle) 6492 -- C Function: scm_t_uint64 * scm_array_handle_u64_writable_elements 6493 (scm_t_array_handle *handle) 6494 -- C Function: scm_t_int64 * scm_array_handle_s64_writable_elements 6495 (scm_t_array_handle *handle) 6496 -- C Function: float * scm_array_handle_f32_writable_elements 6497 (scm_t_array_handle *handle) 6498 -- C Function: double * scm_array_handle_f64_writable_elements 6499 (scm_t_array_handle *handle) 6500 -- C Function: float * scm_array_handle_c32_writable_elements 6501 (scm_t_array_handle *handle) 6502 -- C Function: double * scm_array_handle_c64_writable_elements 6503 (scm_t_array_handle *handle) 6504 Like ‘scm_array_handle_<kind>_elements’, but the pointer is good 6505 for reading and writing. 6506 6507 -- C Function: const scm_t_uint32 * scm_array_handle_bit_elements 6508 (scm_t_array_handle *handle) 6509 Return a pointer to the words that store the bits of the 6510 represented array, which must be a bit array. 6511 6512 Unlike other arrays, bit arrays have an additional offset that must 6513 be figured into index calculations. That offset is returned by 6514 ‘scm_array_handle_bit_elements_offset’. 6515 6516 To find a certain bit you first need to calculate its position as 6517 explained above for ‘scm_array_handle_dims’ and then add the 6518 offset. This gives the absolute position of the bit, which is 6519 always a non-negative integer. 6520 6521 Each word of the bit array storage block contains exactly 32 bits, 6522 with the least significant bit in that word having the lowest 6523 absolute position number. The next word contains the next 32 bits. 6524 6525 Thus, the following code can be used to access a bit whose position 6526 according to ‘scm_array_handle_dims’ is given in POS: 6527 6528 SCM bit_array; 6529 scm_t_array_handle handle; 6530 scm_t_uint32 *bits; 6531 ssize_t pos; 6532 size_t abs_pos; 6533 size_t word_pos, mask; 6534 6535 scm_array_get_handle (&bit_array, &handle); 6536 bits = scm_array_handle_bit_elements (&handle); 6537 6538 pos = ... 6539 abs_pos = pos + scm_array_handle_bit_elements_offset (&handle); 6540 word_pos = abs_pos / 32; 6541 mask = 1L << (abs_pos % 32); 6542 6543 if (bits[word_pos] & mask) 6544 /* bit is set. */ 6545 6546 scm_array_handle_release (&handle); 6547 6548 -- C Function: scm_t_uint32 * scm_array_handle_bit_writable_elements 6549 (scm_t_array_handle *handle) 6550 Like ‘scm_array_handle_bit_elements’ but the pointer is good for 6551 reading and writing. You must take care not to modify bits outside 6552 of the allowed index range of the array, even for contiguous 6553 arrays. 6554 6555 6556File: guile.info, Node: VLists, Next: Record Overview, Prev: Arrays, Up: Data Types 6557 65586.6.14 VLists 6559------------- 6560 6561The ‘(ice-9 vlist)’ module provides an implementation of the “VList” 6562data structure designed by Phil Bagwell in 2002. VLists are immutable 6563lists, which can contain any Scheme object. They improve on standard 6564Scheme linked lists in several areas: 6565 6566 • Random access has typically constant-time complexity. 6567 6568 • Computing the length of a VList has time complexity logarithmic in 6569 the number of elements. 6570 6571 • VLists use less storage space than standard lists. 6572 6573 • VList elements are stored in contiguous regions, which improves 6574 memory locality and leads to more efficient use of hardware caches. 6575 6576 The idea behind VLists is to store vlist elements in increasingly 6577large contiguous blocks (implemented as vectors here). These blocks are 6578linked to one another using a pointer to the next block and an offset 6579within that block. The size of these blocks form a geometric series 6580with ratio ‘block-growth-factor’ (2 by default). 6581 6582 The VList structure also serves as the basis for the “VList-based 6583hash lists” or “vhashes”, an immutable dictionary type (*note 6584VHashes::). 6585 6586 However, the current implementation in ‘(ice-9 vlist)’ has several 6587noteworthy shortcomings: 6588 6589 • It is _not_ thread-safe. Although operations on vlists are all 6590 “referentially transparent” (i.e., purely functional), adding 6591 elements to a vlist with ‘vlist-cons’ mutates part of its internal 6592 structure, which makes it non-thread-safe. This could be fixed, 6593 but it would slow down ‘vlist-cons’. 6594 6595 • ‘vlist-cons’ always allocates at least as much memory as ‘cons’. 6596 Again, Phil Bagwell describes how to fix it, but that would require 6597 tuning the garbage collector in a way that may not be generally 6598 beneficial. 6599 6600 • ‘vlist-cons’ is a Scheme procedure compiled to bytecode, and it 6601 does not compete with the straightforward C implementation of 6602 ‘cons’, and with the fact that the VM has a special ‘cons’ 6603 instruction. 6604 6605 We hope to address these in the future. 6606 6607 The programming interface exported by ‘(ice-9 vlist)’ is defined 6608below. Most of it is the same as SRFI-1 with an added ‘vlist-’ prefix 6609to function names. 6610 6611 -- Scheme Procedure: vlist? obj 6612 Return true if OBJ is a VList. 6613 6614 -- Scheme Variable: vlist-null 6615 The empty VList. Note that it’s possible to create an empty VList 6616 not ‘eq?’ to ‘vlist-null’; thus, callers should always use 6617 ‘vlist-null?’ when testing whether a VList is empty. 6618 6619 -- Scheme Procedure: vlist-null? vlist 6620 Return true if VLIST is empty. 6621 6622 -- Scheme Procedure: vlist-cons item vlist 6623 Return a new vlist with ITEM as its head and VLIST as its tail. 6624 6625 -- Scheme Procedure: vlist-head vlist 6626 Return the head of VLIST. 6627 6628 -- Scheme Procedure: vlist-tail vlist 6629 Return the tail of VLIST. 6630 6631 -- Scheme Variable: block-growth-factor 6632 A fluid that defines the growth factor of VList blocks, 2 by 6633 default. 6634 6635 The functions below provide the usual set of higher-level list 6636operations. 6637 6638 -- Scheme Procedure: vlist-fold proc init vlist 6639 -- Scheme Procedure: vlist-fold-right proc init vlist 6640 Fold over VLIST, calling PROC for each element, as for SRFI-1 6641 ‘fold’ and ‘fold-right’ (*note ‘fold’: SRFI-1.). 6642 6643 -- Scheme Procedure: vlist-ref vlist index 6644 Return the element at index INDEX in VLIST. This is typically a 6645 constant-time operation. 6646 6647 -- Scheme Procedure: vlist-length vlist 6648 Return the length of VLIST. This is typically logarithmic in the 6649 number of elements in VLIST. 6650 6651 -- Scheme Procedure: vlist-reverse vlist 6652 Return a new VLIST whose content are those of VLIST in reverse 6653 order. 6654 6655 -- Scheme Procedure: vlist-map proc vlist 6656 Map PROC over the elements of VLIST and return a new vlist. 6657 6658 -- Scheme Procedure: vlist-for-each proc vlist 6659 Call PROC on each element of VLIST. The result is unspecified. 6660 6661 -- Scheme Procedure: vlist-drop vlist count 6662 Return a new vlist that does not contain the COUNT first elements 6663 of VLIST. This is typically a constant-time operation. 6664 6665 -- Scheme Procedure: vlist-take vlist count 6666 Return a new vlist that contains only the COUNT first elements of 6667 VLIST. 6668 6669 -- Scheme Procedure: vlist-filter pred vlist 6670 Return a new vlist containing all the elements from VLIST that 6671 satisfy PRED. 6672 6673 -- Scheme Procedure: vlist-delete x vlist [equal?] 6674 Return a new vlist corresponding to VLIST without the elements 6675 EQUAL? to X. 6676 6677 -- Scheme Procedure: vlist-unfold p f g seed [tail-gen] 6678 -- Scheme Procedure: vlist-unfold-right p f g seed [tail] 6679 Return a new vlist, as for SRFI-1 ‘unfold’ and ‘unfold-right’ 6680 (*note ‘unfold’: SRFI-1.). 6681 6682 -- Scheme Procedure: vlist-append vlist ... 6683 Append the given vlists and return the resulting vlist. 6684 6685 -- Scheme Procedure: list->vlist lst 6686 Return a new vlist whose contents correspond to LST. 6687 6688 -- Scheme Procedure: vlist->list vlist 6689 Return a new list whose contents match those of VLIST. 6690 6691 6692File: guile.info, Node: Record Overview, Next: SRFI-9 Records, Prev: VLists, Up: Data Types 6693 66946.6.15 Record Overview 6695---------------------- 6696 6697“Records”, also called “structures”, are Scheme’s primary mechanism to 6698define new disjoint types. A “record type” defines a list of “fields” 6699that instances of the type consist of. This is like C’s ‘struct’. 6700 6701 Historically, Guile has offered several different ways to define 6702record types and to create records, offering different features, and 6703making different trade-offs. Over the years, each “standard” has also 6704come with its own new record interface, leading to a maze of record 6705APIs. 6706 6707 At the highest level is SRFI-9, a high-level record interface 6708implemented by most Scheme implementations (*note SRFI-9 Records::). It 6709defines a simple and efficient syntactic abstraction of record types and 6710their associated type predicate, fields, and field accessors. SRFI-9 is 6711suitable for most uses, and this is the recommended way to create record 6712types in Guile. Similar high-level record APIs include SRFI-35 (*note 6713SRFI-35::) and R6RS records (*note rnrs records syntactic::). 6714 6715 Then comes Guile’s historical “records” API (*note Records::). 6716Record types defined this way are first-class objects. Introspection 6717facilities are available, allowing users to query the list of fields or 6718the value of a specific field at run-time, without prior knowledge of 6719the type. 6720 6721 Finally, the common denominator of these interfaces is Guile’s 6722“structure” API (*note Structures::). Guile’s structures are the 6723low-level building block for all other record APIs. Application writers 6724will normally not need to use it. 6725 6726 Records created with these APIs may all be pattern-matched using 6727Guile’s standard pattern matcher (*note Pattern Matching::). 6728 6729 6730File: guile.info, Node: SRFI-9 Records, Next: Records, Prev: Record Overview, Up: Data Types 6731 67326.6.16 SRFI-9 Records 6733--------------------- 6734 6735SRFI-9 standardizes a syntax for defining new record types and creating 6736predicate, constructor, and field getter and setter functions. In Guile 6737this is the recommended option to create new record types (*note Record 6738Overview::). It can be used with: 6739 6740 (use-modules (srfi srfi-9)) 6741 6742 -- Scheme Syntax: define-record-type type 6743 (constructor fieldname ...) 6744 predicate 6745 (fieldname accessor [modifier]) ... 6746 6747 Create a new record type, and make various ‘define’s for using it. 6748 This syntax can only occur at the top-level, not nested within some 6749 other form. 6750 6751 TYPE is bound to the record type, which is as per the return from 6752 the core ‘make-record-type’. TYPE also provides the name for the 6753 record, as per ‘record-type-name’. 6754 6755 CONSTRUCTOR is bound to a function to be called as ‘(CONSTRUCTOR 6756 fieldval ...)’ to create a new record of this type. The arguments 6757 are initial values for the fields, one argument for each field, in 6758 the order they appear in the ‘define-record-type’ form. 6759 6760 The FIELDNAMEs provide the names for the record fields, as per the 6761 core ‘record-type-fields’ etc, and are referred to in the 6762 subsequent accessor/modifier forms. 6763 6764 PREDICATE is bound to a function to be called as ‘(PREDICATE obj)’. 6765 It returns ‘#t’ or ‘#f’ according to whether OBJ is a record of 6766 this type. 6767 6768 Each ACCESSOR is bound to a function to be called ‘(ACCESSOR 6769 record)’ to retrieve the respective field from a RECORD. Similarly 6770 each MODIFIER is bound to a function to be called ‘(MODIFIER record 6771 val)’ to set the respective field in a RECORD. 6772 6773An example will illustrate typical usage, 6774 6775 (define-record-type <employee> 6776 (make-employee name age salary) 6777 employee? 6778 (name employee-name) 6779 (age employee-age set-employee-age!) 6780 (salary employee-salary set-employee-salary!)) 6781 6782 This creates a new employee data type, with name, age and salary 6783fields. Accessor functions are created for each field, but no modifier 6784function for the name (the intention in this example being that it’s 6785established only when an employee object is created). These can all 6786then be used as for example, 6787 6788 <employee> ⇒ #<record-type <employee>> 6789 6790 (define fred (make-employee "Fred" 45 20000.00)) 6791 6792 (employee? fred) ⇒ #t 6793 (employee-age fred) ⇒ 45 6794 (set-employee-salary! fred 25000.00) ;; pay rise 6795 6796 The functions created by ‘define-record-type’ are ordinary top-level 6797‘define’s. They can be redefined or ‘set!’ as desired, exported from a 6798module, etc. 6799 6800Non-toplevel Record Definitions 6801............................... 6802 6803The SRFI-9 specification explicitly disallows record definitions in a 6804non-toplevel context, such as inside ‘lambda’ body or inside a LET 6805block. However, Guile’s implementation does not enforce that 6806restriction. 6807 6808Custom Printers 6809............... 6810 6811You may use ‘set-record-type-printer!’ to customize the default printing 6812behavior of records. This is a Guile extension and is not part of 6813SRFI-9. It is located in the (srfi srfi-9 gnu) module. 6814 6815 -- Scheme Syntax: set-record-type-printer! type proc 6816 Where TYPE corresponds to the first argument of 6817 ‘define-record-type’, and PROC is a procedure accepting two 6818 arguments, the record to print, and an output port. 6819 6820This example prints the employee’s name in brackets, for instance 6821‘[Fred]’. 6822 6823 (set-record-type-printer! <employee> 6824 (lambda (record port) 6825 (write-char #\[ port) 6826 (display (employee-name record) port) 6827 (write-char #\] port))) 6828 6829Functional “Setters” 6830.................... 6831 6832When writing code in a functional style, it is desirable to never alter 6833the contents of records. For such code, a simple way to return new 6834record instances based on existing ones is highly desirable. 6835 6836 The ‘(srfi srfi-9 gnu)’ module extends SRFI-9 with facilities to 6837return new record instances based on existing ones, only with one or 6838more field values changed—“functional setters”. First, the 6839‘define-immutable-record-type’ works like ‘define-record-type’, except 6840that fields are immutable and setters are defined as functional setters. 6841 6842 -- Scheme Syntax: define-immutable-record-type type 6843 (constructor fieldname ...) 6844 predicate 6845 (fieldname accessor [modifier]) ... 6846 Define TYPE as a new record type, like ‘define-record-type’. 6847 However, the record type is made _immutable_ (records may not be 6848 mutated, even with ‘struct-set!’), and any MODIFIER is defined to 6849 be a functional setter—a procedure that returns a new record 6850 instance with the specified field changed, and leaves the original 6851 unchanged (see example below.) 6852 6853In addition, the generic ‘set-field’ and ‘set-fields’ macros may be 6854applied to any SRFI-9 record. 6855 6856 -- Scheme Syntax: set-field record (field sub-fields ...) value 6857 Return a new record of RECORD’s type whose fields are equal to the 6858 corresponding fields of RECORD except for the one specified by 6859 FIELD. 6860 6861 FIELD must be the name of the getter corresponding to the field of 6862 RECORD being “set”. Subsequent SUB-FIELDS must be record getters 6863 designating sub-fields within that field value to be set (see 6864 example below.) 6865 6866 -- Scheme Syntax: set-fields record ((field sub-fields ...) value) ... 6867 Like ‘set-field’, but can be used to set more than one field at a 6868 time. This expands to code that is more efficient than a series of 6869 single ‘set-field’ calls. 6870 6871 To illustrate the use of functional setters, let’s assume these two 6872record type definitions: 6873 6874 (define-record-type <address> 6875 (address street city country) 6876 address? 6877 (street address-street) 6878 (city address-city) 6879 (country address-country)) 6880 6881 (define-immutable-record-type <person> 6882 (person age email address) 6883 person? 6884 (age person-age set-person-age) 6885 (email person-email set-person-email) 6886 (address person-address set-person-address)) 6887 6888First, note that the ‘<person>’ record type definition introduces named 6889functional setters. These may be used like this: 6890 6891 (define fsf-address 6892 (address "Franklin Street" "Boston" "USA")) 6893 6894 (define rms 6895 (person 30 "rms@gnu.org" fsf-address)) 6896 6897 (and (equal? (set-person-age rms 60) 6898 (person 60 "rms@gnu.org" fsf-address)) 6899 (= (person-age rms) 30)) 6900 ⇒ #t 6901 6902Here, the original ‘<person>’ record, to which RMS is bound, is left 6903unchanged. 6904 6905 Now, suppose we want to change both the street and age of RMS. This 6906can be achieved using ‘set-fields’: 6907 6908 (set-fields rms 6909 ((person-age) 60) 6910 ((person-address address-street) "Temple Place")) 6911 ⇒ #<<person> age: 60 email: "rms@gnu.org" 6912 address: #<<address> street: "Temple Place" city: "Boston" country: "USA">> 6913 6914Notice how the above changed two fields of RMS, including the ‘street’ 6915field of its ‘address’ field, in a concise way. Also note that 6916‘set-fields’ works equally well for types defined with just 6917‘define-record-type’. 6918 6919 6920File: guile.info, Node: Records, Next: Structures, Prev: SRFI-9 Records, Up: Data Types 6921 69226.6.17 Records 6923-------------- 6924 6925A “record type” is a first class object representing a user-defined data 6926type. A “record” is an instance of a record type. 6927 6928 Note that in many ways, this interface is too low-level for every-day 6929use. Most uses of records are better served by SRFI-9 records. *Note 6930SRFI-9 Records::. 6931 6932 -- Scheme Procedure: record? obj 6933 Return ‘#t’ if OBJ is a record of any type and ‘#f’ otherwise. 6934 6935 Note that ‘record?’ may be true of any Scheme value; there is no 6936 promise that records are disjoint with other Scheme types. 6937 6938 -- Scheme Procedure: make-record-type type-name field-names [print] 6939 [#:parent=‘#f’] [#:uid=‘#f’] [#:extensible?=‘#f’] 6940 [#:opaque?=‘#f’] [#:allow-duplicate-field-names?=‘#t’] 6941 Create and return a new “record-type descriptor”. 6942 6943 TYPE-NAME is a string naming the type. Currently it’s only used in 6944 the printed representation of records, and in diagnostics. 6945 FIELD-NAMES is a list of elements of the form ‘(immutable NAME)’, 6946 ‘(mutable NAME)’, or NAME, where NAME are symbols naming the fields 6947 of a record of the type. Duplicates are not allowed among these 6948 symbols, unless ALLOW-DUPLICATE-FIELD-NAMES? is true. 6949 6950 (make-record-type "employee" '(name age salary)) 6951 6952 The optional PRINT argument is a function used by ‘display’, 6953 ‘write’, etc, for printing a record of the new type. It’s called 6954 as ‘(PRINT record port)’ and should look at RECORD and write to 6955 PORT. 6956 6957 Pass the ‘#:parent’ keyword to derive a record type from a 6958 supertype. A derived record type has the fields from its parent 6959 type, followed by fields declared in the ‘make-record-type’ call. 6960 Record predicates and field accessors for instance of a parent type 6961 will also work on any instance of a subtype. 6962 6963 Allowing record subtyping has a small amount of overhead. To avoid 6964 this overhead, prevent extensibility by passing ‘#:extensible? #f’. 6965 By default, record types in Guile are not extensible. 6966 6967 Generally speaking, calling ‘make-record-type’ returns a fresh 6968 record type; it _generates_ new record types. However sometimes 6969 you only want to define a record type if one hasn’t been defined 6970 already. For a _nongenerative_ record type definition, pass a 6971 symbol as the ‘#:uid’ keyword parameter. If a record with the 6972 given UID was already defined, it will be returned instead. The 6973 type name, fields, parent (if any), and so on for the 6974 previously-defined type must be compatible. 6975 6976 R6RS defines a notion of “opaque” record types. Given an instance 6977 of an opaque record type, one cannot obtain a run-time 6978 representation of the record type. *Note rnrs records 6979 procedural::, for full details. The ‘#:opaque?’ flag is used by 6980 Guile’s R6RS layer to record this information. The default is 6981 determined by whether the parent type, if any, was opaque. 6982 6983 Fields are mutable by default, meaning that ‘record-modifier’ will 6984 return a procedure that can update a record in place. Specifying a 6985 field using the form ‘(immutable NAME)’ instead marks a field as 6986 immutable. 6987 6988 -- Scheme Procedure: record-constructor rtd 6989 Return a procedure for constructing new members of the type 6990 represented by RTD. The result will be a procedure accepting 6991 exactly as many arguments as there are fields in the record type. 6992 6993 -- Scheme Procedure: record-predicate rtd 6994 Return a procedure for testing membership in the type represented 6995 by RTD. The returned procedure accepts exactly one argument and 6996 returns a true value if the argument is a member of the indicated 6997 record type; it returns a false value otherwise. 6998 6999 -- Scheme Procedure: record-accessor rtd field-name 7000 Return a procedure for reading the value of a particular field of a 7001 member of the type represented by RTD. The returned procedure 7002 accepts exactly one argument which must be a record of the 7003 appropriate type; it returns the current value of the field named 7004 by the symbol FIELD-NAME in that record. 7005 7006 If FIELD-NAME is a symbol, it must be a member of the list of 7007 field-names in the call to ‘make-record-type’ that created the type 7008 represented by RTD. If multiple fields in RTD have the same name, 7009 ‘record-accessor’ returns the first one. 7010 7011 If FIELD-NAME is an integer, it should be an index into 7012 ‘(record-type-fields RTD)’. This allows accessing fields with 7013 duplicate names. 7014 7015 -- Scheme Procedure: record-modifier rtd field-name 7016 Return a procedure for writing the value of a particular field of a 7017 member of the type represented by RTD. The returned procedure 7018 accepts exactly two arguments: first, a record of the appropriate 7019 type, and second, an arbitrary Scheme value; it modifies the field 7020 named by the symbol FIELD-NAME in that record to contain the given 7021 value. The returned value of the modifier procedure is 7022 unspecified. The symbol FIELD-NAME is a field name or a field 7023 index, as in ‘record-modifier’. 7024 7025 -- Scheme Procedure: record-type-descriptor record 7026 Return a record-type descriptor representing the type of the given 7027 record. That is, for example, if the returned descriptor were 7028 passed to ‘record-predicate’, the resulting predicate would return 7029 a true value when passed the given record. Note that it is not 7030 necessarily the case that the returned descriptor is the one that 7031 was passed to ‘record-constructor’ in the call that created the 7032 constructor procedure that created the given record. 7033 7034 -- Scheme Procedure: record-type-name rtd 7035 Return the type-name associated with the type represented by rtd. 7036 The returned value is ‘eqv?’ to the TYPE-NAME argument given in the 7037 call to ‘make-record-type’ that created the type represented by 7038 RTD. 7039 7040 -- Scheme Procedure: record-type-fields rtd 7041 Return a list of the symbols naming the fields in members of the 7042 type represented by RTD. The returned value is ‘equal?’ to the 7043 field-names argument given in the call to ‘make-record-type’ that 7044 created the type represented by RTD. 7045 7046 7047File: guile.info, Node: Structures, Next: Dictionary Types, Prev: Records, Up: Data Types 7048 70496.6.18 Structures 7050----------------- 7051 7052A “structure” is a first class data type which holds Scheme values or C 7053words in fields numbered 0 upwards. A “vtable” is a structure that 7054represents a structure type, giving field types and permissions, and an 7055optional print function for ‘write’ etc. 7056 7057 Structures are lower level than records (*note Records::). Usually, 7058when you need to represent structured data, you just want to use 7059records. But sometimes you need to implement new kinds of structured 7060data abstractions, and for that purpose structures are useful. Indeed, 7061records in Guile are implemented with structures. 7062 7063* Menu: 7064 7065* Vtables:: 7066* Structure Basics:: 7067* Vtable Contents:: 7068* Meta-Vtables:: 7069* Vtable Example:: 7070 7071