Skip to content

Commit ce0b19c

Browse files
livecodealilivecodeali
committed
[[ StdMlc ]] Update test file and docs for string and sort
1 parent 9283527 commit ce0b19c

File tree

3 files changed

+165
-71
lines changed

3 files changed

+165
-71
lines changed

‎libscript/src/sort.mlc‎

Lines changed: 68 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -3,38 +3,63 @@ module com.livecode.sort
33
public foreign handler MCSortExecSortListAscendingText(inout Target as list) as undefined binds to "<builtin>"
44
public foreign handler MCSortExecSortListAscendingBinary(inout Target as list) as undefined binds to "<builtin>"
55
public foreign handler MCSortExecSortListAscendingNumeric(inout Target as list) as undefined binds to "<builtin>"
6-
// public foreign handler MCSortExecSortStringListAscendingNumeric(inout Target as list) as undefined binds to "<builtin>"
76
public foreign handler MCSortExecSortListAscendingDateTime(inout Target as list) as undefined binds to "<builtin>"
87
public foreign handler MCSortExecSortListDescendingText(inout Target as list) as undefined binds to "<builtin>"
98
public foreign handler MCSortExecSortListDescendingBinary(inout Target as list) as undefined binds to "<builtin>"
109
public foreign handler MCSortExecSortListDescendingNumeric(inout Target as list) as undefined binds to "<builtin>"
11-
// public foreign handler MCSortExecSortStringListDescendingNumeric(inout Target as list) as undefined binds to "<builtin>"
1210
public foreign handler MCSortExecSortListDescendingDateTime(inout Target as list) as undefined binds to "<builtin>"
1311

1412
--
1513

1614
/*
1715

18-
Summary: Sorts <Target> in ascending order by comparing its elements on a codepoint by codepoint basis.
16+
Summary: Sorts <Target> in ascending text order.
1917
Target: An expression that evaluates to a list of strings.
2018

19+
Example:
20+
variable tTestList as list
21+
put the empty list into tTestList
22+
23+
push "xyz" onto tTestList
24+
push 2 onto tTestList
25+
push "abcd" onto tTestList
26+
push 1 onto tTestList
27+
28+
sort tTestList in ascending order -- tTestList is ["abcd", "xyz", 2, 1]
29+
30+
Description:
31+
Text sort is performed by comparing string elements on a codepoint by codepoint basis. Non-string elements come after all string elements in the sort order. The sort is stable, so that non-string elements are not re-ordered relative to each other.
2132
*/
2233

2334
syntax SortListAscendingText is statement
24-
"sort" <Target: Expression> "in" "ascending" "text" "order"
35+
"sort" <Target: Expression> "in" "ascending" ["text"] "order"
2536
begin
2637
MCSortExecSortListAscendingText(Target)
2738
end syntax
2839

2940
/*
3041

31-
Summary: Sorts <Target> in descending order by comparing its elements on a codepoint by codepoint basis.
42+
Summary: Sorts <Target> in descending text order.
3243
Target: An expression that evaluates to a list of strings.
3344

45+
Example:
46+
variable tTestList as list
47+
put the empty list into tTestList
48+
49+
push "abcd" onto tTestList
50+
push 1 onto tTestList
51+
push "xyz" onto tTestList
52+
push 2 onto tTestList
53+
54+
sort tTestList in descending order -- tTestList is ["xyz", "abcd", 1, 2]
55+
56+
Description:
57+
Text sort is performed by comparing string elements on a codepoint by codepoint basis. Non-string elements come after all string elements in the sort order. The sort is stable, so that non-string elements are not re-ordered relative to each other.
58+
3459
*/
3560

3661
syntax SortListDescendingText is statement
37-
"sort" <Target: Expression> "in" "descending" "text" "order"
62+
"sort" <Target: Expression> "in" "descending" ["text"] "order"
3863
begin
3964
MCSortExecSortListDescendingText(Target)
4065
end syntax
@@ -43,9 +68,11 @@ end syntax
4368

4469
/*
4570

46-
Summary: Sorts <Target> in ascending order by comparing its elements on a byte by byte basis.
71+
Summary: Sorts <Target> in ascending binary order.
4772
Target: An expression that evaluates to a list of binary data.
4873

74+
Description:
75+
Binary sort is performed by comparing data elements on a byte by byte basis. Non-data elements come after all data elements in the sort order. The sort is stable, so that non-data elements are not re-ordered relative to each other.
4976
*/
5077

