1: @node Library modules - Gauche extensions, Library modules - SRFIs, Library modules - Overview, Top 2: @chapter Library modules - Gauche extensions 3: @c NODE ?饤?Ö¥??⥸?塼?? Gauche????⥸?塼??@c ---------------------------------------------------------------------- 4: @menu 5: * Arrays:: 6: * Character code conversion:: 7: * Collection framework:: 8: * Configuration parameters:: 9: * Dictionary framework:: 10: * Low-level file operations:: 11: * Hooks:: 12: * Interactive session:: 13: * Listener:: 14: * User-level logging:: 15: * Singleton:: 16: * Slot with validator:: 17: * Networking:: 18: * Parameters:: 19: * Parsing command-line options:: 20: * High Level Process Interface:: 21: * Reloading modules:: 22: * Simple dispatcher:: 23: * Sequence framework:: 24: * Syslog:: 25: * Termios:: 26: * Unit testing:: 27: * Threads:: 28: * Measure timings:: 29: * Uniform vectors:: 30: * Comparing version numbers:: 31: * Virtual ports:: 32: @end menu 33: 34: @node Arrays, Character code conversion, Library modules - Gauche extensions, Library modules - Gauche extensions 35: @section @code{gauche.array} - Arrays 36: @c NODE ??, @code{gauche.array} - ?? 37: 38: @deftp {Module} gauche.array 39: @mdindex gauche.array 40: @c EN 41: This module provides multi-dimensional array data type and operations. 42: The primitive API follows SRFI-25. 43: Besides a generic srfi-25 array that can store any Scheme objects, 44: this module also provides array classes that stores numeric objects 45: efficiently, backed up by 46: homogeneous numeric vectors (@xref{Uniform vectors}). 47: An external representation of arrays, using SRFI-10 mechanism, 48: is also provided. 49: @c JP 50: ???Υ⥸?塼??¿???????Υǡ????????פȤ????ؤ???????????Þ¤??? 51: ?×¥??Æ¥??Ö¤?PI??RFI-25????????????Τ˽????Þ¤??? 52: Ǥ?Õ¤?cheme???Ö¥??????Ȥ???FI-25????????Ë¡? 53: ?Ñ°???Ù¥???(@ref{Uniform vectors}??????ä????Ǥ?????????󷿤??????????? 54: ?Þ¤???SRFI-10??ä????γ??ɽ????????????? 55: @c COMMON 56: 57: @c EN 58: Each element of an @var{N}-dimensional array can be accessed 59: by @var{N} integer indices, 60: @code{[ @var{i_0} @var{i_1} @dots{} @var{i_N-1} ]}. 61: An array has associated @var{shape} that knows lower-bound @var{s_k} and 62: upper-bound @var{e_k} of index of each dimension, where 63: @var{s_k} <= @var{e_k}, and the index @var{i_k} must satisfy 64: @var{s_k} <= @var{i_k} < @var{e_k}. 65: (Note: it is allowed to have @var{s_k} == @var{e_k}, but such array can't 66: store any data. It is also allowed to have zero-dimensional array, 67: that can store a single data.). 68: The shape itself is a [ @var{D} x 2 ] array, where @var{D} is the 69: dimension of the array which the shape represents. 70: @c JP 71: @var{N}????????Æ¥??????code{N}?Ĥ???????Ã¥??? 72: @code{[ @var{i_0} @var{i_1} @dots{} @var{i_N-1} ]}?Ç¥??????????????? 73: ???Ï¡??Ƽ????Î¥???Ã¥????β???var{s_k}??????@var{e_k}??? 74: @var{shape}??äƤ??Þ¤????????Ç¡?@var{s_k} <= @var{e_k}?Ǥ??ê¡¢ 75: @var{k}??????Î¥???Ã¥???@var{i_k}??@var{s_k} <= @var{i_k} < @var{e_k} ????????Ȥ??Þ¤??? 76: (@var{s_k} == @var{e_k} ?Ǥ???????????Þ¤????? 77: ??????ϥǡ????ò¥¹¥È¥????뤳?ȤϤǤ??Þ¤????Þ¤???0??????????Þ¤?????????????Ç¡??????Þ¤?)?? 78: Shape?Ϥ??켫??? [ @var{D} x 2 ] ??????? 79: ??????var{D}?Ϥ???hape??ɽ????????μ???????? 80: @c COMMON 81: 82: @c EN 83: You can pass index(es) to array access primitives in a few ways; 84: each index can be passed as individual argument, 85: or can be 'packed' in a vector or one-dimensional array. 86: In the latter case, such a vector or an array is called an "index object". 87: Using a vector is efficient in Gauche when you iterate over the elements 88: by changing the vector elements, for it won't involve memory allocation. 89: @c JP 90: ???Î¥×¥??Æ¥??Ö¤?Ф?????Ã¥???????ˤϤ????Ĥ??Ë¡?????????? 91: ?Æ¥???Ã¥??????????????Ϥ????Ȥ????Þ¤????? 92: ?Ù¥????????????ѥå?????Ϥ????Ȥ????Þ¤??? 93: ???ˤ????Æ¥???Ã¥??????ѥå????줿?Ù¥???????????Ã¥??????Ö¥??????È¡??ȸƤ֤??Ȥ?????????Gauche?Ǥϡ??????Ǥ˼????È¥??????????????ʽ??Ǥ??Ù¥????ò¥¤¥?Ã¥??????Ö¥??????ȤȤ??ƻȤ??ȼ㴳??????Ǥ??礦?? 94: @c COMMON 95: 96: @c EN 97: Arrays can be compared by the @code{equal?} procedure. 98: @code{Equal?} returns @code{#t} if two arrays have the same 99: shape and their corresponding elements are the same 100: in the sense of @code{equal?}. 101: @c JP 102: ????code{equal?}??????????뤳?Ȥ???????? 103: ??Ĥ???hape??????????Þ¤????????????@code{equal?}?ΰ?????????????????code{equal?}?Ǥ??????ʤ??????? 104: @c COMMON 105: 106: @c EN 107: Internally, an array consists of a backing storage and a mapping procedure. 108: A backing storage is an object of aggregate type that can be accessed 109: by an integer index. A mapping procedure takes 110: multi-dimensional indices (or index object) and 111: returns a scalar index into the backing storage. 112: @c JP 113: ??Ū?ˤϡ??????????Î¥???Ã¥????Ç¥????????????Хå??ó¥°¥??ȥ졼???È¡? 114: ¿?????Î¥???Ã¥?????Ã¥??ó¥°¥??ȥ졼???ؤΥ???Ã¥????˥ޥåפ???³???Ȥ????????????Þ¤??? 115: @c COMMON 116: @end deftp 117: 118: @deftp {Class} <array-base> 119: @clindex array-base 120: @c EN 121: An abstract base class of array types, that implements generic operations 122: on the array. To create an array instance, 123: you should use one of the following concrete array classes. 124: @c JP 125: ???˴ؤ?????????õ¤·¤Æ¤??ë¡¢??Ý¥Ù¡??????饹?Ǥ??? 126: ?ºݤ?????ó¥¹¥??󥹤???Ï¡??ʲ??Τ????줫?ζ???饹??äƲ??????? 127: @c COMMON 128: @end deftp 129: 130: @deftp {Class} <array> 131: @deftpx {Class} <u8array> 132: @deftpx {Class} <s8array> 133: @deftpx {Class} <u16array> 134: @deftpx {Class} <s16array> 135: @deftpx {Class} <u32array> 136: @deftpx {Class} <s32array> 137: @deftpx {Class} <u64array> 138: @deftpx {Class} <s64array> 139: @deftpx {Class} <f16array> 140: @deftpx {Class} <f32array> 141: @deftpx {Class} <f64array> 142: @clindex array 143: @clindex u8array 144: @clindex s8array 145: @clindex u16array 146: @clindex s16array 147: @clindex u32array 148: @clindex s32array 149: @clindex u64array 150: @clindex s64array 151: @clindex f16array 152: @clindex f32array 153: @clindex f64array 154: @c EN 155: Concrete array classes. The @code{<array>} class implements srfi-25 156: compatible array, i.e. an array that can store any Scheme objects. 157: The @code{<u8array>} class through @code{<f64array>} classes uses 158: a @code{<u8vector>} through @code{<f64vector>} as a backing storage, 159: and can only store a limited range of integers or inexact real numbers, 160: but they are space efficient. 161: @c JP 162: ???󥯥饹?Ǥ???@code{<array>}???饹??rfi-25?ß´????????ʤ???Ǥ?Õ¤?cheme???Ö¥??????Ȥ???Ǥ??????õ¤·¤Þ¤??? 163: @code{<u8array>}????ode{<f64array>}?ޤǤϡ? 164: ???줾??ode{<u8vector>}????ode{<f64vector>}??Ã¥??ó¥°¥??ȥ졼???Ȥ???????????õ¤·¡???¤??줿??Ϥ????????????Τʼ¿?ߤ?Ψ?????????뤳?Ȥ??Ǥ??Þ¤??? 165: @c COMMON 166: @end deftp 167: 168: 169: @deftp {Reader syntax} @code{#,(<array> @var{shape} @var{obj} @dots{})} 170: @c EN 171: An array is written out in this format. (Substitute @code{<array>} for 172: @code{<u8array>} if the array is @code{<u8array>}, etc.) 173: @var{shape} is a list 174: of even number of integers, and each 2@var{n}-th integer 175: and 2@var{n}+1-th integer specifies the 176: inclusive lower-bound and exclusive upper-bound of @var{n}-th dimension, 177: respectively. The following @var{obj} @dots{} are the values in the array 178: listed in row-major order. 179: @c JP 180: ???Ϥ??η???ǽñ¤½Ð¤??????? 181: (?????????code{<u8array>}?Ǥ????é¡¢@code{<array>}????code{<u8array>} 182: ?Ȥʤ?????) 183: @var{shape}?϶?Ĥ????ꥹ?Ȥǡ? 184: 2@var{n}???????var{n}??????Î¥???Ã¥????β??¤?@var{n}+1???????var{n}??????Î¥???Ã¥????ξ?(+1)????Þ¤??? 185: ???θ????????Ǥ?row-major?ν??ñ¤½Ð¤??????? 186: @c COMMON 187: 188: @c EN 189: When read back, this syntax is read as an array with the same shape 190: and content, so it is @code{equal?} to the original array. 191: @c JP 192: ???ι?ʸ????ß¹??Þ¤??È¡???????code{equal?}?Ǥ???????????????? 193: @c COMMON 194: 195: @example 196: @c EN 197: ; an array such that: 198: @c JP 199: ; ???Τ褦????@c COMMON 200: ; 8 3 4 201: ; 1 5 9 202: ; 6 7 2 203: #,(<array> (0 3 0 3) 8 3 4 1 5 9 6 7 2) 204: 205: @c EN 206: ; a 4x4 identity matrix 207: @c JP 208: ; 4x4????̹?? COMMON 209: #,(<array> (0 4 0 4) 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1) 210: @end example 211: @end deftp 212: 213: @defun array? obj 214: [SRFI-25] 215: @c EN 216: Returns @code{#t} if @var{obj} is an array, @var{#f} otherwise. 217: It is equivalent to @code{(is-a? obj <array-base>)}. 218: @c JP 219: @var{obj}?????Ǥ???@var{#t}?????????Ǥʤ???@var{#f}??????????? 220: @code{(is-a? obj <array-base>)}??????? 221: @c COMMON 222: @end defun 223: 224: @defun make-array shape &optional init 225: [SRFI-25] 226: @c EN 227: Creates an array of shape @var{shape}. 228: @var{Shape} must be a [ @var{D} x 2 ] array, and for each @var{k} 229: (0 <= @var{k} < @var{D}), the [ @var{k} 0 ] element must be less than or 230: equal to the [ @var{k} 1] element. 231: If @var{init} is given, all the elements are initialized by it. 232: Otherwise, the initial value of the elements are undefined. 233: @c JP 234: Shape??@var{shape}?Ǥ??????????Þ¤??? 235: @var{Shape}??[ @var{D} x 2 ] ????? 236: 0 <= @var{k} < @var{D} ?ʤ?@var{k}??Ф?????[ @var{k} 0 ] ????[ @var{k} 1 ]?ʲ??Ǥʤ????ʤ?????@var{init}??Í¿?????????Ï¡????γ??Ǥ?@var{init}?ǽ??????????? 237: @var{init}??Í¿?????ʤ??ä????????Ǥν?????????? 238: @c COMMON 239: 240: @example 241: (make-array (shape 0 2 0 2 0 2) 5) 242: @result{} #,(<array> (0 2 0 2 0 2) 5 5 5 5 5 5 5 5) 243: @end example 244: @end defun 245: 246: @defun make-u8array shape &optional init 247: @defunx make-s8array shape &optional init 248: @findex make-u16array 249: @findex make-s16array 250: @findex make-u32array 251: @findex make-s32array 252: @findex make-u64array 253: @findex make-s64array 254: @dots{} 255: @end defun 256: @defun make-f32array shape &optional init 257: @defunx make-f64array shape &optional init 258: @c EN 259: Like @code{make-array}, but creates and returns an uniform numeric array. 260: @c JP 261: @code{make-array}?È»???Þ¤??????Ñ°?????Ö¤??Þ¤??? 262: @c COMMON 263: @end defun 264: 265: @defun shape bound @dots{} 266: [SRFI-25] 267: @c EN 268: Takes even number of exact integer arguments, and returns 269: a two-dimensional array that is suitable for representing the shape 270: of an array. 271: @c JP 272: ??Ĥ???Τ?????????????hape?Ȥ??ƻȤ??????????Ö¤??Þ¤??? 273: @c COMMON 274: 275: @example 276: (shape 0 2 1 3 3 5) 277: @result{} #,(<array> (0 3 0 2) 0 2 1 3 3 5) 278: 279: (shape) 280: @result{} #,(<array> (0 0 0 2)) 281: @end example 282: @end defun 283: 284: @defun array shape init @dots{} 285: [SRFI-25] 286: @c EN 287: Creates an array of shape @var{shape}, initializing its elements by 288: @var{init} @dots{}. 289: @c JP 290: Shape??@var{shape}?Ǥ?????????????? 291: ?????Ǥ?r{init} @dots{}?ǽ??????Þ¤??? 292: @c COMMON 293: 294: @example 295: (array (shape 0 2 1 3) 'a 'b 'c 'd) 296: @result{} #,(<array> (0 2 1 3) a b c d) 297: @end example 298: @end defun 299: 300: @defun array-rank array 301: [SRFI-25] 302: @c EN 303: Returns the number of dimensions of an array @var{array}. 304: @c JP 305: ??@var{array}?μ?????Ö¤??Þ¤??? 306: @c COMMON 307: 308: @example 309: (array-rank (make-array (shape 0 2 0 2 0 2))) @result{} 3 310: (array-rank (make-array (shape))) @result{} 0 311: @end example 312: @end defun 313: 314: @defun array-shape array 315: @c EN 316: Returns a shape array of @var{array}. 317: @c JP 318: ??@var{array}??hape?????????Þ¤??? 319: @c COMMON 320: @end defun 321: 322: @defun array-start array dim 323: @defunx array-end array dim 324: @defunx array-length array dim 325: [SRFI-25+] 326: @c EN 327: @code{Array-start} returns the inclusive lower bound of index of 328: @var{dim}-th dimension of an array @var{array}. 329: @code{Array-end} returns the exclusive upper bound. 330: And @code{array-length} returns the difference between two. 331: @code{Array-start} and @code{array-end} are defined in SRFI-25. 332: @c JP 333: @code{array-start}????r{array}??var{dim}???μ?????????Ã¥????β??¤???Þ¤??? 334: @code{array-end}?Ͼ?+1?ò¡¢¤?????code{array-length}????Ԥκ?????Þ¤??? 335: @code{array-start}??code{array-end}??RFI-25??????????Þ¤??? 336: @c COMMON 337: 338: @example 339: (define a (make-array (shape 1 5 0 2))) 340: 341: (array-start a 0) @result{} 1 342: (array-end a 0) @result{} 5 343: (array-length a 0) @result{} 4 344: (array-start a 1) @result{} 0 345: (array-end a 1) @result{} 2 346: (array-length a 1) @result{} 2 347: @end example 348: @end defun 349: 350: @defun array-size array 351: @c EN 352: Returns the total number of elements in the array @var{array}. 353: @c JP 354: ??@var{array}???????Ö¤??Þ¤??? 355: @c COMMON 356: 357: @example 358: (array-size (make-array (shape 5 9 1 3))) @result{} 8 359: (array-size (make-array (shape))) @result{} 1 360: (array-size (make-array (shape 0 0 0 2))) @result{} 0 361: @end example 362: @end defun 363: 364: @defun array-ref array k @dots{} 365: @defunx array-ref array index 366: [SRFI-25] 367: @c EN 368: Gets the element of array @code{array}. In the first form, 369: the element is specified by indices @var{k} @dots{}. 370: In the second form, the element is specified by an index object 371: @var{index}, which must be a vector or an one-dimensional array. 372: @c JP 373: ??@var{array}???Ǥ?????Þ¤????ǽ?????Ǥϡ? 374: ??????????Ã¥???@var{k} @dots{}?Ç»?ꤵ?????? 375: 2???η???Ǥϡ????Ï¥Ù¥????Þ¤??????????Î¥???Ã¥??????Ö¥???????var{index} 376: ?Ç»?ꤵ?????? 377: @c COMMON 378: @end defun 379: 380: @defun array-set! array k @dots{} value 381: @defunx array-set! array index value 382: [SRFI-25] 383: @c EN 384: Sets the element of array @var{array} to @var{value}. In the first form, 385: the element is specified by indices @var{k} @dots{}. 386: In the second form, the element is specified by an index object 387: @var{index}, which must be a vector or an one-dimensional array. 388: @c JP 389: ??@var{array}???Ǥ?var{value}?ò¥»¥Ã¥È¤??Þ¤??? 390: ?ǽ?????Ǥϡ? 391: ??????????Ã¥???@var{k} @dots{}?Ç»?ꤵ?????? 392: 2???η???Ǥϡ????Ï¥Ù¥????Þ¤??????????Î¥???Ã¥??????Ö¥???????var{index} 393: ?Ç»?ꤵ?????? 394: @c COMMON 395: @end defun 396: 397: @defun share-array array shape proc 398: [SRFI-25] 399: @c EN 400: Creates and returns a new array of shape @var{shape}, that shares 401: the backing storage with the given array @var{array}. 402: The procedure @var{proc} maps the indices of the new array to 403: the indices to the original array, i.e. @var{proc} must be a @var{n}-ary 404: procedure that returns @var{m} values, where @var{n} is the dimension 405: of the new array and @var{m} is the one of the original array. 406: Furthermore, @var{proc} must be an affine function; each mapping 407: has to be a linear combination of input arguments plus optional constant. 408: (@code{Share-array} optimizes the mapping function based on the affinity 409: assumption, so @var{proc} won't be called every time the new array 410: is accessed). 411: @c JP 412: Shape??@var{shape}?Ǥ??ꡢͿ????????@var{array}?ȥХå??ó¥°¥??ȥ졼????Í???ë¿·?????????????Ö¤??Þ¤??? 413: @var{proc}?Ï¡??????????ؤΥ???Ã¥?????????ؤΥ???Ã¥??????ޥåפ???³???Ǥ????????????μ?????var{n}???Ť????μ?????var{m}??????????@var{proc}??var{n}?Ĥΰ???@var{m}?Ĥ?ͤ???????Ǥʤ??? 414: ?ʤ????󡣤??????ƥޥåԥ󥰤?ffine?ޥåԥ󥰡????ʤ??? 415: ??Ϥ?????????(?ץ饹????ʤ????ʤ?????(@code{share-array}??var{proc}??affine?ޥåԥ󥰤Ǥ?????????Ë´???? 416: ?????????Þ¤????????????Ë¥?????????????var{proc}???ƤФ??Ȥ????櫓?Ǥ????????? 417: @c COMMON 418: @end defun 419: 420: @defun array-for-each-index array proc &optional index 421: @end defun 422: 423: @defun shape-for-each shape proc &optional index 424: @end defun 425: 426: @defun tabulate-array shape proc &optional index 427: @end defun 428: 429: @defun array-retabulate! array shape proc &optional index 430: @defunx array-retabulate! array proc &optional index 431: @end defun 432: 433: @defun array-map! array shape proc array0 array1 @dots{} 434: @defunx array-map! array proc array0 array1 @dots{} 435: @end defun 436: 437: @defun array-map shape proc array0 array1 @dots{} 438: @defunx array-map proc array0 array1 @dots{} 439: @end defun 440: 441: @defun array->vector array 442: @defunx array->list array 443: @end defun 444: 445: @defun array-concatenate a b &optional dimension 446: @end defun 447: 448: @defun array-transpose array &optional dim1 dim2 449: @end defun 450: 451: @defun array-rotate-90 array &optional dim1 dim2 452: @end defun 453: 454: @defun array-flip array &optional dimension 455: @defunx array-flip! array &optional dimension 456: @end defun 457: 458: @defun identity-array dimension &optional class 459: @end defun 460: 461: @defun array-inverse array 462: @end defun 463: 464: @defun determinant array 465: @defunx determinant! array 466: @end defun 467: 468: @defun array-mul a b 469: @end defun 470: 471: @defun array-expt array pow 472: @end defun 473: 474: @defun array-div-left a b 475: @defunx array-div-right a b 476: @end defun 477: 478: @defun array-add-elements array array-or-scalar @dots{} 479: @defunx array-add-elements! array array-or-scalar @dots{} 480: @end defun 481: 482: @defun array-sub-elements array array-or-scalar @dots{} 483: @defunx array-sub-elements! array array-or-scalar @dots{} 484: @defunx array-mul-elements array array-or-scalar @dots{} 485: @defunx array-mul-elements! array array-or-scalar @dots{} 486: @defunx array-div-elements array array-or-scalar @dots{} 487: @defunx array-div-elements! array array-or-scalar @dots{} 488: @end defun 489: 490: @c ---------------------------------------------------------------------- 491: @node Character code conversion, Collection framework, Arrays, Library modules - Gauche extensions 492: @section @code{gauche.charconv} - Character Code Conversion 493: @c NODE ʸ?ú¥³¡¼??Ñ´?, @code{gauche.charconv} - ʸ?ú¥³¡¼??Ñ´? 494: 495: @deftp {Module} gauche.charconv 496: @mdindex gauche.charconv 497: @c EN 498: This module defines a set of functions that converts character encoding 499: schemes (CES) of the given data stream. 500: This module also overloads Gauche's file stream creating functions 501: (such as @code{open-input-file} and @code{call-with-output-file}) 502: so that they accept @code{:encoding} keyword argument. 503: @c JP 504: Í¿???????Ç¡??????ȥ꡼??ʸ???????Ç¥??ó¥°¤?????뤿???????????????⥸?塼???????Þ¤??????Υ⥸?塼??@code{open-input-file}??code{call-with-output-file}??Î¥Õ¥????륹?ȥ꡼????????³????????????@code{:encoding} ??????É°?ǧ?????????ˤ??Þ¤??? 505: @c COMMON 506: 507: @c EN 508: As of release 0.5.6, Gauche natively supports conversions between 509: typical Japanese character encodings: ISO2022JP, ISO2022JP-3, 510: EUC-JP (EUC-JISX0213), Shift_JISX0213, UTF-8 (Unicode 3.2). 511: Conversions between other encodings are handled by @code{iconv(3)}. 512: @xref{Supported character encoding schemes}, for details. 513: @c JP 514: ??????0.5.6????Gauche???μ????󥳡??Ç¥???(ISO2022JP, ISO2022JP-3, EUC-JP (EUC-JISX0213), Shift_JIS (Shift_JISX0213), 515: UTF-8 (Unicode 3.2))?Ö¤?Ñ´?????Ç»???ˤʤ??????? 516: ?åµ?ʳ??Î¥????ɤȤ?Ñ´???code{iconv(3)}??Ѥ??Þ¤??? 517: ???Ý¡??Ȥ????????Ç¥??ó¥°¥????Æ¥??ؤ????Ù¤?@ref{Supported character encoding schemes}?ò»²¾È¤??Ʋ??????? 518: @c COMMON 519: @end deftp 520: 521: @menu 522: * Supported character encoding schemes:: 523: * Autodetecting the encoding scheme:: 524: * Conversion ports:: 525: * Extended port procedures:: 526: @end menu 527: 528: @node Supported character encoding schemes, Autodetecting the encoding scheme, Character code conversion, Character code conversion 529: @subsection Supported character encoding schemes 530: @c NODE ???Ý¡??Ȥ???ʸ???????Ç¥??? 531: @c EN 532: A CES is represented by its name as a string or a symbol. 533: Case is ignored. There may be several aliases defined for a single encoding. 534: @c JP 535: CES????????????Ï¥??????ꤷ?Þ¤????ʸ??????????뤵?????? 536: Ʊ??CES?ˤ????Ĥ????????Ĥ??Ƥ??뤳?Ȥ????????? 537: @c COMMON 538: 539: @c EN 540: A CES name "none" is special. When Gauche's native encoding is @code{none}, 541: Gauche just treats a string as a byte sequence, and it's up to the application 542: to interpret the sequence in an appropriate encoding. So, conversion 543: to and from CES "none" does nothing. 544: @c JP 545: CES̾ "none" ??ü?????Gauche?Υͥ??Æ¥??Ö¥??󥳡??Ç¥??ó¥°¤?@code{none}??????Gauche?????ñ?ʤ????????Æ°????????Î¥??󥳡??Ç¥??󥰤β?????ץꥱ????????????????????????äơ?CES "none" ?ؤ?Ñ´??????? "none" 546: ????????Ï¡Ö²??⤷?ʤ???Ñ´??Ȥ??Æ°????Þ¤??? 547: @c COMMON 548: 549: @c EN 550: You can check whether the specific conversion is supported on 551: your system or not, by the following function. 552: @c JP 553: ????Ñ´????????Æ¥????Ý¡??Ȥ??????뤫?ɤ????ϼ??μ???????٤뤳?Ȥ??Ǥ??Þ¤??? 554: @c COMMON 555: 556: @defun ces-conversion-supported? from-ces to-ces 557: @c EN 558: Returns @code{#t} if conversion from the character encoding scheme 559: (CES) @var{from-ces} to @var{to-ces} is supported in this system. 560: 561: Note that this procedure may return true even if system only supports 562: partial conversion between @var{from-ces} and @var{to-ces}. 563: In such case, actual conversion might lose information by coercing 564: characters in @var{from-ces} which are not supported in @var{to-ces}. 565: (For example, conversion from Unicode to EUC-JP is "supported", 566: although Unicode has characters that are not in EUC-JP). 567: 568: Also note that this procedure always returns @code{#t} 569: if @var{from-ces} and/or @var{to-ces} is "none", 570: for conversion to/from CES "none" always succeeds (in fact, it does nothing). 571: 572: @example 573: ;; see if you can convert the internal encoding to EUC-JP 574: (ces-conversion-supported? (gauche-character-encoding) "euc-jp") 575: @end example 576: @c JP 577: CES @var{from-ces}????ar{to-ces}?ؤ?Ñ´??????Ý¡??Ȥ???????@code{#t}???????Ǥʤ???@code{#f}????Þ¤??? 578: 579: ?????ƥब@var{from-ces}????ar{to-ces}?ؤ?Ñ´????Ū?ˤ??? 580: ???Ý¡??Ȥ??Ƥ??ʤ????Ǥ⤳?μ?????code{#t}??????Ȥ?????Ʋ??????? 581: ???Τ褦?ʾ????ºݤ?Ñ´?????var{from-ces}?ˤ??ä?var{to-ces}?ˤʤ? 582: ?????ɤ??ʸ???????????Ǿ?ò¼º¤????⤷??????㤨?С?Unicode????C-JP?ؤ?Ñ´??Ï¥??Ý¡??Ȥ??????Þ¤????? 583: Unicode?ˤ?UC-JP?ˤʤ?ʸ???Þ¤????Þ¤?)?? 584: 585: @var{from-ces}??@var{to-ces}?? "none" ?ʤ????μ????Ͼ?@code{#t}?????Þ¤????ʤ??ʤ餽?Τ褦??Ñ´??Ͼ??????????(?????????ʤ??櫓?Ǥ???)?? 586: 587: @example 588: ;; ?????󥳡??Ç¥??ó¥°¤???C-JP??Ñ´??Ǥ??뤫? 589: (ces-conversion-supported? (gauche-character-encoding) "euc-jp") 590: @end example 591: @c COMMON 592: @end defun 593: 594: @c EN 595: Also there are two useful procedures to deal with CES names. 596: @c JP 597: ?Þ¤???CES?ò°·¤???Ĥ???³??????Õ¤??????Þ¤??? 598: @c COMMON 599: 600: @defun ces-equivalent? ces-a ces-b &optional unknown-value 601: @c EN 602: Returns true if two CESes @var{ces-a} and @var{ces-b} are equivalent 603: to the knowledge of the system. Returns false if they are not. 604: If the system doesn't know about equivalency, @var{unknown-value} 605: is returned, whose default is @code{#f}. 606: 607: CES "none" works like a wild card; it is "equivalent" to any CES. 608: (Thus, @code{ces-equivalent?} is not transitive. 609: The intended use of @code{ces-equivalent?} 610: is to compare two given CES names and see if conversion is required or not). 611: @c JP 612: CES @var{ces-a}??var{ces-b}???????Æ¥??????????ä?????@code{#t}????ʤ?????code{#f}????Þ¤??? 613: ?????ƥब???????ǽ????????var{unknown-value}????????? 614: ?????Þ¤??????Υǥե?????code{#f}?Ǥ??? 615: 616: CES̾ "none" ?ϥ磻???????ɤΤ褦?????Þ¤????????ɤ?ES?Ȥ?????????????(???äơ?@code{ces-equivalent?} ???????ǤϤ??????????μ????Ï¡???Ĥ?ES??ä????????Ñ´??? 617: ɬ????ɤ?????Ǥ??뤿?????Ǥ?)?? 618: @c COMMON 619: 620: @example 621: (ces-equivalent? 'eucjp "EUC-JP") @result{} #t 622: (ces-equivalent? 'shift_jis "EUC-JP") @result{} #f 623: (ces-equivalent? "NoSuchEncoding" 'utf-8 '?) @result{} ? 624: @end example 625: @end defun 626: 627: @defun ces-upper-compatible? ces-a ces-b &optional unknown-value 628: @c EN 629: Returns true if a string encoded in CES @var{ces-b} can also 630: be regarded as a string encoded in @var{ces-a} without conversion, 631: to the knowledge of the system. 632: Returns false if not. Returns @var{unknown-value} 633: if the system can't determine which is the case. 634: 635: Like @code{ces-equivalent?}, CES "none" works like a wildcard. 636: It is upper-compatible to any CES, and any CES is upper-compatible to 637: "none". 638: @c JP 639: CES @var{ces-b}?Ç¥??󥳡??ɤ??줿ʸ?????????Æ¥?????? 640: ???̵????var{ces-a}?Ç¥??󥳡??ɤ??줿???ȸ????????@code{#t}?????Þ¤?????????ʤ?????var{#f}????Þ¤??? 641: ?????ƥबȽ??Ǥ??ʤ?????var{unknown-value}????????? 642: ?????Þ¤??????Υǥե?????code{#f}?Ǥ??? 643: 644: @code{ces-equivalent?}?????Ë¡?CES̾ "none" ?ϥ磻???????ɤȤ???Ư???Þ¤???@var{ces-a} ?? @var{ces-b} ?? "none" ?Ǥ????? 645: ??@code{#t}??????????? 646: @c COMMON 647: 648: @example 649: (ces-upper-compatible? "eucjp" "ASCII") @result{} #t 650: (ces-upper-compatible? "eucjp" "utf-8") @result{} #f 651: (ces-upper-compatible? "utf-8" "NoSuchEncoding" '?) @result{} ? 652: @end example 653: @end defun 654: 655: @c EN 656: Conversion between common japanese CESes (EUC_JP, Shift JIS, UTF-8 657: and ISO2022-JP) of the character set JIS X 0201 and JIS X 0213 658: is handled by Gauche's built-in algorithm (see below for details). 659: When other CES name is given, Gauche uses 660: @code{iconv(3)} if it is linked. 661: @c JP 662: ????ʸ????IS X 0201?Ú¤?IS X 0213?Î¥??󥳡??Ç¥???(EUC_JP??Shift JIS??UTF-8?Ú¤?SO2022-JP) ?Ö¤?Ñ´??˴ؤ??Ƥϡ? 663: Gauche??????Ñ´????르?ꥺ??????Þ¤? (?ܺ٤ϲ???íµ?ò»²¾??? 664: ????????ES?˴ؤ??Ƥϡ?????????????Gauche??code{iconv(3)}????????????Þ¤??? 665: @c COMMON 666: 667: @c EN 668: When Gauche's conversion routine encounters a character that can't 669: be mapped, it replaces the character for "geta mark" (U+3013) 670: if it's a multibyte character in the input encoding, or for '?' if it's 671: a singlebyte character in the input encoding. 672: If that happens in iconv, handling of such character depends 673: on iconv implementation (glibc implementation returns an error). 674: @c JP 675: ???ES?إޥå?Ô²??????ʸ?????????Gauche??Ñ´??롼???????????CES?Ç¥Þ¥??Ð¥??ȤǤ?????geta mark '??' (U+3013) ?Ë¡? 676: ??CES?Ç¥??ó¥°¥????ȤǤ????? '?' ??Ö´????Þ¤??? 677: iconv?ˤ?????ǥޥå?Ô²?????????????ν???conv?μ????????Þ¤?(?????libc?Ǥϥ??顼?Ȥʤ???)?? 678: @c COMMON 679: 680: @c EN 681: If the conversion routine encounters an input sequence that 682: is illegal in the input CES, an error is signalled. 683: @c JP 684: ????롼??󤬡???CES?Ȥ?????????ʸ???в?????????顼????𤵤????? 685: @c COMMON 686: 687: @c EN 688: @strong{Details of Gauche's native conversion algorithm:} 689: Between EUC_JP, Shift JIS and ISO2022JP, Gauche uses arithmetic 690: conversion whenever possible. This even maps the undefined codepoint 691: properly. Between Unicode (UTF-8) and EUC_JP, Gauche uses lookup tables. 692: Between Unicode and Shift JIS or ISO2022JP, Gauche converts the 693: input CES to EUC_JP, then convert it to the output CES. 694: If the same CES is specified for input and output, Gauche's conversion 695: routine just copies input characters to output characters, without 696: checking the validity of the encodings. 697: @c JP 698: @strong{Gauche?????????르?ꥺ???ܺ?} 699: EUC_JP??Shift JIS???Ú¤?SO2022JP?Ö¤?Ñ´??ϲ???ʸ¤????ǹԤ??Þ¤??? 700: ʸ?????Î¥????ɥݥ?????????˽??ä?Ñ´????????? 701: Unicode(UTF-8)??UC_JP?Ö¤?Ñ´??ϥơ??Ö¥??Ã¥????åפˤ??ƹԤ??Þ¤??? 702: Unicode??hift JIS?Þ¤???SO2022JP?Ö¤?Ñ´??Ï¡???CES???UC_JP????????????????ES??Ñ´????뤳?Ȥˤ??ƹԤ??Þ¤??? 703: ???Ƚ?Ϥ?ES??Gauche??????르?ꥺ?ब???Ý¡??Ȥ????Ϥ?ù¤·¤«?ä????? 704: Gauche??Ñ´??롼?????󥳡??Ç¥??ó¥°¤?????Ï¥???Ã¥??????? 705: ñ??????Ϥ˥??Ô¡????Þ¤??? 706: @c COMMON 707: 708: @table @code 709: @item EUC_JP, EUCJP, EUCJ, EUC_JISX0213 710: @c EN 711: Covers ASCII, JIS X 0201 kana, JIS X 0212 and JIS X 0213 character sets. 712: JIS X 0212 character set is supported merely because it uses 713: the code region JIS X 0213 doesn't use, and JIS X 0212 characters 714: are not converted properly to Shift JIS and UTF-8. 715: Use JIS X 0213. 716: @c JP 717: ASCII, JIS X 0201???Ê¡?JIS X 0212???Ú¤?IS X 0213ʸ???Ȥò¥«¥Ð¡????Þ¤??? 718: JIS X 0212?Ï¡?ñ??IS X 0213?ȽŤʤ????????ɤ?äƤ??뤿?????Ý¡??????????Þ¤?????¾??ES?ؤ?Ñ´??ϹԤ??ʤ??Τ?????Ʋ??????? 719: ?ʤ???JIS X 0213?λ?Ѥò¤ª¤????ᤷ?Þ¤??? 720: @c COMMON 721: 722: @item SHIFT_JIS, SHIFTJIS, SJIS 723: @c EN 724: Covers Shift_JISX0213, except that 0x5c and 0x7e is mapped to ASCII 725: character set (REVERSE SOLIDUS and TILDE), 726: instead of JIS X 0201 Roman (YEN SIGN and OVERLINE). 727: @c JP 728: Shift_JISX0213?ò¥«¥Ð¡????Þ¤???â????0x5c??x7e?˴ؤ??Ƥ?JIS X 0201 Roman (YEN SIGN??VERLINE) ?ǤϤʤ? 729: ASCII (REVERSE SOLIDUS??ILDE) ?˥ޥåפ??????? 730: @c COMMON 731: 732: @item UTF-8, UTF8 733: @c EN 734: Unicode 3.2. Note that some JIS X 0213 characters are mapped to Extension B 735: (U+20000 and up). 736: Some JIS X 0213 characters are mapped to two 737: unicode characters (one base character plus a combining character). 738: @c JP 739: Unicode 3.2?Ǥ???JIS X 0213?????????Ĥ???xtension B (U+20000?? 740: ?˥ޥåפ???????JIS X 0213????????????Ĥ????Ĥ?nicodeʸ??se character + combining character)?˥ޥåפ??????? 741: @c COMMON 742: 743: @item ISO2022JP, CSISO2022JP, ISO2022JP-1, ISO2022JP-2, ISO2022JP-3 744: @c EN 745: These encodings differ a bit 746: (except ISO2022JP and CSISO2022JP, which are synonyms), but 747: Gauche handles them same. If one of these CES is specified as input, 748: Gauche recognizes escape sequences of any of CES. 749: ISO2022JP-2 defines several non-Japanese escape sequences, and