סקלרים ומחרוזות

index

מציאת המיקום של תת־מחרוזת בתוך מחרוזת.

index סורק את STR משמאל לימין בחיפוש אחר ההופעה הראשונה של SUBSTR ומחזיר את המיקום מבוסס־האפס שבו היא מתחילה. ללא מטה־תווים של ביטויים רגולריים, ללא קיפול אותיות, ללא wildcard־ים - SUBSTR מותאם מילולית, תו אחר תו. כאשר החיפוש נכשל, index מחזיר -1.

תקציר

index STR, SUBSTR
index STR, SUBSTR, POSITION

מה מקבלים בחזרה

מספר שלם. בהתאמה, ה־offset מבוסס־האפס של התו הראשון של SUBSTR בתוך STR. ללא התאמה, -1. ערך הזקיף הוא הדרך האידיומטית לבדיקה:

if (index($line, $needle) >= 0) { ... }   # found
if (index($line, $needle) == -1) { ... }  # not found

POSITION וערך ההחזרה משתמשים בסולם מבוסס־אפס זהה, כך שניתן להזין את האחד חזרה לשני כדי לעבור על כל הופעה:

my $pos = -1;
while (($pos = index($text, $needle, $pos + 1)) != -1) {
    push @hits, $pos;
}

כיצד POSITION מפורש

POSITION הוא ה־offset המוקדם ביותר שבו ההתאמה רשאית להתחיל. החיפוש עדיין ממשיך עד סוף STR; POSITION אינו תוחם את החיפוש, הוא רק מסיט את נקודת ההתחלה.

• POSITION מושמט או undef - חיפוש מ־offset 0.

• POSITION שלילי או לפני ההתחלה - מטופל כ־0.

• POSITION מעבר לסוף STR - מטופל כסוף, כך שהדרך היחידה להתאים היא אם SUBSTR הוא המחרוזת הריקה (שמתאימה בכל offset, כולל הסוף).

SUBSTR ריק תמיד מתאים, ומתאים ב־POSITION (מהודק אל תוך הטווח). זה נובע מהכלל ״המיקום הראשון שבו SUBSTR מופיע״: המחרוזת הריקה מופיעה בכל מקום.

index("hello", "");      # 0
index("hello", "", 3);   # 3
index("hello", "", 99);  # 5   (clamped to end of string)

דוגמאות

מציאת תו בודד או מילה שלמה:

index("Perl is great", "P");     # 0
index("Perl is great", "g");     # 8
index("Perl is great", "great"); # 8

דיווח על החטאה:

index("Perl is great", "Z");     # -1

דילוג מעבר להתאמה מוקדמת באמצעות POSITION לאיתור ההופעה השנייה:

index("Perl is great", "e", 5);  # 10

מעבר על כל הופעה של תת־מחרוזת:

my $s = "abcabcabc";
my $p = -1;
while (($p = index($s, "bc", $p + 1)) != -1) {
    print "hit at $p\n";
}
# hit at 1
# hit at 4
# hit at 7

אידיום נפוץ - בדיקת הכלה מבלי לבנות regex:

if (index($path, "/tmp/") != -1) {
    warn "path touches /tmp";
}

משתלב באופן טבעי עם substr כדי לפצל על ההופעה הראשונה של מפריד:

my $line = "key=value=with=equals";
my $eq   = index($line, "=");
my ($k, $v) = $eq >= 0
    ? (substr($line, 0, $eq), substr($line, $eq + 1))
    : ($line, undef);

מקרי קצה

• SUBSTR ריק מתאים ב־POSITION (מהודק אל תוך STR). index($s, "") הוא 0; index($s, "", $n) הוא $n חסום ב־length $s. אף פעם לא -1.

• STR ריק עם SUBSTR לא־ריק מחזיר -1. STR ריק עם SUBSTR ריק מחזיר 0.

• POSITION שלילי מהודק ל־0. index אינו מפרש offset שלילי כ־״מהסוף״ - זו עבודתו של rindex, וגם שם הסמנטיקה שונה.

• POSITION מעבר לסוף STR מהודק ל־length STR, כך שרק SUBSTR ריק יכול להתאים.

• ארגומנטים undef מומרים למחרוזת "" ומפעילים אזהרת uninitialized תחת use warnings. index(undef, "x") הוא -1; index("abc", undef) הוא 0 (כלל תת־המחרוזת הריקה).

• תווים, לא בתים. index פועל על רצף התווים הלוגי של המחרוזת. עבור מחרוזת של תווים רחבים, ה־offset המוחזר הוא offset של תווים, לא offset של בתים. אם נחוצים offset־ים של בתים, יש להוריד או לקודד את המחרוזת תחילה (use bytes לתצוגת־בתים לקסיקלית, או Encode::encode_utf8 לעבודה על מחרוזת אוקטטים).

• רגישות לרישיות: index רגיש לאותיות גדולות וקטנות. הפכו תחילה את שני הארגומנטים לאותיות קטנות אם רוצים חיפוש ללא רגישות לאותיות גדולות וקטנות, או השתמשו ב־=~ /\Q$needle\E/i וב־@- / $-[0] כדי לשחזר את המיקום.

הבדלים מ־upstream

תואם מלא ל־upstream Perl 5.42.

ראו גם

• rindex - אותם כללי התאמה, סורק מימין ומחזיר את ה־offset של ההופעה האחרונה ב־POSITION או לפניו

• substr - חילוץ האזור המותאם לאחר ש־index איתר אותו, או החלפתו במקום

• length - חסם עליון ל־POSITION תקף; מחזיר אורך תווים בסולם זהה שבו index משתמש

• pos - מעקב מיקום לסריקה מבוססת regex; השתמשו יחד עם m//g כאשר נחוצות לכידות במקום offset גולמי

• sprintf - בניית מחרוזת החיפוש כאשר SUBSTR מורכב מחלקים; index מקבל ליטרל, אז יש להכינה תחילה