C/Standardikirjastot/string.h

#include <string.h>

Kirjasto merkkijonojen ja puskurien käsittelyyn.

size_t, NULL: ks. stddef.h

Puskurien käsittely

Ohjelmoijan vastuulla on varmistaa, että puskureissa on annetun koon verran tilaa (kirjoittaessa) tai dataa (luettaessa).

 void *memcpy(void *kohde, const void *lähde, size_t koko);

Kopioi annetun koon verran merkkejä (yleensä tavuja) lähteestä kohteeseen. Esimerkiksi 50 int-kokonaislukua sisältävän puskurin kopiointi toiseen puskuriin on memcpy(puskuri2, puskuri1, 50 * sizeof(int)); Palauttaa kohdeosoittimen sellaisenaan.

Puskurit eivät saa olla ollenkaan päällekkäin. Tällä ei voi siis esimerkiksi siirtää puskurissa olevia tavuja hieman eteenpäin tai taaksepäin, mihin on käytettävä memmove:a.

 void *memmove(void *kohde, const void *lähde, size_t koko);

Kopioi annetun koon verran merkkejä (yleensä tavuja) lähteestä kohteeseen. Toisin kuin memcpy:n kohdalla, lähde- ja kohdepuskurit saavat olla päällekkäin, ja kopiointi tehdään niin, että sellaiset tapaukset toimivat ongelmitta. Muuten toimii samoin kuin memcpy. Tämän takia memmove voi olla hieman hitaampi. Palauttaa kohdeosoittimen sellaisenaan.

 void *memset(void *kohde, int arvo, size_t koko);

Korvaa koon verran merkkejä (yleensä tavuja) kohteesta annetulla arvolla (joka muunnetaan unsigned char:ksi automaattisesti). Lähes aina arvo on 0, jolloin tämä nollaa muistia. Hyödyllinen muistin tai joidenkin tietueiden alustamiseen. Palauttaa kohdeosoittimen sellaisenaan.

 int memcmp(const void *puskuri1, const void *puskuri2, size_t koko);

Vertaa kahden samanpituisen puskurin sisältöä. Niissä olevat arvot tulkitaan etumerkittöminä merkkeinä/tavuina (unsigned char). Vertailu suoritetaan leksikografisella periaatteella, jonka mukaan ensimmäinen puskureissa eroava tavu on merkitsevä. Palauttaa positiivisen arvon, jos ensimmäisestä puskurista löytyi suurempi arvo kun jälkimmäisestä; negatiivisen arvon, jos jälkimmäisestä puskurista löytyi suurempi arvo kun ensimmäisestä, tai nollan, jos puskurien sisältö on sama annetun koon sisällä.

 void *memchr(const void *puskuri, int arvo, size_t koko);

Hakee puskurista arvoa (joka muunnetaan unsigned char:ksi automaattisesti). Palauttaa osoittimen puskurin ensimmäiseen merkkiin tai tavuun, joka on yhtä kuin annettu arvo. Jos sellaista ei löytynyt puskurista annetun koon sisällä, palauttaa NULL:in.

Merkkijonokirjasto

Kaikki nämä funktiot toimivat C-merkkijonoilla (ks. Merkkijonot), eli taulukoilla tai puskureilla, jotka sisältävät merkkejä ja päättyvät loppumerkkiin (nollamerkki, eli merkki, jonka koodi on 0). Merkkijonon pituutta rajoittaa ainoastaan se, missä nollamerkki sijaitsee, ellei sitä ole muuten rajoitettu.

Puskurien kokoja on syytä tarkkailla näidenkin funktioiden kanssa.

Kopiointi

 char *strcpy(char *kohde, const char *lähde);

Kopioi merkkijonon lähteestä kohteeseen, mukaan lukien jonon päättävän nollamerkin. Funktio ei tarkista tai rajoita kohdepuskurin pituutta mitenkään, joten on turvallisempaa käyttää strncpy:ä. Palauttaa kohdeosoittimen sellaisenaan.

 char *strncpy(char *kohde, const char *lähde, size_t koko);

