Useful API Functions: Unterschied zwischen den Versionen

Aus expecco Wiki (Version 2.x)
Zur Navigation springen Zur Suche springen
 
(122 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
This document lists most useful (and often needed) functions.
This document lists most useful (and most often needed) classes and functions.
Be aware, that there are many more to be found in either the class references or via the builtin class browser.
Be aware, that there are many more to be found in either the class references or via the builtin [[Tools_ClassBrowser/en | class browser]].


== String ==
== [[String API Functions | String]] ==


Strings are sequences of characters. Expecco uses and supports the Unicode encoding standard and supports the whole unicode range. <br>However, not all fonts will contain all characters, resulting in some missing characters being drawn with a replacement char (typically a box-like rectangle) in text windows.<br>The concrete details depend on the operating system and the set of installed fonts.
Reference: [http://live.exept.de/ClassDoc/classDocOf:,String String]
inherits from: [http://live.exept.de/ClassDoc/classDocOf:,CharacterArray CharacterArray]
[http://live.exept.de/ClassDoc/classDocOf:,Collection Collection]


String instances inherit a lot of functionality from String's superclasses: SequenceableCollection and Collection. Thus, all functions found there (enumeration, mapping, filtering, searching etc.) can also be applied to strings.


Read more: [[String_API_Functions|String API Functions]]<br>
Notice: except when written otherwise, all indices are 1-based. Valid indices range from 1 to the string's size.
Reference: [http://live.exept.de/ClassDoc/classDocOf:,String String]

inherits from: [http://live.exept.de/ClassDoc/classDocOf:,CharacterArray CharacterArray] and
=== Accessing ===
[http://live.exept.de/ClassDoc/classDocOf:,SequenceableCollection SequenceableCollection] and [http://live.exept.de/ClassDoc/classDocOf:,Collection Collection]

===== size =====
Returns the number of characters in the string (i.e. the string's length).

''aString'' '''size'''
''aString''.'''size'''() [JS]

Example:
'hello world' size
=> 11

===== at: =====
Returns the character at an index.

''aString'' ''at:'' ''index''
''aString''[ ''índex'' ] [JS]

Example:
'hello world' at:2
=> $e


=== Copying ===

===== copyFrom:to: =====
Copies characters from a start index to an end index.

''aString'' '''copyFrom:''' ''startIndex'' '''to:''' ''endIndex''
''aString''.'''copyFrom_to'''( ''startIndex'', ''endIndex'' ) [JS]

Example:
'hello world' copyFrom:1 to:5.
=> 'hello'

===== copyFrom:count: =====
Copies a number of characters starting at the given index.

''aString'' '''copyFrom:''' ''startIndex'' '''count:''' ''numChars''
''aString''.'''copyFrom_count'''( ''startIndex'', ''numChars'' ) [JS]

Example:
'hello world' copyFrom:7 count:3.
=> 'wor'

===== copyFrom: =====
Copies from the given index to the end.

''aString'' '''copyFrom:''' ''startIndex'''
''aString''.'''copyFrom'''( ''startIndex'' ) [JS]

Example:
'hello world' copyFrom:6.
=> ' world'

===== copyTo: =====
Copies from the start to the given index.

''aString'' '''copyTo:''' ''endIndex''
''aString''.'''copyTo'''( ''endIndex'' ) [JS]

Example:
'hello world' copyTo:6.
=> 'hello '

===== copyLast: =====
Copies the last count characters.

''aString'' '''copyLast:''' ''count''
''aString''.'''copyLast'''( ''count'' ) [JS]

Example:
'hello world' copyLast:4.
=> 'world '

===== copyButFirst: =====
Copies except for the first count characters.

''aString'' '''copyButFirst:''' ''count''
''aString''.'''copyButFirst'''( ''count'' ) [JS]

Example:
'hello world' copyButFirst:4.
=> ' world'

===== copyButLast: =====
Copies except for the last count characters.

''aString'' '''copyButLast:''' ''count''
''aString''.'''copyButLast'''( ''count'' ) [JS]

Example:
'hello world' copyButLast:4.
=> 'hello w'

===== copyBetween:and:caseSensitive: =====
Finds two substrings and copies the part between them.

''aString'' '''copyBetween:''' ''leftString'' '''and:''' ''rightString'' '''caseSensitive:''' ''boolean''
''aString''.'''copyBetween_and_caseSensitive'''( ''leftString'', ''rightString'', ''boolean'' ) [JS]

Example:
'hello small world' copyBetween:'hello' and:'world' caseSensitive:true
=> ' small '

'helloworld' copyBetween:'hello' and:'world' caseSensitive:true
=> ''

'hello small World' copyBetween:'hello' and:'world' caseSensitive:true
=> nil

'hello small World' copyBetween:'hello' and:'world' caseSensitive:false
=> ' small '

===== copyReplaceString:withString: =====
''aString'' '''copyReplaceString:''' ''oldString'' '''withString:''' ''newString''
''aString''.'''copyReplaceString_withString'''( ''oldString'', ''newString'' ) [JS]

Example:
'hello small world' copyReplaceString:'small' withString:'big'
=> ' hello big world '
'hello small world' copyReplaceString:'big' withString:'bigger'
=> ' hello small world '

===== withoutPrefix:[caseSensitive:] =====
If string starts with a prefix-string, return a copy without it. Otherwise return the original string.

''aString'' '''withoutPrefix:''' ''prefixString'' [ '''caseSensitive:''' ''boolean' ]'
''aString''.'''withoutPrefix'''( ''prefixString'' ) [JS]

Example:
'hello small world' withoutPrefix:'hello '
=> ' small world '
'small world' withoutPrefix:'hello '
=> ' small world '

===== withoutSuffix:[caseSensitive:] =====
If string ends with a prefix-string, return a copy without it. Otherwise return the original string.

''aString'' '''withoutSuffix:''' ''suffixString'' [ '''caseSensitive:''' ''boolean' ]'
''aString''.'''withoutSuffix'''( ''suffixString'' ) [JS]

Example:
'hello small world' withoutSuffix:' world'
=> ' hello small'
'hello small' withoutSuffix:' world'
=> ' hello small '

=== Concatenation ===

===== , (comma) =====
''string1'' ''',''' ''string2''
''string1'' '''+''' ''string2'' [JS]

Example:
'hello', ' ' , 'world'
=> 'hello world'

=== Splitting ===

===== splitBy: =====
Splits a string into pieces, given a splitting character.

''aString'' '''splitBy:''' ''aCharacter''

''aString''.'''splitBy'''( ''aCharacter'' ) [JS]

Example:
'hello world here are six words' splitBy: $ <- trailing space here
=> #( 'hello' 'world' 'here' 'are' 'six' 'words')
'hello-world here are six-words' splitBy: $-
=> #( 'hello' 'world here are six' 'words')

===== splitOn: =====
Splits a string into pieces, given a splitter.
The splitter may be a single character, a string or a block, which returns true to split.
This is a more general version of the above "splitBy:", for complex splits.

''aString'' '''splitOn:''' ''aCharacter''
''string1'' '''splitOn:''' ''string2''
''aString'' '''splitOn:''' [ :char | ''<condition-expression on char>'' ]

''aString''.'''splitOn'''( ''aCharacter'' ) [JS]
''string1''.'''splitOn'''( ''string2'' ) [JS]
''aString''.'''splitOn'''( (char) => ''<condition-expression on char>'' ) [JS]

Example:
'hello world here are six words' splitOn: $ <- trailing space here
=> #( 'hello' 'world' 'here' 'are' 'six' 'words')
'hello-world here are six-words' splitOn: $-
=> #( 'hello' 'world here are six' 'words')
'hello world and goodbye world' splitOn: ' and '
=> #( 'hello world' 'goodbye world')
'hello-world, commas and semis; here' splitOn: [:ch | (ch == $,) or:[ ch == $; ]]
=> #( 'hello-world' 'çommas and semis' 'here')
'aWordWithCamelCase' splitOn: [:ch | ch isUppercase ]
=> #( 'a' 'Word' 'With' 'Camel' 'Case')
'aWordWithCamelCase' splitOn: #isUppercase
=> #( 'a' 'Word' 'With' 'Camel' 'Case')
"hello world here are six words".splitOn( $' ' ) <- space character here
=> [ "hello" , "world" , "here" , "are" , "six" , "words" ]
"hello world and goodbye world".splitOn(" and ")
=> [ "hello world" , "goodbye world"]
"hello-world, commas and semis; here".splitOn( (ch) => (ch == $',') || ( ch == $';') )
=> [ "hello-world" , "çommas and semis" , "here"]

=== Case Conversion ===

===== asLowercase =====
''aString1'' '''asLowercase'''
''string1''.'''asLowercase'''() [JS]

Example:
'HELLO' asLowercase
=> 'hello'

===== asUppercase =====
''aString1'' '''asUppercase'''
''string1''.'''asUppercase'''() [JS]

Example:
'hello' asUppercase
=> 'HELLO'

===== asUppercaseFirst =====
''aString1'' '''asUppercaseFirst'''
''string1''.'''asUppercaseFirst'''() [JS]

Example:
'hello' asUppercaseFirst
=> 'Hello'

=== Comparing ===

===== sameAs: =====
Compares two strings, ignoring case.
<br>"caselessEqual:"is an alias which performs the same operation.
''string1'' '''sameAs:''' ''string2''
''string1''.'''sameAs'''( ''string2'' ) [JS]

Example:
'HELLO' sameAs: 'HeLlo'
=> true
'HELxO' sameAs: 'HeLlo'
=> false
'HELLO' caselessEqual: 'HeLlo'
=> true

===== caselessBefore: / caselessAfter: =====
Compare two strings, ignoring case.
''string1'' '''caselessBefore:''' ''string2''
''string1'' '''caselessAfter:''' ''string2''
''string1''.'''caselessBefore'''( ''string2'' ) [JS]
''string1''.'''caselessAfter'''( ''string2'' ) [JS]

Example:
'HELLO' caselessBefore: 'world'
=> true
'bce' caselessBefore: 'abc'
=> false

===== startsWith:[caseSensitive:] =====
Checks if a string starts with another string.
Comes in two variants, one being strict, the other with optional case-insensitivity.

''string1'' '''startsWith:''' ''prefixString''
''string1'' '''startsWith:''' ''prefixString'' '''caseSensitive:''' ''boolean''
''string1''.'''startsWith'''( ''prefixString'' ) [JS]
''string1''.'''startsWith_caseSensitive'''( ''prefixString'', ''boolean'' ) [JS]

Example:
'hello' startsWith: 'hel'
=>true
'Hello' startsWith: 'hel'
=>false
'Hello' startsWith: 'hel' caseSensitive: false
=>true
'Hexlo' startsWith: 'hel' caseSensitive: false
=>false

===== endsWith:[caseSensitive:] =====
Checks if a string ends with another string.
Comes in two variants, one being strict, the other with optional case-insensitivity.

''string1'' '''endsWith:''' ''prefixString''
''string1'' '''endsWith:''' ''prefixString'' '''caseSensitive:''' ''boolean''
''string1''.'''endsWith'''( ''prefixString'' ) [JS]
''string1''.'''endsWith_caseSensitive'''( ''prefixString'', ''boolean'' ) [JS]

Example:
'hello' endsWith: 'lo'
=>true
'Hello' endsWith: 'Lo'
=>false
'Hello' endsWith: 'Lo' caseSensitive: false
=>true
'Hexlo' endsWith: 'LX' caseSensitive: false
=>false


== [[Collection API Functions | Collection]] ==
=== Searching ===


Collection is an abstract class, serving as a superclass for a number of useful concrete classes (such as Set, Dictionary, Tree, SortedCollection, String etc.)
===== indexOf: / lastIndexOf: =====
It is useful to get a feeling of the set of operations provided there (there are a lot!), so you should not have to reinvent the wheel.
Returns the first/last index of an element (a character). Returns 0 if not found.
''aString'' '''indexOf:''' ''aCharacter''
''aString'' '''lastIndexOf:''' ''aCharacter''
''aString''.'''indexOf'''( ''aCharacter'' ) [JS]
''aString''.'''lastIndexOf'''( ''aCharacter'' ) [JS]


Read more: [[Collection_API_Functions|Collection API Functions]]<br>
Example:
Reference: [http://live.exept.de/ClassDoc/classDocOf:,Collection Collection]
'HELLO' indexOf: $L
=> 3
'HELLO' indexOf: $x
=> 0
'HELLO' lastIndexOf: $L
=> 4


== [[Filename API Functions | Filename]] ==
===== indexOf:startingAt: / lastIndexOf:startingAt: =====
Returns the next/previous index of an element (a character) given a search start index .
Returns 0 if not found.
''aString'' '''indexOf:''' ''aCharacter'' '''startingAt:''' ''startIndex''
''aString'' '''lastIndexOf:''' ''aCharacter'' '''startingAt:''' ''startIndex''
''aString''.'''indexOf_startingAt'''( ''aCharacter'', ''startIndex'' ) [JS]
''aString''.'''lastIndexOf_startingAt'''( ''aCharacter'', ''startIndex'' ) [JS]


Although strings could be used to represent file names and pathes, expecco uses instances of a specialized class called "''Filename''" to represent those. Filename instances know about any details of the underlying operating system (such as the directory separator, any naming restrictions etc.) and also provide a number of useful functions for file and directory access. Filename provides a portable representation, so that code can run on both Windows and Unix unchanged (that is: use "/" in filenames when possible. On a Windows machine, these will be replaced internally by "\" characters).
Example:
'HELLO WORLD' indexOf: $O startingAt: 6
=> 8
'HELLO WORLD' indexOf: $x startingAt: 6
=> 0
'HELLO WORLD' indexOf: $L startingAt: 6
=> 0
'HELLO WORLD' lastIndexOf: $O startingAt: 7
=> 5


Read more: [[Filename_API_Functions|Filename API Functions]]<br>
===== indexOfAny:[startingAt:] / lastIndexOfAny:[startingAt:] =====
Reference: [http://live.exept.de/ClassDoc/classDocOf:,Filename Filename]
Similar to the above, but searches for any element in the given argument collection.
This may be a string (of characters) or an array or any other collection of characters.
Returns 0 if not found.
''aString'' '''indexOfAny:''' ''aCollectionOfCharacters'' [ '''startingAt:''' ''startIndex'' ]
''aString'' '''lastIndexOfAny:''' ''aCollectionOfCharacters'' [ '''startingAt:''' ''startIndex'' ]
''aString''.'''indexOfAny'''( ''aCollectionOfCharacters'' ) [JS]
''aString''.'''indexOfAny_startingAt'''( ''aCollectionOfCharacters'', ''startIndex'' ) [JS]
''aString''.'''lastIndexOfAny'''( ''aCollectionOfCharacters'' ) [JS]
''aString''.'''lastIndexOfAny_startingAt'''( ''aCollectionOfCharacters'', ''startIndex'' ) [JS]


== [[Stream API Functions | Stream]] ==
Example:
'HELLO, WORLD' indexOfAny: ',;'
=> 6
'HELLO; WORLD' indexOfAny: ',;'
=> 6
'HELLO; WORLD' indexOfAny: #( $, $; )
=> 6
'HELLO. WORLD' indexOfAny: #( $, $; )
=> 0


Streams can be internal (eg. reading from a String) or external (eg. a file stream, pipe or socket). Streams can be used to read bytewiese, character wise (with optional UTF decoding/encoding) or object-wise.
===== indexOfSeparator / indexOfSeparatorStartingAt: =====
Most uses are with external streams, which are byte or character oriented: FileStream, PipeStream, Socket are examples.
Searches for a whitespace character (Space, Tab, CR or NL).
Returns 0 if not found.
''aString'' '''indexOfSeparator'''
''aString'' '''indexOfSeparatorStartingAt:''' ''startIndex''
''aString''.'''indexOfSeparator'''() [JS]
''aString''.'''indexOfSeparatorStartingAt'''( ''startIndex'' ) [JS]


Read more: [[Stream_API_Functions|Stream API Functions]]<br>
Example:
Reference: [http://live.exept.de/ClassDoc/classDocOf:,Stream Stream]
'HELLO WORLD' indexOfSeparator
=> 6
'HELLO WORLD' indexOfSeparatorStartingAt: 7
=> 0


== [[Number API Functions | Number]] ==
===== indexOfString:[startingAt:] / lastIndexOfString:[startingAt:] =====
Returns the first/last index of an element (a character). Returns 0 if not found.
''aString'' '''indexOfString:''' ''aSubstring'' [ '''startingAt:''' ''startIndex'' ]
''aString'' '''lastIndexOfString:''' ''aSubstring'' [ '''startingAt:''' ''startIndex'' ]
''aString''.'''indexOfString'''( ''aSubstring'' ) [JS]
''aString''.'''lastIndexOfString'''( ''aSubstring'' ) [JS]


Expecco supports a full numeric stack of numbers; both exact (integers and fractions) and inexact (IEEE floats in various precisions). Integer operations do not overflow or loose bits: expecco will automatically choose an appropriate representation to eg. be able to represent huge numbers.
Example:
'HELLO' indexOfString:'LL'
=> 3
'HELLO' indexOfString: 'LX'
=> 0
'HELLO BELLO' lastIndexOfString: 'LL'
=> 9


Read more: [[Number_API_Functions|Number API Functions]]<br>
=== Pattern Matching ===
Reference: [http://live.exept.de/ClassDoc/classDocOf:,Number Number] and its subclasses
[http://live.exept.de/ClassDoc/classDocOf:,Integer Integer],
[http://live.exept.de/ClassDoc/classDocOf:,Float Float],
[http://live.exept.de/ClassDoc/classDocOf:,Fraction Fraction],
[http://live.exept.de/ClassDoc/classDocOf:,FixedPoint ScaledDecimal],
[http://live.exept.de/ClassDoc/classDocOf:,Complex Complex]


===== matches:[caseSensitive:] =====
== [[Date & Time]] ==
Expecco provides a number of time related support classes: TimeDuration, Time, Date and Timestamp (aka. ''TimeAndDate'') for local, UTC and timezone specific. Although timestamps support picosecond precision, current operating systems will only provide milli or microsecond resolution timestamps. However finer resolution values may come from exact measurement devices or be computed in technical/physical processes.
True if a string matches a GLOB match pattern.
''aString'' '''matches:''' ''patternString'' [ '''caseSensitive:''' ''boolean''
''aString''.'''matches'''( ''patternString'' ) [JS]
''aString''.'''matches_caseSensitive'''( ''patternString'', ''boolean'' ) [JS]


Read more: [[Date_and_Time_API_Functions|Date and Time API Functions]]<br>
Example:
Reference: [http://live.exept.de/ClassDoc/classDocOf:,Date Date], [http://live.exept.de/ClassDoc/classDocOf:,Time Time], [http://live.exept.de/ClassDoc/classDocOf:,Timestamp Timestamp], [http://live.exept.de/ClassDoc/classDocOf:,UtcTimestamp UtcTimestamp], [http://live.exept.de/ClassDoc/classDocOf:,TZTimestamp TZTimestamp], [http://live.exept.de/ClassDoc/classDocOf:,TimeDuration TimeDuration].
'HELLO world' matches: 'HE*'
=> true
'HELLO world' matches: 'he*'
=> false
'HELLO world' matches: 'he*' caseSensitive: false
=> true


== [[PhysicalValues/en|Physical Values]] ==
=== Encoding / Decoding ===
Since 20.1, expecco supports an additional framework to represent physical values, such as mass (in kg), length (in meters), velocity, [[PhysicalValues/en#Acceleration|acceleration]], voltage, electric current etc.
<br>Beside being able to do arithmetic as in <code>3.0 kiloMeter / 20 minutes</code> (which gives "2.5 m/s") they can also be used for conversion between metric and imperial unit systems (eg. "<code>10 nauticalMiles asMeters</code>" gives the answer "18520 m" and "<code>15 inches asMilliMeters</code>" returns "381 mm").


Read more: [[PhysicalValues/en|PhysicalValues]]<br>
===== utf8Encoded / utf8Decoded =====
Encode / decode into/from utf8 encoding.
''aString'' '''utf8Encoded'''
''aString''.'''utf8Encoded'''( ) [JS]


== [[Cryptographic_API_Functions/en | Cryptography]] ==
Example:
'&auml;&ouml;&uuml;' utf8Encoded
=> 'äöü'
'&auml;&ouml;&uuml;' utf8Encoded asByteArray
=> #[195 164 195 182 195 188]
'&auml;&ouml;&uuml;' utf8Encoded utf8Decoded
=> '&auml;&ouml;&uuml;'


Algorithms for hashing, encryption and decryption, certificate handling etc.
===== base64Encoded / base64Decoded =====
Encode / decode into/from base64 encoding.
''aString'' '''base64Encoded'''
''aString''.'''base64Encoded'''( ) [JS]


Read more: [[Cryptographic_API_Functions/en|Cryptographic API Functions]]<br>
Example:
'&auml;&ouml;&uuml;' base64Encoded
=> '5Pb8'
'&auml;&ouml;&uuml;' base64Encoded asByteArray
=> #[53 80 98 56]
'&auml;&ouml;&uuml;' base64Encoded base64Decoded
=> '&auml;&ouml;&uuml;'

Aktuelle Version vom 5. Juni 2025, 09:14 Uhr

This document lists most useful (and most often needed) classes and functions. Be aware, that there are many more to be found in either the class references or via the builtin class browser.

String[Bearbeiten]

Strings are sequences of characters. Expecco uses and supports the Unicode encoding standard and supports the whole unicode range.
However, not all fonts will contain all characters, resulting in some missing characters being drawn with a replacement char (typically a box-like rectangle) in text windows.
The concrete details depend on the operating system and the set of installed fonts.

String instances inherit a lot of functionality from String's superclasses: SequenceableCollection and Collection. Thus, all functions found there (enumeration, mapping, filtering, searching etc.) can also be applied to strings.

Read more: String API Functions
Reference: String inherits from: CharacterArray and SequenceableCollection and Collection

Collection[Bearbeiten]

Collection is an abstract class, serving as a superclass for a number of useful concrete classes (such as Set, Dictionary, Tree, SortedCollection, String etc.) It is useful to get a feeling of the set of operations provided there (there are a lot!), so you should not have to reinvent the wheel.

Read more: Collection API Functions
Reference: Collection

Filename[Bearbeiten]

Although strings could be used to represent file names and pathes, expecco uses instances of a specialized class called "Filename" to represent those. Filename instances know about any details of the underlying operating system (such as the directory separator, any naming restrictions etc.) and also provide a number of useful functions for file and directory access. Filename provides a portable representation, so that code can run on both Windows and Unix unchanged (that is: use "/" in filenames when possible. On a Windows machine, these will be replaced internally by "\" characters).

Read more: Filename API Functions
Reference: Filename

Stream[Bearbeiten]

Streams can be internal (eg. reading from a String) or external (eg. a file stream, pipe or socket). Streams can be used to read bytewiese, character wise (with optional UTF decoding/encoding) or object-wise. Most uses are with external streams, which are byte or character oriented: FileStream, PipeStream, Socket are examples.

Read more: Stream API Functions
Reference: Stream

Number[Bearbeiten]

Expecco supports a full numeric stack of numbers; both exact (integers and fractions) and inexact (IEEE floats in various precisions). Integer operations do not overflow or loose bits: expecco will automatically choose an appropriate representation to eg. be able to represent huge numbers.

Read more: Number API Functions
Reference: Number and its subclasses Integer, Float, Fraction, ScaledDecimal, Complex

Date & Time[Bearbeiten]

Expecco provides a number of time related support classes: TimeDuration, Time, Date and Timestamp (aka. TimeAndDate) for local, UTC and timezone specific. Although timestamps support picosecond precision, current operating systems will only provide milli or microsecond resolution timestamps. However finer resolution values may come from exact measurement devices or be computed in technical/physical processes.

Read more: Date and Time API Functions
Reference: Date, Time, Timestamp, UtcTimestamp, TZTimestamp, TimeDuration.

Physical Values[Bearbeiten]

Since 20.1, expecco supports an additional framework to represent physical values, such as mass (in kg), length (in meters), velocity, acceleration, voltage, electric current etc.
Beside being able to do arithmetic as in 3.0 kiloMeter / 20 minutes (which gives "2.5 m/s") they can also be used for conversion between metric and imperial unit systems (eg. "10 nauticalMiles asMeters" gives the answer "18520 m" and "15 inches asMilliMeters" returns "381 mm").

Read more: PhysicalValues

Cryptography[Bearbeiten]

Algorithms for hashing, encryption and decryption, certificate handling etc.

Read more: Cryptographic API Functions


Copyright © 2014-2024 eXept Software AG

Abgerufen von „https://doc.expecco.de/w2.x/index.php?title=Useful_API_Functions&oldid=30678“