diff options
Diffstat (limited to 'debian/uncrustify-trinity/uncrustify-trinity-0.78.1/documentation/align-thresholds.txt')
-rw-r--r-- | debian/uncrustify-trinity/uncrustify-trinity-0.78.1/documentation/align-thresholds.txt | 219 |
1 files changed, 0 insertions, 219 deletions
diff --git a/debian/uncrustify-trinity/uncrustify-trinity-0.78.1/documentation/align-thresholds.txt b/debian/uncrustify-trinity/uncrustify-trinity-0.78.1/documentation/align-thresholds.txt deleted file mode 100644 index 5c18039d..00000000 --- a/debian/uncrustify-trinity/uncrustify-trinity-0.78.1/documentation/align-thresholds.txt +++ /dev/null @@ -1,219 +0,0 @@ -------------------------------------------------------------------------------- -Alignment thresholds: - -Alignment threshold are used to prevent aligning of certain text. - -Consider this example when aligning assignments: - - a = 2; - gld.settings[somevariable] = 5; - -Without thresholds, this would result in: - - a = 2; - gld.settings[somevariable] = 5; - -However, this is likely not desired. - -So to handle this, we set a limit on the number of columns that a alignment -may move a token. If we set the threshold to, say, 3 characters, then -the two would not be aligned together because 'a = 2' would have to be moved -by 25 columns. - -Here's a more complicated case: - - a = 1; - bb = 2; - ccc = 3; - dddd = 4; - eeeee = 5; - ffffff = 6; - -In this case, we may want this output: - - a = 1; - bb = 2; - ccc = 3; - dddd = 4; - eeeee = 5; - ffffff = 6; - -But, with a threshold of 3, 'a' and 'ffffff' cannot be aligned together. - -So how should these thresholds be implemented? - -One approach is to use the threshold as the maximum difference between the -current maximum and the new maximum. Using this approach, all 6 lines above -are aligned, because the change for each is 1 column. - -Consider this with a line-span of 3 and a column-threshold of 3. -Note that we'll now need to keep track of the last line processed. -(line and column numbers added for clarity) - - 111111 - 123456789012345 - --------------- -1 | a = 1; -2 | eeeee = 5; -3 | ffffff = 6; - -On line 1, the maxcol is set to 3. -On line 2, the maxcol would be set to 7, except that exceeds the threshold. -On line 3, the maxcol would be set to 8, except that exceeds the threshold. - -So, it ends up with one item in the align stack - line 1. -Then we pick up from where we left off - on line 2. -On line 2, the maxcol is set to 7. -On line 3, the maxcol is set to 8. - -End result: - 111111 - 123456789012345 - --------------- -1 | a = 1; -2 | eeeee = 5; -3 | ffffff = 6; - - -Now lets get tricky. - - 111111 - 123456789012345 - --------------- -1 | a = 1; -2 | eeeee = 5; -3 | ccc = 3; -4 | ffffff = 6; - -How should this be aligned? -I think we need to add another list - a 'skipped' list, that runs in parallel -with the 'aligned' list. - -On line 1, the maxcol is set to 3, added to the aligned list. -On line 2, col exceeds the threshold, so it is added to the skipped list. -On line 3, the maxcol is set to 5, added to the aligned list. -Now, after an item is added to the aligned list, the skipped list must be re-scanned. -We now see that line 2 is only 2 columns different, so it is added and maxcol = 7. -The skipped list is now empty. -On line 4, the maxcol is set to 8, added to the aligned list. - -So the output is: - - 111111 - 123456789012345 - --------------- -1 | a = 1; -2 | eeeee = 5; -3 | ccc = 3; -4 | ffffff = 6; - - -Now for a case where the skipped list is not absorbed: - - 111111 - 123456789012345 - --------------- -1 | a = 1; -2 | iiiiiiiiiiiiieeeee = 5; -3 | ccc = 3; -4 | ffffff = 6; - -On line 1, the maxcol is set to 3, added to the aligned list. -On line 2, col exceeds the threshold, so it is added to the skipped list. -On line 3, the maxcol is set to 5, added to the aligned list. -Skipped list is scanned, nothing moved from the skipped list to the aligned list. -On line 4, the maxcol is set to 8, added to the aligned list. - -So the output is: - - 111111 - 123456789012345 - --------------- -1 | a = 1; -2 | iiiiiiiiiiiiieeeee = 5; -3 | ccc = 3; -4 | ffffff = 6; - -As a reminder, the old system would have produced: - -1 | a = 1; -2 | iiiiiiiiiiiiieeeee = 5; -3 | ccc = 3; -4 | ffffff = 6; - -Which is probably not wanted. - - ---===---===---===---===-- -Absolute thresholds -To get a better grip on what thresholds do the absolute thresholds were introduced. -An absolute threshold means that the item, in this case the assign statement, is never -moved more than the threshold value. - -See the below example: -Relative threshold = 10 - 000000000111111111122222222223 - 123456789012345678901234567890 -1| a = 1 -2| aaaaa = 1 -3| bbbbbbbbbbb = 2 -4| ccccccccccccccccccccc = 3 - -Absolute threshold: - 000000000111111111122222222223 - 123456789012345678901234567890 -1| a = 1 -2| aaaaa = 1 -3| bbbbbbbbbbb = 2 -4| cccccccccccccccccccc = 3 - ---===---===---===---===-- -How to do this generically in the code... - -Easy case - one item per line. - -An AlignStack is used to manage alignment. -Here are the functions and what each of them do: -AlignStack::Start(line_span, col_thresh) -AlignStack::Add(pc) -AlignStack::Flush() -AlignStack::Newline(count) -AlignStack::End() - -For each entry, a sequence number is kept. - -AlignStack::Start(line_span, col_thresh) - - initializes the align and skipped lists - - zero max_column - - zero cur_seqnum - - zero nl_count - -AlignStack::Add(start, seqnum) - - update cur_seqnum, assign to item - - if item column is within threshold - - zero nl_count - - add to the aligned list - - if item column is > max_col - - update max_col - - re-adds all items on the skipped list - - if item column is not within threshold, add to skipped list - -AlignStack::NewLines(count) - - adds count to nl_count - - if nl_count > line_span, call AlignStack::Flush() - -AlignStack::Flush() - - step through all the items in aligned list and align the items to max_column - - keep the seq_num of the last aligned item - - zero max_column - - remove all items with a seq_num < last aligned seq_num - - call AlignStack::Add on all remaining items in the skipped list - -AlignStack::End() - - call AlignStack::Flush - - clear the lists - - free resources, etc - -Example usage: see align_assign function in align_assign.cpp - -Chunk *align_assign(Chunk *first, size_t span, size_t thresh, size_t *p_nl_count); |