Kopioi merkkijonon lähteestä kohteeseen, mukaan lukien jonon päättävän nollamerkin, muttei kopioi enempää kuin annetun koon verran merkkejä. Palauttaa kohdeosoittimen sellaisenaan.

Jos lähdemerkkijono ei nollamerkkeineenkään täytä kohdepuskuria, se täytetään loppuun asti nollamerkeillä.

Huomaathan, että jos lähdemerkkijono ei mahdu kohdepuskuriin annetun koon sisällä, kohdepuskuriin ei lisätä nollamerkkiä. Tämäkään ei ole siis erityisen turvallinen.

Jos merkkijonon katkeaminen ei ole ongelma, tämä lienee turvallisempi vaihtoehto:

char *strncpy_safe(char *t, const char *s, size_t n) {
    if (n) {
        *t = '\0';
        strncat(t, s, n - 1);
    }
    return t;
}

 char *strcat(char *kohde, const char *lähde);

Liittää lähdemerkkijonon kohdepuskurissa olevan merkkijonon perään; kohdejonon päättävä nollamerkki korvataan lähdejonon ensimmäisellä merkillä, ja viimeisenä merkkinä kopioidaan lähdejonon nollamerkki. Funktio ei tarkista tai rajoita kohdepuskurin pituutta mitenkään, joten on turvallisempaa käyttää strncat:ia. Palauttaa kohdeosoittimen sellaisenaan. Teoriassa sama kuin strcpy(t + strlen(t), s).

 char *strncat(char *kohde, const char *lähde, size_t koko);

Liittää lähdemerkkijonosta enintään koon verran merkkejä kohdepuskurissa olevan merkkijonon perään; kohdejonon päättävä nollamerkki korvataan lähdejonon ensimmäisellä merkillä. Jos lähdemerkkijono on annettua kokoa pidempi, kopiointi lakkaa kesken ja kohteeseen lisätään vielä nollamerkki. Kohdepuskurissa on siis oltava tilaa vielä koko + 1 merkille. Palauttaa kohdeosoittimen sellaisenaan.

Vertailu

 int strcmp(const char *mjono1, const char *mjono2);

Vertaa kahden C-merkkijonon sisältöä. Vertailu suoritetaan leksikografisella periaatteella, jonka mukaan ensimmäinen jonoissa eroava merkki on merkitsevä. Palauttaa positiivisen arvon, jos ensimmäisestä puskurista löytyi koodiltaan suurempi merkki kun jälkimmäisestä; negatiivisen arvon, jos jälkimmäisestä puskurista löytyi koodiltaan suurempi merkki kun ensimmäisestä, tai nollan, jos merkkijonojen sisältö on sama nollamerkkiin asti.

Nollamerkit kuuluvat myös vertailuun, joten strcmp voi palauttaa nollan vain, jos merkkijonot ovat samanpituisia.

 int strcoll(const char *mjono1, const char *mjono2);

Vertaa kahden C-merkkijonon sisältöä samalla tavalla kuin strcmp, mutta merkkien vertailu tehdään maa-asetusten mukaisesti (ks. locale.h).

 int strncmp(const char *mjono1, const char *mjono2, size_t koko);

Vertaa kahden C-merkkijonon sisältöä samalla tavalla kuin strcmp, mutta rajoittaa lisäksi vertailtavien merkkien lukumäärää. Jos annetun koon sisällä ei löytynyt eroja, funktio palauttaa nollan.

 size_t strxfrm(char *kohde, const char *lähde, size_t koko);

Mukauttaa lähdemerkkijonoa ja sijoittaa mukautetun version kohdepuskuriin, mukaan lukien nollamerkin (jos mahtuu). Sijoittaa puskuriin enintään koon verran merkkejä. Palauttaa luvun, joka kertoo, montako merkkiä kohdepuskuriin olisi kirjoitettu nollamerkkiä lukuun ottamatta (eli kohdepuskuriin tulee mahtua paluuarvon + 1 verran merkkejä). Jos paluuarvo ei ole kokoa pienempi, kohdepuskurin sisältöä ei taata.

lähde saa olla NULL, jos koko on 0. Tällöin palautetaan vain pituus.