5178
syntax SortListAscendingBinary is statement
@@ -56,9 +83,11 @@ end syntax
5683

5784
/*
5885

59-
Summary: Sorts <Target> in descending order by comparing its elements on a byte by byte basis.
86+
Summary: Sorts <Target> in descending binary order.
6087
Target: An expression that evaluates to a list of binary data.
6188

89+
Description:
90+
Binary sort is performed by comparing data elements on a byte by byte basis. Non-data elements come after all data elements in the sort order. The sort is stable, so that non-data elements are not re-ordered relative to each other.
6291
*/
6392

6493
syntax SortListDescendingBinary is statement
@@ -71,63 +100,65 @@ end syntax
71100

72101
/*
73102

74-
Summary: Sorts <Target> in ascending order according to the cardinality of its elements.
75-
If <Target> is a list of strings, the elements are ordered according to the number
76-
represented by the largest initial segment of the string that constitutes a decimal number.
77-
If there is no such initial segment, the element is defined to have the minimum value with
78-
respect to the ordering.
79-
Target: An expression that evaluates to a list of numbers, or strings.
103+
Summary: Sorts <Target> in ascending numeric order.
104+
Target: An expression that evaluates to a list of numbers.
105+
106+
Example:
107+
variable tTestList as list
108+
put the empty list into tTestList
109+
110+
push "abcd" onto tTestList
111+
push 1 onto tTestList
112+
push "xyz" onto tTestList
113+
push 2 onto tTestList
80114

115+
sort tTestList in ascending numeric order -- tTestList is [1, 2, "abcd", "xyz"]
116+
117+
Description:
118+
Numeric sort is performed by comparing numeric elements by cardinality. Non-numeric elements come after all numeric elements in the sort order. The sort is stable, so that non-numeric elements are not re-ordered relative to each other.
81119
*/
82120

83121
syntax SortListAscendingNumeric is statement
84122
"sort" <Target: Expression> "in" "ascending" "numeric" "order"
85123
begin
86124
MCSortExecSortListAscendingNumeric(Target)
87-
// MCSortExecSortStringListAscendingNumeric(Target)
88125
end syntax
89126

90127
/*
91128

92-
Summary: Sorts <Target> in descending order according to the standard total ordering on real numbers.
93-
If <Target> is a list of strings, the elements are ordered according to the number
94-
represented by the largest initial segment of the string that constitutes a decimal number.
95-
If there is no such initial segment, the element is defined to have the minimum value with
96-
respect to the ordering.
97-
Target: An expression that evaluates to a list of numbers, or strings.
129+
Summary: Sorts <Target> in descending numeric order.
130+
Target: An expression that evaluates to a list of numbers.
131+
132+
Example:
133+
variable tTestList as list
134+
put the empty list into tTestList
135+
136+
push "abcd" onto tTestList
137+
push 1 onto tTestList
138+
push "xyz" onto tTestList
139+
push 2 onto tTestList
140+
141+
sort tTestList in descending numeric order -- tTestList is [2, 1, "abcd", "xyz"]
142+
143+
Description:
144+
Numeric sort is performed by comparing numeric elements by cardinality. Non-numeric elements come after all numeric elements in the sort order. The sort is stable, so that non-numeric elements are not re-ordered relative to each other.
98145

99146
*/
100147

101148
syntax SortListDescendingNumeric is statement
102149
"sort" <Target: Expression> "in" "descending" "numeric" "order"
103150
begin
104151
MCSortExecSortListDescendingNumeric(Target)
105-
// MCSortExecSortStringListDescendingNumeric(Target)
106152
end syntax
107153

108154
--
109155

110-
/*
111-
112-
Summary: Sorts <Target> in ascending chronological order.
113-
Target: An expression that evaluates to a list of datetime elements.
114-
115-
*/
116-
117156
syntax SortListAscendingDateTime is statement
118157
"sort" <Target: Expression> "in" "ascending" "chronological" "order"
119158
begin
120159
MCSortExecSortListAscendingDateTime(Target)
121160
end syntax
122161

123-
/*
124-
125-
Summary: Sorts <Target> in descending chronological order.
126-
Target: An expression that evaluates to a list of datetime elements.
127-
128-
*/
129-
130-
131162
syntax SortListDescendingDateTime is statement
132163
"sort" <Target: Expression> "in" "descending" "chronological" "order"
133164
begin
@@ -136,27 +167,4 @@ end syntax
136167

