1@menu 2* Introduction to String Processing:: 3* Input and Output:: 4* Characters:: 5* String Processing:: 6* Octets and Utilities for Cryptography:: 7@end menu 8 9@c ----------------------------------------------------------------------------- 10@c ----------------------------------------------------------------------------- 11@node Introduction to String Processing, Input and Output, stringproc-pkg, stringproc-pkg 12@section Introduction to String Processing 13 14The package @code{stringproc} contains functions for processing strings 15and characters including formatting, encoding and data streams. 16This package is completed by some tools for cryptography, e.g. base64 and hash 17functions. 18 19It can be directly loaded via @code{load(stringproc)} or automatically by 20using one of its functions. 21 22For questions and bug reports please contact the author. The following 23command prints his e-mail-address. 24 25@code{printf(true, "~@{~a~@}@@gmail.com", split(sdowncase("Volker van Nek")))$} 26 27 28A string is constructed by typing e.g. @code{"Text"}. 29When the option variable @code{stringdisp} is set to @code{false}, which is 30the default, the double quotes won't be printed. 31@ref{stringp} is a test, if an object is a string. 32 33@example 34(%i1) str: "Text"; 35(%o1) Text 36(%i2) stringp(str); 37(%o2) true 38@end example 39 40Characters are represented by a string of length 1. 41@ref{charp} is the corresponding test. 42 43@example 44(%i1) char: "e"; 45(%o1) e 46(%i2) charp(char); 47(%o2) true 48@end example 49 50In Maxima position indices in strings are like in list 1-indexed 51which results to the following consistency. 52 53@example 54(%i1) is(charat("Lisp",1) = charlist("Lisp")[1]); 55(%o1) true 56@end example 57 58A string may contain Maxima expressions. 59These can be parsed with @ref{parse_string}. 60 61@example 62(%i1) map(parse_string, ["42" ,"sqrt(2)", "%pi"]); 63(%o1) [42, sqrt(2), %pi] 64(%i2) map('float, %); 65(%o2) [42.0, 1.414213562373095, 3.141592653589793] 66@end example 67 68Strings can be processed as characters or in binary form as octets. 69Functions for conversions are @ref{string_to_octets} and @ref{octets_to_string}. 70Usable encodings depend on the platform, the application and the 71underlying Lisp. 72(The following shows Maxima in GNU/Linux, compiled with SBCL.) 73 74@example 75(%i1) obase: 16.$ 76(%i2) string_to_octets("$@pounds{}@euro{}", "cp1252"); 77(%o2) [24, 0A3, 80] 78(%i3) string_to_octets("$@pounds{}@euro{}", "utf-8"); 79(%o3) [24, 0C2, 0A3, 0E2, 82, 0AC] 80@end example 81 82Strings may be written to character streams or as octets to binary streams. 83The following example demonstrates file in and output of characters. 84 85@ref{openw} returns an output stream to a file, 86@ref{printf} writes formatted to that file and by e.g. 87@ref{close} all characters contained in the stream are written to the file. 88 89@example 90(%i1) s: openw("file.txt"); 91(%o1) #<output stream file.txt> 92(%i2) printf(s, "~%~d ~f ~a ~a ~f ~e ~a~%", 9342, 1.234, sqrt(2), %pi, 1.0e-2, 1.0e-2, 1.0b-2)$ 94(%i3) close(s)$ 95@end example 96 97@ref{openr} then returns an input stream from the previously used file and 98@ref{readline} returns the line read as a string. 99The string may be tokenized by e.g. @ref{split} or @ref{tokens} and 100finally parsed by @ref{parse_string}. 101 102@example 103(%i4) s: openr("file.txt"); 104(%o4) #<input stream file.txt> 105(%i5) readline(s); 106(%o5) 42 1.234 sqrt(2) %pi 0.01 1.0E-2 1.0b-2 107(%i6) map(parse_string, split(%)); 108(%o6) [42, 1.234, sqrt(2), %pi, 0.01, 0.01, 1.0b-2] 109(%i7) close(s)$ 110@end example 111 112@opencatbox 113@category{Strings} 114@category{Share packages} 115@category{Package stringproc} 116@closecatbox 117 118 119@c ----------------------------------------------------------------------------- 120@c ----------------------------------------------------------------------------- 121@node Input and Output, Characters, Introduction to String Processing, stringproc-pkg 122@section Input and Output 123 124Example: Formatted printing to a file. 125 126@example 127(%i1) s: openw("file.txt"); 128(%o1) #<output stream file.txt> 129(%i2) control: 130"~2tAn atom: ~20t~a~%~2tand a list: ~20t~@{~r ~@}~%~2t\ 131and an integer: ~20t~d~%"$ 132(%i3) printf( s,control, 'true,[1,2,3],42 )$ 133(%o3) false 134(%i4) close(s); 135(%o4) true 136(%i5) s: openr("file.txt"); 137(%o5) #<input stream file.txt> 138(%i6) while stringp( tmp:readline(s) ) do print(tmp)$ 139 An atom: true 140 and a list: one two three 141 and an integer: 42 142(%i7) close(s)$ 143@end example 144 145@c ----------------------------------------------------------------------------- 146@anchor{close} 147@deffn {Function} close (@var{stream}) 148 149Closes @var{stream} and returns @code{true} if @var{stream} had been open. 150 151@opencatbox 152@category{File input} 153@category{File output} 154@category{Package stringproc} 155@closecatbox 156 157@end deffn 158 159@c ----------------------------------------------------------------------------- 160@anchor{flength} 161@deffn {Function} flength (@var{stream}) 162 163@var{stream} has to be an open stream from or to a file. 164@code{flength} then returns the number of bytes which are currently present in this file. 165 166Example: See @ref{writebyte} . 167 168@opencatbox 169@category{File input} 170@category{File output} 171@category{Package stringproc} 172@closecatbox 173 174@end deffn 175 176@c ----------------------------------------------------------------------------- 177@anchor{flush_output} 178@deffn {Function} flush_output (@var{stream}) 179 180Flushes @var{stream} where @var{stream} has to be an output stream to a file. 181 182Example: See @ref{writebyte} . 183 184@opencatbox 185@category{File output} 186@category{Package stringproc} 187@closecatbox 188 189@end deffn 190 191@c ----------------------------------------------------------------------------- 192@anchor{fposition} 193@deffn {Function} fposition @ 194@fname{fposition} (@var{stream}) @ 195@fname{fposition} (@var{stream}, @var{pos}) 196 197Returns the current position in @var{stream}, if @var{pos} is not used. 198If @var{pos} is used, @code{fposition} sets the position in @var{stream}. 199@var{stream} has to be a stream from or to a file and 200@var{pos} has to be a positive number. 201 202Positions in data streams are like in strings or lists 1-indexed, 203i.e. the first element in @var{stream} is in position 1. 204 205@opencatbox 206@category{File input} 207@category{File output} 208@category{Package stringproc} 209@closecatbox 210 211@end deffn 212 213@c ----------------------------------------------------------------------------- 214@anchor{freshline} 215@deffn {Function} freshline @ 216@fname{freshline} () @ 217@fname{freshline} (@var{stream}) 218 219Writes a new line to the standard output stream 220if the position is not at the beginning of a line und returns @code{true}. 221Using the optional argument @var{stream} the new line is written to that stream. 222There are some cases, where @code{freshline()} does not work as expected. 223 224See also @ref{newline}. 225 226@opencatbox 227@category{File output} 228@category{Package stringproc} 229@closecatbox 230 231@end deffn 232 233@c ----------------------------------------------------------------------------- 234@anchor{get_output_stream_string} 235@deffn {Function} get_output_stream_string (@var{stream}) 236 237Returns a string containing all the characters currently present in 238@var{stream} which must be an open string-output stream. 239The returned characters are removed from @var{stream}. 240 241Example: See @ref{make_string_output_stream} . 242 243@opencatbox 244@category{Package stringproc} 245@closecatbox 246 247@end deffn 248 249@c ----------------------------------------------------------------------------- 250@anchor{make_string_input_stream} 251@deffn {Function} make_string_input_stream @ 252@fname{make_string_input_stream} (@var{string}) @ 253@fname{make_string_input_stream} (@var{string}, @var{start}) @ 254@fname{make_string_input_stream} (@var{string}, @var{start}, @var{end}) 255 256Returns an input stream which contains parts of @var{string} and an end of file. 257Without optional arguments the stream contains the entire string 258and is positioned in front of the first character. 259@var{start} and @var{end} define the substring contained in the stream. 260The first character is available at position 1. 261 262@example 263(%i1) istream : make_string_input_stream("text", 1, 4); 264(%o1) #<string-input stream from "text"> 265(%i2) (while (c : readchar(istream)) # false do sprint(c), newline())$ 266t e x 267(%i3) close(istream)$ 268@end example 269 270@opencatbox 271@category{Package stringproc} 272@closecatbox 273 274@end deffn 275 276@c ----------------------------------------------------------------------------- 277@anchor{make_string_output_stream} 278@deffn {Function} make_string_output_stream () 279 280Returns an output stream that accepts characters. Characters currently present 281in this stream can be retrieved by @ref{get_output_stream_string}. 282 283@example 284(%i1) ostream : make_string_output_stream(); 285(%o1) #<string-output stream 09622ea0> 286(%i2) printf(ostream, "foo")$ 287 288(%i3) printf(ostream, "bar")$ 289 290(%i4) string : get_output_stream_string(ostream); 291(%o4) foobar 292(%i5) printf(ostream, "baz")$ 293 294(%i6) string : get_output_stream_string(ostream); 295(%o6) baz 296(%i7) close(ostream)$ 297@end example 298 299@opencatbox 300@category{Package stringproc} 301@closecatbox 302 303@end deffn 304 305@c ----------------------------------------------------------------------------- 306@anchor{newline} 307@deffn {Function} newline @ 308@fname{newline} () @ 309@fname{newline} (@var{stream}) 310 311Writes a new line to the standard output stream. 312Using the optional argument @var{stream} the new line is written to that stream. 313There are some cases, where @code{newline()} does not work as expected. 314 315See @ref{sprint} for an example of using @code{newline()}. 316 317@opencatbox 318@category{File output} 319@category{Package stringproc} 320@closecatbox 321 322@end deffn 323 324@c ----------------------------------------------------------------------------- 325@anchor{opena} 326@deffn {Function} opena (@var{file}) 327 328Returns a character output stream to @var{file}. 329If an existing file is opened, @code{opena} appends elements at the end of @var{file}. 330 331For binary output see @ref{Functions and Variables for binary input and output, , opena_binary} . 332 333@opencatbox 334@category{File output} 335@category{Package stringproc} 336@closecatbox 337 338@end deffn 339 340@c ----------------------------------------------------------------------------- 341@anchor{openr} 342@deffn {Function} openr @ 343@fname{openr} (@var{file}) @ 344@fname{openr} (@var{file}, @var{encoding}) 345 346 347Returns a character input stream to @var{file}. 348@code{openr} assumes that @var{file} already exists. 349If reading the file results in a lisp error about its encoding 350passing the correct string as the argument @var{encoding} might help. 351The available encodings and their names depend on the lisp being used. 352For sbcl a list of suitable strings can be found at 353@url{http://www.sbcl.org/manual/#External-Formats}. 354 355For binary input see @ref{Functions and Variables for binary input and output, , openr_binary} . 356See also @mref{close} and @mrefdot{openw} 357 358@example 359(%i1) istream : openr("data.txt","EUC-JP"); 360(%o1) #<FD-STREAM for "file /home/gunter/data.txt" @{10099A3AE3@}> 361(%i2) close(istream); 362(%o2) true 363@end example 364 365 366@opencatbox 367@category{File input} 368@category{Package stringproc} 369@closecatbox 370 371@end deffn 372 373@c ----------------------------------------------------------------------------- 374@anchor{openw} 375@deffn {Function} openw (@var{file}) 376 377Returns a character output stream to @var{file}. 378If @var{file} does not exist, it will be created. 379If an existing file is opened, @code{openw} destructively modifies @var{file}. 380 381For binary output see @ref{Functions and Variables for binary input and output, , openw_binary} . 382 383See also @mref{close} and @mrefdot{openr} 384 385@opencatbox 386@category{File output} 387@category{Package stringproc} 388@closecatbox 389 390@end deffn 391 392@c ----------------------------------------------------------------------------- 393@anchor{printf} 394@deffn {Function} printf @ 395@fname{printf} (@var{dest}, @var{string}) @ 396@fname{printf} (@var{dest}, @var{string}, @var{expr_1}, ..., @var{expr_n}) 397 398Produces formatted output by outputting the characters of control-string 399@var{string} and observing that a tilde introduces a directive. 400The character after the tilde, possibly preceded by prefix parameters 401and modifiers, specifies what kind of formatting is desired. 402Most directives use one or more elements of the arguments 403@var{expr_1}, ..., @var{expr_n} to create their output. 404 405If @var{dest} is a stream or @code{true}, then @code{printf} returns @code{false}. 406Otherwise, @code{printf} returns a string containing the output. 407By default the streams @var{stdin}, @var{stdout} and @var{stderr} are defined. 408If maxima is running as a server (which is the normal case if maxima communicating 409with a graphical user interface) @code{setup-client} will define @var{old_stdout} and 410@var{old_stderr}, too. 411 412@code{printf} provides the Common Lisp function @code{format} in Maxima. 413The following example illustrates the general relation between these two 414functions. 415 416@example 417(%i1) printf(true, "R~dD~d~%", 2, 2); 418R2D2 419(%o1) false 420(%i2) :lisp (format t "R~dD~d~%" 2 2) 421R2D2 422NIL 423@end example 424 425The following description is limited to a rough sketch of the possibilities of 426@code{printf}. 427The Lisp function @code{format} is described in detail in many reference books. 428Of good help is e.g. the free available online-manual 429"Common Lisp the Language" by Guy L. Steele. See chapter 22.3.3 there. 430 431@example 432 ~% new line 433 ~& fresh line 434 ~t tab 435 ~$ monetary 436 ~d decimal integer 437 ~b binary integer 438 ~o octal integer 439 ~x hexadecimal integer 440 ~br base-b integer 441 ~r spell an integer 442 ~p plural 443 ~f floating point 444 ~e scientific notation 445 ~g ~f or ~e, depending upon magnitude 446 ~h bigfloat 447 ~a uses Maxima function string 448 ~s like ~a, but output enclosed in "double quotes" 449 ~~ ~ 450 ~< justification, ~> terminates 451 ~( case conversion, ~) terminates 452 ~[ selection, ~] terminates 453 ~@{ iteration, ~@} terminates 454@end example 455 456The directive ~h for bigfloat is no Lisp-standard and is therefore illustrated below. 457 458Note that the directive ~* is not supported. 459 460If @var{dest} is a stream or @code{true}, then @code{printf} returns @code{false}. 461Otherwise, @code{printf} returns a string containing the output. 462 463@example 464(%i1) printf( false, "~a ~a ~4f ~a ~@@r", 465 "String",sym,bound,sqrt(12),144), bound = 1.234; 466(%o1) String sym 1.23 2*sqrt(3) CXLIV 467(%i2) printf( false,"~@{~a ~@}",["one",2,"THREE"] ); 468(%o2) one 2 THREE 469(%i3) printf(true,"~@{~@{~9,1f ~@}~%~@}",mat ), 470 mat = args(matrix([1.1,2,3.33],[4,5,6],[7,8.88,9]))$ 471 1.1 2.0 3.3 472 4.0 5.0 6.0 473 7.0 8.9 9.0 474(%i4) control: "~:(~r~) bird~p ~[is~;are~] singing."$ 475(%i5) printf( false,control, n,n,if n=1 then 1 else 2 ), n=2; 476(%o5) Two birds are singing. 477@end example 478 479The directive ~h has been introduced to handle bigfloats. 480 481@example 482~w,d,e,x,o,p@@H 483 w : width 484 d : decimal digits behind floating point 485 e : minimal exponent digits 486 x : preferred exponent 487 o : overflow character 488 p : padding character 489 @@ : display sign for positive numbers 490@end example 491 492@example 493(%i1) fpprec : 1000$ 494(%i2) printf(true, "|~h|~%", 2.b0^-64)$ 495|0.0000000000000000000542101086242752217003726400434970855712890625| 496(%i3) fpprec : 26$ 497(%i4) printf(true, "|~h|~%", sqrt(2))$ 498|1.4142135623730950488016887| 499(%i5) fpprec : 24$ 500(%i6) printf(true, "|~h|~%", sqrt(2))$ 501|1.41421356237309504880169| 502(%i7) printf(true, "|~28h|~%", sqrt(2))$ 503| 1.41421356237309504880169| 504(%i8) printf(true, "|~28,,,,,'*h|~%", sqrt(2))$ 505|***1.41421356237309504880169| 506(%i9) printf(true, "|~,18h|~%", sqrt(2))$ 507|1.414213562373095049| 508(%i10) printf(true, "|~,,,-3h|~%", sqrt(2))$ 509|1414.21356237309504880169b-3| 510(%i11) printf(true, "|~,,2,-3h|~%", sqrt(2))$ 511|1414.21356237309504880169b-03| 512(%i12) printf(true, "|~20h|~%", sqrt(2))$ 513|1.41421356237309504880169| 514(%i13) printf(true, "|~20,,,,'+h|~%", sqrt(2))$ 515|++++++++++++++++++++| 516@end example 517 518For conversion of objects to strings also see @mrefcomma{concat} @mrefcomma{sconcat} 519@mref{string} and @mrefdot{simplode} 520 521@opencatbox 522@category{File output} 523@category{Package stringproc} 524@closecatbox 525 526@end deffn 527 528@c ----------------------------------------------------------------------------- 529@anchor{readbyte} 530@deffn {Function} readbyte (@var{stream}) 531 532Removes and returns the first byte in @var{stream} which must be a binary input stream. 533If the end of file is encountered @code{readbyte} returns @code{false}. 534 535Example: Read the first 16 bytes from a file encrypted with AES in OpenSSL. 536 537@example 538(%i1) ibase: obase: 16.$ 539 540(%i2) in: openr_binary("msg.bin"); 541(%o2) #<input stream msg.bin> 542(%i3) (L:[], thru 16. do push(readbyte(in), L), L:reverse(L)); 543(%o3) [53, 61, 6C, 74, 65, 64, 5F, 5F, 88, 56, 0DE, 8A, 74, 0FD, 0AD, 0F0] 544(%i4) close(in); 545(%o4) true 546(%i5) map(ascii, rest(L,-8)); 547(%o5) [S, a, l, t, e, d, _, _] 548(%i6) salt: octets_to_number(rest(L,8)); 549(%o6) 8856de8a74fdadf0 550@end example 551 552@opencatbox 553@category{File input} 554@category{Package stringproc} 555@closecatbox 556 557@end deffn 558 559@c ----------------------------------------------------------------------------- 560@anchor{readchar} 561@deffn {Function} readchar (@var{stream}) 562 563Removes and returns the first character in @var{stream}. 564If the end of file is encountered @code{readchar} returns @code{false}. 565 566Example: See @ref{make_string_input_stream}. 567 568@opencatbox 569@category{File input} 570@category{Package stringproc} 571@closecatbox 572 573@end deffn 574 575@c ----------------------------------------------------------------------------- 576@anchor{readline} 577@deffn {Function} readline (@var{stream}) 578 579Returns a string containing all characters starting at the current position 580in @var{stream} up to the end of the line or @code{false} 581if the end of the file is encountered. 582 583@opencatbox 584@category{File input} 585@category{Package stringproc} 586@closecatbox 587 588@end deffn 589 590@c ----------------------------------------------------------------------------- 591@anchor{sprint} 592@deffn {Function} sprint (@var{expr_1}, @dots{}, @var{expr_n}) 593 594Evaluates and displays its arguments one after the other `on a line' starting at 595the leftmost position. The expressions are printed with a space character right next 596to the number, and it disregards line length. 597@code{newline()} might be used for line breaking. 598 599Example: Sequential printing with @code{sprint}. 600Creating a new line with @code{newline()}. 601 602@example 603(%i1) for n:0 thru 19 do sprint(fib(n))$ 6040 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 2584 4181 605(%i2) for n:0 thru 22 do ( 606 sprint(fib(n)), 607 if mod(n,10) = 9 then newline() )$ 6080 1 1 2 3 5 8 13 21 34 60955 89 144 233 377 610 987 1597 2584 4181 6106765 10946 17711 611@end example 612 613@opencatbox 614@category{Package stringproc} 615@closecatbox 616@end deffn 617 618@c ----------------------------------------------------------------------------- 619@anchor{writebyte} 620@deffn {Function} writebyte (@var{byte}, @var{stream}) 621 622Writes @var{byte} to @var{stream} which must be a binary output stream. 623@code{writebyte} returns @code{byte}. 624 625Example: Write some bytes to a binary file output stream. 626In this example all bytes correspond to printable characters and are printed 627by @code{printfile}. 628The bytes remain in the stream until @code{flush_output} or @code{close} have been called. 629 630@example 631(%i1) ibase: obase: 16.$ 632 633(%i2) bytes: map(cint, charlist("GNU/Linux")); 634(%o2) [47, 4E, 55, 2F, 4C, 69, 6E, 75, 78] 635(%i3) out: openw_binary("test.bin"); 636(%o3) #<output stream test.bin> 637(%i4) for i thru 3 do writebyte(bytes[i], out); 638(%o4) done 639(%i5) printfile("test.bin")$ 640 641(%i6) flength(out); 642(%o6) 0 643(%i7) flush_output(out); 644(%o7) true 645(%i8) flength(out); 646(%o8) 3 647(%i9) printfile("test.bin")$ 648GNU 649(%i0A) for b in rest(bytes,3) do writebyte(b, out); 650(%o0A) done 651(%i0B) close(out); 652(%o0B) true 653(%i0C) printfile("test.bin")$ 654GNU/Linux 655@end example 656 657@opencatbox 658@category{File output} 659@category{Package stringproc} 660@closecatbox 661 662@end deffn 663 664@c ----------------------------------------------------------------------------- 665@c ----------------------------------------------------------------------------- 666@node Characters, String Processing, Input and Output, stringproc-pkg 667@section Characters 668 669Characters are strings of length 1. 670 671@c ----------------------------------------------------------------------------- 672@anchor{adjust_external_format} 673@deffn {Function} adjust_external_format () 674 675Prints information about the current external format of the Lisp reader 676and in case the external format encoding differs from the encoding of the 677application which runs Maxima @code{adjust_external_format} tries to adjust 678the encoding or prints some help or instruction. 679@code{adjust_external_format} returns @code{true} when the external format has 680been changed and @code{false} otherwise. 681 682Functions like @ref{cint}, @ref{unicode}, @ref{octets_to_string} 683and @ref{string_to_octets} need UTF-8 as the external format of the 684Lisp reader to work properly over the full range of Unicode characters. 685 686Examples (Maxima on Windows, March 2016): 687Using @code{adjust_external_format} when the default external format 688is not equal to the encoding provided by the application. 689 6901. Command line Maxima 691 692In case a terminal session is preferred it is recommended to use Maxima compiled 693with SBCL. Here Unicode support is provided by default and calls to 694@code{adjust_external_format} are unnecessary. 695 696If Maxima is compiled with CLISP or GCL it is recommended to change 697the terminal encoding from CP850 to CP1252. 698@code{adjust_external_format} prints some help. 699 700CCL reads UTF-8 while the terminal input is CP850 by default. 701CP1252 is not supported by CCL. @code{adjust_external_format} 702prints instructions for changing the terminal encoding and external format 703both to iso-8859-1. 704 7052. wxMaxima 706 707In wxMaxima SBCL reads CP1252 by default but the input from the application 708is UTF-8 encoded. Adjustment is needed. 709 710Calling @code{adjust_external_format} and restarting Maxima 711permanently changes the default external format to UTF-8. 712 713@example 714(%i1)adjust_external_format(); 715The line 716(setf sb-impl::*default-external-format* :utf-8) 717has been appended to the init file 718C:/Users/Username/.sbclrc 719Please restart Maxima to set the external format to UTF-8. 720(%i1) false 721@end example 722 723Restarting Maxima. 724 725@example 726(%i1) adjust_external_format(); 727The external format is currently UTF-8 728and has not been changed. 729(%i1) false 730@end example 731 732@opencatbox 733@category{Package stringproc} 734@closecatbox 735 736@end deffn 737 738@c ----------------------------------------------------------------------------- 739@anchor{alphacharp} 740@deffn {Function} alphacharp (@var{char}) 741 742Returns @code{true} if @var{char} is an alphabetic character. 743 744To identify a non-US-ASCII character as an alphabetic character 745the underlying Lisp must provide full Unicode support. 746E.g. a German umlaut is detected as an alphabetic character with SBCL in GNU/Linux 747but not with GCL. 748(In Windows Maxima, when compiled with SBCL, must be set to UTF-8. 749See @ref{adjust_external_format} for more.) 750 751Example: Examination of non-US-ASCII characters. 752 753The underlying Lisp (SBCL, GNU/Linux) is able to convert the typed character 754into a Lisp character and to examine. 755 756@example 757(%i1) alphacharp("@"u"); 758(%o1) true 759@end example 760 761In GCL this is not possible. An error break occurs. 762 763@example 764(%i1) alphacharp("u"); 765(%o1) true 766(%i2) alphacharp("@"u"); 767 768package stringproc: @"u cannot be converted into a Lisp character. 769 -- an error. 770@end example 771 772@opencatbox 773@category{Predicate functions} 774@category{Package stringproc} 775@closecatbox 776 777@end deffn 778 779@c ----------------------------------------------------------------------------- 780@anchor{alphanumericp} 781@deffn {Function} alphanumericp (@var{char}) 782 783Returns @code{true} if @var{char} is an alphabetic character or a digit 784(only corresponding US-ASCII characters are regarded as digits). 785 786Note: See remarks on @ref{alphacharp}. 787 788@opencatbox 789@category{Predicate functions} 790@category{Package stringproc} 791@closecatbox 792 793@end deffn 794 795@c ----------------------------------------------------------------------------- 796@anchor{ascii} 797@deffn {Function} ascii (@var{int}) 798 799Returns the US-ASCII character corresponding to the integer @var{int} 800which has to be less than @code{128}. 801 802See @ref{unicode} for converting code points larger than @code{127}. 803 804Examples: 805 806@example 807(%i1) for n from 0 thru 127 do ( 808 ch: ascii(n), 809 if alphacharp(ch) then sprint(ch), 810 if n = 96 then newline() )$ 811A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 812a b c d e f g h i j k l m n o p q r s t u v w x y z 813@end example 814 815@opencatbox 816@category{Package stringproc} 817@closecatbox 818 819@end deffn 820 821@c ----------------------------------------------------------------------------- 822@anchor{cequal} 823@deffn {Function} cequal (@var{char_1}, @var{char_2}) 824 825Returns @code{true} if @var{char_1} and @var{char_2} are the same character. 826 827@opencatbox 828@category{Predicate functions} 829@category{Package stringproc} 830@closecatbox 831 832@end deffn 833 834@c ----------------------------------------------------------------------------- 835@anchor{cequalignore} 836@deffn {Function} cequalignore (@var{char_1}, @var{char_2}) 837 838Like @code{cequal} but ignores case which is only possible for non-US-ASCII 839characters when the underlying Lisp is able to recognize a character as an 840alphabetic character. See remarks on @ref{alphacharp}. 841 842@opencatbox 843@category{Predicate functions} 844@category{Package stringproc} 845@closecatbox 846 847@end deffn 848 849@c ----------------------------------------------------------------------------- 850@anchor{cgreaterp} 851@deffn {Function} cgreaterp (@var{char_1}, @var{char_2}) 852 853Returns @code{true} if the code point of @var{char_1} is greater than the 854code point of @var{char_2}. 855 856@opencatbox 857@category{Predicate functions} 858@category{Package stringproc} 859@closecatbox 860 861@end deffn 862 863@c ----------------------------------------------------------------------------- 864@anchor{cgreaterpignore} 865@deffn {Function} cgreaterpignore (@var{char_1}, @var{char_2}) 866 867Like @code{cgreaterp} but ignores case which is only possible for non-US-ASCII 868characters when the underlying Lisp is able to recognize a character as an 869alphabetic character. See remarks on @ref{alphacharp}. 870 871@opencatbox 872@category{Predicate functions} 873@category{Package stringproc} 874@closecatbox 875 876@end deffn 877 878@c ----------------------------------------------------------------------------- 879@anchor{charp} 880@deffn {Function} charp (@var{obj}) 881 882Returns @code{true} if @var{obj} is a Maxima-character. 883See introduction for example. 884 885@opencatbox 886@category{Predicate functions} 887@category{Package stringproc} 888@closecatbox 889 890@end deffn 891 892@c ----------------------------------------------------------------------------- 893@anchor{cint} 894@deffn {Function} cint (@var{char}) 895 896Returns the Unicode code point of @var{char} which must be a 897Maxima character, i.e. a string of length @code{1}. 898 899Examples: The hexadecimal code point of some characters 900(Maxima with SBCL on GNU/Linux). 901 902@example 903(%i1) obase: 16.$ 904(%i2) map(cint, ["$","@pounds{}","@euro{}"]); 905(%o2) [24, 0A3, 20AC] 906@end example 907 908Warning: It is not possible to enter characters corresponding to code points 909larger than 16 bit in wxMaxima with SBCL on Windows when the external format 910has not been set to UTF-8. See @ref{adjust_external_format}. 911 912@c Command @U not supported by texinfo 5. 913@c @example 914@c (%i3) cint("@U{1d538}"); 915@c (%o3) 1D538 916@c @end example 917 918CMUCL doesn't process these characters as one character. 919@code{cint} then returns @code{false}. 920@c Converting to UTF-8-octets and finally to Unicode serves as a workaround. 921Converting a character to a code point via UTF-8-octets may serve as a workaround: 922 923@code{utf8_to_unicode(string_to_octets(character));} 924 925@c Command @U not supported by texinfo 5. 926@c @example 927@c (%i4) utf8_to_unicode(string_to_octets("@U{1d538}")); 928@c (%o4) 1D538 929@c @end example 930 931See @ref{utf8_to_unicode}, @ref{string_to_octets}. 932 933@opencatbox 934@category{Package stringproc} 935@closecatbox 936 937@end deffn 938 939@c ----------------------------------------------------------------------------- 940@anchor{clessp} 941@deffn {Function} clessp (@var{char_1}, @var{char_2}) 942 943Returns @code{true} if the code point of @var{char_1} is less than the 944code point of @var{char_2}. 945 946@opencatbox 947@category{Predicate functions} 948@category{Package stringproc} 949@closecatbox 950 951@end deffn 952 953@c ----------------------------------------------------------------------------- 954@anchor{clesspignore} 955@deffn {Function} clesspignore (@var{char_1}, @var{char_2}) 956 957Like @code{clessp} but ignores case which is only possible for non-US-ASCII 958characters when the underlying Lisp is able to recognize a character as an 959alphabetic character. See remarks on @ref{alphacharp}. 960 961@opencatbox 962@category{Predicate functions} 963@category{Package stringproc} 964@closecatbox 965 966@end deffn 967 968@c ----------------------------------------------------------------------------- 969@anchor{constituent} 970@deffn {Function} constituent (@var{char}) 971 972Returns @code{true} if @var{char} is a graphic character but not a space character. 973A graphic character is a character one can see, plus the space character. 974(@code{constituent} is defined by Paul Graham. 975See Paul Graham, ANSI Common Lisp, 1996, page 67.) 976 977@example 978(%i1) for n from 0 thru 255 do ( 979tmp: ascii(n), if constituent(tmp) then sprint(tmp) )$ 980! " # % ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @@ A B 981C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c 982d e f g h i j k l m n o p q r s t u v w x y z @{ | @} ~ 983@end example 984 985@opencatbox 986@category{Predicate functions} 987@category{Package stringproc} 988@closecatbox 989 990@end deffn 991 992@c ----------------------------------------------------------------------------- 993@c @deffn {Function} cunlisp (@var{lisp_char}) 994@c Converts a Lisp-character into a Maxima-character. 995@c (You won't need it.) 996@c 997@c @opencatbox 998@c @category{Package stringproc} 999@c @closecatbox 1000@c 1001@c @end deffn 1002 1003@c ----------------------------------------------------------------------------- 1004@anchor{digitcharp} 1005@deffn {Function} digitcharp (@var{char}) 1006 1007Returns @code{true} if @var{char} is a digit where only the corresponding 1008US-ASCII-character is regarded as a digit. 1009 1010@opencatbox 1011@category{Predicate functions} 1012@category{Package stringproc} 1013@closecatbox 1014 1015@end deffn 1016 1017@c ----------------------------------------------------------------------------- 1018@c @deffn {Function} lcharp (@var{obj}) 1019@c Returns @code{true} if @var{obj} is a Lisp-character. 1020@c (You won't need it.) 1021@c 1022@c @opencatbox 1023@c @category{Predicate functions} 1024@c @category{Package stringproc} 1025@c @closecatbox 1026@c 1027@c @end deffn 1028 1029@c ----------------------------------------------------------------------------- 1030@anchor{lowercasep} 1031@deffn {Function} lowercasep (@var{char}) 1032 1033Returns @code{true} if @var{char} is a lowercase character. 1034 1035Note: See remarks on @ref{alphacharp}. 1036 1037@opencatbox 1038@category{Predicate functions} 1039@category{Package stringproc} 1040@closecatbox 1041 1042@end deffn 1043 1044@c ----------------------------------------------------------------------------- 1045@anchor{newline_variable} 1046@defvr {Variable} newline 1047 1048The newline character (ASCII-character 10). 1049 1050@opencatbox 1051@category{Global variables} 1052@category{Package stringproc} 1053@closecatbox 1054 1055@end defvr 1056 1057@c ----------------------------------------------------------------------------- 1058@anchor{space_variable} 1059@defvr {Variable} space 1060 1061The space character. 1062 1063@opencatbox 1064@category{Global variables} 1065@category{Package stringproc} 1066@closecatbox 1067 1068@end defvr 1069 1070@c ----------------------------------------------------------------------------- 1071@anchor{tab_variable} 1072@defvr {Variable} tab 1073 1074The tab character. 1075 1076@opencatbox 1077@category{Global variables} 1078@category{Package stringproc} 1079@closecatbox 1080 1081@end defvr 1082 1083@c ----------------------------------------------------------------------------- 1084@anchor{unicode} 1085@deffn {Function} unicode (@var{arg}) 1086 1087Returns the character defined by @var{arg} which might be a Unicode code point 1088or a name string if the underlying Lisp provides full Unicode support. 1089 1090Example: Characters defined by hexadecimal code points 1091(Maxima with SBCL on GNU/Linux). 1092 1093@example 1094(%i1) ibase: 16.$ 1095(%i2) map(unicode, [24, 0A3, 20AC]); 1096(%o2) [$, @pounds{}, @euro{}] 1097@end example 1098 1099Warning: In wxMaxima with SBCL on Windows it is not possible to convert 1100code points larger than 16 bit to characters when the external format 1101has not been set to UTF-8. See @ref{adjust_external_format} for more information. 1102 1103@c Command @U not supported by texinfo 5. 1104@c @example 1105@c (%i3) unicode(1D538); 1106@c (%o3) @U{1d538} 1107@c @end example 1108 1109CMUCL doesn't process code points larger than 16 bit. 1110In these cases @code{unicode} returns @code{false}. 1111@c Converting characters to UTF-8 octets and finally to Unicode serves as a workaround. 1112Converting a code point to a character via UTF-8 octets may serve as a workaround: 1113 1114@code{octets_to_string(unicode_to_utf8(code_point));} 1115 1116@c Command @U not supported by texinfo 5. 1117@c @example 1118@c (%i4) octets_to_string(unicode_to_utf8(1D538)); 1119@c (%o4) @U{1d538} 1120@c @end example 1121 1122See @ref{octets_to_string}, @ref{unicode_to_utf8}. 1123 1124In case the underlying Lisp provides full Unicode support the character might be 1125specified by its name. The following is possible in ECL, CLISP and SBCL, 1126where in SBCL on Windows the external format has to be set to UTF-8. 1127@code{unicode(name)} is supported by CMUCL too but again limited to 16 bit 1128characters. 1129 1130The string argument to @code{unicode} is basically the same string returned by 1131@code{printf} using the "~@@c" specifier. 1132But as shown below the prefix "#\" must be omitted. 1133Underlines might be replaced by spaces and uppercase letters by lowercase ones. 1134 1135Example (continued): Characters defined by names 1136(Maxima with SBCL on GNU/Linux). 1137 1138@example 1139(%i3) printf(false, "~@@c", unicode(0DF)); 1140(%o3) #\LATIN_SMALL_LETTER_SHARP_S 1141(%i4) unicode("LATIN_SMALL_LETTER_SHARP_S"); 1142(%o4) @ss{} 1143(%i5) unicode("Latin small letter sharp s"); 1144(%o5) @ss{} 1145@end example 1146 1147@opencatbox 1148@category{Package stringproc} 1149@closecatbox 1150 1151@end deffn 1152 1153@c ----------------------------------------------------------------------------- 1154@anchor{unicode_to_utf8} 1155@deffn {Function} unicode_to_utf8 (@var{code_point}) 1156 1157Returns a list containing the UTF-8 code corresponding to the Unicode @var{code_point}. 1158 1159Examples: Converting Unicode code points to UTF-8 and vice versa. 1160 1161@example 1162(%i1) ibase: obase: 16.$ 1163(%i2) map(cint, ["$","@pounds{}","@euro{}"]); 1164(%o2) [24, 0A3, 20AC] 1165(%i3) map(unicode_to_utf8, %); 1166(%o3) [[24], [0C2, 0A3], [0E2, 82, 0AC]] 1167(%i4) map(utf8_to_unicode, %); 1168(%o4) [24, 0A3, 20AC] 1169@end example 1170 1171@opencatbox 1172@category{Package stringproc} 1173@closecatbox 1174 1175@end deffn 1176 1177@c ----------------------------------------------------------------------------- 1178@anchor{uppercasep} 1179@deffn {Function} uppercasep (@var{char}) 1180 1181Returns @code{true} if @var{char} is an uppercase character. 1182 1183Note: See remarks on @ref{alphacharp}. 1184 1185@opencatbox 1186@category{Predicate functions} 1187@category{Package stringproc} 1188@closecatbox 1189 1190@end deffn 1191 1192@c ----------------------------------------------------------------------------- 1193@anchor{us_ascii_only} 1194@defvr {Variable} us_ascii_only 1195 1196This option variable affects Maxima when the character encoding 1197provided by the application which runs Maxima is UTF-8 but the 1198external format of the Lisp reader is not equal to UTF-8. 1199 1200On GNU/Linux this is true when Maxima is built with GCL 1201and on Windows in wxMaxima with GCL- and SBCL-builds. 1202With SBCL it is recommended to change the external format to UTF-8. 1203Setting @code{us_ascii_only} is unnecessary then. 1204See @ref{adjust_external_format} for details. 1205 1206@code{us_ascii_only} is @code{false} by default. 1207Maxima itself then (i.e. in the above described situation) parses the UTF-8 encoding. 1208 1209When @code{us_ascii_only} is set to @code{true} it is assumed that all strings 1210used as arguments to string processing functions do not contain Non-US-ASCII characters. 1211Given that promise, Maxima avoids parsing UTF-8 and strings can be processed more efficiently. 1212 1213@opencatbox 1214@category{Global variables} 1215@category{Package stringproc} 1216@closecatbox 1217 1218@end defvr 1219 1220@c ----------------------------------------------------------------------------- 1221@anchor{utf8_to_unicode} 1222@deffn {Function} utf8_to_unicode (@var{list}) 1223 1224Returns a Unicode code point corresponding to the @var{list} which must contain 1225the UTF-8 encoding of a single character. 1226 1227Examples: See @ref{unicode_to_utf8}. 1228 1229@opencatbox 1230@category{Package stringproc} 1231@closecatbox 1232 1233@end deffn 1234 1235@c ----------------------------------------------------------------------------- 1236@c ----------------------------------------------------------------------------- 1237@node String Processing, Octets and Utilities for Cryptography, Characters, stringproc-pkg 1238@section String Processing 1239 1240Position indices in strings are 1-indexed like in Maxima lists. 1241See example in @ref{charat}. 1242 1243@c ----------------------------------------------------------------------------- 1244@anchor{charat} 1245@deffn {Function} charat (@var{string}, @var{n}) 1246 1247Returns the @var{n}-th character of @var{string}. 1248The first character in @var{string} is returned with @var{n} = 1. 1249 1250@example 1251(%i1) charat("Lisp",1); 1252(%o1) L 1253(%i2) charlist("Lisp")[1]; 1254(%o2) L 1255@end example 1256 1257@opencatbox 1258@category{Package stringproc} 1259@closecatbox 1260 1261@end deffn 1262 1263@c ----------------------------------------------------------------------------- 1264@anchor{charlist} 1265@deffn {Function} charlist (@var{string}) 1266 1267Returns the list of all characters in @var{string}. 1268 1269@example 1270(%i1) charlist("Lisp"); 1271(%o1) [L, i, s, p] 1272@end example 1273 1274@opencatbox 1275@category{Package stringproc} 1276@closecatbox 1277 1278@end deffn 1279 1280@c ----------------------------------------------------------------------------- 1281@anchor{eval_string} 1282@deffn {Function} eval_string (@var{str}) 1283 1284Parse the string @var{str} as a Maxima expression and evaluate it. 1285The string @var{str} may or may not have a terminator (dollar sign @code{$} or semicolon @code{;}). 1286Only the first expression is parsed and evaluated, if there is more than one. 1287 1288Complain if @var{str} is not a string. 1289 1290Examples: 1291 1292@example 1293(%i1) eval_string ("foo: 42; bar: foo^2 + baz"); 1294(%o1) 42 1295(%i2) eval_string ("(foo: 42, bar: foo^2 + baz)"); 1296(%o2) baz + 1764 1297@end example 1298 1299See also @ref{parse_string}. 1300 1301@opencatbox 1302@category{Package stringproc} 1303@closecatbox 1304 1305@end deffn 1306 1307@c ----------------------------------------------------------------------------- 1308@anchor{parse_string} 1309@deffn {Function} parse_string (@var{str}) 1310 1311Parse the string @var{str} as a Maxima expression (do not evaluate it). 1312The string @var{str} may or may not have a terminator (dollar sign @code{$} or semicolon @code{;}). 1313Only the first expression is parsed, if there is more than one. 1314 1315Complain if @var{str} is not a string. 1316 1317Examples: 1318 1319@example 1320(%i1) parse_string ("foo: 42; bar: foo^2 + baz"); 1321(%o1) foo : 42 1322(%i2) parse_string ("(foo: 42, bar: foo^2 + baz)"); 1323 2 1324(%o2) (foo : 42, bar : foo + baz) 1325@end example 1326 1327See also @ref{eval_string}. 1328 1329@opencatbox 1330@category{Package stringproc} 1331@closecatbox 1332 1333@end deffn 1334 1335@c ----------------------------------------------------------------------------- 1336@anchor{scopy} 1337@deffn {Function} scopy (@var{string}) 1338 1339Returns a copy of @var{string} as a new string. 1340 1341@opencatbox 1342@category{Package stringproc} 1343@closecatbox 1344 1345@end deffn 1346 1347@c ----------------------------------------------------------------------------- 1348@anchor{sdowncase} 1349@deffn {Function} sdowncase @ 1350@fname{sdowncase} (@var{string}) @ 1351@fname{sdowncase} (@var{string}, @var{start}) @ 1352@fname{sdowncase} (@var{string}, @var{start}, @var{end}) 1353 1354Like @ref{supcase} but uppercase characters are converted to lowercase. 1355 1356@opencatbox 1357@category{Package stringproc} 1358@closecatbox 1359 1360@end deffn 1361 1362@c ----------------------------------------------------------------------------- 1363@anchor{sequal} 1364@deffn {Function} sequal (@var{string_1}, @var{string_2}) 1365 1366Returns @code{true} if @var{string_1} and @var{string_2} contain the same 1367sequence of characters. 1368 1369@opencatbox 1370@category{Predicate functions} 1371@category{Package stringproc} 1372@closecatbox 1373 1374@end deffn 1375 1376@c ----------------------------------------------------------------------------- 1377@anchor{sequalignore} 1378@deffn {Function} sequalignore (@var{string_1}, @var{string_2}) 1379 1380Like @code{sequal} but ignores case which is only possible for non-US-ASCII 1381characters when the underlying Lisp is able to recognize a character as an 1382alphabetic character. See remarks on @ref{alphacharp}. 1383 1384@opencatbox 1385@category{Predicate functions} 1386@category{Package stringproc} 1387@closecatbox 1388 1389@end deffn 1390 1391@c ----------------------------------------------------------------------------- 1392@anchor{sexplode} 1393@deffn {Function} sexplode (@var{string}) 1394 1395@code{sexplode} is an alias for function @code{charlist}. 1396 1397@opencatbox 1398@category{Package stringproc} 1399@closecatbox 1400 1401@end deffn 1402 1403@c ----------------------------------------------------------------------------- 1404@anchor{simplode} 1405@deffn {Function} simplode @ 1406@fname{simplode} (@var{list}) @ 1407@fname{simplode} (@var{list}, @var{delim}) 1408 1409@code{simplode} takes a list of expressions and concatenates them into a string. 1410If no delimiter @var{delim} is specified, @code{simplode} uses no delimiter. 1411@var{delim} can be any string. 1412 1413See also @mrefcomma{concat} @mrefcomma{sconcat} @mref{string} and @mrefdot{printf} 1414 1415Examples: 1416 1417@example 1418(%i1) simplode(["xx[",3,"]:",expand((x+y)^3)]); 1419(%o1) xx[3]:y^3+3*x*y^2+3*x^2*y+x^3 1420(%i2) simplode( sexplode("stars")," * " ); 1421(%o2) s * t * a * r * s 1422(%i3) simplode( ["One","more","coffee."]," " ); 1423(%o3) One more coffee. 1424@end example 1425 1426@opencatbox 1427@category{Package stringproc} 1428@closecatbox 1429 1430@end deffn 1431 1432@c ----------------------------------------------------------------------------- 1433@anchor{sinsert} 1434@deffn {Function} sinsert (@var{seq}, @var{string}, @var{pos}) 1435Returns a string that is a concatenation of @code{substring(@var{string}, 1, @var{pos}-1)}, 1436the string @var{seq} and @code{substring (@var{string}, @var{pos})}. 1437Note that the first character in @var{string} is in position 1. 1438 1439Examples: 1440 1441@example 1442(%i1) s: "A submarine."$ 1443(%i2) concat( substring(s,1,3),"yellow ",substring(s,3) ); 1444(%o2) A yellow submarine. 1445(%i3) sinsert("hollow ",s,3); 1446(%o3) A hollow submarine. 1447@end example 1448 1449@opencatbox 1450@category{Package stringproc} 1451@closecatbox 1452 1453@end deffn 1454 1455@c ----------------------------------------------------------------------------- 1456@anchor{sinvertcase} 1457@deffn {Function} sinvertcase @ 1458@fname{sinvertcase} (@var{string}) @ 1459@fname{sinvertcase} (@var{string}, @var{start}) @ 1460@fname{sinvertcase} (@var{string}, @var{start}, @var{end}) 1461 1462Returns @var{string} except that each character from position @var{start} to @var{end} is inverted. 1463If @var{end} is not given, 1464all characters from @var{start} to the end of @var{string} are replaced. 1465 1466Examples: 1467 1468@example 1469(%i1) sinvertcase("sInvertCase"); 1470(%o1) SiNVERTcASE 1471@end example 1472 1473@opencatbox 1474@category{Package stringproc} 1475@closecatbox 1476 1477@end deffn 1478 1479@c ----------------------------------------------------------------------------- 1480@anchor{slength} 1481@deffn {Function} slength (@var{string}) 1482 1483Returns the number of characters in @var{string}. 1484 1485@opencatbox 1486@category{Package stringproc} 1487@closecatbox 1488 1489@end deffn 1490 1491@c ----------------------------------------------------------------------------- 1492@anchor{smake} 1493@deffn {Function} smake (@var{num}, @var{char}) 1494 1495Returns a new string with a number of @var{num} characters @var{char}. 1496 1497Example: 1498 1499@example 1500(%i1) smake(3,"w"); 1501(%o1) www 1502@end example 1503 1504@opencatbox 1505@category{Package stringproc} 1506@closecatbox 1507 1508@end deffn 1509 1510@c ----------------------------------------------------------------------------- 1511@anchor{smismatch} 1512@deffn {Function} smismatch @ 1513@fname{smismatch} (@var{string_1}, @var{string_2}) @ 1514@fname{smismatch} (@var{string_1}, @var{string_2}, @var{test}) 1515 1516Returns the position of the first character of @var{string_1} at which @var{string_1} and @var{string_2} differ or @code{false}. 1517Default test function for matching is @code{sequal}. 1518If @code{smismatch} should ignore case, use @code{sequalignore} as test. 1519 1520Example: 1521 1522@example 1523(%i1) smismatch("seven","seventh"); 1524(%o1) 6 1525@end example 1526 1527@opencatbox 1528@category{Package stringproc} 1529@closecatbox 1530 1531@end deffn 1532 1533@c ----------------------------------------------------------------------------- 1534@anchor{split} 1535@deffn {Function} split @ 1536@fname{split} (@var{string}) @ 1537@fname{split} (@var{string}, @var{delim}) @ 1538@fname{split} (@var{string}, @var{delim}, @var{multiple}) 1539 1540Returns the list of all tokens in @var{string}. 1541Each token is an unparsed string. 1542@code{split} uses @var{delim} as delimiter. 1543If @var{delim} is not given, the space character is the default delimiter. 1544@var{multiple} is a boolean variable with @code{true} by default. 1545Multiple delimiters are read as one. 1546This is useful if tabs are saved as multiple space characters. 1547If @var{multiple} is set to @code{false}, each delimiter is noted. 1548 1549Examples: 1550 1551@example 1552(%i1) split("1.2 2.3 3.4 4.5"); 1553(%o1) [1.2, 2.3, 3.4, 4.5] 1554(%i2) split("first;;third;fourth",";",false); 1555(%o2) [first, , third, fourth] 1556@end example 1557 1558@opencatbox 1559@category{Package stringproc} 1560@closecatbox 1561 1562@end deffn 1563 1564@c ----------------------------------------------------------------------------- 1565@anchor{sposition} 1566@deffn {Function} sposition (@var{char}, @var{string}) 1567Returns the position of the first character in @var{string} which matches @var{char}. 1568The first character in @var{string} is in position 1. 1569For matching characters ignoring case see @ref{ssearch}. 1570 1571@opencatbox 1572@category{Package stringproc} 1573@closecatbox 1574 1575@end deffn 1576 1577@c ----------------------------------------------------------------------------- 1578@anchor{sremove} 1579@deffn {Function} sremove @ 1580@fname{sremove} (@var{seq}, @var{string}) @ 1581@fname{sremove} (@var{seq}, @var{string}, @var{test}) @ 1582@fname{sremove} (@var{seq}, @var{string}, @var{test}, @var{start}) @ 1583@fname{sremove} (@var{seq}, @var{string}, @var{test}, @var{start}, @var{end}) 1584 1585Returns a string like @var{string} but without all substrings matching @var{seq}. 1586Default test function for matching is @code{sequal}. 1587If @code{sremove} should ignore case while searching for @var{seq}, use @code{sequalignore} as test. 1588Use @var{start} and @var{end} to limit searching. 1589Note that the first character in @var{string} is in position 1. 1590 1591Examples: 1592 1593@example 1594(%i1) sremove("n't","I don't like coffee."); 1595(%o1) I do like coffee. 1596(%i2) sremove ("DO ",%,'sequalignore); 1597(%o2) I like coffee. 1598@end example 1599 1600@opencatbox 1601@category{Package stringproc} 1602@closecatbox 1603 1604@end deffn 1605 1606@c ----------------------------------------------------------------------------- 1607@anchor{sremovefirst} 1608@deffn {Function} sremovefirst @ 1609@fname{sremovefirst} (@var{seq}, @var{string}) @ 1610@fname{sremovefirst} (@var{seq}, @var{string}, @var{test}) @ 1611@fname{sremovefirst} (@var{seq}, @var{string}, @var{test}, @var{start}) @ 1612@fname{sremovefirst} (@var{seq}, @var{string}, @var{test}, @var{start}, @var{end}) 1613 1614Like @code{sremove} except that only the first substring that matches @var{seq} is removed. 1615 1616@opencatbox 1617@category{Package stringproc} 1618@closecatbox 1619 1620@end deffn 1621 1622@c ----------------------------------------------------------------------------- 1623@anchor{sreverse} 1624@deffn {Function} sreverse (@var{string}) 1625 1626Returns a string with all the characters of @var{string} in reverse order. 1627 1628@opencatbox 1629@category{Package stringproc} 1630@closecatbox 1631 1632@end deffn 1633 1634@c ----------------------------------------------------------------------------- 1635@anchor{ssearch} 1636@deffn {Function} ssearch @ 1637@fname{ssearch} (@var{seq}, @var{string}) @ 1638@fname{ssearch} (@var{seq}, @var{string}, @var{test}) @ 1639@fname{ssearch} (@var{seq}, @var{string}, @var{test}, @var{start}) @ 1640@fname{ssearch} (@var{seq}, @var{string}, @var{test}, @var{start}, @var{end}) 1641 1642Returns the position of the first substring of @var{string} that matches the string @var{seq}. 1643Default test function for matching is @code{sequal}. 1644If @code{ssearch} should ignore case, use @code{sequalignore} as test. 1645Use @var{start} and @var{end} to limit searching. 1646Note that the first character in @var{string} is in position 1. 1647 1648Example: 1649 1650@example 1651(%i1) ssearch("~s","~@{~S ~@}~%",'sequalignore); 1652(%o1) 4 1653@end example 1654 1655@opencatbox 1656@category{Package stringproc} 1657@closecatbox 1658 1659@end deffn 1660 1661@c ----------------------------------------------------------------------------- 1662@anchor{ssort} 1663@deffn {Function} ssort @ 1664@fname{ssort} (@var{string}) @ 1665@fname{ssort} (@var{string}, @var{test}) 1666 1667Returns a string that contains all characters from @var{string} in an order such there are no two successive characters @var{c} and @var{d} such that @code{test (@var{c}, @var{d})} is @code{false} and @code{test (@var{d}, @var{c})} is @code{true}. 1668Default test function for sorting is @var{clessp}. 1669The set of test functions is @code{@{clessp, clesspignore, cgreaterp, cgreaterpignore, cequal, cequalignore@}}. 1670 1671Examples: 1672 1673@example 1674(%i1) ssort("I don't like Mondays."); 1675(%o1) '.IMaddeiklnnoosty 1676(%i2) ssort("I don't like Mondays.",'cgreaterpignore); 1677(%o2) ytsoonnMlkIiedda.' 1678@end example 1679 1680@opencatbox 1681@category{Package stringproc} 1682@closecatbox 1683 1684@end deffn 1685 1686@c ----------------------------------------------------------------------------- 1687@anchor{ssubst} 1688@deffn {Function} ssubst @ 1689@fname{ssubst} (@var{new}, @var{old}, @var{string}) @ 1690@fname{ssubst} (@var{new}, @var{old}, @var{string}, @var{test}) @ 1691@fname{ssubst} (@var{new}, @var{old}, @var{string}, @var{test}, @var{start}) @ 1692@fname{ssubst} (@var{new}, @var{old}, @var{string}, @var{test}, @var{start}, @var{end}) 1693 1694Returns a string like @var{string} except that all substrings matching @var{old} are replaced by @var{new}. 1695@var{old} and @var{new} need not to be of the same length. 1696Default test function for matching is @code{sequal}. 1697If @code{ssubst} should ignore case while searching for old, use @code{sequalignore} as test. 1698Use @var{start} and @var{end} to limit searching. 1699Note that the first character in @var{string} is in position 1. 1700 1701Examples: 1702 1703@example 1704(%i1) ssubst("like","hate","I hate Thai food. I hate green tea."); 1705(%o1) I like Thai food. I like green tea. 1706(%i2) ssubst("Indian","thai",%,'sequalignore,8,12); 1707(%o2) I like Indian food. I like green tea. 1708@end example 1709 1710@opencatbox 1711@category{Package stringproc} 1712@closecatbox 1713 1714@end deffn 1715 1716@c ----------------------------------------------------------------------------- 1717@anchor{ssubstfirst} 1718@deffn {Function} ssubstfirst @ 1719@fname{ssubstfirst} (@var{new}, @var{old}, @var{string}) @ 1720@fname{ssubstfirst} (@var{new}, @var{old}, @var{string}, @var{test}) @ 1721@fname{ssubstfirst} (@var{new}, @var{old}, @var{string}, @var{test}, @var{start}) @ 1722@fname{ssubstfirst} (@var{new}, @var{old}, @var{string}, @var{test}, @var{start}, @var{end}) 1723 1724Like @code{subst} except that only the first substring that matches @var{old} is replaced. 1725 1726@opencatbox 1727@category{Package stringproc} 1728@closecatbox 1729 1730@end deffn 1731 1732@c ----------------------------------------------------------------------------- 1733@anchor{strim} 1734@deffn {Function} strim (@var{seq},@var{string}) 1735 1736Returns a string like @var{string}, 1737but with all characters that appear in @var{seq} removed from both ends. 1738 1739Examples: 1740 1741@example 1742(%i1) "/* comment */"$ 1743(%i2) strim(" /*",%); 1744(%o2) comment 1745(%i3) slength(%); 1746(%o3) 7 1747@end example 1748 1749@opencatbox 1750@category{Package stringproc} 1751@closecatbox 1752 1753@end deffn 1754 1755@c ----------------------------------------------------------------------------- 1756@anchor{striml} 1757@deffn {Function} striml (@var{seq}, @var{string}) 1758 1759Like @code{strim} except that only the left end of @var{string} is trimmed. 1760 1761@opencatbox 1762@category{Package stringproc} 1763@closecatbox 1764 1765@end deffn 1766 1767@c ----------------------------------------------------------------------------- 1768@anchor{strimr} 1769@deffn {Function} strimr (@var{seq}, @var{string}) 1770 1771Like @code{strim} except that only the right end of @var{string} is trimmed. 1772 1773@opencatbox 1774@category{Package stringproc} 1775@closecatbox 1776 1777@end deffn 1778 1779@c ----------------------------------------------------------------------------- 1780@anchor{stringp} 1781@deffn {Function} stringp (@var{obj}) 1782 1783Returns @code{true} if @var{obj} is a string. 1784See introduction for example. 1785 1786@opencatbox 1787@category{Predicate functions} 1788@category{Package stringproc} 1789@closecatbox 1790 1791@end deffn 1792 1793@c ----------------------------------------------------------------------------- 1794@anchor{substring} 1795@deffn {Function} substring @ 1796@fname{substring} (@var{string}, @var{start}) @ 1797@fname{substring} (@var{string}, @var{start}, @var{end}) 1798 1799Returns the substring of @var{string} beginning at position @var{start} and ending at position @var{end}. 1800The character at position @var{end} is not included. 1801If @var{end} is not given, the substring contains the rest of the string. 1802Note that the first character in @var{string} is in position 1. 1803 1804Examples: 1805 1806@example 1807(%i1) substring("substring",4); 1808(%o1) string 1809(%i2) substring(%,4,6); 1810(%o2) in 1811@end example 1812 1813@opencatbox 1814@category{Package stringproc} 1815@closecatbox 1816 1817@end deffn 1818 1819@c ----------------------------------------------------------------------------- 1820@anchor{supcase} 1821@deffn {Function} supcase @ 1822@fname{supcase} (@var{string}) @ 1823@fname{supcase} (@var{string}, @var{start}) @ 1824@fname{supcase} (@var{string}, @var{start}, @var{end}) 1825 1826Returns @var{string} except that lowercase characters from position @var{start} to @var{end} are replaced by the corresponding uppercase ones. 1827If @var{end} is not given, 1828all lowercase characters from @var{start} to the end of @var{string} are replaced. 1829 1830Example: 1831 1832@example 1833(%i1) supcase("english",1,2); 1834(%o1) English 1835@end example 1836 1837@opencatbox 1838@category{Package stringproc} 1839@closecatbox 1840 1841@end deffn 1842 1843@c ----------------------------------------------------------------------------- 1844@anchor{tokens} 1845@deffn {Function} tokens @ 1846@fname{tokens} (@var{string}) @ 1847@fname{tokens} (@var{string}, @var{test}) 1848 1849Returns a list of tokens, which have been extracted from @var{string}. 1850The tokens are substrings whose characters satisfy a certain test function. 1851If test is not given, @var{constituent} is used as the default test. 1852@code{@{constituent, alphacharp, digitcharp, lowercasep, uppercasep, charp, characterp, alphanumericp@}} is the set of test functions. 1853(The Lisp-version of @code{tokens} is written by Paul Graham. ANSI Common Lisp, 1996, page 67.) 1854 1855Examples: 1856 1857@example 1858(%i1) tokens("24 October 2005"); 1859(%o1) [24, October, 2005] 1860(%i2) tokens("05-10-24",'digitcharp); 1861(%o2) [05, 10, 24] 1862(%i3) map(parse_string,%); 1863(%o3) [5, 10, 24] 1864@end example 1865 1866@opencatbox 1867@category{Package stringproc} 1868@closecatbox 1869 1870@end deffn 1871 1872@c ----------------------------------------------------------------------------- 1873@c ----------------------------------------------------------------------------- 1874@node Octets and Utilities for Cryptography, , String Processing, stringproc-pkg 1875@section Octets and Utilities for Cryptography 1876 1877@c ----------------------------------------------------------------------------- 1878@anchor{base64} 1879@deffn {Function} base64 (@var{arg}) 1880 1881Returns the base64-representation of @var{arg} as a string. 1882The argument @var{arg} may be a string, a non-negative integer or a list of octets. 1883 1884Examples: 1885 1886@example 1887(%i1) base64: base64("foo bar baz"); 1888(%o1) Zm9vIGJhciBiYXo= 1889(%i2) string: base64_decode(base64); 1890(%o2) foo bar baz 1891(%i3) obase: 16.$ 1892(%i4) integer: base64_decode(base64, 'number); 1893(%o4) 666f6f206261722062617a 1894(%i5) octets: base64_decode(base64, 'list); 1895(%o5) [66, 6F, 6F, 20, 62, 61, 72, 20, 62, 61, 7A] 1896(%i6) ibase: 16.$ 1897(%i7) base64(octets); 1898(%o7) Zm9vIGJhciBiYXo= 1899@end example 1900 1901Note that if @var{arg} contains umlauts (resp. octets larger than 127) 1902the resulting base64-string is platform dependend. 1903However the decoded string will be equal to the original. 1904 1905@opencatbox 1906@category{Package stringproc} 1907@closecatbox 1908 1909@end deffn 1910 1911@c ----------------------------------------------------------------------------- 1912@anchor{base64_decode} 1913@deffn {Function} base64_decode @ 1914@fname{base64_decode} (@var{base64-string}) @ 1915@fname{base64_decode} (@var{base64-string}, @var{return-type}) 1916 1917By default @code{base64_decode} decodes the @var{base64-string} back to the original string. 1918 1919The optional argument @var{return-type} allows @code{base64_decode} to 1920alternatively return the corresponding number or list of octets. 1921@var{return-type} may be @code{string}, @code{number} or @code{list}. 1922 1923Example: See @ref{base64}. 1924 1925@opencatbox 1926@category{Package stringproc} 1927@closecatbox 1928 1929@end deffn 1930 1931@c ----------------------------------------------------------------------------- 1932@anchor{crc24sum} 1933@deffn {Function} crc24sum @ 1934@fname{crc24sum} (@var{octets}) @ 1935@fname{crc24sum} (@var{octets}, @var{return-type}) 1936 1937By default @code{crc24sum} returns the @code{CRC24} checksum of an octet-list 1938as a string. 1939 1940The optional argument @var{return-type} allows @code{crc24sum} to 1941alternatively return the corresponding number or list of octets. 1942@var{return-type} may be @code{string}, @code{number} or @code{list}. 1943 1944Example: 1945 1946@example 1947-----BEGIN PGP SIGNATURE----- 1948Version: GnuPG v2.0.22 (GNU/Linux) 1949 1950iQEcBAEBAgAGBQJVdCTzAAoJEG/1Mgf2DWAqCSYH/AhVFwhu1D89C3/QFcgVvZTM 1951wnOYzBUURJAL/cT+IngkLEpp3hEbREcugWp+Tm6aw3R4CdJ7G3FLxExBH/5KnDHi 1952rBQu+I7+3ySK2hpryQ6Wx5J9uZSa4YmfsNteR8up0zGkaulJeWkS4pjiRM+auWVe 1953vajlKZCIK52P080DG7Q2dpshh4fgTeNwqCuCiBhQ73t8g1IaLdhDN6EzJVjGIzam 1954/spqT/sTo6sw8yDOJjvU+Qvn6/mSMjC/YxjhRMaQt9EMrR1AZ4ukBF5uG1S7mXOH 1955WdiwkSPZ3gnIBhM9SuC076gLWZUNs6NqTeE3UzMjDAFhH3jYk1T7mysCvdtIkms= 1956=WmeC 1957-----END PGP SIGNATURE----- 1958@end example 1959 1960@example 1961(%i1) ibase : obase : 16.$ 1962(%i2) sig64 : sconcat( 1963 "iQEcBAEBAgAGBQJVdCTzAAoJEG/1Mgf2DWAqCSYH/AhVFwhu1D89C3/QFcgVvZTM", 1964 "wnOYzBUURJAL/cT+IngkLEpp3hEbREcugWp+Tm6aw3R4CdJ7G3FLxExBH/5KnDHi", 1965 "rBQu+I7+3ySK2hpryQ6Wx5J9uZSa4YmfsNteR8up0zGkaulJeWkS4pjiRM+auWVe", 1966 "vajlKZCIK52P080DG7Q2dpshh4fgTeNwqCuCiBhQ73t8g1IaLdhDN6EzJVjGIzam", 1967 "/spqT/sTo6sw8yDOJjvU+Qvn6/mSMjC/YxjhRMaQt9EMrR1AZ4ukBF5uG1S7mXOH", 1968 "WdiwkSPZ3gnIBhM9SuC076gLWZUNs6NqTeE3UzMjDAFhH3jYk1T7mysCvdtIkms=" )$ 1969(%i3) octets: base64_decode(sig64, 'list)$ 1970(%i4) crc24: crc24sum(octets, 'list); 1971(%o4) [5A, 67, 82] 1972(%i5) base64(crc24); 1973(%o5) WmeC 1974@end example 1975 1976@opencatbox 1977@category{Package stringproc} 1978@closecatbox 1979 1980@end deffn 1981 1982@c ----------------------------------------------------------------------------- 1983@anchor{md5sum} 1984@deffn {Function} md5sum @ 1985@fname{md5sum} (@var{arg}) @ 1986@fname{md5sum} (@var{arg}, @var{return-type}) 1987 1988Returns the @code{MD5} checksum of a string, a non-negative integer or 1989a list of octets. The default return value is a string containing 32 hex characters. 1990 1991The optional argument @var{return-type} allows @code{md5sum} to alternatively 1992return the corresponding number or list of octets. 1993@var{return-type} may be @code{string}, @code{number} or @code{list}. 1994 1995Examples: 1996 1997@example 1998(%i1) ibase: obase: 16.$ 1999(%i2) msg: "foo bar baz"$ 2000(%i3) string: md5sum(msg); 2001(%o3) ab07acbb1e496801937adfa772424bf7 2002(%i4) integer: md5sum(msg, 'number); 2003(%o4) 0ab07acbb1e496801937adfa772424bf7 2004(%i5) octets: md5sum(msg, 'list); 2005(%o5) [0AB,7,0AC,0BB,1E,49,68,1,93,7A,0DF,0A7,72,42,4B,0F7] 2006(%i6) sdowncase( printf(false, "~@{~2,'0x~^:~@}", octets) ); 2007(%o6) ab:07:ac:bb:1e:49:68:01:93:7a:df:a7:72:42:4b:f7 2008@end example 2009 2010Note that in case @var{arg} contains German umlauts or other non-ASCII 2011characters (resp. octets larger than 127) the @code{MD5} checksum is platform dependend. 2012 2013@opencatbox 2014@category{Package stringproc} 2015@closecatbox 2016 2017@end deffn 2018 2019@c ----------------------------------------------------------------------------- 2020@anchor{mgf1_sha1} 2021@deffn {Function} mgf1_sha1 @ 2022@fname{mgf1_sha1} (@var{seed}, @var{len}) @ 2023@fname{mgf1_sha1} (@var{seed}, @var{len}, @var{return-type}) 2024 2025Returns a pseudo random number of variable length. 2026By default the returned value is a number with a length of @var{len} octets. 2027 2028The optional argument @var{return-type} allows @code{mgf1_sha1} to alternatively 2029return the corresponding list of @var{len} octets. 2030@var{return-type} may be @code{number} or @code{list}. 2031 2032The computation of the returned value is described in @code{RFC 3447}, 2033appendix @code{B.2.1 MGF1}. 2034@code{SHA1} ist used as hash function, i.e. the randomness of the computed number 2035relies on the randomness of @code{SHA1} hashes. 2036 2037Example: 2038 2039@example 2040(%i1) ibase: obase: 16.$ 2041(%i2) number: mgf1_sha1(4711., 8); 2042(%o2) 0e0252e5a2a42fea1 2043(%i3) octets: mgf1_sha1(4711., 8, 'list); 2044(%o3) [0E0,25,2E,5A,2A,42,0FE,0A1] 2045@end example 2046 2047@opencatbox 2048@category{Package stringproc} 2049@closecatbox 2050 2051@end deffn 2052 2053@c ----------------------------------------------------------------------------- 2054@anchor{number_to_octets} 2055@deffn {Function} number_to_octets (@var{number}) 2056 2057Returns an octet-representation of @var{number} as a list of octets. 2058The @var{number} must be a non-negative integer. 2059 2060Example: 2061 2062@example 2063(%i1) ibase : obase : 16.$ 2064(%i2) octets: [0ca,0fe,0ba,0be]$ 2065(%i3) number: octets_to_number(octets); 2066(%o3) 0cafebabe 2067(%i4) number_to_octets(number); 2068(%o4) [0CA, 0FE, 0BA, 0BE] 2069@end example 2070 2071@opencatbox 2072@category{Package stringproc} 2073@closecatbox 2074 2075@end deffn 2076 2077@c ----------------------------------------------------------------------------- 2078@anchor{octets_to_number} 2079@deffn {Function} octets_to_number (@var{octets}) 2080 2081Returns a number by concatenating the octets in the list of @var{octets}. 2082 2083Example: See @ref{number_to_octets}. 2084 2085@opencatbox 2086@category{Package stringproc} 2087@closecatbox 2088 2089@end deffn 2090 2091@c ----------------------------------------------------------------------------- 2092@anchor{octets_to_oid} 2093@deffn {Function} octets_to_oid (@var{octets}) 2094 2095Computes an object identifier (OID) from the list of @var{octets}. 2096 2097Example: RSA encryption OID 2098 2099@example 2100(%i1) ibase : obase : 16.$ 2101(%i2) oid: octets_to_oid([2A,86,48,86,0F7,0D,1,1,1]); 2102(%o2) 1.2.840.113549.1.1.1 2103(%i3) oid_to_octets(oid); 2104(%o3) [2A, 86, 48, 86, 0F7, 0D, 1, 1, 1] 2105@end example 2106 2107@opencatbox 2108@category{Package stringproc} 2109@closecatbox 2110 2111@end deffn 2112 2113@c ----------------------------------------------------------------------------- 2114@anchor{octets_to_string} 2115@deffn {Function} octets_to_string @ 2116@fname{octets_to_string} (@var{octets}) @ 2117@fname{octets_to_string} (@var{octets}, @var{encoding}) 2118 2119Decodes the list of @var{octets} into a string according to current system defaults. 2120When decoding octets corresponding to Non-US-ASCII characters 2121the result depends on the platform, application and underlying Lisp. 2122 2123Example: Using system defaults 2124(Maxima compiled with GCL, which uses no format definition and 2125simply passes through the UTF-8-octets encoded by the GNU/Linux terminal). 2126 2127@example 2128(%i1) octets: string_to_octets("abc"); 2129(%o1) [61, 62, 63] 2130(%i2) octets_to_string(octets); 2131(%o2) abc 2132(%i3) ibase: obase: 16.$ 2133(%i4) unicode(20AC); 2134(%o4) @euro{} 2135(%i5) octets: string_to_octets(%); 2136(%o5) [0E2, 82, 0AC] 2137(%i6) octets_to_string(octets); 2138(%o6) @euro{} 2139(%i7) utf8_to_unicode(octets); 2140(%o7) 20AC 2141@end example 2142 2143In case the external format of the Lisp reader is equal to UTF-8 the optional 2144argument @var{encoding} allows to set the encoding for the octet to string conversion. 2145If necessary see @ref{adjust_external_format} for changing the external format. 2146 2147Some names of supported encodings (see corresponding Lisp manual for more): @* 2148CCL, CLISP, SBCL: @code{utf-8, ucs-2be, ucs-4be, iso-8859-1, cp1252, cp850} @* 2149CMUCL: @code{utf-8, utf-16-be, utf-32-be, iso8859-1, cp1252} @* 2150ECL: @code{utf-8, ucs-2be, ucs-4be, iso-8859-1, windows-cp1252, dos-cp850} 2151 2152Example (continued): Using the optional encoding argument 2153(Maxima compiled with SBCL, GNU/Linux terminal). 2154 2155@example 2156(%i8) string_to_octets("@euro{}", "ucs-2be"); 2157(%o8) [20, 0AC] 2158@end example 2159 2160@opencatbox 2161@category{Package stringproc} 2162@closecatbox 2163 2164@end deffn 2165 2166@c ----------------------------------------------------------------------------- 2167@anchor{oid_to_octets} 2168@deffn {Function} oid_to_octets (@var{oid-string}) 2169 2170Convertes an object identifier (OID) to a list of @var{octets}. 2171 2172Example: See @ref{octets_to_oid}. 2173 2174@opencatbox 2175@category{Package stringproc} 2176@closecatbox 2177 2178@end deffn 2179 2180@c ----------------------------------------------------------------------------- 2181@anchor{sha1sum} 2182@deffn {Function} sha1sum @ 2183@fname{sha1sum} (@var{arg}) @ 2184@fname{sha1sum} (@var{arg}, @var{return-type}) 2185 2186Returns the @code{SHA1} fingerprint of a string, a non-negative integer or 2187a list of octets. The default return value is a string containing 40 hex characters. 2188 2189The optional argument @var{return-type} allows @code{sha1sum} to alternatively 2190return the corresponding number or list of octets. 2191@var{return-type} may be @code{string}, @code{number} or @code{list}. 2192 2193Example: 2194 2195@example 2196(%i1) ibase: obase: 16.$ 2197(%i2) msg: "foo bar baz"$ 2198(%i3) string: sha1sum(msg); 2199(%o3) c7567e8b39e2428e38bf9c9226ac68de4c67dc39 2200(%i4) integer: sha1sum(msg, 'number); 2201(%o4) 0c7567e8b39e2428e38bf9c9226ac68de4c67dc39 2202(%i5) octets: sha1sum(msg, 'list); 2203(%o5) [0C7,56,7E,8B,39,0E2,42,8E,38,0BF,9C,92,26,0AC,68,0DE,4C,67,0DC,39] 2204(%i6) sdowncase( printf(false, "~@{~2,'0x~^:~@}", octets) ); 2205(%o6) c7:56:7e:8b:39:e2:42:8e:38:bf:9c:92:26:ac:68:de:4c:67:dc:39 2206@end example 2207 2208Note that in case @var{arg} contains German umlauts or other non-ASCII 2209characters (resp. octets larger than 127) the @code{SHA1} fingerprint is platform dependend. 2210 2211@opencatbox 2212@category{Package stringproc} 2213@closecatbox 2214 2215@end deffn 2216 2217@c ----------------------------------------------------------------------------- 2218@anchor{sha256sum} 2219@deffn {Function} sha256sum @ 2220@fname{sha256sum} (@var{arg}) @ 2221@fname{sha256sum} (@var{arg}, @var{return-type}) 2222 2223Returns the @code{SHA256} fingerprint of a string, a non-negative integer or 2224a list of octets. The default return value is a string containing 64 hex characters. 2225 2226The optional argument @var{return-type} allows @code{sha256sum} to alternatively 2227return the corresponding number or list of octets (see @ref{sha1sum}). 2228 2229Example: 2230 2231@example 2232(%i1) string: sha256sum("foo bar baz"); 2233(%o1) dbd318c1c462aee872f41109a4dfd3048871a03dedd0fe0e757ced57dad6f2d7 2234@end example 2235 2236Note that in case @var{arg} contains German umlauts or other non-ASCII 2237characters (resp. octets larger than 127) the @code{SHA256} fingerprint is platform dependend. 2238 2239@opencatbox 2240@category{Package stringproc} 2241@closecatbox 2242 2243@end deffn 2244 2245@c ----------------------------------------------------------------------------- 2246@anchor{string_to_octets} 2247@deffn {Function} string_to_octets @ 2248@fname{string_to_octets} (@var{string}) @ 2249@fname{string_to_octets} (@var{string}, @var{encoding}) 2250 2251Encodes a @var{string} into a list of octets according to current system defaults. 2252When encoding strings containing Non-US-ASCII characters 2253the result depends on the platform, application and underlying Lisp. 2254 2255In case the external format of the Lisp reader is equal to UTF-8 the optional 2256argument @var{encoding} allows to set the encoding for the string to octet conversion. 2257If necessary see @ref{adjust_external_format} for changing the external format. 2258 2259See @ref{octets_to_string} for examples and some more information. 2260 2261@opencatbox 2262@category{Package stringproc} 2263@closecatbox 2264 2265@end deffn 2266 2267