File Coverage

blib/lib/Text/Levenshtein/Damerau/XS.pm
Criterion Covered Total %
statement 7 7 100.0
branch n/a
condition 2 2 100.0
subroutine 4 4 100.0
pod 1 2 50.0
total 14 15 93.3


line stmt bran cond sub pod time code
1             package Text::Levenshtein::Damerau::XS;
2 3     3   142865 use strict;
  3         4  
  3         66  
3 3     3   72 use 5.008_008;
  3         8  
4              
5             require Exporter;
6            
7             $Text::Levenshtein::Damerau::XS::VERSION = '3.1';
8             @Text::Levenshtein::Damerau::XS::EXPORT_OK = qw/xs_edistance/;
9             @Text::Levenshtein::Damerau::XS::ISA = qw/Exporter/;
10              
11             eval {
12             require XSLoader;
13             XSLoader::load(__PACKAGE__, $Text::Levenshtein::Damerau::XS::VERSION);
14             1;
15             } or do {
16             require DynaLoader;
17             DynaLoader::bootstrap(__PACKAGE__, $Text::Levenshtein::Damerau::XS::VERSION);
18 3     3 0 539 sub dl_load_flags {0} # Prevent DynaLoader from complaining and croaking
19             };
20              
21              
22              
23              
24             sub xs_edistance {
25             # shift shift shift is faster than $_[0] $_[1] $_[2]
26 24   100 24 1 8612 return Text::Levenshtein::Damerau::XS::cxs_edistance( [unpack('U*', shift)], [unpack('U*',shift)], shift || 0);
27             }
28              
29             1;
30              
31             =encoding utf8
32              
33             =head1 NAME
34              
35             Text::Levenshtein::Damerau::XS - XS Damerau Levenshtein edit distance.
36              
37             =head1 SYNOPSIS
38              
39             use Text::Levenshtein::Damerau::XS qw/xs_edistance/;
40              
41             print xs_edistance('Neil','Niel');
42             # prints 1
43              
44             =head1 DESCRIPTION
45              
46             Returns the true Damerau Levenshtein edit distance of strings with adjacent transpositions. XS implementation (requires a C compiler). Works correctly with utf8.
47              
48             use Text::Levenshtein::Damerau::XS qw/xs_edistance/;
49             use utf8;
50              
51             xs_edistance('ⓕⓞⓤⓡ','ⓕⓤⓞⓡ'),
52             # prints 1
53              
54             Speed improvements over L<Text::Levenshtein::Damerau::PP>:
55              
56             # Text::Levenshtein::Damerau::PP::pp_edistance("four","fuor")
57             timethis 1000000: 381 wallclock secs (380.45 usr + 0.01 sys =
58             380.46 CPU) @ 2628.40/s (n=1000000)
59              
60             # Text::Levenshtein::Damerau::XS::xs_edistance("four","fuor")
61             timethis 1000000: 19 wallclock secs (19.43 usr + 0.00 sys =
62             19.43 CPU) @ 51466.80/s (n=1000000)
63              
64             =head1 METHODS
65              
66             =head2 xs_edistance
67              
68             Arguments: source string and target string.
69              
70             =over
71              
72             =item * I<OPTIONAL 3rd argument> int (max distance; only return results with $int distance or less). 0 = unlimited. Default = 0.
73              
74             =back
75              
76             Returns: int that represents the edit distance between the two argument. Stops calculations and returns -1 if max distance is set and reached.
77              
78             Wrapper function to take the edit distance between a source and target string using XS algorithm implementation.
79              
80             use Text::Levenshtein::Damerau::XS qw/xs_edistance/;
81             print xs_edistance('Neil','Niel');
82             # prints 1
83              
84             # Max edit distance of 1
85             print xs_edistance('Neil','Niely',1); # distance is 2
86             # prints -1
87              
88             =head1 TODO
89              
90             =over 4
91              
92             =item * Handle very large strings of text. Can be accomplished by reworking the scoring matrix or writing to disk.
93              
94             =item * Add from_file methods.
95              
96             =item * Add binary/byte string support.
97              
98             =back
99              
100             =head1 SEE ALSO
101              
102             =over 4
103              
104             =item * L<Text::Levenshtein::Damerau>
105              
106             =item * L<Text::Levenshtein::Damerau::PP>
107              
108             =back
109              
110             =head1 BUGS
111              
112             Please report bugs to:
113              
114             L<https://rt.cpan.org/Public/Dist/Display.html?Name=Text-Levenshtein-Damerau-XS>
115              
116             =head1 AUTHOR
117              
118             Nick Logan <F<ugexe@cpan.org>>
119              
120             =head1 LICENSE AND COPYRIGHT
121              
122             This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
123              
124             =cut