137168
--
138169

139-
// When we have paramaterised list type, this can select based on runtime type.
140-
// For now, default is text.
141-
142-
syntax SortListAscending is statement
143-
"sort" <Target: Expression> ["in" "ascending" "order"]
144-
begin
145-
MCSortExecSortListAscendingText(Target)
146-
// MCSortExecSortListAscendingBinary(Target)
147-
// MCSortExecSortListAscendingNumeric(Target)
148-
// MCSortExecSortListAscendingDateTime(Target)
149-
end syntax
150-
151-
syntax SortListDescending is statement
152-
"sort" <Target: Expression> "in" "descending" "order"
153-
begin
154-
MCSortExecSortListDescendingText(Target)
155-
// MCSortExecSortListDescendingBinary(Target)
156-
// MCSortExecSortListDescendingNumeric(Target)
157-
// MCSortExecSortListDescendingDateTime(Target)
158-
end syntax
159-
160-
--
161-
162170
end module

‎libscript/src/string.mlc‎

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,6 @@ Summary: Prepends <Source> to <Target>.
4242
Source: An expression which evaluates to a string.
4343
Target: An expression which evaluates to a string container.
4444

45-
Example: put tPrefix before tString
4645
*/
4746

4847
syntax PutStringBefore is statement
@@ -57,7 +56,6 @@ Summary: Appends <Source> to <Target>.
5756
Source: An expression which evaluates to a string.
5857
Target: An expression which evaluates to a string container.
5958

60-
Example: put tSuffix after tString
6159
*/
6260

6361
syntax PutStringAfter is statement
@@ -75,7 +73,13 @@ Source: An expression which evaluates to a string.
7573
Target: An expression which evaluates to a string container.
7674
Replacement: An expression which evaluates to a string.
7775

78-
Example: replace " " with "_" in tString
76+
Example:
77+
variable tString as string
78+
put "purple" into tString
79+
replace "p" with "t" in tString -- tString is "turtle"
80+
81+
Description:
82+
Replaces each occurrence of the string <Pattern> in <Target> with <Replacement>.
7983
*/
8084

8185
syntax ReplaceString is statement
@@ -91,9 +95,11 @@ Summary: Concatenates <Left> and <Right>.
9195

9296
Left: An expression which evaluates to a string.
9397
Right: An expression which evaluates to a string.
94-
output: String consisting of the value of the left hand expression with the value of the right hand expression appended to the end.
98+
output: The result of concatenating <Left> and <Right>.
99+
100+
Description:
101+
The result consists of the chars of <Left> followed by those of <Right>.
95102

96-
Example: put tLeft & tRight into tConcatenated
97103
*/
98104

99105
syntax ConcatenateStrings is left binary operator with precedence 2
@@ -107,9 +113,10 @@ Summary: Concatenates <Left> and <Right> with a space between.
107113

108114
Left: An expression which evaluates to a string.
109115
Right: An expression which evaluates to a string.
110-
output: String consisting of the value of the left hand expression with the value of the right hand expression appended to the end, and a space character inserted between them
116+
output: The result of concatenating <Left> and <Right> with a space between.
111117

112-
Example: put tLeft && tRight into tConcatSpace
118+
Description:
119+
The result consists of the chars of <Left> followed by a space, and then the chars of <Right>.
113120
*/
114121

115122
syntax ConcatenateStringsWithSpace is left binary operator with precedence 2
@@ -123,7 +130,10 @@ end syntax
123130
/*
124131
Summary: Uppercases <Source>.
125132
Source: An expression which evaluates to a string.
126-
output:
133+
output: <Source> with each of its chars uppercased.
134+
135+
Description:
136+
127137
*/
128138

129139

@@ -136,7 +146,9 @@ end syntax
136146
/*
137147
Summary: Lowercases <Source>.
138148
Source: An expression which evaluates to a string.
139-
output:
149+
output: <Source> with each of its chars lowercased.
150+
151+
Description:
140152
*/
141153

142154

@@ -175,7 +187,7 @@ output: Returns false if the result of evaluating <Left> is the same as that
175187
*/
176188

177189
syntax IsNotEqualTo is neutral binary operator with precedence 1
178-
<Left: Expression> "is not" <Right: Expression>
190+
<Left: Expression> "is" "not" <Right: Expression>
179191
begin
180192
MCStringEvalIsNotEqualTo(Left, Right, output)
181193
end syntax

0 commit comments

Comments
 (0)