Skip to content

Commit b3f5d47

Browse files
JavaScriptDudeJavaScriptDude
authored
Update README.md
1 parent 5c62abf commit b3f5d47

File tree

1 file changed

+73
-37
lines changed

1 file changed

+73
-37
lines changed

‎README.md‎

Lines changed: 73 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,12 @@ cmp_func|Multi column sorting in the model `java.util.Comparator`|Reasonable spe
3636
superfast|NoneType safe sample implementation of multi column sorting as mentioned in [example from python docs](https://docs.python.org/3/howto/sorting.html#sort-stability-and-complex-sorts)|Fastest by orders of magnitude but a bit more complex to write.
3737

3838

39-
39+
<br>
4040

4141
### Dictionary Examples
4242
For data:
4343
```
44-
rows_dict = [
44+
rows_before = [
4545
{'idx': 0, 'name': 'joh', 'grade': 'C', 'attend': 100}
4646
,{'idx': 1, 'name': 'jan', 'grade': 'a', 'attend': 80}
4747
,{'idx': 2, 'name': 'dav', 'grade': 'B', 'attend': 85}
@@ -52,43 +52,74 @@ rows_dict = [
5252
```
5353

5454
### `multisort`
55-
Sort rows_dict by _grade_, descending, then _attend_, ascending and put None first in results:
55+
Sort rows_before by _grade_, descending, then _attend_, ascending and put None first in results:
56+
```
57+
from multisort import multisort, mscol
58+
rows_sorted = multisort(rows_before, [
59+
mscol('grade', reverse=False),
60+
'attend'
61+
])
62+
```
63+
64+
-or- without `mscol`
65+
5666
```
5767
from multisort import multisort
58-
rows_sorted = multisort(rows_dict, [
59-
('grade', reverse=False),
60-
('attend')
68+
rows_sorted = multisort(rows_before, [
69+
('grade', False),
70+
'attend'
6171
])
72+
```
6273

74+
Sort rows_before by _grade_, descending, then _attend_ and call upper() for _grade_:
6375
```
64-
Sort rows_dict by _grade_, descending, then _attend_ and call upper() for _grade_:
76+
from multisort import multisort, mscol
77+
rows_sorted = multisort(rows_before, [
78+
mscol('grade', reverse=False, clean=lambda s: None if s is None else s.upper()),
79+
'attend'
80+
])
81+
```
82+
83+
-or- without `mscol`
6584
```
6685
from multisort import multisort
67-
rows_sorted = multisort(rows_dict, [
68-
mscol('grade', 'reverse'=False, clean=lambda s: None if s is None else s.upper()),
69-
('attend')
86+
rows_sorted = multisort(rows_before, [
87+
('grade', False, lambda s: None if s is None else s.upper()),
88+
'attend'
7089
])
71-
7290
```
91+
92+
7393
`multisort` parameters:
7494
option|dtype|description
7595
---|---|---
7696
`rows`|int or str|Key to access data. int for tuple or list
7797
`spec`|str, int, list|Sort specification. Can be as simple as a column key / index or `mscol`
7898
`reverse`|bool|Reverse order of final sort (defalt = False)
7999

80-
`multisort` spec options:
81-
option|dtype|description
82-
---|---|---
83-
`key`|int or str|Key to access data. int for tuple or list
84-
`reverse`|bool|Reverse sort of column
85-
`clean`|func|Function / lambda to clean the value. These calls can cause a significant slowdown.
86-
`required`|bool|Default True. If false, will substitute None or default if key not found (not applicable for list or tuple rows)
87-
`default`|any|Value to substitute if required==False and key does not exist or None is found. Can be used to achive similar functionality to pandas `na_position`
100+
101+
`spec` entry options:
102+
option|position|dtype|description
103+
---|---|---|---
104+
`key`|0|int or str|Key to access data. int for tuple or list
105+
`reverse`|1|bool|Reverse sort of column
106+
`clean`|2|func|Function / lambda to clean the value. These calls can cause a significant slowdown.
107+
`required`|3|bool|Default True. If false, will substitute None or default if key not found (not applicable for list or tuple rows)
108+
`default`|4|any|Value to substitute if required==False and key does not exist or None is found. Can be used to achive similar functionality to pandas `na_position`
109+
110+
\* `spec` entries can be passed as:
111+
&nbsp;&nbsp;&nbsp;&nbsp;type|description
112+
---|---
113+
&nbsp;&nbsp;&nbsp;&nbsp;`String`|Column name
114+
&nbsp;&nbsp;&nbsp;&nbsp;`tuple`|Tuple of 1 or more `spec` options in their order as listed (see `position`)
115+
&nbsp;&nbsp;&nbsp;&nbsp;`mscol()`|Importable helper to aid in readability. Suggested for three or more of the options.
116+
117+
118+
<br><br>
88119

89120

90121
### `sorted` with `cmp_func`
91-
Sort rows_dict by _grade_, descending, then _attend_ and call upper() for _grade_:
122+
Sort rows_before by _grade_, descending, then _attend_ and call upper() for _grade_:
92123
```
93124
def cmp_student(a,b):
94125
k='grade'; va=a[k]; vb=b[k]
@@ -99,9 +130,11 @@ def cmp_student(a,b):
99130
k='attend'; va=a[k]; vb=b[k];
100131
if va != vb: return -1 if va < vb else 1
101132
return 0
102-
rows_sorted = sorted(rows_dict, key=cmp_func(cmp_student), reverse=True)
133+
rows_sorted = sorted(rows_before, key=cmp_func(cmp_student), reverse=True)
103134
```
104135

136+
<br>
137+
105138
### For reference: `superfast` methodology with list of dicts:
106139
```
107140
def key_grade(student):
@@ -114,6 +147,8 @@ students_sorted = sorted(students, key=key_attend)
114147
students_sorted.sort(key=key_grade, reverse=True)
115148
```
116149

150+
<br>
151+
117152
### Object Examples
118153
For data:
119154
```
@@ -126,7 +161,7 @@ class Student():
126161
def __str__(self): return f"name: {self.name}, grade: {self.grade}, attend: {self.attend}"
127162
def __repr__(self): return self.__str__()
128163
129-
rows_obj = [
164+
rows_before = [
130165
Student(0, 'joh', 'C', 100)
131166
,Student(1, 'jan', 'a', 80)
132167
,Student(2, 'dav', 'B', 85)
@@ -135,13 +170,15 @@ rows_obj = [
135170
,Student(5, 'joe', None, 55)
136171
]
137172
```
173+
<br>
138174

139175
### `multisort`
140-
(Same syntax as with 'dict' example)
176+
(Same syntax as with Dictionary example above)
141177

178+
<br>
142179

143180
### `sorted` with `cmp_func`
144-
Sort rows_obj by _grade_, descending, then _attend_ and call upper() for _grade_:
181+
Sort rows_before by _grade_, descending, then _attend_ and call upper() for _grade_:
145182
```
146183
def cmp_student(a,b):
147184
if a.grade != b.grade:
@@ -151,14 +188,14 @@ def cmp_student(a,b):
151188
if a.attend != b.attend:
152189
return -1 if a.attend < b.attend else 1
153190
return 0
154-
rows_sorted = sorted(rows_obj, key=cmp_func(cmp_student), reverse=True)
191+
rows_sorted = sorted(rows_before, key=cmp_func(cmp_student), reverse=True)
155192
```
156193

157194

158195
### List / Tuple Examples
159196
For data:
160197
```
161-
rows_tuple = [
198+
rows_before = [
162199
(0, 'joh', 'a' , 100)
163200
,(1, 'joe', 'B' , 80)
164201
,(2, 'dav', 'A' , 85)
@@ -169,19 +206,15 @@ rows_tuple = [
169206
(COL_IDX, COL_NAME, COL_GRADE, COL_ATTEND) = range(0,4)
170207
```
171208

209+
<br>
210+
172211
### `multisort`
173-
Sort rows_tuple by _grade_, descending, then _attend_, ascending and put None first in results:
174-
```
175-
from multisort import multisort
176-
rows_sorted = multisort(rows_tuple, [
177-
mscol(COL_GRADE, reverse=False, default='0'),
178-
(COL_ATTEND)
179-
])
212+
(Same syntax as with Dictionary example above)
180213

181-
```
214+
<br>
182215

183216
### `sorted` with `cmp_func`
184-
Sort rows_tuple by _grade_, descending, then _attend_ and call upper() for _grade_:
217+
Sort rows_before by _grade_, descending, then _attend_ and call upper() for _grade_:
185218
```
186219
def cmp_student(a,b):
187220
k=COL_GRADE; va=a[k]; vb=b[k]
@@ -193,10 +226,13 @@ def cmp_student(a,b):
193226
if va != vb:
194227
return -1 if va < vb else 1
195228
return 0
196-
rows_sorted = sorted(rows_tuple, key=cmp_func(cmp_student), reverse=True)
229+
rows_sorted = sorted(rows_before, key=cmp_func(cmp_student), reverse=True)
197230
```
198231

199-
### Tests / Samples
232+
<br><br>
233+
234+
235+
### `multisort` library Test / Sample files (/tests)
200236
Name|Descr|Other
201237
---|---|---
202238
tests/test_multisort.py|multisort unit tests|-

0 commit comments

Comments
 (0)