diff options
Diffstat (limited to 'src/libaudcore/tuple.h')
| -rw-r--r-- | src/libaudcore/tuple.h | 49 |
1 files changed, 26 insertions, 23 deletions
diff --git a/src/libaudcore/tuple.h b/src/libaudcore/tuple.h index 55f3e2e..873f699 100644 --- a/src/libaudcore/tuple.h +++ b/src/libaudcore/tuple.h @@ -1,6 +1,6 @@ /* * tuple.h - * Copyright 2007-2011 William Pitcock, Christian Birchinger, Matti Hämäläinen, + * Copyright 2007-2013 William Pitcock, Christian Birchinger, Matti Hämäläinen, * Giacomo Lozito, Eugene Zagidullin, and John Lindgren * * Redistribution and use in source and binary forms, with or without @@ -90,6 +90,7 @@ const char * tuple_field_get_name (int field); TupleValueType tuple_field_get_type (int field); typedef struct _Tuple Tuple; +typedef struct _TupleFormatter TupleFormatter; /* Creates a new, blank tuple with a reference count of one. */ Tuple * tuple_new (void); @@ -105,45 +106,41 @@ void tuple_unref (Tuple * tuple); /* Makes a copy of <tuple>. Only use tuple_copy() if you need to modify one * copy of the tuple while not modifying the other. In most cases, tuple_ref() * is more appropriate. */ -Tuple *tuple_copy(const Tuple *); +Tuple * tuple_copy (const Tuple * tuple); /* Parses the URI <filename> and sets FIELD_FILE_NAME, FIELD_FILE_PATH, * FIELD_FILE_EXT, and FIELD_SUBSONG_ID accordingly. */ -void tuple_set_filename(Tuple *tuple, const char *filename); +void tuple_set_filename (Tuple * tuple, const char * filename); /* Convenience function, equivalent to calling tuple_new() and then * tuple_set_filename(). */ -Tuple *tuple_new_from_filename(const char *filename); +Tuple * tuple_new_from_filename (const char * filename); /* Sets a field to the integer value <x>. */ -void tuple_set_int (Tuple * tuple, int nfield, const char * field, int x); +void tuple_set_int (Tuple * tuple, int field, int x); -/* Sets the field specified by <nfield> (one of the FIELD_* constants) or - * <field> (one of the names returned by tuple_field_get_name() to the string - * value <str>. Only one of <nfield> or <field> may be set. If <nfield> is - * set, <field> must be NULL; if <field> is set, <nfield> must be -1. As a +/* Sets a field to the string value <str>. If <str> is not valid UTF-8, it will + * be converted according to the user's character set detection rules. As a * special case, if <str> is NULL, the result is equivalent to calling * tuple_unset(). */ -void tuple_set_str (Tuple * tuple, int nfield, const char * field, const char * str); +void tuple_set_str (Tuple * tuple, int field, const char * str); /* Clears any value that a field is currently set to. */ -void tuple_unset (Tuple * tuple, int nfield, const char * field); +void tuple_unset (Tuple * tuple, int field); /* Returns the value type of a field, or TUPLE_UNKNOWN if the field has not been * set to any value. */ -TupleValueType tuple_get_value_type (const Tuple * tuple, int nfield, - const char * field); +TupleValueType tuple_get_value_type (const Tuple * tuple, int field); /* Returns the string value of a field. The returned string is pooled and must * be released with str_unref() when no longer needed. If the field has not * been set to any value, returns NULL. */ -char * tuple_get_str (const Tuple * tuple, int nfield, const char * field); +char * tuple_get_str (const Tuple * tuple, int field); /* Returns the integer value of a field. If the field has not been set to any - * value, returns 0. (In hindsight, it would have been better to return -1 in - * this case. If you need to distinguish between a value of 0 and a field not - * set to any value, use tuple_get_value_type().) */ -int tuple_get_int (const Tuple * tuple, int nfield, const char * field); + * value, returns -1. If you need to distinguish between a value of -1 and a + * field not set to any value, use tuple_get_value_type(). */ +int tuple_get_int (const Tuple * tuple, int field); /* Fills in format-related fields (specifically FIELD_CODEC, FIELD_QUALITY, and * FIELD_BITRATE). Plugins should use this function instead of setting these @@ -168,10 +165,16 @@ int tuple_get_n_subtunes (Tuple * tuple); /* Returns the <n>th member of the subtune array. */ int tuple_get_nth_subtune (Tuple * tuple, int n); -/* Generates a formatted title string for <tuple> according to <format>. The - * syntax of <format> is documented in tuple_formatter.c. The returned string - * is pooled and must be released with str_unref() when no longer need. The - * returned string is never NULL, though it may be the empty string. */ -char * tuple_format_title (Tuple * tuple, const char * format); +/* Creates a tuple formatter object for the given format. The syntax of + * <format> is documented in tuple_formatter.c. */ +TupleFormatter * tuple_formatter_new (const char * format); + +/* Destroys a tuple formatter object. */ +void tuple_formatter_free (TupleFormatter * formatter); + +/* Generates a title string for <tuple> using the given formatter object. The + * returned string is pooled and must be released with str_unref() when no + * longer needed. Never returns NULL, but may return an empty string. */ +char * tuple_format_title (TupleFormatter * formatter, const Tuple * tuple); #endif /* LIBAUDCORE_TUPLE_H */ |