Mukauttaminen tapahtuu maa-asetusten mukaisesti (ks. locale.h). Periaate on, että mukautettuja merkkijonoja voi vertailla strcmp:llä niin, että niiden tulos on sama kuin jos alkuperäisiä merkkijonoja olisi vertailtu strcoll:lla.

Haku

 char *strchr(const char *mjono, int merkki);

Hakee merkkijonosta tiettyä merkkiä (joka muunnetaan char:ksi automaattisesti). Palauttaa osoittimen merkkijonon ensimmäiseen merkkiin, joka on yhtä kuin annettu merkki. Jos sellaista ei löytynyt merkkijonosta, palauttaa NULL:in.

strchr:ää voi käyttää myös nollamerkillä, jolloin funktio palauttaa puskurin nollamerkkiin, eli merkkijonon loppuun.

 size_t strcspn(const char *mjono, const char *haettavat);

Palauttaa, montako ensimmäistä merkkiä merkkijonosta mjono ovat sellaisia, joita ei ole merkkijonossa haettavat. Nollamerkkiä merkkijonossa haettavat ei lasketa.

 char *strpbrk(const char *mjono, const char *haettavat);

Palauttaa osoittimen ensimmäiseen merkkijonon mjono merkkiin, joka on merkkijonossa haettavat, tai NULL:n, jos sellaista ei löydy. Nollamerkkiä merkkijonossa haettavat ei lasketa.

 char *strrchr(const char *mjono, int merkki);

Hakee merkkijonosta tiettyä merkkiä (joka muunnetaan char:ksi automaattisesti). Palauttaa osoittimen merkkijonon viimeiseen merkkiin, joka on yhtä kuin annettu merkki. Jos sellaista ei löytynyt merkkijonosta, palauttaa NULL:in.

strrchr:ää voi käyttää myös nollamerkillä, jolloin funktio palauttaa puskurin nollamerkkiin, eli merkkijonon loppuun.

 size_t strspn(const char *mjono, const char *haettavat);

Palauttaa, montako ensimmäistä merkkiä merkkijonosta mjono ovat sellaisia, jotka ovat merkkijonossa haettavat. Nollamerkkiä merkkijonossa haettavat ei lasketa.

 char *strstr(const char *mjono, const char *alijono);

Hakee alimerkkijonoa (esim. sanaa) merkkijonosta mjono, ja palauttaa osoittimen ensimmäiseen löydettyyn tulokseen. Jos sitä ei löytynyt ollenkaan, palauttaa NULL:n. Jos alimerkkijono on tyhjä, palauttaa mjono-osoittimen sellaisenaan.

 char *strtok(char *mjono, const char *erottimet);

Pilkkoo merkkijonon annettujen erottimien perusteella. Kun erotin löytyy merkkijonosta, se korvataan nollamerkillä, ja funktio palauttaa osoittimen merkkijonon alkuun; näin se 'palauttaa' merkkijonon, joka päättyy juuri ennen erotinta.

Tämän jälkeen strtok:ia voi kutsua uudelleen niin, että mjono on NULL, jolloin se jatkaa hakua. strtok:lla on siten sisäinen tila.

Palauttaa NULL:in, kun mitään erottimista ei enää löytynyt merkkijonosta.

Muut

 size_t strlen(const char *mjono);

Palauttaa merkkijonon pituuden merkkeinä. Nollamerkkiä ei lasketa pituuteen. Käytännössä sama kuin (size_t)(strchr(mjono, '\0') - mjono), eli hakee merkkijonosta loppumerkin ja päättelee pituudeksi sen, miten monta merkkiä sen piti käydä läpi.

 char *strerror(int virhenumero);

Muuntaa virhekoodin virhetekstiksi sisäiseen puskuriin ja palauttaa osoitteen puskuriin. Puskurin sisältö voi muuttua uuden strerror-kutsun jälkeen, mutta käyttäjän ei pidä muokata sitä.

Yhteisen sisäisen puskurin takia strerror:n käyttö monisäikeisessä ohjelmassa on hankalaa ja vaatii jonkinlaisen rakenteen, jolla estetään useaa säiettä kutsumasta niitä samaan aikaan, ja kopioidaan merkkijono toiseen puskuriin ennen seuraavan kutsun alkua.